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

Svengali's Notes: A few words about orienting the models!!! (Main-Entity: 0,0,0 and Subent: 0,0,0 or relative to Main)

X/Y have to be centered (in relation to the Main-Entity) and port_radius defines the movement on Z.

A few words about naming the models and naming conventions in general.

And names of textures have to be exactly (case-sensitive) the same as in .dat defined.

Please try to avoid using too many Vertices and Faces for your models - try to find the balance between visual quality and used processing time. The same for the textures - try to reduce the size and help to keep Oolite smooth and fast.

The slits dimensions are fixed (69mx69mx250m), only the visible part can be adjusted with the standard way. Chapter IV will show you two other technics to do it in a more flexible way.

Chapter III - Finalizing

shipdata examples

Svengali's Notes:

Some words about moving the Subentity via Quaternion for finetuning or in general.

Some words about how Oolite is finding the right Subent == dock

a. by role (docking-slit) and if not found

b. by name, so if 'dock' (LOWERCASE!!!) is used in the entityname it will be handled as docking-slit

c. if nothing is found and scan_class = Station Oolite will use a standard slit.

Remember: The slit itself has to be placed on the z-axis (X/Y = 0) and the port_radius defines Z.

Unfortunately all this means that you can't adjust the slits dimensions, only the visible part can be adjusted with the standard way. Chapter IV will show you two other technics to do it in a more flexible way.

Chapter IV - Advanced options

Main Entity

Sub-Entity

Scriptable

Svengali's Notes:

Way 1)

port_radius

port_dimensions

Some words about deprecated, but still working.

Way 2)

Scripted

Pro: Flexible positions

Contra: Slow and not failsafe

---

Some examples of more advanced stuff

• Tweaking Docking: See HIMSN Naval Bases & Nephthys Stations
• Tweaking TL levels: this is read-only. But see Montana05's multiple models with different TL's as a work around for this in S.I.R.F.
• Adding Missions: see Riredi OXP
• Adding description/depth/possibilities: see Black Monk Monastery, Royal Hunting Lodges & Galactic Navy OXP naval bases

---

Snippets from elsewhere

• Important: You need to include "station" or "carrier" as one of the "roles" in the Shipdata.plist, or docking will fail dismally, no matter the excellence of the dock itself!

• Aegidian (2003-6?): Quick and easy instructions for wings3D.

 1. Make a panel on your main model where the dock entrance will be. A rectangle 192x64 is ideal, but you can go bigger - and use different shapes.

 2. Assign the special material hole to the rectangle.

 3. While you have it selected make a note of the coordinates of the centre of the rectangle.

 4. As a separate model, make a cube then scale it to the dimensions of your rectangle and a depth of 250. So a cube scaled to 192 x 64 x 250.

 5. Select the face of the cube facing the same way as your dock entrance in (1.) and assign it the hole material.

 6. While it's selected choose Tools - Center - All from the menu to move that face to the origin.

 7. Select the object, and from the right-click menu choose Invert to turn the cube 'inside out'.

 8. Texture your new dock. And convert it to an Oolite .dat model file.

 9. Position the new dock as a subentity of the station, at the coordinates you noted down in (3.)

10. You should now be done. You can vary the shape of the dock entrance in stage 1. If you copy and paste the panel into a new model you can even use it to extrude the dock shape.

• Charlie on the above (2007): For those who prefer to use an alternate 3D package to Wings you don't have to use it for the hole material. Just chopping holes in your model & dock seems to work!

• dajt (David Taylor on backwards facing docks (2007)

• Killer Wolf (2022): I actually did a dockable asteroid, the hacker outpost and salvage gang that was incorporated into the Anarchies OXP according to a search. You could fly inside it and then into the docking bay itself so you could probably reverse engineer that if needed. I wrote a post about docks (2009) on page 2 of the "things I wish I knew.." thread. Beyond that stations like the Hathor Trade Station also have docking tunnels that might help.

• Murgh (2022): For starters you just leave a 192m x 64m slit (material defined as a "hole" in the [station/dockable] model).. always facing the Z axis, with the hole's center at x=0 and y=0 if there will be rotation..

There are of course plenty of fine dock models you can directly borrow or modify, or build a 192x64x250 (or bigger) cube yourself, skinning its insides (In Wings3D, in "body mode", invert the dock's surfaces for UVmapping to look right) to your pleasure.. I'd recommend keeping the two models separate to make it easier (to keep distinct objects with regular and inverted texturing apart), since they will be two different .dat files and the unification of the two happens later in the shipdata.plist.

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)
• Scanner Blebs (2009) This thread contains posts on positioning of docking ports, enabling bounding boxes, getting station docks properly formatted (one presumes that references are to the Nuit Space Station OXP).
• Putting it all together (2018) by Phkb - for ships but recent
• Javascript for docking and launching at 2 different docks at 180° by User:Thargoid (2011)
• 1 1/2 pages on station population percentages (2010)