Skip to content
zabloo

Glossary

The words the rest of these docs are written in — envelope, IR, binding, named action, degradation — each in one plain sentence and one example from the same shop screen.

These are the words the rest of the documentation is written in. Each one gets one plain sentence and one example, and the examples are all the same screen: the guild shop the getting started guide builds, with a gold counter and a list of things to buy. Read the page once from the top and the format reference stops needing footnotes; after that, come back to it by link whenever a page uses a word you have not met.

What ships

Envelope

An envelope is the one JSON file the game downloads and draws: a version number, a dictionary of tokens, one or more views, and the images they use.

The shop screen, its theme and its icons travel together in a single envelope, and the game loads it the same way whether it came from your editor or from a hot-update. Full page: The envelope.

{ "v": 1, "tokens": { … }, "views": { "shop": { … } }, "assets": { … } }

IR

The IR — intermediate representation — is the format inside the envelope: a tree of nodes carrying layout, style, and the two hooks into the game.

It is data and only data. It cannot branch, compute or call anything, which is what makes it safe to send into a game that shipped months ago: a new envelope changes what a player sees without changing what the build can do. Full section: The format.

{ "type": "Text", "text": { "bind": "player.gold" }, "style": { "fontSize": 20 } }

View

A view is one screen inside the envelope, stored under an id the game asks for by name.

One envelope carries several — hud, shop, settings — and the game decides which one is on screen. In a scaffolded project every .tsx file in src/views/ is a view, and the filename is the id.

"views": { "shop": { "type": "Container", "children": [ … ] } }

Token

A token is a named value — a color, a spacing, a radius — that styles point at instead of writing the number themselves.

The gold of the shop’s counter is {color.gold} in every node that uses it, so re-theming the whole UI is a new dictionary rather than a new tree. That is why a theme can be hot-updated on its own. Full page: Style & tokens.

"tokens": { "color.gold": "#facc15" },
"style":  { "color": "{color.gold}" }

What draws it

SDK

The SDK is the open-source library you install in your engine: it loads the envelope, lays it out, draws it, and gives the game the API to drive it.

Unity is the reference SDK for v1. @zabloo/renderer-web is the same contract on a web page — it is what runs the live previews on this site, and what the pnpm dev preview uses while you author.

Renderer

The renderer is the drawing half of the SDK: its own layout pass, its own tessellator, its own glyph atlas.

It self-renders, so there is no DOM and no engine widget behind a zabloo UI — the shop screen is drawn on the GPU from the same envelope everywhere. That is why the product page can let you press Run on the real thing instead of showing a picture of it.

Node, primitive, composite

A node is one element of the tree in a view: a type, its layout, its style, its children.

A primitive is one of the thirteen node types the IR defines — the closed set the catalog documents, one page each. A composite is a component @zabloo/react exports for convenience — List, Row, Modal — that flattens into primitives when you export and never reaches the IR.

The shop’s list of items is authored as <List>, a composite; what the game receives is a Repeat node, a primitive.

What the game and the UI exchange

Two words in this group carry the whole product. The game owns the data; the UI only says where to read it — that is a binding. The UI fires names, not functions — that is a named action. There is no third mechanism, and nothing else in the format is dynamic.

Binding

A binding is an address into the game’s data, written where a value would otherwise go.

The gold counter is not given a number: it is given player.gold, and it reads whatever the game has there, re-laying out when that moves. The game pushes; the UI follows. Full page: Bindings & actions.

{ "type": "Text", "text": { "bind": "player.gold" } }

Data path

A data path is that address: dot-separated segments, where a numeric segment indexes an array and nothing else does.

Reading a path is total — one that leads nowhere yields no value, so a binding whose data has not arrived yet renders nothing instead of breaking the frame.

player.gold
shop.items.3.name

Named action

A named action is a string the UI fires and the game subscribes to.

The shop’s Buy button declares "buy"; what buying does lives in the game and never in the JSON. That is exactly what lets the screen be replaced without touching the build — the UI fires names, not functions, because a function cannot be serialized.

{ "type": "Button", "onClick": "buy" }

Action context

An action context is what an action fired from inside a repeated row carries with it, so the game can tell which row fired it.

Without it, every Buy button in the shop would send the same bare "buy". With it, the game receives the item’s path, its stable key and its position.

{ "path": "shop.items.3", "key": "sword-01", "index": 3 }

Host channel

The host channel is the runtime API the game drives the UI through: seven operations going in, three callbacks coming back.

SetData("player.gold", 1250) moves the number the counter is bound to; onAction is where "buy" arrives. It is deliberately not part of the envelope — these are runtime operations, and a document has no place to put them. Full page: The host channel.

How it holds up over time

Hot-update

A hot-update is publishing a new envelope to a build players already have installed.

Because the screens travel as data, moving the Buy button or adding a row to the shop is a new payload rather than a new build — nothing is recompiled and nothing is reinstalled. It is also why an SDK meeting content newer than itself is the normal case here rather than the error case.

Degradation

Degradation is what an SDK does with the parts of an envelope it does not recognize, instead of failing.

An unknown node type draws as a Container keeping its layout, style and children; an unknown property is ignored; an unknown value in a closed set falls back to that property’s default. The result is a screen that is incomplete rather than wrong — and a corrupt envelope never takes the game down. Full pages: Loading and Versioning.

Focus scope

A focus scope is the region keyboard and gamepad navigation is allowed to move within.

Normally it is the whole view. While a modal Overlay is up — the shop’s “confirm purchase” dialog — the scope is that overlay’s subtree: the pad cannot walk back into the list behind it, and closing the dialog restores the focus to where it was. Full page: Input & focus.