KSP vessel lifecycle and related stuff

[S1gmoid]

Hey. I've tried to understand KSP modding by reading mod code, but I feel I've reached a local ditch and I definitely need some background knowledge to proceed further.

Mainly, what I'm looking for is an explanation of the main state machines of KSP, how a vessel gets loaded, put on rails, taken off rails, unloaded. What is preserved and what is deleted. How rails are stored and when and how can they be affected.

The tutorials I've found so far seem to be very basic... and for example right now, for the life of me I cannot make heads or tails from this (from RemoteTech2):

        private void OnVesselOnRails(Vessel v)        {
            if (v.parts.Count == 0)
            {
                RegisterProto(v);
            }
        }

WHAT?! I mean, WHAT? Why am I cheking if there are any parts? Why am I only doing something if there aren't? What does it mean if parts.Count is 0, and what if it isn't?

I'm looking for answers to this and a lot of similar questions.

[NathanKell]

Whenever a Vessel (which is a collection of Parts, each of which may have any number of PartModules) is put on rails (i.e. is no longer in the 2.5km active zone, or you go into timewarp) it's serialized to confignode and to a ProtoVessel, ProtoParts and ProtoModules. (This is similar to when it's saved to .sfs, or when the editor saves a craft to .craft, although in those cases it's just serialized, no proto-whatever hang around).

When the vessel goes off rails (or is read from disk), OnLoad is called for every module to update its status to what was saved in the confignode.

What that code is doing is checking to make sure that the serialization is complete (i.e. not just that the event fired, but that the vessel was serialized, and thus no longer has [unserialized] Parts in its Parts list, but instead has protoparts with confignodes for data storage), and if so, to register it with Remotetech as a ProtoVessel (the class used instead of Vessel when a craft goes on rails, just as Parts have ProtoPart etc).

[S1gmoid]

Wow thanks. That really explains it. So data for a vessel needs to be stored into the protovessel when it is unloaded.

Do protovessels have some kind of regular update function that is called on them, or are they just passive structures moved around until they are reloaded?

[Diazo]

Note that there seems to be 3 levels of ship existence.

Unloaded

Loaded-OnRails

Loaded-OffRails

Unloaded: This is the state ships exist in while not in the flight scene and if they are outside the 2.5km physics sphere around your active vessel while in the flight scene. While in this state vessels exist as protoVessels in the save file and do not exist as a Vessel object. (Serialized to a configNode as per NathanKell's post.)

Loaded-OnRails: While timewarp is engaged, all vessels (including the active vessel) exist in this state. While timewarp is disengaged, vessels from about 300m away to 2.5km away from the currently loaded vessel exist in this state. I believe that in this state vessels are loaded, in that the parts and partModules of a vessel exist, but physics is applied to the vessel as a single object, not each individual part. Test this however before relying on it as I'm am not 100% sure. If you tie into the GameEvent.VesselOnRails and GameEvent.VesselOffRails, you can see vessels go on and off rails, notably the debris left behind on the launchpad goes on rails when the active vessel is only about 350-400meters altitude.

Loaded-OffRails: With timewarp disengaged, the currently active vessel and all other vessels within about 300m exist in this state. Vessels in this state get full physics applied to each part and all the other bells and whistles.

As for protoVessels, I am not aware of any update function called on them. They are editable but it has to be triggered by you somehow, there is no Update() method to tie into.

D.

[DMagic]

All of the orbit information (including the OrbitDriver) in the Vessel class is still available when a vessel is not loaded. I'm pretty sure it's all loaded through the ProtoVessel instance, not the Vessel load method, but you can grab the instance of the vessel you're looking for (FlightGlobals.Vessels returns all of them) and get most of the non-part-relevant information. All of that info updates regularly, just as it would if the vessel were in physics range.

Unloaded: This is the state ships exist in while not in the flight scene and if they are outside the 2.5km physics sphere around your active vessel while in the flight scene. While in this state vessels exist as protoVessels in the save file and do not exist as a Vessel object. (Serialized to a configNode as per NathanKell's post.)

The vessel object does exist outside of physics range. ProtoVessel has a Vessel field (vesselRef) that handles everything I described above.

I track orbital parameters for unloaded vessels in my contracts, and SCANsat tracks them for updating scanning coverage; I've never used ProtoVessel for any of those functions. I do use it when I need to get at Science Data stored in ProtoPartModules though.

Edited October 21, 2014 by DMagic

[NathanKell]

Asmi's ECLSS mod is based on a (multithreaded) unloaded-vessel-update framework, so while there isn't ingame support for doing stuff to unloaded vessels, there is available a strong library to expand upon for handling tick-based unloaded vessel updates.

[S1gmoid]

Asmi's ECLSS mod is based on a (multithreaded) unloaded-vessel-update framework, so while there isn't ingame support for doing stuff to unloaded vessels, there is available a strong library to expand upon for handling tick-based unloaded vessel updates.

Thanks, that should be helpful!

There are two things I'm thinking of trying my hand at in relation to unloaded vessels. One is persisting the flight computer data from RT2 when the vessel is unloaded, and potentially create a warning when there is an upcoming event... Currently RT2 calls Dispose() on the flight computer class upon unload...

The bigger one is a "better de-orbiting" functionality that would simulate atmospheric braking on unloaded orbiting vessels.

I wanted to get rid of this piece of debris, went to great length to push it into a crash trajectory (verified with the Trajectories mod), only to watch it come straight back up from a periapsis of 40000 meters. So I decided this definitely needs some doing. I'm looking into possible codesharing with Trajectories, as I guess the logic is similar.

[NathanKell]

Sounds neat!

You might want to look into HoneyFox's Orbit Manipulator for the latter case.