JSON Plugin

Parse, read, build and save JSON from a gamemode.

The JSON plugin ships with Knight. It is a Go plugin, so it is already compiled into the server binary: no installation step, just call its natives from .sa.

1. Basic use

knight

let profile = "";

system::start() {
    profile = JsonParse("{"name":"CJ","money":4900,"admin":true,"bag":{"items":3}}");
};

player::command("/profile") {
    SendClientMessage(playerid, "name={JsonGetString(profile, "name")}");
    SendClientMessage(playerid, "money={JsonGetInt(profile, "money")}");
    SendClientMessage(playerid, "items={JsonGetInt(profile, "bag.items")}");
    if (JsonGetBool(profile, "admin")) {
        SendClientMessage(playerid, "Admin");
    }
};

Warning

{ and } start string interpolation in Knight. Escape them as \{ and \} inside JSON literals, or load the document from a file instead.

2. Loading from a file

knight

let data = JsonParseFile("data/config.json");
if (data == "") {
    Log("config.json missing or invalid");
    return;
}
let enabled = JsonGetBool(data, "features.shop");
JsonFree(data);

Paths are relative to the plugin root (scriptfiles by default, or KNIGHT_JSON_ROOT). Absolute paths and .. traversal are rejected.

3. Writing JSON

knight

player::command("/save") {
    let doc = JsonParse("{}");
    JsonSaveFile(doc, "players/" + PlayerName(playerid) + ".json", 2);
    JsonFree(doc);
};

Native reference

JSON 14

Signature	Description
`JsonParse(string text) -> string`	Parse a JSON string; returns a document id or "".
`JsonParseFile(string path) -> string`	Parse a file inside the root; returns a document id or "".
`JsonStringify(string id, int indent) -> string`	Serialise a document (0 = compact).
`JsonFree(string id) -> bool`	Release a document.
`JsonGetString(string id, string path) -> string`	Read a value as a string.
`JsonGetInt(string id, string path) -> int`	Read a value as an integer.
`JsonGetFloat(string id, string path) -> float`	Read a value as a float.
`JsonGetBool(string id, string path) -> bool`	Read a value as a boolean.
`JsonHas(string id, string path) -> bool`	Whether a path exists.
`JsonType(string id, string path) -> string`	object/array/string/number/bool/null/missing.
`JsonCount(string id, string path) -> int`	Array/object length, or string length.
`JsonKeys(string id, string path) -> string`	Comma-separated keys, sorted.
`JsonEscape(string text) -> string`	Quoted, escaped JSON string.
`JsonSaveFile(string id, string path, int indent) -> bool`	Write a document inside the root.

5. Paths

The second argument walks nested values with dots.

Path	Selects
`"name"`	top-level `name`
`"bag.items"`	nested object field
`"tags.1"`	second array element
`""`	the whole document

6. Memory

Parsed documents stay in memory until JsonFree(id) or server shutdown. Always free a document you no longer need, especially when parsing per player or per request.

knight

player::command("/check", string text) {
    let doc = JsonParse(text);
    if (doc != "") {
        SendClientMessage(playerid, "keys={JsonKeys(doc)}");
        JsonFree(doc);
    }
};