The .prism binary format

The binary encoding

.prism is the compact, fast-loading encoding of a Document, the compiled counterpart to the .prisma text form. It holds the same elements, properties, values, samples and connections in a packed, self-describing binary crate (magic PRSMC). The relationship is the one between a source file and its build artifact: .prisma is to .prism what .ts is to .js. Author in text, ship in binary, convert either way at any time.

kinogaki convert world.prisma world.prism            # text → binary
kinogaki convert world.prism  world.prisma            # binary → text, identical Document

doc.save("world.prism", Codec::PrismBinary);         // → PRSMC crate on disk
std::string bytes = doc.toString(Codec::PrismBinary); // → the same crate as bytes

Document back;
back.loadString(bytes, Codec::PrismBinary);          // read it back, same Document

doc.save("world.prism", kg.Codec.PRISM_BINARY)       # → PRSMC crate on disk

back = kg.Document()
back.load("world.prism")                             # encoding read from the content

Why binary

Text is for humans and diffs; binary is for machines and size. .prism loads faster (it reads packed floats directly, skipping the parse of decimal numerals) and is dramatically smaller when a document holds large numeric arrays such as meshes, images, and long animation tracks. It is also self-describing: the crate carries its own dtype and shape information, so it round-trips exactly and carries its own schema.

Compression

Pass compress to pack the crate body with Core's built-in LZ coder, which stands on the standard library alone and is a real win for array-heavy documents:

std::string packed = serializeBinary(doc, /*compress*/ true);   // flag bit set; auto-inflated on load

packed = kg.encode(doc, kg.Codec.PRISM_BINARY, compress=True)   # flag bit set; auto-inflated on load

kinogaki convert world.prisma world.prism --compress

A load detects the compression flag and inflates transparently, so a packed .prism opens exactly like an unpacked one. The compressor is fuzzed against the standard library to guarantee round-trip integrity.

Packages

A whole tree of documents and assets packs into a related container (magic PRSMZ), a bundle. That is how a directory of pages, images and stylesheets becomes one compressed file you move as a single object. Bundles default to the compressed binary container because that is the right home for image and asset data.

Detection by content

All three encodings (text #prisma, binary PRSMC, package PRSMZ) are recognised by their leading bytes. Hand Core a buffer and it reads the encoding from the content whatever the file was named; a .txt that is really a .prism still loads. For the foreign formats Core reads through codecs (JSON, Markdown, HTML, SVG, raw bytes), see codecs.