kOS-simpleJson CKAN

Overview

This addon extends kOS with simple JSON functionality, allowing you to serialize kOS data structures to basic JSON strings and parse plain JSON strings back into kOS structures. It uses the SimpleJson library internally for efficient JSON processing.

While kOS provides its own READJSON and WRITEJSON functions which allow complete serialization and deserialization without loss of types, this addon provides the functionality to read and write plain JSON data without the need for custom types. The only drawback is that when converting a structure to and from JSON, it might not be the same type anymore. See supported type conversions for more info.

Features

• JSON Stringification: Convert kOS structures (Lexicons, Lists, primitives, etc.) to JSON strings
• JSON Parsing: Parse JSON strings into kOS structures
• Type Support: Handles strings, numbers (int/double), booleans, arrays, and objects
• Robust Number Handling: Automatically handles numeric type conversions and ranges
• Special Structure Support: Serializes PID loops and ranges correctly

Requirements

• kOS

Installation

1. Download the latest release
2. Extract the contents to your KSP GameData folder
3. The addon will be loaded automatically when KSP starts

Your directory structure should look like:

GameData/
└─ kOS-simpleJson/
   ├─ Plugins/
   │  └─ kOS-simpleJson.dll
   └─ LICENSE

Usage

The addon provides two main functions accessible through the base path ADDONS:JSON:

STRINGIFY

Converts a kOS structure to a JSON string.

// Stringify a lexicon
SET myLex TO LEXICON("name", "Rocket", "altitude", 1000, "active", True).
SET jsonString TO ADDONS:JSON:STRINGIFY(myLex).
PRINT jsonString.
// Output: {"name":"Rocket","altitude":1000,"active":true}

// Stringify a list
SET myList TO LIST(1, 2, 3, "four").
SET jsonString TO ADDONS:JSON:STRINGIFY(myList).
PRINT jsonString.
// Output: [1,2,3,"four"]

// Stringify primitives
PRINT ADDONS:JSON:STRINGIFY(42).        // Output: 42
PRINT ADDONS:JSON:STRINGIFY("hello").   // Output: "hello"
PRINT ADDONS:JSON:STRINGIFY(True).      // Output: true

PARSE

Parses a JSON string into a kOS structure.

// Parse JSON object
SET jsonString TO "{""name"":""Rocket"",""altitude"":1000}".
SET myLex TO ADDONS:JSON:PARSE(jsonString).
PRINT myLex["name"].      // Output: Rocket
PRINT myLex["altitude"].  // Output: 1000

// Parse JSON array
SET jsonString TO "[1,2,3,4,5]".
SET myList TO ADDONS:JSON:PARSE(jsonString).
PRINT myList[0].  // Output: 1

// Parse primitives
PRINT ADDONS:JSON:PARSE("42").      // Output: 42
PRINT ADDONS:JSON:PARSE("true").    // Output: True

Supported Types

kOS to JSON (STRINGIFY)

JSON to kOS (PARSE)

Examples

Working with API Responses

// Simulating an API response
SET apiResponse TO "{""vessel"":{""name"":""Explorer 1"",""mass"":5000,""parts"":25}}".
SET data TO ADDONS:JSON:PARSE(apiResponse).
PRINT "Vessel: " + data["vessel"]["name"].
PRINT "Mass: " + data["vessel"]["mass"].

Saving Configuration

// Create configuration
SET config TO LEXICON(
    "launchAzimuth", 90,
    "targetAltitude", 80000,
    "stages", LIST(
        LEXICON("fuel", 100, "engines", 1),
        LEXICON("fuel", 200, "engines", 2)
    )
).

// Save to file
SET jsonConfig TO ADDONS:JSON:STRINGIFY(config).
LOG jsonConfig TO "0:/config.json".

// Load from file
SET loadedJson TO OPEN("0:/config.json"):READALL:STRING.
SET loadedConfig TO ADDONS:JSON:PARSE(loadedJson).

Technical Details

The addon implements the IFormatWriter interface from kOS.Safe.Serialization, using the SimpleJsonFormatter class to handle serialization and deserialization. The main entry point is the SimpleJsonAddon class, which is decorated with the [kOSAddon("JSON")] attribute to register it with kOS.

Known Limitations

• Circular references are not supported and will cause serialization errors
• Some complex kOS types may not serialize correctly (please report as issues)
• JSON null values are converted to empty strings

Credits

• Uses kOS built-in SimpleJson for JSON processing
• Built for kOS (Kerbal Operating System)
• Copyright © Throin 2025