Application Data

Extended mode includes strict JSON values, UUIDs, SHA-256, explicit text codecs, Unicode filesystem paths, and atomic file replacement. These commands are intended for project files, preferences, asset indexes, migration IDs, and other durable application data.

UTF-8 paths

Extended Strings passed as paths are strict UTF-8 and are converted to Unicode Windows paths. Invalid UTF-8 and embedded NUL bytes are rejected. Original mode retains its active Windows ANSI-code-page interpretation. The same rule is used by streams, directory commands, JSON and SHA file commands, images, audio, textures, meshes, shaders, heightmaps, captures, and asynchronous world loading.

JSON ownership and types

A JSON value is an explicitly owned positive Int handle. Zero means a failed parse, load, or lookup; JSON null is a real handle whose JsonKind is JSON_NULL. Every successful constructor, parse, load, copy, and child lookup returns a handle that must be released with FreeJson. FreeJson 0 is safe.

Child getters return deep copies, and container setters copy their input. Freeing or mutating a parent therefore cannot invalidate another live handle. JSON distinguishes Boolean, signed Long integer, finite Double number, String, array, object, and null. Inspect untrusted data with JsonKind before using a strict getter.

Objects preserve insertion order. Parsing rejects duplicate keys, malformed UTF-8, excessive depth or size, Long overflow, non-finite numbers, comments, and trailing commas. Serialization is deterministic UTF-8 without a BOM or final newline. Indent zero is compact; one through eight selects pretty-print spaces.

UUID and SHA-256 bytes

CreateUuid uses the operating system cryptographic random generator and produces a lowercase RFC version-4 UUID. UUID Bank conversion supports UUID_BYTES_RFC network/display order and the mixed-endian UUID_BYTES_WINDOWS Windows GUID/.NET Guid.ToByteArray() layout. Always state the layout at interoperability boundaries.

SHA-256 consumes exact stored String bytes, a selected Bank range, or raw file bytes. It adds no BOM, terminator, normalization, or newline conversion. Hex output is 64 lowercase ASCII characters and raw output is a new 32-byte Bank. SHA-256 is an integrity and identity primitive; it is not a password-storage API and does not authenticate data by itself.

Atomic writes and diagnostics

WriteTextAtomic, WriteBankAtomic, and SaveJsonAtomic write a unique sibling file, flush it, close it, and request write-through publication. A handled failure preserves the previous destination and never uses delete-then-rename. The guarantee is old-or-new complete content for the publication operation, not a multi-file transaction or protection from failing hardware and network filesystems. Replacement publishes the completed sibling file's metadata and does not promise to preserve arbitrary destination attributes or ACL metadata.

Malformed external JSON and expected filesystem or codec failures return zero or an empty result and set context-local diagnostics. Invalid handles, wrong JSON kinds, invalid Bank ranges, and invalid indentation are programming errors and raise RuntimeError.

Workers

JSON memory operations, JSON loading and serialization, UUID parsing and byte conversion, SHA-256, codecs, and read-only filesystem operations are worker-safe. JSON handles are private to one runtime context and never cross a Job boundary. Return copied data in a result Bank. Random UUID creation and every write command remain main-thread-only. File hashing and loading check for cancellation between bounded chunks.