Pioneer dev forum

Locators are named point objects with orientation. ('Empty' object in Blender). They are used by the ship's autopilot to safely navigate through the station to the assigned bay. When passing through the waypoint, the ship will assume it orientation, so that the Y-axis of the locator is facing the top of the ship, and the Z-axis is towards the back of the ship (unless it is canceled by the ending :pos). The same applies to the bay locator:


Two kinds of locators are used:
BAY (PAD, PORT) bay_ - means separate landing site for the ship
WAYPOINT wp_ - all other locators except bays

The docking path is created as a chain of waypoints referencing the previous one (in-reference).
The undock path is created as a chain of waypoints referencing the next one (out-reference).
The same point can be included in both the docking route and the undocking route.

Waypoint syntax (things in square brackets can be omitted):
name is any sequence of ascii characters except '_' and ':'
reference is a name of some other point
in-reference is a name of the previous waypoint of the docking route
out-reference is a name of the next waypoint of the undocking route
:pos indicating that the ship is not required to adopt the orientation of a given tag

example:
wp_gr2:gr1_gr3 - waypoint with name 'gr2' with in-reference from 'gr1' and out-reference to 'gr3', that is, its previous point of the docking route is gr1, and the next point when undocking is gr3

Bay syntax: name is any sequence of ascii characters except '_' and ':'
min_size, max_size - integers, mean the minimum and maximum allowable size of the ship for this bay, meters
references means the same as for waypoints, of course, these are names of the last waypoint of the docking route, and the first waypoint of the undocking route

example:
bay_A1_s0_20:gr1_gr2

Simplifications.

If a reference to an output point is omitted, the input reference is copied to the output:

wp_a10:a11 == wp_a10:a11_a11
bay_B1_s0_20:gr3 == bay_B1_s0_20:gr3_gr3

If both references are omitted, they are considered non-existent:

wp_entr == wp_entr:_

wp_a12:_a10 - no previous dock waypoint, next undock waypoint is a10
wp_a12:a10_ - previous dock wp is a10, no next undock wp

The absence of an input reference at the point means that this point can be the beginning of the docking route.
The absence of an output reference means that this point can be the end of the undock route.
If the bay does not have a docking/undocking reference, one waypoint is added to it 500 m above.

Docking and undocking routes are built starting from the bay, following the refs until a null reference is encountered in this direction.
Input refs are considered only when building an input route.
Output refs are considered only when building an output route.

Route point blocking.

If the ship has received permission to dock, all points of the docking route are blocked, this means that it is unacceptable to move along any other route containing one of the blocked points.

As ship passes the waypoints, the autopilot can send a signal to the station so that the passed waypoint is unlocked.

After the end of the passage along the route, all points of this route are unlocked.

Example of locators configuration.

See the names of locators, and what connections are formed from that names:


Show the route for only one bay:


Route building starts from bay4. since only one ref is specified (gr2), it automatically becomes both an input ref and an output ref. Further by the refs from gr2, we are going to gr1 for the docking route and gr3 for the undocking. Further, following the link from gr1, we come to wp_entr, which has no further links, so this is the entrance. And following the link from gr3 we get to wp_exit, which also has no links, so this is the end of the undocking route (exit).
As you can see, many points are reused by different bays.

see which points are blocked when the ship receives permission to dock at bay4. As you can see, point wp_gr3 and wp_exit are free, so undocking can be started at the same time, for example from bay8.


Also, after passing the points, the autopilot releases them, so after passing wp_gr1 you can start another docking, for example, in bay2


If all the bays are available at the same time (for example, at ground stations), you can simply place bay locators only. Above each bay, at an altitude of 500 m, one waypoint will be automatically set to ensure a vertical landing. On the other hand, it may be worth organizing traffic more strictly, creating waypoints of approach to the station, waypoints of departure, so that the trajectories of ships do not intersect, etc.

Thus, using this system, you can create a network of waypoints of any complexity, probably for any station architecture. With one limitation - bay can only be connected to one entrance and one exit.

Very cool. One thought: what happens if a ship doesn't free / un-lock it's waypoints? Maybe it got blown up, or aborted or something, I just imagine a situation where a path is locked, because <edge case>.

Fluffyfreak might be interested in seeing this, posted by Gliese on IRC, landing on a space station without rails:
https://imgur.com/a/7yjhXaC

Some explanation of how a ship determines how fast it can pass a waypoint. This depends on the radius of the waypoint, the acceleration that the ship can produce, and the angle at which the path breaks at that point. For simplicity, we take the minimum acceleration - that which is produced by the weakest thrusters of the ship.

The waypoint radius is the distance from the waypoint to the center of the ship when we consider that we have reached the waypoint.

The angle of the path determines how much of the speed needs to be reduced in order to fit into the turn. Obviously, if you need to turn 90 degrees, you need to reduce all the speed, and if there is no turn at all, you don’t need to brake at all, the speed can be as high as you like.

The ship enters the waypoint with a speed v0, and upon reaching the center, the velocity component in this direction should decrease and become v.

The reduction factor, k, I called it "passability", is max(cos(a), 0), And the cosine is conveniently calculated through the scalar product of the corresponding vectors.

By means of simple transformations, we obtain an expression for the speed at the center of the waypoint. To avoid dividing by 0 when k=1, we specify the maximum possible speed, for example c.

Here are my calculations on paper and the resulting formulas for v and k_max.


The resulting speed is used by the autopilot (as end-speed) to calculate the speed at the moment, so as not to overshoot the turn.

I would like to add that immediately after entering the sphere of a waypoint, the ship switches to the next one, and therefore flies in a certain arc (red dotted line).

There is a problem with the ship missing the waypoint because it is not achieving the required speed efficiently enough in the Propulsion::AIMatchSpeed function. To explain the problem, I will consider a two-dimensional case, along the Y (up) and Z (back) axes.

We can take the available thrust in the corresponding axes, and translate it into the maximum change in speed that we can achieve in the current frame - max frame accel. (A) The resulting rectangle is all possible maximum changes in speed in a given plane.

We are given the speed that we want to achieve, we also need to suppress the current speed, and the speed that external forces will create in a given frame, usually gravity. (B) Since the end of the sum of vectors lies outside the rectangle, we will not be able to achieve the required speed in the current frame. The current implementation projects the sum vector onto the axes and then crops them, the picture shows that this is not optimal. It can also lead to strange results if a strong thruster is directed away from the required speed.

It seems that we can do better if we try to get as close as possible to the desired velocity vector in the current frame (proposed vector). That is, we are looking for the intersection with the previously described rectangle, if there is one, or the nearest point. Different cases are presented in (C):
1. If the end of the vector ends up inside the rectangle, we will achieve the desired speed in the current frame.
2. We can have 2 intersections, we choose the one that is closer to the end.
3, 4 If there are no intersections, we find the hopefully "closest" point to the vector on the rectangle. This will be a bit of a strange algorithm, especially for the 3D case. I think this is the hardest part.

And the last trivial step, we scale the rectangle to a +- 1.0 and this will result in the required states of the thrusters. (D)