UUID

A UUID is the persistent identifier of a block. Every block has one, assigned at creation. The UUID survives every save and load: a block’s UUID in a template file is the same UUID when that template is opened in a different session, on a different device, or in a different environment entirely.

This is what makes UUIDs the right anchor for external references to specific blocks. The numeric handle the engine uses for in-session API calls is fast but is not stable across sessions. UUIDs are slower to look up but persist through serialization.

The decision depends on how long the reference needs to live.

Numeric handle. The lightweight identifier the engine uses internally while a scene is loaded. Every API call that addresses a block uses its handle. Handles are valid only for the current session. Loading the same scene file twice can produce different handles for the same blocks, so handles must not be stored externally or relied on after a reload.

UUID. The persistent identifier that survives serialization. A block’s UUID is part of its saved state, so it is the same UUID across save, load, archive, and string serialization. The right choice when the reference needs to outlive the current session: storing a pointer to a specific block in a database, identifying placeholder targets across template versions, building automation that addresses the same block consistently over time.

The most common pattern is template-driven automation. A template’s headline placeholder has a stable UUID. The automation pipeline stores that UUID alongside the template ID in a database. When the pipeline runs, it loads the template, finds the block by UUID, sets the headline text from a data record, and exports. The lookup by UUID works because the UUID is the same every time the template loads, regardless of which server runs the pipeline or which session is doing the rendering.

UUIDs are also exposed as properties on shapes, which makes shape-specific properties queryable across sessions the same way block properties are.

The Block API provides a find-by-UUID method that returns the block with a given UUID in the currently loaded scene. The UUID is also stored in the serialized scene file, so it persists through save-to-string and save-to-archive operations.

See block for the block primitive, block-kind for the semantic-label alternative when UUID is not appropriate (multiple blocks of the same kind), and template for how UUIDs are used in template automation.