OXP howto dockable stations

Introduction

A small tutorial by Svengali about making a Station dockable in Oolite.

I'll try to show you what Oolite expects from you to make a Station-Entity dockable and where the limits are.
A lot of users have asked this question in the past and sometimes it's a bit tricky to get it working. But it's really no magic.

Before we'll start, you should be familiar with modelling and texturing and a bit knowledge about setting up the structure of oxps won't hurt too.

For a deeper understanding you should take a look in the following pages - just in case .-)

• Docking_Instructions
• Shipdata.plist
• Station_Ships
• Quaternion
• Oolite_JavaScript_Reference:_Entity
• Oolite_JavaScript_Reference:_System
• Oolite_JavaScript_Reference:_Vector3D
• Oolite_JavaScript_Reference:_Quaternion

Chapter I

Point A - Absolute

The first step is to understand the basics how Oolite is calculating positions and distances, but don't worry, it's not so hard and we won't explore the Math behind it. It only needs some practice. So let's begin.

A Star-System in Oolite has a Middle-Point (0,0,0). You can imagine this as the BIGBANG-point.

This is the 'Absolute Middle-Point' (Point A) and is the Reference-point for every single Entity in Oolite. Planets, Moons, Stations and Ships are positioned in relation to this point! Everything!

You can see the relation to Point A in action by activating the FPS display (see Display Frame Rate). The displayed coordinates are translated to another Coordinates-System (here 'pwm' instead of 'abs'), but you'll get a feeling for it. For more info about the Coordinate-Systems see

• Oolite_coordinate_systems
• Methods.

Point E - Entity

Now the fun starts. Lets take a look at the pic "Point E".

Every Entity (Ship, Station, Asteroid, Cargo Cannister, etc.) has a own Middle-Point (Point E) that is used to determine the Entities position in space in relation to the Absolute Middle-Point (Point A) and also to calculate the distances and relative positions of Entities to each other. This point defines also (in conjunction with other parameters like the Ships mass) the Entity itself (e.g. Oolite places the models vertices in relation to that point and can check for collisions and laser hits then) and is used to place the Subentities if declared.

The Entities Middle-Point (Point E) is absolute (0,0,0) for the Entity itself AND relative (e.g. -12356.3, 20582,8, -238.76), because it is set in relation to the Star-Systems Middle-Point (Point A). This means positioning a Entity has to be seen in relation to Point A!

To talk about two middle-points sounds confusing, but it gives Oolite the possibility to calculate everything a lot faster and is easier to handle, because you only have ONE fixed point (Point A) and everything (Point E's) is set in relation to this point!

Let's take a look in one possible way to add a Entity that uses Point A as reference.

 system.legacy_addShipsAt('trader', 1, 'abs', [-10,20,30]);

As you can see we're trying to create 1 trader. The Reference-Point is Point A and we are trying to position the trader at absolute X = -10, Y = 20 and Z = 30. Point A is somewhere nearby the Witchpoint Beacon, so we have to move to this point to see this ship. So a Ships middle-point (Point E) is related to the Star-Systems middle-point (Point A) and we'll get a absolute position for this Entity in the Star-System (e.g. [-10,20,30]).

In Javascript we can access this position, change it or calculate other things in relation to it.

You might think that's it - basics finished.

Oh, no - wait a moment...

Point D - Docking

The last point is now how Oolite is doing the docking. With all that knowledge packed it is fairly simple to see that Oolite checks for positions and distances of Entities (Point E's) to each other. This is probably a timeintensive task, but the development-team is doing a great job and the Math behind it is pretty spectacular for noobs like me. (Thanks Aegidian and Ahruman).

The docking procedure itself is simply triggered by another Point E, if a ship comes in range. This point is different to Ships middle-points, so lets call it Point D. It's more a virtual sphere than a point, but as I've said above - no magic .-)

This point is like the other points not visible, so no player will see this trigger. The docks you can see in Stations are only there to give your eyes and brain something to work with. But internally this sphere has some side effects. The collision detection is disabled inside this sphere and reduced in a corridor along the Z-Axis. That's also the reason why a dock has always to be oriented to show along the Z-Axis.

But this can also cause some problems for players trying to dock. The trigger and the corridor are invisible and if you don't have the right angle while approaching you can pass the point where the collision detection is disabled/lowered. The result is then probably a Finale Grande -Press Space-.

Another very important note is that the docking-sphere is attached to the Main-Entity, even if a Subentity is used for the visual part!

Basics done. Confused? Don't worry - it will become worse .-)

Chapter II - The right models

Positioning

Chapter III - Finalizing

shipdata examples

Chapter IV - Advanced options

Main Entity

Sub-Entity

Scriptable

Links

Tutorials:

• modelling
• texturing
• structure of oxps

Documentation:

• Methods
• Docking_Instructions
• Shipdata.plist
• Station_Ships
• Quaternion
• Oolite_coordinate_systems
• Oolite_JavaScript_Reference:_Entity
• Oolite_JavaScript_Reference:_System
• Oolite_JavaScript_Reference:_Vector3D
• Oolite_JavaScript_Reference:_Quaternion

BB Threads:

• (REQUEST) Station tutorial (2012)
• Putting it all together (2018) by Phkb - for ships but recent