Mothership and Childship Automatic Docking Scripts

So whats it do?
Pretty much what it says on the tin - your mothership and child ships can move about freely and when its time for the fleet to move on, you can call these scripts to help get things docked appropriately without having to organize it all yourself

The workshop pages have a pretty hefty description for both and the config options, but the long story short is you can set up the mothership with docks that only take ships meeting given criteria, then the child ship will send the criteria of itself to allow the mothership to dynamically pick an open and appropriate dock for the childship to dock at.

While the mothership cannot move during the docking procedure, this is not dependent in any way on your mothership staying put the whole time the child ship is undocked

How do I use it?
Please see the workshop for both scripts...I'd detail it out here too but honestly don't feel like formatting for here after the pain of doing it for steam

Ok, where are those links?
Here:
Mothership Script
Childship Script

What about a sample world?
You can find a sample world (including known issues and what is working int he description) Right here

What are you going to change on me?
If I make updates I will most likely not change config options or commands, only expand into new ones or refine how existing ones behave. In fact, I'd be making efforts specifically to avoid changing either of those.

I think it should do X.
Please let me know! I'm not opposed to expanding it, but its got all the features I've thought of (though as stated, not all tested) so its likely I won't be expanding it

I tried doing X and it didn't work.
Again, please let me know.I know its likely not fool proof yet, but I've yet to have any notable malfunctions myself. that said, I programmed it all myself in two weekends using notepad++, its not going to be perfect.

I used this in my workshop ship.
Neat. Please let me know! I don't care if you do or not, I just want to see how others might have put it to use.

I just came here to see what the config options mean.
All configuration must be pasted into the Custom Data of the blocks, no other data should be placed in the Custom Data, Custom Data config for a mothership MUST begin with “MothershipConfig:”, all options for a childship MUST begin with "ChildshipConfig:", and all options should be on their own line. Option names and values are seperated by a =.
All optional config values can be omitted entirely and will assume the default values specified below.
Fields whose type is “Freeform” may contain any characters a-z, A-Z, and 0-9.

The available options are below:
MothershipName

• Values:
  • Freeform
    > Default: None
• Notes:
  • Must match on all blocks associated with this mothership
  • Extra spaces on this line can cause problems
  • Its reccomended this is unique to all friendly motherships
• Use:
  • Motherships: This is used to identify all blocks associated with this mothership. It is also the name used by child ships to specify where to dock
  • Childships: Unused

ChildshipName

• Values:
  • Freeform
    > Default: None
• Notes:
  • Must match on all blocks associated with this childship
  • Extra spaces on this line can cause problems
  • It would be best if this is unique to all friendly childships
• Use:
  • Motherships: Unused
  • Childships: This is used to identify all blocks associated with this childship.

ShipClass

• Values:
  • Any
    > Default
  • LargeShip
  • SmallShip
• Use:
  • Motherships: This will filter ships by the grid size the dock will accept
  • Childships: Unused
• Notes:
  • Merge block docks will ignore this value and will only accept their own grid size

DockName

• Values:
  • Freeform
    > Default: *
• Use:
  • Mothership/Childship: This will serve as a “class” of docks and only requests from child ships using the same DockName for their dock will dock here. Does not have to be unique per ship

DockId

• Values:
  • Freeform
    > Default: none
• Use:
  • Mothership/Childship: This will serve as a ship-unique identifier for this dock.
• Notes:
  • For a childship this is used to specify which dock to use during the "RequestDocking,Using=" calls
  • For a mothership this is only used for the wildcard "%ThisDock%" in parameters for events

ShipSize

• Values:
  • Any
    > Default
  • Tiny
  • Small
  • Medium
  • Large
  • Massive
• Uses:
  • Motherships: This can be used to specify a dock should be only for ships of a given size. Used with ShipSizeMode to specify a minimum or maximum ship size
  • Childships: This can be used to specify a dock point should only be used for docks supporting a given ship size. If its Any, will only dock at docks for any size

ShipSizeMode

• Values:
  • Exact
    > Default
  • OrSmaller
  • OrLarger
• Uses:
  • Motherships :This can be used in with ShipSize to control its filtering behavior. Ignored if ShipSize is any
  • Childships: Unusued

DockDistance:

• Values:
  • Whole Number
    > Default: 50
  > Minimum: 10
  
• Uses:
  • Motherships: Child ships will to to this distance prior to aligning themselves for docking
  • Childships: Unused
• Notes:
  • Less than 50 is not recommended due to remote block navigation quirks
  • Distance measured is in meters straight out from the “docking face” of dock blocks

DefaultDock:

• Values:
  • true/false
    > Default: false
• Uses:
  • Motherships: Unused
  • Childships: If this is true, this dock will be used if no dock point is specified when requesting docking

RingLeader:

• Values:
  • Freeform – Another point's DockId
    > Default: None
• Uses:
  • Motherships: Unused
    
  • Childships: If set, this docking point will only be used in conjunction with the specified Dock ID and will attempt to lock when the parent does. This dock cannot be called on its own

RelatedDocks:

• Values:
  • Freeform – a | seperated list of other DockIds
    > Default: None
• Uses:
  • Motherships: Unused
  • Childships: If set, this dock will attempt to lock all Dock IDs in this list when it docks

OnDock:

• Values:
  • Freeform – a name of a programmable block on the grid
    > Default: None
• Uses:
  • Motherships: If set, will attempt to run this programmable block after a childship docks
    
  • ChildShips: If set, will attempt to run this programmable block after docking

OnDockParameters:

• Values:
  • Freeform – may use %MothershipName%, %ChildshipName%, %ThisDock%, %Action%, and %CurrentDock% to substitute in the current Mothership name, Docking childshipname, the mothership's dock name, the action name ("OnDock"), and current Dock ID
    > Default: None
• Uses:
  • Motherships: If set, this value is passed in a parameter into the OnDock block
    • MothershipName and CurrentDock are not valid wildcards for motherships
  • Childships: If set, this value is passed in a parameter into the OnDock block
    • ChildshipName and ThisDock are not valid wildcards for childships

• Notes:
  • Unlike other freeform fields, this and other paramater fields should accept any non-newline character

OnUndock:

• Values:
  • Freeform – a name of a programmable block on the grid
    > Default: None
• Uses:
  • Motherships: If set, will attempt to run this programmable block after a childship undocks
    
  • ChildShips: If set, will attempt to run this programmable block after undocking

OnUndockParameters:

• Values:
  • Freeform – may use %MothershipName%, %ChildshipName%, %ThisDock%, %Action%, and %CurrentDock% to substitute in the current Mothership name, Docking childshipname, the mothership's dock name, the action name ("OnUndock"), and current Dock ID
    > Default: None
• Uses:
  • Motherships: If set, this value is passed in a parameter into the OnUndock block
    • MothershipName and CurrentDock are not valid wildcards for motherships
  • Childships: If set, this value is passed in a parameter into the OnUndock block
    • ChildshipName and ThisDock are not valid wildcards for childships

• Notes:
  • Unlike other freeform fields, this and other paramater fields should accept any non-newline character

OnAccept:

• Values:
  • Freeform – a name of a programmable block on the grid
    > Default: None
• Uses:
  • Motherships: If set, will attempt to run this programmable block after notifying a childship it may dock
    
  • ChildShips: If set, will attempt to run this programmable block after receiving notification it may dock

OnAcceptParameters:

• Values:
  • Freeform – may use %MothershipName%, %ChildshipName%, %ThisDock%, %Action%, and %CurrentDock% to substitute in the current Mothership name, Docking childshipname, the mothership's dock name, the action name ("OnAccept"), and current Dock ID
    > Default: None
• Uses:
  • Motherships: If set, this value is passed in a parameter into the OnAccept block
    • MothershipName and CurrentDock are not valid wildcards for motherships
  • Childships: If set, this value is passed in a parameter into the OnAccept block
    • ChildshipName and ThisDock are not valid wildcards for childships

• Notes:
  • Unlike other freeform fields, this and other paramater fields should accept any non-newline character

OnAcceptDelay:

• Values:
  • Whole number >= 0
    > Default: 0
• Uses:
  • Motherships: If set, causes the mothership to pause the specified number of seconds before sending position data for the dock its accepted the child at.
  • Childships: Unused
• Notes:
  • If you are going to move your dock using OnAccept (such as a pop out dock) it is very important this delay be at least as long as the movement takes.

LeftOffset/RightOffset/UpOffset/DownOffset:

• Values:
  • Whole number
    > Default: 0
• Uses:
  • Motherships: If set, causes any child ship docking at this dock to offset itself the specified number of meters relative to the up/down/left/right sides of the during initial autopilot phase
    
  • Childships: Unused
• Notes:
  • Child ships will attempt to align themselves along the left/right axis, then the up/down axis.
  • Keep in mind you'll need some clearance for the autopilot to work

BackupDock:

• Values:
  • Freeform - Must be a DockId of another dock on this ship
• Uses:
  • Motherships: Unused
  • Childships: If this dock is called and rejected by a mothership, the request will be retried with the dock matching this ID
• Notes:
  • You can create an infinite request loop with this. Be careful about that.

PassThroughBlockName:

• Values:
  • Freeform - Must be the name of a programmable block on this ship
    > Default: None
• Uses:
  • Motherships: If an argument not valid for this programmable block is received, its automatically passed onto the programmable block with this name
    
  • Childships: If an argument not valid for this programmable block is received, its automatically passed onto the programmable block with this name
• Notes:
  • This is just to make it so you can pass through messages from antenna

Edit: Added sample world 2/19
Edit 2: Updated Sample world URL - Steam would not let me update the prior one
Fixed a few small issues
Edit 3: World and scripts updated 2/19 per suggestions/feedback in thread
Edit 4: Big giant update to move config descriptions here. They're too long for steam's workshop
Edit 5: Added new config options: OnDock/OnDockParameters/OnAcceptDelay/RightOffset/LeftOffset/UpOffset/DownOffset for motherships, OnUndock/OnUndockParameters/OnAccept/OnAcceptParameters to both motherships and childships
Edit 6: The save cycle has been added and config options are updated so parameters for event calls should accept any characters
Edit 7: 3/25: The scripts have been updated so they can detect if they need to leave thier timer block running or not to improve performance This DOES require additional config see script patch notes and descriptions
Edit 8: 4/14: The scripts have been updated to function properly with a timer using a one second delay as well as to pass through unrecognized messages
Edit 9: 11/26: The scripts have been updated to leverage the auto updating API - that means timer blocks are no longer required. Current implementation ignores any timer block names and always updates at 1 tick. It seems to be performing well on my rig, but if I get complaints I'll implement 10 and 100 tick update options let me know!
Edit 10: 11/27: Clarified the %action% wildcard

 

Do you have example ships we can test and see the setup done 'correctly'?

 

Thats a very good point/suggestion. I do not currently, but I'll work on it. I'd release my test world but its full of...lets say failures where the ship stopping distance was incorrect for a bit, and I can purpose build some better ships than the ones I was using for this.

 

Added a sample world. Right now it'll show config and unfortunately some of the bugs I'm working on fixing (using this world as a test bed). The workshop description includes whats working and known issues.

 

So I loaded the world and went through a few things. I also went through some of the code.

1. The weldership is locked, but not connected to the connector on the 'mothership' on world load. Taking control of the ship and flying it a short distance away and then it tries to fly back. But if I fly further away, it turns 180 and keeps flying AWAY from the connector.

2. Connectors "Lock" != connected. The "Lock" means that there is magnetic lock. This is different from being 'connected' Your code assumes that 'locked' is the same for landing gears, merge blocks and connectors. It's not. Fortunately, the new status names things in a clearer way.

Example: Mothership line 217:

Code:

		} else if (dType == DockType.Connector) {
			IMyShipConnector conn = (IMyShipConnector) dockBlock;
217			locked = conn.IsLocked;

For connected, you want to use: locked=conn.Status == MyShipConnectorStatus.Connected;

There is also: MyShipConnectorStatus.Connectable (the old 'Locked") and MyShipConnectorStatus.Unconnected

Child script has the exact same code, but at line 752 but it correctly uses the (obsolete) conn.IsConnected. At line 866 there is code like above (from motherhsip)

3. World description on Steam has a line that says

• • Keen hasn't whitelisted the proper way to get the lock state of landing gear and connectors yet, so you always get a warning using the script

This is not correct. use the status values listed above.
For landing gears, the status enums are:

Code:

LandingGearMode.Locked
LandingGearMode.ReadyToLock
LandingGearMode.Unlocked

4. The antenna range on the welder ship is kinda low (500m), so if it's out of range, it cannot transmit messages to the motherhsip.

5. Pressing '1' on the command bar causes the.. test ship.. to (almost) land using landing gear. But the weldership does not move.

6. Sending the argument "RequestDocking" (saved as default argument on the PB) on the weldership displays the message "Docking Request Rejected"

This is the sequence of messages sent/received:

Code:

MothershipRequest,MothershipName=MainBase,RequestorName=WelderShip,Type=MergeBlock,DockName=WelderMerge,ShipSize=Tiny,ShipClass=SmallShip
MothershipResponse,MothershipName=MainBase,RequestorName=WelderShip,Status=REJECTED

I assume that the request is being rejected because the mothership does not have a compatible merge block. But the child does not then ask for a connector dock.

Well, that's enough for now..

 

First off, thank you for the feedback.

Alright now in order:
1. There is an issue where it left its thruster override on, I'll add that to the issue list. I also need to add a way for it to tell if its already docked at a mothership if the programmable block is recompiled. Thanks for pointing it out

2. Hm I thought I tried that and got a prohibited message. Guess it was just on landing gear then, I must never tried it on connectors.

3. I'd tried using that (And I'll leave it in commented out for now) - However I do get a message stating "Error: The type or member 'LandingGearMode.ReadyToLock' is prohibited." Its actually a post by you that I discovered I wasn't doing it wrong, it was just currently broken.

4. Yeah for demonstration purposes I should crank that up.

5 and 6. This is due to the request to get children using the default dock (The one in the PB, which was a bad choice to leave in a sample world, as well as all requests from motherships to try to get child ships). I think I need to come up with a way to "rank" docks by preference so rejection leads to trying other docks instead of stopped at your first choice.


I did just upload an update but I'll push #2 and #3, and see about cleaning up the world a bit for #1 and #4 - Hopefully steam lets me update the world instead of having to create a new one with the same name again.

#5 and #6 I'm going to have to think about a bit. It might end up being "If you don't specify a dock id you're going to get whatever one your ship finds works first," but that feels too unpredictable. Maybe I'll throw in an option to do requests by dock class as well.

Edit: A closing " was missed

 

Alright so 5 was due both to what you pointed out in #6 and an issue with the Mothership script. The sample world and both scripts have been updated - the WelderShip uses the new "BackupDock" config option to retry the request with the "RearConnector" now

 

if you search for a test ships for your script. here i have an option for you https://steamcommunity.com/sharedfiles/filedetails/?id=433426873
at the moment i am working on a rebuilt version of modern vanilla techs, but the original is still working.

 

Another sizable update for cancelling docking requests, a bunch of event handlers, and some offset options. Tested this out in gravity a bit too, and it seems to work

I need to figure out exactly what to persist in the save cycle and after that I think this is complete barring any issues or feedback.

 

Alright so this should be "complete" barring any bugs. Any feedback or reports of issues are welcome

 

Could you consider expanding this with an additional escort script?
Off the top of my head, helpful features would include: keeping the escort in antenna range, based on actual antenna range minus a safety buffer; autopilot pathing of the escort avoiding the mothership's forward vector; randomized waypoints within acceptable range to generate a randomized escort pattern.
As I understand, it would be difficult to use fixed weapons for this kind of project. I humbly suggest focusing first efforts around turret drones.

 

So you'd be looking for synchronized movement more or less? With the "mothership" having a number of drones staying within a fixed sphere of influence, but clear of the current direction of movement?

 

Does this work on planets?

 

It has been tested in natural gravity up to 0.3g. As long as there's enough thrust on the ships, however, there's no reason it shouldn't work in any gravity.

If you use it in gravity and it doesn't work, please let me know. Really the only reason I didn't test it in higher gravity is due to being too lazy to make a new test ship that could fly in higher gravity, and 0.3g being about the max test ships I had handy could deal with.

 

Ill try it out sometime

 

Precisely.

 

Some updates for performance - who wants timer blocks always beeping at them anyways?

 

Added pass through functionality and made use of the timer exploit optional

 

This is an awesome pair of scripts. I had started working out a similar, but far more basic, script using AI waypoints but those are horribly imprecise.

The one thing I had to modify was FetchAntenna so that it can handle disabled antennas (e.g. backup or emergency antennas).

Code:

public void FetchAntenna ()
{
  if (antenna == null) {
    List<IMyTerminalBlock> antennas = new List<IMyTerminalBlock>();
    GridTerminalSystem.GetBlocksOfType<IMyRadioAntenna>(antennas);
    foreach(var ant in antennas) {
      if((ant as IMyFunctionalBlock).Enabled) {
        antenna = ant as IMyRadioAntenna;
        break;
      }
    }
  }
}

It may also be worth noting in the description that we should not have multiple active antennas sending the same messages to the PB (something I accidentally did while trying to figure out why my docking requests were timing out). Obviously you get two (or however many antennas you have configured) requests and that's not great, but it also means that somehow responses are never sent, eventually leading to request to time out.

 

Thanks for the feedback!

You're definitely right, that is a weak point in them I hadn't considered, great catch.

It is a bit odd it times out doing that though, I'd almost expect two responses to go out (one for a OK and one for a no docks available/OK for a different dock). I'll have to build something and test it out. Not sure if its a game limitation or something I'm doing.

Hopefully as the end of summer draws near I'll get time to make a config script too that'll help do a lot of the initial setup.

 

For those of you that pay attention here but not to the workshop, this has been updated!

Nothing major here (In fact I didn't even put in cameroon's fix yet) but now that my life isn't total insanity, I at least updated the scripts to no longer make any use of timer blocks and instead leverage the new in game API for updating programmable blocks automatically every tick.

Testing with 4-6 ships running on my machine didn't show any ill effects, if you see some, please let me know and I'll implement a 10 tick and 100 tick option.

 

Hey where to change the Tick ourself? Is it in line 60 of childship script?

Man i love you for sharing this. I hope some guy makes a huge well described tutorial for all of this <3

 

Code:

Runtime.UpdateFrequency = UpdateFrequency.Update1;

That line, at 1342, is where the tick frequency is located, however reading documentation there's going to be a bit more fiddling I have to do to ensure calculations are done right when using update10 and update100 as its not garenteed something will run every 10 or 100 ticks when using those. Unfortunately as this script does a lot of calculations based on velocity and acceleration, knowing how long as elapsed in game between runs is a must have, so I'll have to be careful. Its very very likely if you change that in its current state ships will ram one another pretty spectacularly

Are you experiencing lag when docking ships due to the current setting? If so I'll prioritize it and try to get it out this weekend.

That said if this is coded correctly (And I know the jerk that made it, thats an if for sure) this SHOULD at least only keep itself ticking away while its docking or has tasks queued up for when it undocks.



Actually that gives me an idea. Even if while docking we need a tick rate of 1, while queuing up for later actions we can probably deal with the 10 or maybe even 100. That should be very easy to manage if nothing else.

I know thats a big thing on my to do list too, I'm not really proficient with videos, and I document like a java coder (you'll never guess why that is). Still, needs to be done.

 

Hello I encountered some problem when using Landing-Gears. I wanted to control a bridge + sound when requesting, docking and undocking. So i tried first with the sound which already showed me it isn't working. When requesting, it works as it should, but it ignores docking and undocking with landinggears.


My Lift/Bridge/Sound-Controller called LiftController code:

Code:

public void Main(string argument)
{
  IMySoundBlock sb = (IMySoundBlock) GridTerminalSystem.GetBlockWithName("LiftSb");

  if("OnDock".Equals(argument))
  {	
  	sb.GetActionWithName("PlaySound").Apply(sb);
  }

  else if ("OnUndock".Equals(argument) || "OnAccept".Equals(argument))
  {
  	sb.GetActionWithName("PlaySound").Apply(sb);
  }
}

Sensors Custom Data:

Code:

MothershipConfig:
MothershipName=MainBase
ShipClass=LargeShip
DockName=WagiShuttleDock
DockDistance=75
OnDock=LiftController
OnUndock=LiftController
OnAccept=LiftController
OnDockParameters=%Action%
OnUndockParameters=%Action%
OnAcceptParameters=%Action%

EDIT:
Another Problem.

Following scenario on example map. Fly with the shuttle to the Secondary Base, back to main and again to secondary base. Next time it tries to fly to the mainbase, it rejects the request.

It seems to be since use without timers. Bc when i Reinitialize the PB from Main base with or without timer it will work like a charm - But when using a timer i run in some other problems, for example the ToolShip does not turn off the autopilot when it's in fron from the hangar. When i deactivate it manually, it will continue.



Greez

 

Actually the example map had an issue, I did not set up the sensor to detect large/small ships and nothing else where the shuttle lands.

Can you verify your landing gear sensor on the mothership is set up to detect large/small ships and only large/small ships? What you're describing does match up with what happens when I forget to do that.

 

Thanks this was the issue.

But whats going wrong with the shuttle? When traveling some times one of the bases will reject the request ad it stops. Have done some other bases and my own shuttle which works fine.

 

That was the shuttle's problem too - it would dock, but the mothership would never acknowledge it did, so when it requested docking at the mothership again it had no available docks.

It flows kind of like this:
1. Request to mothership comes in, it finds a dock, and marks it as in progress
a. While its in progress or docked, it will NEVER allow something else to dock there

2. When the docking is complete, it marks it as not in progress but docked
b. This was never happening as its dependent on the sensor on the landing gear style docks

3. Docking is requested for a dock thats in progress, it gets rejected due to 2b

I wonder if I can change sensor settings automatically when it detects its used for a dock...

 

is there something i can type in config so the ship will land align left without rotate the RC-Block?