[Info/Help] Docking/undocking logic and my attempt to find a way to force a docked ship to go into storage

[TelluriumCrystal]

I've been doing some digging in the XML files to try and learn how docking, storage, retrieval, and undocking of ships is handled. My ultimate goal here is to find a way to get a ship that is docked somewhere to be moved into internal storage on command.

What I've determined so far is that order.dock.xml handles docking ships and move.undock.xml handles undocking. Docking is done by calling request_docking to choose and lock in a docking pad for the ship, and once the ship is in position dock is called to actually dock the ship. Similarly, undocking is done by calling request_undocking to move the ship to a docking pad or launch tube if not already there, then calling undock to actually undock. So docking looks like this:

Code: Select all

<!-- a bunch of logic to check if the ship is able to dock with the target -->
<request_docking ship="$thisship" container="$destination" requirebuilding="$building" requiretrading="$trading" allowplayeronly="$allowplayeronly" ventureronly="$ventureplatform" ventureplatform="$ventureplatform" queuedresult="$queuedresult" grantedresult="$grantedresult" />
<!-- a bunch of logic to get the ship onto the docking pad -->
<dock ship="$thisship" />

And undocking like this:

Code: Select all

<request_undocking ship="$thisship" queuedresult="$queuedresult" grantedresult="$grantedresult" highpriority="false"/>
<undock ship="$thisship" />
<!-- a bunch of logic to get the ship clear of the docking pad and ship/station -->

Note also that if my interpretation is correct, launch tubes are specified using the "highpriority" field for undocking, so if that is true then the undocking request will be for one of the launch tubes.

The key takeaway from this is that nowhere in the XML files is it mentioned how to get a ship that is currently docked to go into storage. There seem to be a hardcoded queues for docking and undocking, and the request_docking and request_undocking commands themselves place ships into these queues. Some internal logic then determines if ships need to be stored to let incoming ships dock or where currently stored ships may be retrieved for undocking. Therefore it seems as if there is no way to directly order a ship to be stored or retrieved using XML (although calling request_undocking without calling undock might retrieve a ship, but it could go to either a launch tube or a docking pad).

I did, however, discover in common.xsd a command called request_retrieval, which is supposed to retrieve a ship from storage. Strangely, this command is not used anywhere in any of the existing scripts. Unfortunately, there is no corresponding command for putting a ship into storage.

So therefore my conclusion is that the only way to force a ship to go into storage is to get enough queued docking requests such that all pads are required for docking. This will cause the internal logic to bring any currently docked ships into internal storage. My initial thought for achieving this is to just spawn a bunch of ships some obscene distance from the sector center, make them request docking on the ship/station I want to store ships, and then cancel the docking request and despawn them. Not exactly an elegant solution.

I'm pretty new to modding X games though, and this is actually my first time looking at the XML files, so I would appreciate thoughts on this from more experienced members of the community.

[photoncody]

Hey OP,

You might try looking in the logic for the defence drones for a carrier/big ship. For some reason, those go into storage immediately when they dock.

I'm not a modder myself, just wanting to throw out a helpful suggestion that may point you in the right direction

Thanks for working on a way on this!

[TelluriumCrystal]

Yeah I was thinking the same thing, here's what I've found out so far looking at drones.

I decided to look at mining drones first, which are launched during mining operations to pick up ore for capital mining vessels. It took a bit of digging, but it looks like the actual capital mining script is mining.collect.ship.capital.xml, and the code that handles launching drones is as follows:

Code: Select all

<launch_drone name="$drone" object="this.ship" category="unitcategory.orecollector" exact="1"/>
<do_if value="$drone.isoperational">
    <debug_text text="'%1 drone launched [pickup count: %2, asteroid count: %3 (%4)]'.[player.age, $pickup.count, $asteroids.count, ($asteroidhull)L]" chance="$debugchance"/>
    <start_script name="'mining.collect.drone'" object="$drone.pilot">
        <param name="homebase" value="this.ship" />
        <param name="target" value="$pickuptarget"/>
    </start_script>
    <set_owner object="$pickuptarget" faction="this.ship.owner"/>
    <!-- command action waiting drone -->
    <set_command_action commandaction="commandaction.waitingdrones" />
</do_if>

Which basically runs the launch_drone command, checks if a drone was actually created, and if so has the drone run the mining.collect.drone.xml script. Looking at the mining drone script, the very first command is, you guessed it:

Code: Select all

<run_script name="'move.undock'"/>

So my guess is that the launch_drone command "spawns" a drone in the ship's internal hangar storage and then has the drone use the same undocking process a ship does. More importantly, however, is what happens when a drone lands. In mining.collect.drone.xml the last script called is order.dock.xml. This is what I looked at in the initial post, and I didn't see anything there that handled a special case for drones. However, assuming that order.dock.xml completed successfully focus should return to mining.collect.drone.xml. There doesn't seem to be anything that happens after executing order.dock.xml besides handling cases where the drone failed to dock. Ok, so eventually focus should return to mining.collect.ship.capital.xml, but there's nothing on drones after they dock there either. There are a couple of lines near the end of order.mining.collect.ship.xml that executes lib.recall.subordinates.xml and waits for it to complete to recall any drones once the ship's cargo hold is full, but that just ends up executing order.dock.xml for each drone. So nowhere in the entire chain of mining scripts is there any command given to a drone after it has docked.

While sifting through mining.collect.drone.xml I discovered this comment near the end:

Code: Select all

<!-- drone no longer exists if the drone docked successfully -->

So considering that comment and all the above, I am fairly certain that there is some hardcoded logic that immediately stores any drones that land on a pad. Nowhere in the XML is this logic exposed, so if a drone docks with anything it will immediately get stored and then despawned. There seems to be no way to leverage the drone docking behavior to get normal ships to be stored upon docking. Not to mention it might undesirable to use this system for storing ships, as the drone is definitely spawned/despawned as a part of this process and that happening to a ship would probably break something.

I'm going to look at the scripts handling the other drone types but I suspect they all behave the same way.