Cookbook & conventions

Conventions over rules

An element's type token is a label for a reader: object, group, heading, rect, folder are strings that say how to interpret an element, and Core leaves their meaning to the reader. A domain is therefore a convention: an agreed vocabulary of type tokens and property names, layered on the same container. These recipes show the common ones.

A scene

Hierarchy via nesting, materials via connections, animation via time samples:

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

A structured document

The document codec targets this shape; you can also author it directly. Blocks are ordered children keyed by index; inline runs are ordered children of a block:

def document "document" {
    def heading "0" { int32 level = 2  def text "0" { str text = "Title" } }
    def paragraph "1" { def text "0" { str text = "A paragraph with " }
                        def strong "1" { def text "0" { str text = "bold" } } }
}

A directory tree

A bundle: a folder element is a directory; a file is a typed content element whose name property is the filename:

def folder "site" {
    def document "page"  { str name = "index.html"  /* …structural body… */ }
    def blob     "logo"  { str name = "logo.png"  uint8[] data = [ /* bytes */ ] }
}

JSON as navigable elements

kinogaki convert config.json config.prisma maps objects and arrays to elements so every node is path-addressable:

kinogaki convert config.json config.prisma
kinogaki check config.prisma          # then query or edit any value by path

Idioms worth knowing

Define top-down. An element's parents must exist before it: define /world before /world/ball.
Prefer doc.eval for reads. doc.eval(slot, t) follows connections and samples; reading the stored default skips both.
Override by referencing, don't copy. Pull a shared asset in with a reference and override locally; never paste it.
Let identity be the path. Don't invent an id property: /world/ball is the id. Stable addressing is what makes edits, links, and agent operations precise.
Commit .prisma, ship .prism. Diff the ASCII form in review; serve the binary form to programs.

These are conventions, not constraints. The same container holds all of them, which is exactly why one library, one addressing scheme, and one set of guarantees cover every Prism document you will write.

‹ The C ABI Document ›