json

JSON encode/decode library for Luau. Encodes Lua values to JSON strings and decodes JSON strings back to Lua values. Used for communication with the Rust side of the engine, the VFS read/write bridge, and any wire-format that needs JSON.

Pure Luau, no engine dependencies. Compact and pretty-printed encoders, plus a hand-rolled decoder that streams the input by position so it works under WASM as well as native.

Exports

• Json.encode(value: any, indent?: string, currentIndent?: string) -> string — compact encode. Functions / unknown types and NaN/Inf encode as null.
• Json.encodePretty(value: any, indentStr?: string) -> string — pretty-printed encode with sorted object keys (diff-friendly).
• Json.encodeArgs(...: any) -> string — encode varargs as a JSON array.
• Json.decode(str: string) -> any — decode a JSON string. Returns the decoded value, or nil + error message on failure. The string is one JSON value with optional whitespace around it; anything else after the value is a failure naming the character and its position.

Usage

local Json = require("@builtin::modules.json")

local widget   = { type = "button", text = "Click Me" }
local compact  = Json.encode(widget)            -- '{"text":"Click Me","type":"button"}'
local pretty   = Json.encodePretty(widget, "  ")

local decoded  = Json.decode(compact)
local v, err   = Json.decode("oops")             -- v = nil, err = error message

Notes

• Object keys are sorted alphabetically in both encoders for consistent output across runs.
• Numeric keys on objects are stringified at encode time (JSON has no numeric keys). Pure-integer key sets get detected as arrays via isArray and encoded with brackets.
• NaN, +Inf, -Inf encode as null — JSON has no representation. Round trips through decode recover null (Lua nil), so they don't preserve.
• Unicode \uXXXX escapes decode to UTF-8 by hand to stay WASM-safe. Only the BMP is covered; supplementary planes via surrogate pairs are not.
• Functions encode as null.
• Decode is character-streamed — no regex, no string.match patterns on the whole input — so the line-and-column information needs to be reconstructed from the position offset.