API Reference: http://manitcor.com/ksp/KerbalData/0.2.0Alpha


Consumer API

Classes starting with the word "Kerbal" are "top level" consumer API's. For most development, this is the easiest way to use KerbalData. The top level API provides the following features:
  • KSP Install Aware
  • Specialized Models with extended properties to translate KSP data to standard formats (TimeSpan for game and mission time for example)
  • Utilizes configured repos allowing for easy integration with multiple data stores
  • Provides lazy loading of data
  • Maintains data used to initialize the object and state can be restored to time of load or last save
All operations with the top level API start with a KerbalData instance. This class will maintain all the references necessary. The constructor accepts the root path for a KSP install. Once initialized KerbalData will scan the KSP install and load initial meta-data (currently only names) but not the actual files into memory. KSP files are only serilized and loaded on initial access of pariticular named data. Once loaded the data will be maintained and no additional calls will be made to the data until Save() is called.

Examples

Simple WPF editor written in C# showing binding to KSP data elements and using many parts of the API.

// Use your own install path
var kd = new KerbalData(@"C:\KSP");

// Load a save file using the same short name provided in the game UI
var sf = kd.Saves["testing"];

// One of many helper methods, this one re-fills all ships
sf.Game.FlightState.FillResources();

// Setting the title of the save game, this will change in-game name display 
// (still need to wire in dir name change)
sf.Game.Title = "I AM IRON MAN";

// Another helper method, this clears all vessels marked as debris or unknown vessel types.
sf.Game.FlightState.ClearDebris();

// Grabbing a vessel from the game
var sat = 
     sf.Game.FlightState.Vessels.Where(v => v.Name.Contains("Beta Geo-Sat")).FirstOrDefault();

// Changing the orbit (currently defaults to 100km above target)
sat.Orbit.Change(Body.Bop);

// Save file, includes data backup of original file
sf.Save();

KSP Data Models

Model classes for each type of KSP data are implemented to provide easier access to the data and to allow the API better control to provide additional features. When using the top level API loading and de-serialization of your data is handled by the API, models are exposed as properties off of Kerbal data as shown in the previous examples.

Model data is split into 2 categories:
Mapped Data
Mapped data are strongly typed properties found in the model. To decrease the impact of changes to the save file in future versions only properties that seem to be permanent (best guess) are implemented as mapped properties.

All remaining properties are:

Unmapped Data
All models inherit Dictionary<string, JToken>, after processing all mapped properties the remaining properties are added as children to the dictionary and can be manipulated as JSON.Net objects. Note the JToken is the base data type for JSON.Net the actual type may be a JToken, JObject or a JArray.

Values in the dictionary are either converted with .ToString() during serialization or they are treated as JSON objects if the value is complex.

var kd = new KerbalData("C:\KSP");
kd.Saves["mysaves"].Game.Parameters.Flight["CanQuickSave"] = true;

Model Reference

SaveFile Model


Green=Collection

JSON Data API

The lower level serialization API allows more direct access to the KSP data while dumping features like KSP install aware and data repository loading provided by KerbalData. This is useful for advanced uses where the developer desires to take more direct control of data loading. All lower level API classes start with the prefix "Ksp".

Loading KSP data directly from files as well as conversion of strings between JSON and KSP format is provided by methods in the static KspData class.
// Load a KSP file returns a Json.Net JObject
var jobj = KspData.LoadKspFile("C:\KSP\Saves\mygame\persistent.sfs");

// All objects are either JObject's, JArray's ,JToken's or JProperty's and values are all strings
// Matching case to the names used in the loaded file is required.
var activeVessel = jobj["GAME"]["FLIGHTSTATE"]["activeVessel"];

// Collections are stored as JArrays. The name of the collection is the same as the 
// object name in the file. The serializer looks for objects of the same name at the same 
// level and creates collection. 
var myVessel = jobj["GAME"]["FLIGHTSTATE"]["VESSEL"][0];

// Json.Net also supports Linq
var probes = jobj["GAME"]["FLIGHTSTATE"]["VESSEL"].Where(v => v["type"] == "Probe");

// Upper level API models can also be used if desired by using JSON.Net's ToObject<T>() 
// method. This is the same method used by the upper level API. All child objects are 
// automatically loaded and the data mapped to them.
var game = jobj["GAME"].ToObject<Game>();

// To convert a model instance back to a Json.Net FromObject method
var jobj = JObject.FromObject(game);

// To save the KspData class has what you need no automatic backups are done before
// the save executed. Existing files are automatically overwritten. 
KspData.SaveFile("C:\KSP\Saves\mygame\persistent.sfs", jobj);

Serialization API

KerbalData exposes the following interfaces for future expansion and developer customization. IKspFileConverter and IKspDataConverter work together to provide the primary serialization and deserialization methods. The serialization is split across two classes as to handle for out-of-sync changes from version to version (ie some versions may only need an updated FileConverter, others a DataConverter, others still, both)

The IKerbalDataRepo provides the signature for data loading with the main API the abstract class KerbalDataObject allows for expansion of data models.

IKspFileConverter

Provides base file conversion from KSP text to an internal API data context for construction into another format.

IKspDataConverter

Provides mapping of data context to a specific format. (currently embeds JObject requirements. To be removed in the future.

IKerbalDataRepo

Provides access to loading of KSP data for the upper level API, Currently KerbalData comes with the KspInstallFileRepo which provides repo access to a defiend directiory structure using Ant style paths http://ant.apache.org/manual/dirtasks.html.

KerbalDataObject

Provides the base infrastructure for the upper level API data objects. Custom Data object and mapping structures may be used. All mapping leverages JSON.Net http://james.newtonking.com/projects/json/help/ and all JSON.Net attributes are available to customize serialization into your custom object.

Data objects inheriting this type will be pre-wired with future support of custom data model delivery through the top level consumer API while providing full upper layer capabilities such as repository loading, automatic backup and data change tracking.

Last edited Jan 25, 2013 at 8:04 AM by Manitcor, version 21

Comments

No comments yet.