vscript-json

A pure Squirrel JSON encoder/decoder for use in VScript.

Features

• Load and save JSON files from Squirrel scripts.
• Supports most standard JSON types: objects, arrays, strings, numbers, booleans, and null.
• Pretty-printing and compact output options.
• Handles Unicode escape sequences (e.g., \uXXXX).

Usage

1. Place the scripts

• Place json.nut in the appropriate scripts/vscripts folder for your game.
• .json files for both loading and dumping should be located in the scriptdata folder of your game, as required by VScript file I/O.
• Example for Team Fortress 2:
  • Team Fortress 2/tf/scripts/vscripts/json.nut
  • Team Fortress 2/tf/scriptdata/input.json

2. Include and use in your script:

IncludeScript("json.nut", getroottable());

local table = JSON.load("input.json");
table.offices[0].location = "New Jersey";

local dump = JSON.dumps(table);
printl(dump);
local newTable = JSON.loads(dump);
printl(JSON.dumps(newTable, 2));

JSON.dump(table, "output.json", 2);

• JSON.load(filename) — Load JSON from a file.
• JSON.loads(text) — Parse JSON from a string.
• JSON.dump(obj, filename, indent?) — Write JSON to a file (optionally pretty-printed).
• JSON.dumps(obj, indent?) — Serialize to a JSON string (optionally pretty-printed).

About the indent parameter

• If indent is an integer, that number of spaces will be used for indentation.
• If indent is a string, it will be used as the indentation for each level.
• If indent is anything else (or omitted), the output will be compact (no extra whitespace).

Limitations

• No support for surrogate pairs (UTF-16 encoding): Unicode characters outside the Basic Multilingual Plane (BMP) (e.g., emoji, some rare CJK characters) encoded as surrogate pairs (e.g., \uD83D\uDE0A) are not decoded/encoded correctly. Only single \uXXXX escapes are supported.
• FileToString size limit: Built-in FileToString VScript function can only read the files with size up to 16384 bytes. Going above that disallows you to read that file altogether. Possible solution could be to split the data into multiple jsons or remove the indentation. StringToFile however is umlimited in terms of size.
• StringToFile NULL byte: Built-in StringToFile VScript function has a bug where it always appends a NULL byte to the end of the file.
• Cannot serialize/deserialize class instances: Only basic types (tables, arrays, strings, numbers, booleans, null) are supported. Attempting to serialize class instances or functions will throw an error.
• Key restriction: Only string keys are allowed in JSON objects.
• No key order preservation: Squirrel tables are unordered, so the order of object keys in JSON is not guaranteed to be preserved after loading.