Any doco on the .craft file format?

[markjustmark]

Hi all,

I'm mucking about with a script to write a sub-assembly .craft file so I can auto build an asparagus staged bunch of rockets of arbitrary size.

Has anyone documented the .craft file format? My googling has not given me anything useful.

What I have so far

* the .craft file is a serialised file of heirarchical data

* the main chunk is the PART which can contain EVENTS, ACTIONS, and MODULES

* "part" is the unique name of the part, made up of the name from the appropriate part.cfg file plus a 32 bit unsigned number that starts near 4,294,967,295 (0xFFFFFFFF) and decreases by a random amount for each part

* "pos" is the position coordinates in metres

* "istg" is the inverse staging number (highest number triggers first)

* "link" connects the PARTs with one one-way linked lists starting from the root PART and working outwards and downwards (usually) (no cycles, no two-way links)

* "sym" is an n-way linked list with all the other PARTs that share symmetry with this part. All parts that share symmetry have a "sym" link to every other PART in that symmetry share.

* "attN" is a link which includes a designation of "top" or "bottom" to the PART stacked on the top or bottom of this PART. The stacked part has a corresponding attN link with "bottom" or "top" respectively

* "srfN" is a link to the PART that this PART is surface attached to (including a "srfAttch" designation)

What I'm not so sure about

* "rot" is the rotation of each part expressed as 4 components of a unit vector. I've been putting the x and z components of a unit vector pointing from one PART to its attached buddy in the 2nd and 4th components of this entry, and it seems to work out correctly most of the time.

* "dstg" - something to do with staging...

* "sidx" - some sort of index

* "sqor" - simplified quality of rockets?

* "attm" - something to do with attaching something

Any hints?

Mark

[markjustmark]

I think I've made a bit more progress.

* "sidx" is the symmetry index, starting at 0 for the first symmetrically placed part and going up to n-1 for each part in the n-way symmetry. Interestingly, in my test of just a central fuel tank surrounded by radial decouplers connected to an outer layer of fuel tanks, only the decouplers had sidx numbers, even though outer tanks had sym links with each other as well. The outer tanks were all sidx = 0.

* "rot" looks to be a unit vector at HALF the angle that the part is rotated to. (Unity engine weirdness? Someone using pi/360 instead of 2pi/360 to convert between degrees and radians?) I've only done rotations in 2D at this stage (x/z plane) and can confirm that the 2nd element of the rot vector is the x component and the 4th is the z.

Mark

[NathanKell]

You sure rot isn't a quaternion? Rotations are usually stored as quaternions in Unity/KSP. They're four-component and normalized.

[markjustmark]

Yes, rot is a quaternion.

I just read the wikipedia article on quaternions, then my brain fell out.

Then I read the Unity doco about quaternions, and that said it is a vector [x,y,z,w] and "Don't modify this directly unless you know quaternions inside out."

Then I read a bunch of other articles about calculating to/from rotations and quaternions.

Then I remembered that I'm only working in 2D for the decouplers and tanks of my auto asparagus stager, so I can fudge it.

(But I will probably have to work it out when I start connecting struts and fuel lines...)

Mark

So, I'm going to fudge it

[Ryeesa]

* "istg" is the inverse staging number (highest number triggers first)

* "dstg" - something to do with staging...

it appears you are correct with istg

the way it looks to me is:

istg : the stage in which part is activated (the orange stage groups on the side of your screen)

dstg: the stage in which the part is attached in relation to decouplers; decouplers appear to get there own stage so the object attached will be 1 more than the decoupler

example:

istg 0 = {

dstg 0:

command module 1

fuel tank 1

engine 1

dstg 1:

stack decoupler

}

istg 1 = {

dstg 2:

fuel tank 2

engine 2

}

hope that makes sense

[markjustmark]

Thanks for that, Ryeesa.

Yes, you are absolutely correct.

dstg is everything to do with decoupling.

0 for the final module, 1 for the decouplers, 2 for the next stage parts, 3 for the next decouplers, 4 for the next stage parts, etc.

Just to clarify, istg is only for parts with an activity like engines or decouplers - things that appear in the staging list in the VAB.

With fuel tanks, struts and fuel lines, the istg is set to the dstg.

Also, sidx is not to do with symmetry, but with staging. it is an index of all the things that activate in a particular stage.

Mark

[markjustmark]

By the way, the asparagus staging script is coming along nicely.

Finally got it to the point where it generates a valid, properly staged, correct fuel flowing, asparagus launch subassembly that doesn't explode on the launch pad.

Needs a bit more refactoring so you can select which fuel tanks and which engines to use (it's limited to Jumbo-64s and Mainsails at the moment)

Mark

[mszegedy]

Thank you for your work on decoding the format. My genetic algorithm will be much easier to write now. One noteâ€â€I still can't figure out what sidx does. You said it's the symmetry index, and it makes sense, except for the fact that it seems to be assigned nearly at random. When I created a craft, the root part had sidx=-1, as well as the parts under it. The parts radially attached to it, in symmetry, have sidx=0. Then the parts radially attached to those have sidx=-1. If you radially attach a part to those, then sidx=0. If you radially attach a part to those, but without symmetry, then they'll have sidx=-1. If you radially attach parts to that with symmetry, then they'll have sidx=1. What? How does this work?

[markjustmark]

Hi mszegedy,

sidx has nothing to do with symmetry.

It is the index number of all the things that activate in a particular stage.

So, if you have four rockets that activate in a stage, they will all have the same istg number, and an sidx of 0, 1, 2, & 3 respectively.

Mark

[Ezriilc]

I realize this thread is a bit old, but it's right on topic for my latest project, and I'd be grateful to get some more information on this.

I've read what's here over and over, and everything else Google can tell me, and I still just don't get what "istg" and "dstg" mean, with regards to various staging arrangements.

Can anyone provide a deeper explanation of istg/dstg? I fully expect that I'm simply missing something, so feel free to state the obvious.

If it helps to know what I'm doing, I'm writing a script to parse ship .craft files into usable stats such as Thrust-to-weight ratio ASL, etc.. To do this, I need to know which engines are activated at launch, and which are not, and so far I'm tripping over myself. I know this has been done for MechJeb, but I can't figure out how.

Thanks in advance!

[SlowThought]

What I'm not so sure about

* "rot" is the rotation of each part expressed as 4 components of a unit vector. I've been putting the x and z components of a unit vector pointing from one PART to its attached buddy in the 2nd and 4th components of this entry, and it seems to work out correctly most of the time.

Mark

I suspect KSP uses quaternions internally to express vectors. Your "(x ? z) -> (0 x ? z)" mapping supports this. You can think of quaternions as an extension of complex numbers, with three different "imaginary" directions, basically a 4D number. The complex extension works for the arithmetic. In this context it's better to think of the first component as a scalar, and the last 3 as a vector. Consider Newton's third law:

F=ma -> (0 Fx Fy Fz) = (m 0 0 0)(0 ax ay az)

Quaternions make sure the mixed vector scalar works out, and allows a common data type for the programmers to work with.

[Ezriilc]

I suspect KSP uses quaternions internally to express vectors. Your "(x ? z) -> (0 x ? z)" mapping supports this. You can think of quaternions as an extension of complex numbers, with three different "imaginary" directions, basically a 4D number. The complex extension works for the arithmetic. In this context it's better to think of the first component as a scalar, and the last 3 as a vector. Consider Newton's third law:

F=ma -> (0 Fx Fy Fz) = (m 0 0 0)(0 ax ay az)

Quaternions make sure the mixed vector scalar works out, and allows a common data type for the programmers to work with.

Thanks for that input! It helps me quite a lot.

[NathanKell]

Nope, KSP uses vectors for vectors. It does, however, use quaternions for *orienations*, and quaternions are *not* simply 4-unit vectors (like you'd use in a 4x4 rotation matrix).

If you see a 4-tuple, it's either a vec4 or a quaternion; vec4s are used for, e.g., colors (r, g, b, a), and quaternions for orientations. You might want to read up a bit on using quaternions for orientation, because dealing with them can be *quite* complex (they're a way of representing imaginary numbers, for pete's sake).

[SlowThought]

Nope, KSP uses vectors for vectors. It does, however, use quaternions for *orienations*

I bow to the voice of experience; I've not looked at what code is publicly available. IMHO, quaternions are easier to grok than vectors, at least in terms of how they represent the underlying physics (there are some that argue that vector calculus never would have been, but for the prejudice against the Irishman who discovered quaternions). As you note, they are very convenient for describing orientation (which what markjustmark appears to have been dealing with).

FWIW, twenty-something years ago I derived a common expression for all the basic orbits (elliptical, parabolic, hyperbolic) from a complex representation of Newton's 3rd law. My students weren't impressed (ok, they were terrified). I wish I could find my notes. I have made feeble attempts to do the same starting with quaternions, but not gotten anywhere.

Bottom line, markjustmark was looking at a quaternion. Quats versus vectors borders on the religious. I am one of the Devout Few of the Q, but I'm not very pious by nature

[Taverius]

Something of a necro, but attm may have something to do with whether the part was attached in angle snap mode or not.

Rotation on a snapped part works somewhat differently in the editor.

[Lilleman]

This is an old thread, but I'm willing to make some scripting (edit: in fact, more like a .NET application) with crafts files, and I didn't wanted to make a new thread about it.

I found this : https://kerbaldata.codeplex.com/

But I don't know if I can use it to create/get infos from a ship or a subassembly, is it even up to date?

This thread is probably the most useful source of informations I've found with google. Do you guys know where I can learn more about craft file format?

Edited July 4, 2014 by Lilleman

[Ezriilc]

This is an old thread, but I'm willing to make some scripting (edit: in fact, more like a .NET application) with crafts files, and I didn't wanted to make a new thread about it.

I found this : https://kerbaldata.codeplex.com/

But I don't know if I can use it to create/get infos from a ship or a subassembly, is it even up to date?

This thread is probably the most useful source of informations I've found with google. Do you guys know where I can learn more about craft file format?

This thread is about all there is.

Everything I've learned and used building the "Craft Kitchen" was gleaned mostly from my own tests. It turns the text into an array of config nodes, and then parses it into ship stats.

I don't know if KerbalData is up to date, because I never used it. The only other similar project I know of is "WebVAB", but that's getting a bit aged now.

[Lilleman]

OK, thanks for answering.

I've took a look at Craft Kitchen and WebVAB. Might be useful, I keep that in mind.

I can't get the KerbalData dlls to work, so I'll go old-school and do everything "by hand".

For now I want to create something like this that will be capable of generating a craft file, or a subassembly. So it's more like creating a file from scratch, instead of getting informations from it.

I just figured out how to correctly handle parts sizes, using values from part.cfg files, and positions. I have a quick idea on how symmetry and rotation work, but I presume staging and fueling will be a lot of fun...

I do have a question about Craft Kitchen and the Files Fixer, regarding part IDs: Is this thing really almost random like said earlier in this thread? Just go from 0xFFFFFFFF and decrement randomly each time a part is added? I've did some tests with random values using this "theory": it works, but I don't know why and I don't like this.

I'll post here if I found something interesting that hasn't being said already, or if I manage to code this correctly.

[Ezriilc]

OK, thanks for answering.

...

I do have a question about Craft Kitchen and the Files Fixer, regarding part IDs: Is this thing really almost random like said earlier in this thread? Just go from 0xFFFFFFFF and decrement randomly each time a part is added? I've did some tests with random values using this "theory": it works, but I don't know why and I don't like this.

No problem.

As for part IDs, I honestly have no idea. All I've done is to look for duplicate IDs and remove them from the tree. I imagine that so long as the IDs have the correct number of digits, then it doesn't really matter how they are generated - but that's just a guess.

[Lilleman]

After some investigation, I can at least give some new informations.

First, I can confirm what Mark said about istg, dstg, sidx and their relation with staging:

-istg represent the stage number as you can see it in the VAB.

-dstg has to do with vessel separation into several pieces. Mark explain this better than me, but basically, if you have a very basic rocket: pod+fueltank+engine+decoupler+fueltank+engine, the first part (pod+fueltank+engine) will have dstg = 0, the decoupler dstg = 1, and the final part (fueltank+engine) will have dstg = 2.

-sidx is an index for every part in the current stage that can be activated via staging. Start from 0 every stage. (Always at -1 for fuel tanks?)

-sqor, honestly, no idea. But, I noticed that if sidx != -1, then sqor = istg, otherwise sqor = -1. (Always at -1 for fuel tanks?)

-attm is for attachment mode (to be confirmed); 0 if the part is not attached radially to anything, 1 if it is.

-attRot (attach rotation?) seems to always be 0,0,0,1 (edit: ahem, I don't know what I was thinking. This is, as the name suggest it, the attach rotation, the one you get with WASD in the VAB. The rotation is applied from the attach's origin instead of the part's origin).

-mir (mirror?) seems to always be 1,1,1.

About the part size: Don't forget (like me) that part can be rescaled either to 1m scale or 1.25m, and you should be able to get correct parts positions.

The rotation quaternion can easily be handled with the standard .NET framework, with the help of System.Windows.Media.Media3D.Quaternion and System.Windows.Media.Media3D.Vector3D.

Of course, I could have read the Wikipedia article about quaternion, and come up with an open-source solution, but meh, got this without having to learn a thing! Hooray!

Now to make a list of every module, resource, event, action, etc... This will be long.

If you see something incorrect, let me know, I'm not quite sure about all this yet.

Edited July 7, 2014 by Lilleman

[Ezriilc]

After some investigation, I can at least give some new informations.

First, I can confirm what Mark said about istg, dstg, sidx and their relation with staging:

-istg represent the stage number as you can see it in the VAB.

-dstg has to do with vessel separation into several pieces. Mark explain this better than me, but basically, if you have a very basic rocket: pod+fueltank+engine+decoupler+fueltank+engine, the first part (pod+fueltank+engine) will have dstg = 0, the decoupler dstg = 1, and the final part (fueltank+engine) will have dstg = 2.

-sidx is an index for every part in the current stage that can be activated via staging. Start from 0 every stage. (Always at -1 for fuel tanks?)

-sqor, honestly, no idea. But, I noticed that if sidx != -1, then sqor = istg, otherwise sqor = -1. (Always at -1 for fuel tanks?)

-attm is for attachment mode (to be confirmed); 0 if the part is not attached radially to anything, 1 if it is.

-attRot (attach rotation?) seems to always be 0,0,0,1 (edit: ahem, I don't know what I was thinking. This is, as the name suggest it, the attach rotation, the one you get with WASD in the VAB. The rotation is applied from the attach's origin instead of the part's origin).

-mir (mirror?) seems to always be 1,1,1.

About the part size: Don't forget (like me) that part can be rescaled either to 1m scale or 1.25m, and you should be able to get correct parts positions.

The rotation quaternion can easily be handled with the standard .NET framework, with the help of System.Windows.Media.Media3D.Quaternion and System.Windows.Media.Media3D.Vector3D.

Of course, I could have read the Wikipedia article about quaternion, and come up with an open-source solution, but meh, got this without having to learn a thing! Hooray!

Now to make a list of every module, resource, event, action, etc... This will be long.

If you see something incorrect, let me know, I'm not quite sure about all this yet.

An excellent summary - thanks!