Difference between revisions of "User:Greys/The CFG File and ConfigNodes"

Latest revision as of 19:39, 16 November 2014

The CFG file is a plain text document storing information which has been serialized from ConfigNodes and can be loaded back into those CongifNodes. ConfigNode is a Type used throughout KSP's code to organize information. The key feature of Confignodes is that they can contain Values, which have Strings in them, and they can also contain other ConfigNodes, allowing for branching organization.

CFG File Syntax

The information stored in a cfg file exists as two and only two structures, nodes and values, this is also true in the code. Nodes can contain values, but they can also contain other nodes.

NODE
{
    value = foo
    Value = bar
    node
    {
        value = baz
    }
}

It is important to note from the above example that both Nodes and Values are case sensitive, NODE and node are not the same, but also every Node is a discrete context, the value 'value' from the node 'node' does not conflict with either of the values in NODE. It is common, but not required, that all Nodes will be in ALL UPPERCASE, while all values will be in all lowercase, but even Squad deviates from this.

Working with ConfigNodes

ConfigNode is a type which behaves similarly to a Dictionary<string, string> but can also contain other ConfigNodes, allowing them to be nested. The primary ways of interacting with them is via the methods .GetConfigNode(), .GetConfigNodes(), .GetValue(), and .SetValue(), but there are a lot of other methods. Several methods, such as GetConfigNodes, return an array of ConfigNodes, and have to be put in an object of type ConfigNode[].

It is important to keep in mind that all values stored in ConfigNodes are strings, when loading values you must parse them into whatever the intended type is.

KSP automatically loads all the confignodes defined in CFG files in the /KSP/GameData/ folder into the GameDatabase.Instance object during loading, regardless of if any code wants them. ConfigNodes can also be found in persistent.sfs and *.craft files located in the /KSP/saves/ folder, though the .craft files differ slightly in that they have values outside of the 'Top Level Node' of the file, KSP sets the entire file into a ConfigNode when it's loaded similarly to how part.cfg files worked prior to KSP 0.20.0

Unnecessary nodes and values do no harm at all, they do take up space in the RAM, but it's a very small amount.

ConfigNodes are by default references, so when you GetConfigNode and SetValue, that change is available to any code in the game which looks up that same ConfigNode, unless of course the ConfigNode is private. A ConfigNode can be duplicated by: ConfigNode node = new confignodesomewhereelse.GetConfigNode("name of the node you want");

Bringing it all together

CFG files store the content of ConfigNodes in a plain text file so that it's easily accessible and editable. You can make a CFG file that contains any valid structure, regardless of it if gets used. Both in and out of code this information exists as string text, and everything is case sensitive. In many cases, but not all, a given Node will only be recognized by the code if it is inside a given other Node, an example of this is MODULE, which only counts if it's in a PART node.