Ok, here's basically how dockpoints work in terms of their components:
You will need two main components:
1) A dock
2) A path leading to the dock
I'll start with the assumed situation of a support ship coming in to rearm, meaning we start with....
The pathA docking path has a few components. The first two are a name and a properties field, where the name should just be "$path##", and the properties should be "$dock01-01" for the first dockpoint on the first dock. (I don't know how important this particular field is TBH. It seems a little redundant.)
The last and most important component of a path is the path points themselves. A docking path will consist of four points in order of furthest-away to closest-to. Each of these points has a location and a radius. I think the game uses these points as waypoints for incoming docking ships.
So, it will first fly towards the centre of the first path point until it is within that points radius (the biggest one), and then look to fly inside the radius of the second etc, repeating the process until it gets inside the radius of the final tiny radius point. Once it gets to that point, the path following is complete, and the docking ship will start seeking to dock.
At this point, the game will switch to the data of the dock that is associated with this particular path, which brings us to....
The dockDocks consist of 3 main components: Properties, an associated path number and the docking points. In retail the dock properties field is what defined the docks compatability - ie, calling it a "rearming dock" would mean that it could ONLY dock with a support ship there, and "cargo dock" would mean it could only dock with cargo there. AFAIK this restriction was lifted in FSO, leaving it up to the modder/fredder to decide what should and shouldn't happen. Due to this you should be able to safely call your docks whatever you like - as these names are the ones that appear in FRED.
The path number is just the bit that links the dock itself to the path that leads to it. Easy to forget, but it won't work without it.
Now onto the docking points:
Don't confuse "docks" with "docking points". Each "dock" will have two "docking points" that have a location and a normal. The first one is the main one, as this is the one who's normal the incoming docking ship will seek to align it's own first docking point normal to
in the exact opposite direction, so they will basically be pointing at each other.
Also during this alignment the second dockpoint comes into play. As Galemp described, this controls how the docking ship will rotate around an imaginary axis through the docking point normals when it docks. If that is hard to visualise or makes no sense at all, think of it as basically the bit of data that tells the docking ship which direction the 'front' of the dockee ship is.
Ie, if you have the second docking point in front of the first point (a 1m larger Z axis postion) on both the docking ship and the dockee ship, then when they dock both ships will be facing in the same direction. If both docks are set up so that the second point is 1m behind the first, then they will also both still face the same direction. If however one ship has the second point in front and the other ship has it behind the first, then when they dock they will be facing in directly opposite directions.
Anyway, during this alignment stage you will probably see the docking ship slide around a bit to bring the normals into line, and then it will continue to slide straight down the normal line until both first dockpoints are touching. Once these two points are coincident, the ships are considered docked.
Note: It may try and do the alignment a bit earlier, like at the 3rd path point or so. Not sure there but it seems likely.
And that's it!
Some of this info may be a bit out of date or needlessly precise (mainly the names and properties descriptions) due to the SCP, but follow it and you should be fine. (Though I would certainly like to know from coders if any of it is wrong.
)
