OXP howto dockable stations - Revision history

Cholmondely: /* Links */ Added js for 2 different docks at 180°

2021-10-03T11:06:31Z

‎Links: Added js for 2 different docks at 180°

Cholmondely: /* Links */ Added Link & tags

2021-08-09T09:33:38Z

‎Links: Added Link & tags

Cholmondely: Added another thread

2021-07-15T02:20:29Z

Added another thread

Cholmondely: Linked to Svengali

2021-01-21T14:02:28Z

Linked to Svengali

Uncle Reno at 18:38, 5 June 2010

2010-06-05T18:38:32Z

Svengali: typos

2009-09-22T23:11:38Z

typos

Svengali: First part of tutorial OXP_howto_dockable_stations

2009-09-21T14:15:42Z

First part of tutorial OXP_howto_dockable_stations

New page

=== Introduction ===

A small tutorial 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.<br>
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 [[OXP_howto_model|modelling]] and [[OXP_howto_texture|texturing]]
and a bit knowledge about setting up the [[OXP_howto_plist|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 ===
[[Image:OXP_howto_dockable_pointA.png|thumb|right|160px|Point A]]
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!

You can see it in action by activating the FPS display (see [[Oolite_Keyboard_Controls|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]].

[[Image:OXP_howto_dockable_pointE.png|thumb|right|160px|Point E]]
Now the fun starts. Lets take a look at the pic.

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).

So 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 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 it.

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...

[[Image:OXP_howto_dockable_corridor.png|thumb|right|160px|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. So 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!

=== Chapter II - The right models ===
[[Image:OXP_howto_dockable_isosahedron.png|thumb|right|160px|Positioning]]


=== Chapter III - Finalizing ===
shipdata examples


=== Chapter IV - Advanced options ===
[[Image:OXP_howto_dockable_specialmain.png|thumb|right|160px|Main Entity]]
[[Image:OXP_howto_dockable_specialsub.png|thumb|right|160px|Sub-Entity]]
[[Image:OXP_howto_dockable_specialsubs.png|thumb|right|160px|Scriptable]]


=== Links ===

Tutorials:
* [[OXP_howto_model|modelling]]
* [[OXP_howto_texture|texturing]]
* [[OXP_howto_plist|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]]

@@ Line 134: / Line 134: @@
 * [http://www.aegidian.org/bb/viewtopic.php?f=4&t=12477 (REQUEST) Station tutorial] (2012)
 * [http://aegidian.org/bb/viewtopic.php?p=264830#p264830 Putting it all together] (2018) by [[User:Phkb|Phkb]] - for ships but ''recent''
 <!-- Categories -->

@@ Line 133: / Line 133: @@
 BB Threads:
 * [http://www.aegidian.org/bb/viewtopic.php?f=4&t=12477 (REQUEST) Station tutorial] (2012)
 <!-- Categories -->

← Older revision		Revision as of 18:38, 5 June 2010
Line 132:		Line 132:

	<!-- Categories -->		<!-- Categories -->
		+
		+	[[Category:Oolite scripting]]

@@ Line 130: / Line 130: @@
 * [[Oolite_JavaScript_Reference:_Vector3D]]
 * [[Oolite_JavaScript_Reference:_Quaternion]]
 <!-- Categories -->

@@ Line 1: / Line 1: @@
 === Introduction ===
-A small tutorial about making a Station dockable in Oolite.
+A small tutorial by [[User:Svengali|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.<br>

@@ Line 18: / Line 18: @@
 * [[Oolite_JavaScript_Reference:_Vector3D]]
 * [[Oolite_JavaScript_Reference:_Quaternion]]
 === Chapter I ===
-[[Image:OXP_howto_dockable_pointA.png|thumb|right|160px|Point A]]
+[[Image:OXP_howto_dockable_pointA.png|thumb|right|160px|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.
+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!
+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!
 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]].
-[[Image:OXP_howto_dockable_pointE.png|thumb|right|160px|Point E]]
+[[Image:OXP_howto_dockable_pointE.png|thumb|right|160px|Point E - Entity]]
-Now the fun starts. Lets take a look at the pic.
+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).
+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!
 Let's take a look in one possible way to add a Entity that uses Point A as reference.
@@ Line 48: / Line 46: @@
   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 it.
+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.
@@ Line 56: / Line 54: @@
 Oh, no - wait a moment...
-[[Image:OXP_howto_dockable_corridor.png|thumb|right|160px|Docking]]
+[[Image:OXP_howto_dockable_corridor.png|thumb|right|160px|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. So it's more a virtual sphere than a point, but as I've said above - no magic .-)
+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.
@@ Line 66: / Line 64: @@
 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!
 === Chapter II - The right models ===