Skip to content
Get started

SDK: The contract

What the build, the check and the render rely on. Everything else is the piece's own choice.

  • A piece is drawn in a page, a moment at a time, in any order: the check draws moments out of order and compares them with the same moments drawn in order (AK-D002), and the render draws parts on several pages at once and keeps what it drew in the part cache.
  • A layer’s mount lays it out once; its render(el, t, …) sets every property that moves from t alone (layers.md). Nothing may carry state from one render call to the next. A deck mounts a slide’s components when the slide is shown and may let the slide go and mount them again later, on a new element: what mount made that the page does not free with the element (a WebGL context, a worker, a timer) is let go in unmount(el, …), and nothing is carried from one mount to the next.
  • Piece code sees the moment’s clock, not the wall’s: Date, Date.now() and performance.now() read the moment being drawn (time 0 is 2026-01-01T00:00:00Z); Math.random() and crypto.getRandomValues() are seeded by the piece’s id, the combo, the part and the frame; requestAnimationFrame callbacks run at the moment; setTimeout and setInterval never fire. Use rand(seed) and the noise functions for randomness of your own.
  • CSS animations and transitions run on the browser’s clock: never let them drive the picture.
  • Work a layer must finish before anything is drawn (a 3D scenery’s build, a picture decoding) goes through ctx.wait(promise). Loading may take loadLimit seconds (AK-P002), one moment seekLimit seconds (AK-P003) (defaults.md).
  • A part is rendered once and reused in every combo that has it: a layer reads the combo’s dimensions and its own part’s slot, never another slot’s pick (AK-X005, batches.md).
  • Fonts, pictures, footage, music and data are files in the project, imported or named by paths relative to the module that names them (project.md). A request the stage does not serve is AK-N003; a network request while building is AK-B003.
  • An import of a URL, of a file outside the project or of a package package.json does not declare is AK-B005.
  • The module’s top level runs in Node when the build reads a piece: only parts, pages, covers and a layer’s mount and render touch window and document.
  • A layer changes only its own element: a change to the page outside the stage is AK-R003, and a style value the browser does not accept is AK-R004.

What goes wrong is a problem, not a wrong picture

Section titled “What goes wrong is a problem, not a wrong picture”
  • Every command reads the problems of each page it drew with and prints them, each under its rule: a layer that throws at 0.8 s (AK-R001), work it waits for that fails or does not settle, a picture that does not load (AK-A005), a 3D scenery that does not build (AK-W001). ctx.report({ code, message }) reports one of a layer’s own.
  • A render does not make a file whose drawing raised a problem; it lists it as not made, with why, and keeps nothing of it in the part cache.
  • What piece code prints with console.log, info, warn, error and debug is collected with where it ran (the module, a part, a layer, its moment) and printed by the commands after their own output. It changes no frame.

allyhub check reports problems: what is wrong whatever the taste. Each has a rule, its code’s letter its area:

Codes Area
AK-M… An item, a file’s format: a piece’s fields, the list of work, scripts, messages, docs, sheets
AK-B… The build: ids, network, time, imports, the installed SDK
AK-K… Parts: keys, a piece without parts
AK-D… Determinism
AK-T… Speech: word times, generated voices, ranges, word references, anchors, edits files
AK-S… Text: a missing key (S001), a missing translation (S002, a warning)
AK-A… Media and data files
AK-G… An unknown format
AK-P… Loading and drawing time
AK-R…, AK-N… Run time: an exception, the page changed, a style refused; a request blocked
AK-L… Layout and fonts: text cut at the frame’s edge, missing glyphs, fallback fonts (warnings)
AK-X… The matrix and its combos
AK-W… 3D sceneries

An error must be fixed: a render will not make a file with one. A warning is reported and the render goes on. What is a matter of judgment (text near a face, a loudness step between parts, a still stretch, a cut seam) is never a problem: it is a fact, with its numbers, which allyhub inspect prints for the agent to weigh.

Every default of the piece API has an option that changes it: defaults.md lists them with the option. A command’s defaults are in allyhub help <command>.

Was this page helpful?