19. The .mtpc format#
An .mtpc (mtp compiled) file is the static representation of one world model: what the compiler writes and the only thing the runtime reads. It is JSON, checked against mtpc.schema.json. This document says what each part means; the schema checks the structure, and this document adds the rules a schema cannot express.
Three rules from the other documents shape everything here:
The runtime never guesses a type. Every variable, every attribute and every expression carries its type, so the runtime can turn each expression into one function specialized to its types when the file loads, and never checks or converts a type while drawing (type system, section 1).
The runtime recomputes only what changed. Every bound variable or attribute lists every variable and attribute it can read (data model, “How reactivity works”).
Everything known when compiling is already folded. A variable or an attribute known when compiling holds a plain value, never an expression.
19.1. Top level#
{
"mtpc": 4,
"types": [ … ],
"objects": [ … ],
"functions": [ … ],
"names": { "theta": 3, "p": 5, "d1.face": 9, … },
"shared": { "circle": { "r": { … }, … }, "instance:dial": { … } },
"type-table": [ {"refine": "string", "constraints": [ … ]}, … ]
}
mtpc: the format version, 4.types: every type the illustrator declared that the objects use, directly or through other types or functions: named types, motifs and variants. One nothing uses is left out.objects: every object in the world model (variables, shapes, transitions, animations, components). An object’s id is its position in this list. Objects appear in the order their declarations are reached in the source, depth first: a container comes before its members, a motif instance’s members follow the instance, and a transition or animation written inline as an item comes right before the object that holds it.functions: every function the model calls while drawing, declared withfuncor written in place withfn, in source order. A function only called where the compiler worked out the result, or never called, is left out. A function’s id is its position in this list. A function declared with a docstring,doc@'text', has its"doc"too.shared, only when there is something in it: for each attribute that every shape of one kind has, its most common value among them, when at least two share it, written here once and left out of the shapes that have it; a shape with another value keeps its own. A kind is a shape’skind, such ascircle, orinstance:and the motif’s name for motif instances, since their attributes differ by motif. A kind with one shape shares nothing. A reader puts each value back in every shape of its kind that does not give it, as a copy, before reading the file; after that, the file is read as if every attribute were written in each shape.type-table, only when there is something in it: each structured type the file uses, every type that is not a plain name such as"real", written once. Where the file writes a type at the top of something (an object’stype, an attribute’s, the second item of an expression, a parameter’s, a function’sresult, a declared type’stypeor a variant’sbase), it writes a structured type as its position in this list; a type inside another type is written out in full. A reader puts each back in its place, before reading the file and before putting backsharedvalues.names: each named object’s name, mapped to its id, as an author or a page refers to it:theta,m0(group members are named like any scene object),d1.face(names inside a motif instance are written through the instance). Unnamed objects (head_, ornoneas the name) have no entry. The"name"field of an object holds its own name only:face, notd1.face.
Every reference to an object is resolved to its id. Two things stay names: a parameter or let name inside an expression (["local", …]), and a declared type ("of": "dial"), which is looked up in types.
Same source, same bytes. The file is UTF-8 JSON written with keys sorted, no whitespace between tokens (, and : as separators), non-ASCII characters written as themselves, and one newline at the end. Numbers are written in their shortest form that reads back exactly. Lists are in the orders given here.
19.2. Types#
Every type is written as JSON:
Type |
Written |
|---|---|
built-in |
|
a built-in shape type |
|
a declared type |
|
a component |
|
an interface |
|
a list |
|
a function |
|
broadened |
|
narrowed |
|
A constraint is an array: [">=", 0], ["<", 1], ["length", 3], ["one-of", ["left", "right"]], ["const"], ["wrap", 0, 360]. A list’s known length is always written as a length constraint.
19.2.1. Declared types#
{"name": "unit", "kind": "type", "type": T}
{"name": "dial", "kind": "motif", "params": [P, …]}
{"name": "bar", "kind": "variant", "params": [P, …], "base": T, "fixed": ["width", "y", …]}
A parameter P is {"name": …, "type": T}, with "default": value when it has one (no "default" key means no default; "default": null means the default is none). A variant’s base is the shape type it refines, and fixed lists the attributes its body sets, which no instance and no writer may change.
19.3. Values#
A value is plain JSON, read according to the type that always accompanies it:
Type |
Written |
|---|---|
|
a number |
|
|
|
|
|
|
|
a string |
|
a string, |
|
|
|
|
|
an array of values of type T |
|
|
|
|
an object (a shape, a transition, an animation, …) |
|
a function |
|
19.4. Expressions#
An expression is an array: its operation first, then its type, then its parts. frame in a read is the id of the container the reading expression sits in (null at the top level and directly in the scene), or "caller" inside a function body, where the frame is that of the expression making the call, passed along with each call. The runtime converts the value read through every translate and transform that applies to the shape read but not to that container (reference, “Coordinates”), and deps include those translate and transform attributes. Types written here are what the compiler proved: a result that may be none has a {"union": [T, "none"]} type, and the runtime never checks for none anywhere else.
Expression |
Written |
|---|---|
a literal |
|
a list or point built from expressions |
|
an interpolated string |
|
a variable |
|
an attribute |
|
an object itself (a group passed to |
|
a value brought into an interval |
|
a value checked against constraints |
|
a parameter or |
|
a built-in function or operator |
|
a function from |
|
a call through a function value |
|
a function as a value |
|
a part |
|
an attribute of every member of a group |
|
|
|
|
|
|
|
|
|
a point on a shape’s box |
|
|
|
19.5. Free and bound values#
A variable’s value, every attribute of a mutable object, and every condition a component reads is written free or bound:
{"type": T, "free": value}
{"type": T, "bound": expr, "deps": [[id, attr], …]}
{"type": T, "start": expr, "deps": [[id, attr], …]}
with "fixed": true on a variant instance’s fixed attributes.
A free one holds its starting value. A writer may change it while drawing, unless its type has a
constconstraint, it is fixed, or its object is a token.A started one, written
free@expror(free expr)in the source, is free, and its starting value isexpr’s value, which the runtime reads once, when it builds the live model, and never again;depslists what it reads, as for a bound one. From then on it is free like any other.A bound one holds an expression.
depslists every variable and attribute it can read: directly, through any function it calls, and through captured names. Where a read depends on a value known only while drawing, such asg[side].pos,depslists every one it could read (theposof every member). When any of them changes, this one is recomputed, and nothing else is.[id, null]is a variable.A variable or an attribute known when compiling is written as free, with a
constconstraint in its type, whether the illustrator wrote it that way or the compiler folded it. One exception: one given a constant (the bare name of aconstvariable or of a built-in constant, or a read of aconstattribute) is free with noconstconstraint, as if given its value.Every attribute of a shape is written, including those left at their default, in the shape or, when it is the value most shapes of its kind share, once in
shared(see “Top level”).posis not: it isxandyread or written together. A line’s attributes are itsfromandto, a triangle’s its corners, a polyline’s and a polygon’s itspoints, a curve’s itsfrom,toandcontrols; theirxandyare computed (the midpoint, the centroid, the mean of the points, the mean of a curve’s ends and controls), and a write to them is split into writes to every end or corner, or moves every point.
19.6. Objects#
Every object has:
{"kind": …, "type": T, "access": "scene" | "page", "name": "theta" | null, …}
and "doc", a string, when its declaration gives a docstring, doc@'text' (reference, “Docstrings”); then what its kind needs:
Kind |
Further keys |
|---|---|
|
|
|
|
a row or a column |
kind |
|
|
|
|
|
|
|
|
a motif instance |
kind |
a variant instance |
the kind of its base shape ( |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
A listener on a shape or a term has "in": one id, that of the view whose body holds it (reference, “Listeners and controls in views”). It hears the pointer only in that view, and nothing in it while that view is quiet. A listener on its own view (on-view, on-ready, on-live, on-quiet, and an on-pointermove on a canvas) has no "in" key: its "view" names that view. A control whose source gives (in view…) has "in": the ids of those views, in the order written, at least one. It belongs to those views, and one without it to none, with no "in" key: the runtime hides a control while all its views are quiet. An older file may have a listener on a shape with several views in "in", or with no "in", which the runtime reads as heard in every view that shows its shape.
A control or a listener whose source gives (priority n) has "priority": n, an int from 1 to 1000, and one without it has no "priority" key: the runtime gives it its kind’s priority, 1000 for on-view, 300 for on-ready, 700 for a gesture (on-drag, a slider’s knob held, on-pointermove) and 500 for the rest (reference, “Concurrency”). Whether the reader set a writer off is not in the file: the runtime knows it from what started the writer.
A writer’s "conditions" is a list of clamps, one per condition, already in the form the reference requires (a comparison of the variable or attribute written with a value not depending on it): {"target": [id, attr], "op": ">=" | ">" | "<=" | "<", "limit": L}, L free or bound. Before emitting a write to that target, the runtime clamps it to the limit.
Motif and variant instances are written out in full: the runtime never builds an instance itself.
19.6.1. Steps#
["move", [id, attr], transitionId, duration, ease]
["wait", seconds]
["at-once", step, …]
["in-order", step, …]
["loop", n | null, step]
A move carries its own duration and ease, resolved from the transition and the nearest enclosing default, so one named transition can be used in animations with different defaults. An animation’s "steps" is one step; several steps written in a row in the source become one in-order. A play’s steps are the items of the top-level in-order, inside a loop around the whole of it, or the one step when there is none. A (move …) with a target, or the name of a transition, in an animation’s body, is written as a move; a (move none …), as a wait. A slider’s move is written as an animation of one move, with duration 1, which the compiler adds. An animation with (loop n) or (loop) has a loop step around its body, n being the number of rounds, or null for forever; each round starts again from the start of its step, reading every move’s ends again.
19.6.2. Transitions#
{"from": V | null, "to": V | null, "duration": seconds | null,
"ease": "linear" | ["step", n] | ["step-ease", p]
| {"func": id} | null,
"path": null | {"func": id}}
A transition is a value: it never changes. Its from and to (V, free or bound) can be bound only so that they can hold expressions; each is read once, when a move along the transition starts, and never followed during the move. null for from or to means the value of what is moved when the move starts. "linear" is the straight line a move with no ease takes; every other ease is a step or a function. null for duration or ease means the transition gives none of its own: each move along it carries the one resolved from the defaults around it. path null is the straight line between the ends.
19.7. Functions#
{"params": [P, …], "result": T, "body": expr}
A parameter P is as in declared types. A function written in place reads its captured names through ["local", …]; the ["func", …] expression that creates it lists them.
19.8. Imported declarations#
Rule 19.1
Of the declarations that a source imports (Rule 5.4), a .mtpc holds only those that the source uses, directly or through other declarations.