External Docking System

Discussion and information relevant to creating special missions, new ships, skins etc.

Moderators: winston, another_commander

User avatar
phkb
Impressively Grand Sub-Admiral
Impressively Grand Sub-Admiral
Posts: 4830
Joined: Tue Jan 21, 2014 10:37 pm
Location: Writing more OXPs, because the world needs more OXPs.

External Docking System

Post by phkb »

The discussion here led to the creation of this new utility, the External docking system.

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 external port they landed at.

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.

Code: Select all

	var eds = worldScripts.ExternalDockSystem;
	eds.$addExternalDock({
        station:my_station, 
        position:[2400, 0, 0], 
        preDockCallback:this.$preDockSetup.bind(this), 
        preDockCallback:this.$postDockSetup.bind(this)
    });
The structure of the object passed to the function call is as follows:

Code: Select all

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

Re: changing the size of the docking port. 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.

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

You can download the mod from here: ExternalDockingSystem.oxz or from the manager.
User avatar
phkb
Impressively Grand Sub-Admiral
Impressively Grand Sub-Admiral
Posts: 4830
Joined: Tue Jan 21, 2014 10:37 pm
Location: Writing more OXPs, because the world needs more OXPs.

Re: External Docking System

Post by phkb »

I discovered there was an issue with launching from an external docking port, so version 1.2 is now out. You'll also need to grab the updated Nuit, Space Bar Face Lift, and Extra Rock Hermits packs, if you're using any of them.
User avatar
Cholmondely
Archivist
Archivist
Posts: 5364
Joined: Tue Jul 07, 2020 11:00 am
Location: The Delightful Domains of His Most Britannic Majesty (industrial? agricultural? mainly anything?)
Contact:

Re: External Docking System

Post by Cholmondely »

phkb wrote: Sat Feb 03, 2024 2:37 pm
I discovered there was an issue with launching from an external docking port, so version 1.2 is now out. You'll also need to grab the updated Nuit, Space Bar Face Lift, and Extra Rock Hermits packs, if you're using any of them.
Question:

In the case of eternally docked ships and an on-coming disaster - can those ships physically leave their docks and try to flee?

Thinking of novae/massive pirate attacks/massive Thargoid attacks/invading Montanan armadas/onslaughts of Witchspace Lobster devotees, etc.



And do you wish me to cobble together a wiki page for you to nobble? Or are you happier doing it yourself?
Comments wanted:
Missing OXPs? What do you think is missing?
Lore: The economics of ship building How many built for Aronar?
Lore: The Space Traders Flight Training Manual: Cowell & MgRath Do you agree with Redspear?
User avatar
phkb
Impressively Grand Sub-Admiral
Impressively Grand Sub-Admiral
Posts: 4830
Joined: Tue Jan 21, 2014 10:37 pm
Location: Writing more OXPs, because the world needs more OXPs.

Re: External Docking System

Post by phkb »

Cholmondely wrote: Sat Feb 03, 2024 6:44 pm

In the case of eternally docked ships and an on-coming disaster - can those ships physically leave their docks and try to flee?
At the moment, no. The simulated docked ships are subEntities of the station, so they can’t leave on their own. That said, a departure could be simulated just by removing the subEntitiy and creating a new ship at the same location.

For the wiki, I’ll hopefully be able to set all the new pages up later today.
User avatar
phkb
Impressively Grand Sub-Admiral
Impressively Grand Sub-Admiral
Posts: 4830
Joined: Tue Jan 21, 2014 10:37 pm
Location: Writing more OXPs, because the world needs more OXPs.

Re: External Docking System

Post by phkb »

Bug fix release 1.3 is out now. This fixes an issue where jumping from one system that has some external docks defined, to another system that has some external docks, would not reset everything correctly. Should all be sweet now, though.
User avatar
MrFlibble
---- E L I T E ----
---- E L I T E ----
Posts: 324
Joined: Sun Feb 18, 2024 12:13 pm

Re: External Docking System

Post by MrFlibble »

Is it possible to tweak existing OXP ships (e.g. D.T.T. War Lance) to allow them to use external docking?

Currently I just bounce off space bar external docking ports. I switched ships to something standard and it all works as expected,


After testing with a different ship, my previous save with the War Lance can now use external docks where it previously bounced off. Not sure if something 'trips' into proper behaviour only when a normal ship is used, but I don't think I was even prompted to slow down before I tried with a 'normal' ship.
User avatar
phkb
Impressively Grand Sub-Admiral
Impressively Grand Sub-Admiral
Posts: 4830
Joined: Tue Jan 21, 2014 10:37 pm
Location: Writing more OXPs, because the world needs more OXPs.

Re: External Docking System

Post by phkb »

MrFlibble wrote: Fri Mar 29, 2024 4:09 pm
After testing with a different ship, my previous save with the War Lance can now use external docks where it previously bounced off. Not sure if something 'trips' into proper behaviour only when a normal ship is used, but I don't think I was even prompted to slow down before I tried with a 'normal' ship.
That’s… super weird. The external docks aren’t restricted by ship type. It’s based purely on distance, ie how close you are to the docking point, and how fast you’re going. If you’re going more than 100m/s it won’t trigger.

If you weren’t getting the “please slow to 100m/s” messages, that could mean the external docks weren’t getting set up properly. It would be handy to see if there was anything in the logs for those instances, but by the sound of it you’ve run a few sessions since then and the logs won’t show anything. If it happens again, it would be great to see the log and any info it might contain (errors especially).
User avatar
MrFlibble
---- E L I T E ----
---- E L I T E ----
Posts: 324
Joined: Sun Feb 18, 2024 12:13 pm

Re: External Docking System

Post by MrFlibble »

phkb wrote: Sat Mar 30, 2024 12:22 am
It would be handy to see if there was anything in the logs for those instances, but by the sound of it you’ve run a few sessions since then and the logs won’t show anything.
I'd tried quite a few times over the last couple of weeks before switching ships today, bouncing off the docking ports gently enough to 'just' bounce with no damage before resorting to normal docking. I don't recall seeing anything in the logs, and I'm reasonably sure I was curious enough to look.

I'll attempt to reproduce this later/tomorrow by setting it all up on another computer on my bench, with a previous save in place before I add the EDS OXP. If the oddness occurs, I'll grab logs, and tarball the whole shebang before switching ships, so I can diff for what might have changed outside of save files.
User avatar
MrFlibble
---- E L I T E ----
---- E L I T E ----
Posts: 324
Joined: Sun Feb 18, 2024 12:13 pm

Re: External Docking System

Post by MrFlibble »

Couldn't make it happen quite the same on the bench machine.

I had one failure to external dock (with no prompts) at the first space bar I found after installing the OXP. Docked at main, saved, quit, then reloaded and then docked fine at the same external dock, complete with "slow to < 100m/s" prompts. Nothing obvious in the logs, and no obviously relevant diff in the plists.

I tried removing the OXP, load/save, re-add, load, dock, all good. So once it's in, it's fine. It was just the first run that failed for the test setup, and not trivially repeatable.

Must have been something subtle on my laptop which had caused the failure to repeat past the first save.
User avatar
MrFlibble
---- E L I T E ----
---- E L I T E ----
Posts: 324
Joined: Sun Feb 18, 2024 12:13 pm

Re: External Docking System

Post by MrFlibble »

I just blew myself up on the same Space Bar three times.

On approach, the hail from the Space Bar (Lobbie's Can-Can Lounge, Sotique in G1) wasthis:
Our external dock is available after requesting clearance, and can be used if there is delay at the main dock.
Okay, so as soon as I can, I hit Shift-L to ask for landing permission. The reply is this or another similar variant:
Docking clearance not required.
If I believe that. I will not be prompted to reduce speed, and will bounce, or crash.

If I get a lot closer, before hitting Shift-L, and I'm VERY VERY LUCKY I get this:
Come on in, Commander!
Prompts to slow etc. and external docking is fine.

I do not always get the latter case. If I don't get "Come on in", I will not be able to external dock. If I persist, I may be able to get a "Come on in" after several "Not required". Getting that does not guarantee landing will work.

Sometimes, seemingly at random, even without doing clearance, I get "slow to <100" and all works as expected.

I've uploaded screencasts of a fail and a win. The link is valid for a month. The win was had by asking for clearance more than once and you can clearly see the "slow to <100". https://ufile.io/f/mkluo

A minor niggle. Aiming at the normal docking port (to re-dock) I get prompted to slow to <100m/s, which seems a bit unnecessary. I can fly in at whatever speed I like.

Nothing of note in the logs.
User avatar
phkb
Impressively Grand Sub-Admiral
Impressively Grand Sub-Admiral
Posts: 4830
Joined: Tue Jan 21, 2014 10:37 pm
Location: Writing more OXPs, because the world needs more OXPs.

Re: External Docking System

Post by phkb »

The mystery deepens. In the Space Bar facelift, I put in descriptions text to the effect of "You need docking clearance for the external port". That was because, when I checked in my game, the Space Bar had "requiresDockingClearance" set to true. But! Space Bars don't normally have the docking clearance protocol turned on. They should be a "dock at any time" station. So, something on my rig is flipping this switch to true.

It's not the whole reason (because you can still dock even without clearance, you just get fined), but it reveals there are things going on...

Of course, given my track record at this sort of thing, it's probably something I've done myself and promptly forgot all about it. Especially given the number of OXP's I'm running! Shooting self in foot - can do!
User avatar
phkb
Impressively Grand Sub-Admiral
Impressively Grand Sub-Admiral
Posts: 4830
Joined: Tue Jan 21, 2014 10:37 pm
Location: Writing more OXPs, because the world needs more OXPs.

Re: External Docking System

Post by phkb »

OK, I think I worked out the docking request issue.

If you have the "Docking Clearance Protocol" turned on, then any station that doesn't explicitly have "requires_docking_clearance = no;" in their shipdata, will have it turned on by default.

So, one question answered. On to the deeper question: why does it sometimes not work.
MrFlibble wrote: Wed Apr 03, 2024 7:30 pm
I've uploaded screencasts of a fail and a win.
I downloaded both of those, but wasn't able to view either of them. None of my Windows 11 apps will open them. Are they a particular format? I know the extension is MP4, but I guess that could mean a lot of things? Maybe?
User avatar
phkb
Impressively Grand Sub-Admiral
Impressively Grand Sub-Admiral
Posts: 4830
Joined: Tue Jan 21, 2014 10:37 pm
Location: Writing more OXPs, because the world needs more OXPs.

Re: External Docking System

Post by phkb »

Can I get you to try these:
ExternalDockingSystem_1.4.oxz
SPaceBarFacelift_1.5.oxz

You'll need to manually install these. I'd like to confirm they fix the issue before putting in the manager.

When you next give it a go, after loading your game (or jumping into a Anarchy system, if your save game isn't already in an Anarchy) check the log file for the message "adding external doc for " followed by some details about the spacebar. If you don't see that message, that tells me something.
User avatar
MrFlibble
---- E L I T E ----
---- E L I T E ----
Posts: 324
Joined: Sun Feb 18, 2024 12:13 pm

Re: External Docking System

Post by MrFlibble »

phkb wrote: Thu Apr 04, 2024 2:51 am
OK, I think I worked out the docking request issue.

If you have the "Docking Clearance Protocol" turned on, then any station that doesn't explicitly have "requires_docking_clearance = no;" in their shipdata, will have it turned on by default.
I have that set to "off" in overall game options. I should have checked/mentioned that. I notice that despite that setting, some of the more exotic stations (WildShips Kyota stations) fine me 5000 credits if I don't ask for clearance.
phkb wrote: Thu Apr 04, 2024 2:51 am
I downloaded both of those, but wasn't able to view either of them. None of my Windows 11 apps will open them. Are they a particular format? I know the extension is MP4, but I guess that could mean a lot of things? Maybe?
Odd. They're H264-MPEG4 AVC (part 10). They play fine (for me) in VLC, which is the only obvious cross-platform player I have to hand. Maybe windoze cares too much about the suffix, and might prefer m4v or somesuch. Back when I occasionally dabbled with windoze, I used to just drag and drop on VLC to avoid the 'care' about suffix 'correctness'.
phkb wrote: Thu Apr 04, 2024 4:32 am
Can I get you to try these:
ExternalDockingSystem_1.4.oxz
SPaceBarFacelift_1.5.oxz

You'll need to manually install these. I'd like to confirm they fix the issue before putting in the manager.

When you next give it a go, after loading your game (or jumping into a Anarchy system, if your save game isn't already in an Anarchy) check the log file for the message "adding external doc for " followed by some details about the spacebar. If you don't see that message, that tells me something.
On it now!
User avatar
MrFlibble
---- E L I T E ----
---- E L I T E ----
Posts: 324
Joined: Sun Feb 18, 2024 12:13 pm

Re: External Docking System

Post by MrFlibble »

phkb wrote: Thu Apr 04, 2024 4:32 am
... check the log file for the message "adding external doc for " followed by some details about the spacebar. If you don't see that message, that tells me something.
I have a save in flight near the station, but to avoid possible oddness, I tried flying in more conventionally from a station two planets away.

10:57:30.856 [SpaceBarFaceLift]: adding external doc for [Station "A Seedy Space Bar" "A Seedy Space Bar" position: (48509, 9524, 301165) scanClass: CLASS_STATION status: STATUS_IN_FLIGHT]

Apart from the timestamp, that's always the same.

First attempt, I was told I could dock any time, did not ask for permission. Bounced once. Blew up. Did not get '<100' thing.
Second attempt, I asked for clearance, was told "We do not require docking clearance, Commander. Feel free to dock at any time". Got the '<100', and docked fine.
Third attempt, didn't ask for clearance, got the '<!00' message when really close. Docked ok.
Fourth attempt, didn't ask for clearance, no '<100', Hit the space bar! (How apt.)
Fifth. Got really close, no '<100'. Asked for docking clearance. Got "We do not require". Still no '<100'. Hit Shift-L again. Got "not required". Flew away a bit, came back, still no '<100'. Kept asking until I got a "Come on in, Commander.", and bounced off again at speed '2'. Looks like this attempt is doomed to fail. Did a conventional dock. Departed, flew back towards the ext dock, got the '<100'. I flew into the station at speed just for giggles.

From that, it all seems a bit random.
Post Reply