Docking and Vessel Type Rules (0.23.5)

[Claw]

This question of docking priorities and ship hierarchy has been floating around for a little while and came up again recently. While it may not be detrimental to the design of your ship, I've explored the docking and undocking rules and will try to document them here. They're actually pretty simple from what I've found so far. They are far less complex than the Fuel Flow rules.

Docking Parent/Child Establishment Rules (Root Vessel)

When two ships dock, the rules are evaluated in ascending order (1, 2, 3...). If a rule is invoked, then the parent/child relationship is established and the VESSEL's heirachy is established. The choice of what becomes parent/child is a matter of three layers of priority. I'm not certain of all these rules or where the thresholds are, but this is what some of my testing has shown.

Rule 1: Parent status does not depend on which vessel is "in control" and which is the "target" at the time of docking. The vessels become parent or child based on the rules below.

Rule 2: If the Vessel Types differ, parent status is assigned to the vessel with a higher priority Type.

• Type priority order from lowest to highest is: Debris, Probe, Rover, Lander, Ship, Station, Base.
  
• Easy way to remember priority order: the priority corresponds to the map filter order (buttons at top, from left to right).
  
• The Vessel Type used is whatever is currently set via the "Rename Vessel" menu.
  

Rule 3: If two Vessels are of the same type, the "larger" Vessel becomes the parent.

• The "Larger" vessel is the vessel with the highest part count.
  

Rule 4: If two Vessels are of the same type and size, the first one listed in the save file becomes the parent.

• Generally, the first vessel in the save file will be the first one launched. However, if previous docking/undocking/decoupling was performed, order in the save file is established per the undocking/decoupling rules.
  

Rule 5: The child's root part ID and vessel type is stored by the parent. The child is then shuffled and re-rooted to connect via its docking port. The child's docking port then takes on the parent vessel's docking port as it's parent.

Undocking/Decoupling Vessel Type Rules

Rule 1: If the vessels were previously two separate vessels, the child vessel reverts to its previous Name and Type, regardless of re-naming or re-Typing of the parent.

Rule 2: If the vessels have been connected since launch:

• The vessel containing the original root part is the parent vessel and retains the Parent Name and Type. (There are a few instances where the parent is renamed with [Type] appended.)
  
• The child vessel is automatically assigned a Type via the "Vessel Type at Time of Launch" rules. (Type preference is given to the highest priority vessel controller.)
  
• The child vessel is automatically assigned a Name in the form "Parent's Name" + [Type]. (If the parent is named "Ares", then a separated probe core is named "Ares Probe")
  

Rule 3: The child vessel's MET timer resets after decoupling/undocking.

Rule 4: "If Focus" shifts to the craft per the criteria below. This criteria is shaky, and sensitive to a lot of "what ifs?"

• "Control From Here" overrides all other priorities. Focus will stay with the vessel that has the "Control" part, regardless of root part or if it has a valid control ability.
  
• Any manned vessels have priority over unmanned and uncontrolled vessels. (Here, unmanned means vessels that could contain kerbals, but don't. Such as an empty Mk1 Pod.)
  
• Probe cores have priority over unmanned vessels and uncontrolled parts. Except if the Unmanned pod recently had a Kerbal in it, then it will take focus.
  
• For two craft with the same priority (such as splitting two Mk1 pods, or splitting two OKTO2 probe cores), focus stays with vessel containing the original the root part.
  

Vessel Type at time of Launch

It's probably easier to understand the Vessel Type during initial decoupling/undocking operations by exploring the rules for how KSP determines the default Type for a vessel.

Rule 1: As before, Type priority order from lowest to highest is: Debris, Probe, Rover, Lander, Ship, Station, Base. If more than one of the rules below is present, the Type is set by the highest priority controller.

Rule 2: If a vessel has no source of control, it is assigned Type = Debris.

Rule 3: If a vessel uses a probe core (or rover body) for control, it is assigned Type = Probe.

Rule 4: If a vessel uses a lander can or cupola for control, it is assigned Type = Lander.

• It doesn't matter if the crew stations are unoccupied.
  

Rule 5: If a vessel uses a command pod or cockpit for control, it is assigned Type = Ship.

• It doesn't matter if the crew stations are unoccupied.
  

- You can find and edit the default Type in each component's part.cfg file. Look for the line similar to "vesselType = Lander" and change it to the desired default type. The type name is case sensitive.

- Incidentally, the game loads a Kerbal into the first "Lander" or "Ship" that it comes to in the Vessel's hierarchy, regardless of priority.

Edited May 11, 2014 by Claw

[Captain Sierra]

A fun fact about rules 4 and 5 for vessel type is that it is defined in the .cfg and can be edited.

While the stock cupola pod reads as follows:

vesselType = Lander

Mine has been edited to read:

vesselType = Station

This makes cupolas define crafts as stations for me, given that the cupola is used almost exclusively for stations and multi-part ships in my space program.

Random tidbit over.

[Claw]

...

Random tidbit over.

Thanks, and added.

[Pecan]

Nice work Claw, and useful info Capt. :-)

[Padishar]

Good stuff. This should give me enough to be getting on with for the simulated undocking and redocking code in my mission planner. I'll let you know if I find any cases that break the rules or if the coding of the rules sheds any light on how they are probably implemented in the core game. I need to do some KSP/Unity UI research now to work out how it can actually be presented...

[Claw]

Nice work Claw, and useful info Capt. :-)

Thanks Pecan.

Good stuff. This should give me enough to be getting on with for the simulated undocking and redocking code in my mission planner. I'll let you know if I find any cases that break the rules or if the coding of the rules sheds any light on how they are probably implemented in the core game. I need to do some KSP/Unity UI research now to work out how it can actually be presented...

That would be excellent. All updated info is good info.

I've done quite a few experiments, but quite frankly they're relatively uninteresting. I'm still deciding how best to show any examples that are useful beyond simply illustrating the point.

[Padishar]

I have just posted an update to my development version of KER that includes the button in the flight engineer tweakable I mentioned in the other thread that dumps the part tree to output_log.txt. The info includes the vessel name and type and also the vesselType and initialVesselName property of every part (as well as all sorts of info important to the deltaV simulation code). I'm going to add some more info to it (showing the original root part after docking etc.) as soon as I get a bit more time...

[Bloojay]

Is this information still relevant or has it changed?

[Padishar]

There is a fairly high chance that the behaviour has changed at some point since 0.23.5 but I don't know for definite.  @Claw hasn't been around on the forum for quite a while but it should be quite easy to run tests to confirm the rules (think along the lines of rovers with docking ports to make the tests easier)...