The .prisma ASCII format

The ASCII encoding

.prisma is the human-authorable encoding of a Document — a USDA-flavoured ASCII format (as opposed to the binary one) that is diff-clean and stable, the form you write by hand and commit to git. It is one of Core's two native encodings; the other is the .prism binary. They carry the same Document and convert losslessly either way.

Every file begins with a version header, then nests prims with braces:

#prisma 3.0
def group "world" {
    def object "ball" {
        float3 position = (0, 1, 0)
        float  radius   = 1.5
        float3 albedo   = (1, 1, 1)
        albedo.connect  = </world/mat.out>
    }
}

The grammar, briefly

• Header — #prisma <version> (the current format is 3.0; older majors still parse).
• Prim — def <type> "<name>" { … }. The type token is a plain string; quote it if it is not a bare identifier. The name is quoted, so it may contain digits and punctuation (which is what lets the JSON codec use indexed names like "0", "1").
• Property — <dtype> <name> = <value>. Scalars are bare (1.5, true, "hi"); vectors are parenthesised ((0, 1, 0)); arrays are bracketed ([0.1, 0.2]); multi-dimensional shapes carry their dtype-and-shape so the text is self-describing.
• Time samples — a brace block of time: value keyframes instead of a single value.
• Connection — <slot>.connect = <path>, the target on the left, the source path in angle brackets.

Stable and diff-clean

The serializer sorts deterministically, so two saves of the same Document produce byte-identical files and a real change produces a small, readable diff. That is a deliberate property: .prisma is meant to live in version control, be reviewed in a pull request, and merge sanely. Values are self-describing (the dtype and shape travel with the data), so a .prisma file needs no external schema to be read correctly.

Parsing, with located errors

deserialize accepts an optional ParseError* that is filled with a file-absolute line:column and a message on failure — the same diagnosis the CLI's check surfaces:

ParseError err;
auto doc = deserialize(text, &err);
if (!doc) fprintf(stderr, "%zu:%zu: %s\n", err.line, err.column, err.message.c_str());

$ prism check broken.prisma
broken.prisma:4:18: error: invalid value for its declared type

Encoding is detected by content, never by suffix, so a mislabelled file still loads. When you want compactness or large numeric arrays instead of readability, reach for the binary format.