pioneerspacesim/pioneer — pull request #2058 by fluffyfreak (2013-02-13 19:56:19+00:00)
Title: **WIP:** New space station docking system and grouping.

# Description:
A new modeller based docking & bay grouping configuration system so that the modeller can define the orientations and positions used during docking and departure. Also the bays can be grouped together which replaces the dock_one_at_a_time flag.

## The Problem(s):
The existing Lua based docking procedure does not scale to handling N docking bays/ports. It's also difficult to get the positioning correct through scripting as opposed to doing it directly within the modelling program.
Also controlling the simultaneous docking of ships for bays is currently controlled by a single flag which is either on or off.

## The Solution(s):
Get the orientation and position of numbered and named waypoints from the mesh file itself.
Create a way to group the bays in the Lua with a simple interface.

# This horrendous commit:
The limitation on the number of bays is gone, or rather it's lifted from 4 to 240.
You can define docking using Lua or from the modelling program.
You can group bays together with docking/leaving being limited to a single ship at a time per-group, however ships can dock with each group simultaneously.

Included is a WIP spacestation with 8 bays, it's not meant to go into the final PR for this but I need to submit this for feedback and it's included to demonstrate usage.

There's a MAX2013 file that has the current docking port waypoints setup within it for that station so you can see how they're currently named and used. It doesn't have doors or anything and is... well it's a bit crap :) but the waypoints are what matter! :D

## Waypoint naming:
I'll briefly run down the list of waypoints but bear in mind that all of this is work in progress and might change a little over time.

### Approach waypoints:
You can only have 2 of these for each bay, the 1st is far out and then 2nd is just outside the bay doors.
Naming:
"approach_port#_stage#" - "approach_" is what identifies it in the code, "port#_" is the bay number, I might change it to "bay#_" instead of "port#_" so let me know what you think, "stage#" is either 1 or 2 for the approach waypoints.
Approach waypoints are only used to approach the station before docking waypoints take over.

### Docking waypoints:
You can have lots of these, but weirdly their numbering starts at 2 - it doesn't HAVE to be this way but it's kinda how the current Lua driven stuff works because it takes the last approach waypoint as it's first position... horrible.
Naming:
"docking_port#_stage#" - "docking_" is the identifier, "port#_" is the same as above, "stage#" runs from 2 (currently) upto whatever number you like! The last stage number is where it will be when it has docked, so in my model it is docked and oriented to waypoint "docking_port1_stage4".

### Leaving waypoints:
You can have lots of these and they DON'T have to be the same as the docking waypoints, meaning that you could enter and leave via different routes in theory. These are conventionally number 1-N where N is a big number :)
Naming:
"leaving_port#_stage#" this is all the same format as the above explanations.
The last waypoint's orientation is MUCH more important than the rest, you have have the others cause the ship to spin, flip and pirouette if you want but the last waypoint defines what direction it will accelerate away from the station in... I had some hilarious explosions getting that bugger wrong, repeatedly! I suggest pointing it _away_ from the spacestation ;)

###Naming notes:
You'll notice in my max file that there's some other text after the real named part like "_pt01", it's ignored by the code, you could write "andysmells0001" if you liked it'd still work :) I just found that when duplicating the waypoints MAX would helpfully rename the "stage1" to something like "stage02" which was not what I wanted. The extra sacrificial text just made editing easier.

### Important bits:
The current waypoint is used to attach the centre of the ship, but this means that the last waypoint is always wrong for some ships and they end up sticking through the landing pad. I'm still working out how to fix this but I have only two options:
The waypoints are used to define where the bottom of the ship goes, i.e. where the wheels/feet are.
I collision test the last waypoint with the bounding box to decide when it's reached it.
I'm thinking of trying out option #2 first but be aware that I might need to use option #1, am going to try and discuss it on the mailing list to get feedback and submit a dummy Pull Request to get advice on the code etc.

Orientation is a bitch! There's two conventions to orienting the ship along the waypoints! AAAARGH! It's again because of the Lua docking code which I'm trying not to break.
I'll have to go into more detail with them in another post but take a look and have a play around. The approach orientation is different from the docking & leaving orientations.

# Current state:
There's some dubious decisions about the naming and location of bays and their groups data structures. I need some advice or ideas about better locations to store that data and define the structures.
Also what do people think of the actual approach so far?
Problems? Solutions? Issues? Stupid things I've definitely done?

Andy