External Docking System

Nuit station featuring two liners externally docked

Overview

This mod provides a system that allows external docking ports to be added to dockable stations. Ideally, the station model and textures will already have a place where an external dock has been included. This OXP allows for that external dock to be used by players.

How it works for the player

When a station has been assigned an external dock, the player only needs to approach the indicated point directly, and slow to less than 100m/s. When the player is close enough, the docking sequence will be initiated.

If the OXP doesn't do anything to change the behaviour, when the player launches from the station, it will be from the standard internal port. An OXP can elect to have the player launch through the external port, but there are additional setup requirements for this.

Compatible OXPs

At time of writing (Feb 2024) this works with the following:

• Nuit Space Station OXP the fons et origo of this OXP! You will need Nuit v.2.2 or better
• Extra Rock Hermits
• Space Bar Facelift‎ - a retexture for Random Hits OXP's Space Bar - which now adds something extra

How it works for the developer

There are a couple of steps to getting the system to work.

1. Have some sort of visual clue for the player about where the external dock is. Flashers are the obvious choice, and a set of flashers can be found in the effectdata.plist file of this OXP (they are currently commented out).

2. Make sure it will be possible for the player to reach the external dock at less than 100m/s. That might seem like an odd instruction, but it will be critical if your carrier/station is either (a) rotating or (b) moving. Docking head on with a moving landing pad will be tricky. Ideally, external docking ports should only be added to stationary ships.

3. Add the following code somewhere in your station spawning script.

   var eds = worldScripts.ExternalDockSystem;
   eds.$addExternalDock({
       station:my_station, 
       position:[2400, 0, 0], 
       preDockCallback:this.$preDockSetup.bind(this), 
       postDockCallback:this.$postDockSetup.bind(this)
   });

The structure of the object passed to the function call is as follows:

   station:ship,               // The station to which you are attaching an external port
   position:[x,y,z]            // The x, y and z coordinates for the docking port, relative to the centre of your station
   realPosition:pos,           // The real in-game position for the docking port, independent to the station
                               // Note: you must provide either the position or realPosition
   scale:1,                    // To change the size of the docking port (1 = no change; 0.5 = half size; 2 = double size; etc). Default is 1.
   allowLaunch:true,           // Indicates whether ships that dock at the external port should launch through it as well. Default is false.
   dockRange:150,              // Indicates how far away from the dock point the player must reach before docking commences. Default is 150 (meters).
   launchDistanceBoost:1000,   // Indicates how far further forward to position the player from the dock when launching. Default is 0 (meters).
   launchSubEntityIndex:5      // If launches will be conducted through the external port, this specifies the index of the subentity that will be used to work out
                               //   the orientation the player ship will have on launch
   preDockCallback,            // The function to call just before the player is docked at the station (and prior to all docking-related world events)
   postDockCallback            // The function to call just after the player is docked at the station (after shipWillDockWithStation but before shipDockedWithStation)

Only the station and position parameters are required. All the others are optional.

Notes: "scale": By default, EDS will notify the player of excess speed when they are within 2000m of the dock port. If that distance is too great, such that it would conflict with other functions of the station, changing the size property will scale the distance as required. So, a value of 0.5 would reduce the distance of the point to 1000m.

"launchSubEntityIndex": When the player is launched through a normal dock, their ship is aligned to the orientation of the dock. If a launch is to take place through an external port, a similar subentity must be chosen to allow the player's ship to have the correct alignment, otherwise they may launch in the wrong direction and crash into the station.

See Space Bar Facelift or Extra Rock Hermits for a simple example of this in action. See the Nuit Space Station OXP for a more complex example, with 4 external docking ports.

Download

Download ExternalDockingSystem_1.8.oxz v1.8 (downloaded 0 times).

License

This work is licensed under the Creative Commons Attribution-Noncommercial-Share Alike 4.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/4.0/

Discussion

This OXP is discussed at this forum link: https://bb.oolite.space/viewtopic.php?f=4&t=21574

Version History

1.8

• Fixes JS error when player ship is destroyed.
• Corrected info link in manifest file.

1.7

• Removed debug message.
• Tightened the deviation angle when aligning ship with the visual effect.

1.6

• Reverted 1.5 tweaks as they didn't help. :(

1.5

• Tweaks to ensure 100% reliability when docking at an external point.

1.4

• Reduce speed message will now only be displayed if player ship is pointing at dock point.
• Warning message about not having docking clearance will now be sent when on approach to an external docking point.
• Added "realPosition" as option for creating external docks.
• Added "dockRange" to allow for docking at a greater distance from the dock point.
• Added "launchDistanceBoost" to allow for a greater launch distance.
• Call to $addExternalDock now returns the visual entity created by the routine.
• Saving and reloading your game will now restore your external dock position, allowing you to launch from that dock.

1.3

• Fixed issue where the internal array of docks was not being reset correctly when jumping to a new system.
• Added protection for when a station with external docks is destroyed.

1.2

• Reworked the interface code to use an object, rather than individual parameters.
• Reworked the code to correctly orient the player ship on launch when using an external dock.
• Added ability to easily prevent launches from the external port.

1.1

• Checking more docking status types when docking to determine if the player has actually requested to dock.
• Changed flashers to be a single invisible one, leaving it up to the station how they want to alert players to external docks.
• Moving stations can now be handled, but it is still recommended that only non-moving stations have external docks.

1.0

• Initial release.

Quick Facts

0-{{{2}}}

Version	Released	License	Features	Category	Author(s)	Feedback
1.8	2024-04-16	CC BY-NC-SA 4.0	Equipment	Misc OXPs‏‎	phkb	Oolite BB

Gameplay and Balance indicator