# Provenance and Lifecycle

> Where a thing came from — Engine, Platform or Project — and what stage it is at: Definition, Scene Entity or Live Entity. Every noun has a coordinate on both.

- Source: https://diceytable.com/docs/editor/concepts/provenance
- Last verified: 2026-10-06

Two of the three axes DiceyTable describes a scene with. The third —
[composition](https://diceytable.com/docs/editor/concepts/scene-model) — tells you *what kind of thing* something
is. These two tell you **who defined it** and **what stage of its life it is at**.

They are orthogonal. A `light` component is Engine provenance; a light you placed in your
scene is a Scene Entity; the `pc.LightComponent` the runtime built from it is part of a Live
Entity. Same subject, three different coordinates, all true at once.

## Axis 1 — Provenance: who defined it

| Term | Meaning | Examples |
|---|---|---|
| **Engine** | Provided by PlayCanvas. | Engine components `render`, `rigidbody`, `collision`, `light`, `camera`, `script`, `sound`, `element`, `screen`. Engine systems such as `app.systems.rigidbody`. |
| **Platform** | Defined by DiceyTable, available in every project. | Platform entity kinds (`card`, `deck`, `die`, `token`, `board`, `bag`, `custom`, `card-holder`, `button`, `table`, `coin`); platform concepts (Seat Zone, Snap Point, Zone, Decal, Text Label, Joint, Wall, Poster, Room Light). |
| **Project** | Defined by an author, inside one mod or scene. | Project materials, textures, scripts, models, decks, and the authored scene itself. |

### Why the Inspector colors headers differently

The Inspector renders **Engine** sections and **Platform** panels with different header
accents. That is not decoration — it is the provenance axis made visible.

| Section | Provenance | Notes |
|---|---|---|
| `ENTITY` | — | Not a component at all. The entity header: enabled, name, slug, tags, transform, parent. |
| `PIECE` | **Platform** | DiceyTable's classification: entity kind (`TYPE`) and physical `SURFACE`. Sits above `RENDER` because those are not engine-render fields. |
| `RENDER` | **Engine** | Intrinsic. Material assignment. |
| `RIGIDBODY` | **Engine** | Intrinsic. |
| `COLLISION` | **Engine** | Intrinsic. |
| `LIGHT` | **Engine** | Optional; addable and removable. |
| `CAMERA` | **Engine** | Optional; addable and removable. |
| `SCRIPT` | **Engine** | Optional; the attached project script. |
| `DIE SETTINGS` | **Platform** | |
| `SOUND SETS (BUILT-IN)` | **Platform** | |
| `SOUND OVERRIDES` | **Platform** | |
| `ENTITY (ADVANCED)` | — | Read-only view of the Live Entity: guid, path, real component types, child Live Entities. |

`PIECE` is the section that used to make the question "what is a component?" unanswerable:
entity kind and surface material once lived inside `RENDER`, which implied they were render
fields. They are not. Splitting them out is why the accent colors are worth reading.

### Provenance in the project explorer

Provenance is not only a naming convention — it decides **what ends up in your GitHub repo**.

The project's Models, Materials and Textures folders list your own items *and* the built-ins
your scene actually references. Built-ins are shown there because leaving them out is a lie by
omission: the felt your table is made of is in the scene either way, and whether it is yours or
the platform's is what decides whether it is published.

Two badges tell you which is which:

| Badge | Provenance | Published to your repo? | Loaded from |
|---|---|---|---|
| *(none)* | **Project** | Yes | Your repo |
| Built-in | **Platform** | No | DiceyTable's standard items |

To change a built-in, copy it into the project (**Duplicate to project**, or drag it from the
Library pane). The copy is a **Project** item — published and loaded from your repo — that stays
**linked** to the built-in it came from: it can take the platform's later updates, be **Reset to
source**, or be **Detached**. See
[Credits and linked copies](https://diceytable.com/docs/editor/interface/asset-explorer#credits-and-linked-copies).

Projects made before linked copies existed may hold a material that kept a built-in's **id**,
which overrides the built-in of that id. Opening such a project in an editable tab gives it a
link record automatically, so it gets the same Reset to source / Detach actions. A read-only tab
(the project is open in another tab) writes nothing, and a built-in the platform no longer lists
gets no link. Because the original
built-in it was copied from is unknown, every setting that differs from today's built-in counts
as your change.

A separate **In use** badge marks anything the scene references, whatever its provenance. It is
advisory: deleting an item still in use is allowed (you often delete a texture precisely because
you are replacing what uses it), but you are told first rather than finding out when the table
renders a placeholder.

> Preset **overrides** made in the admin item editor are a different thing again: they are
> global to the platform, not stored in your project, and so are not shown as customization
> here. If they were, the badge would promise a publish that never happens.

## Axis 2 — Lifecycle: Definition, Scene Entity, Live Entity

| Term | Meaning | Where it lives |
|---|---|---|
| **Definition** (also *Template*, *Preset*, *Asset*) | The reusable blueprint. **Not in the scene.** | The project tree and asset explorer. |
| **Scene Entity** | An authored instance placed in the scene. **Persisted and replicated. Addressed by `id`.** | The scene document: its entities, seat zones, room lights, wall posters. |
| **Live Entity** | The `pc.Entity` the runtime builds from a Scene Entity. **Ephemeral. Addressed by `guid`. Never persisted.** | The running PlayCanvas graph. |

### The canonical sentence

> A **Scene Entity** is authored in the scene document and *instantiated* at runtime as a
> **Live Entity** (`pc.Entity`) carrying **Engine Components**.

That sentence encodes the whole model. Read it left to right:

1. **Authored in the scene document** — the document is what you edit and what gets saved.
2. **Instantiated at runtime** — the Live Entity is built *from* the document, downstream
   of it.
3. **Carrying Engine Components** — the components hang off the *Live* Entity, not the
   authored row. What the document stores is their authored state.

Read it right to left and you get the mistake it exists to prevent: the belief that the
`pc.Entity` is the thing, and the document a serialization of it. It is the other way
around, and [Document vs engine](https://diceytable.com/docs/editor/concepts/document-vs-engine) explains what
that rules out.

### Worked coordinates

| Subject | Provenance | Lifecycle | Composition |
|---|---|---|---|
| A standard die preset in the asset explorer | Platform | Definition | — |
| A GLB model you imported | Project | Definition | — |
| The `chess-board` row in your Hierarchy | Platform kind `board`, Project content | Scene Entity | Entity |
| The `pc.Entity` drawn for that row this frame | Engine | Live Entity | Entity |
| The `rigidbody` on it | Engine | Live Entity | Component |
| Its authored mass and friction | Platform schema | Scene Entity | (a Component's authored state) |
| `Lights (3)` in the Hierarchy | Platform | — | Folder |
| `seat-group-0` | Platform | — | Tag Group |

The two blank Lifecycle cells are not an oversight. A Folder and a Tag Group are authoring
constructs; neither is instantiated as anything.

## Identifier mapping

When you meet a schema or runtime identifier, this is what it is in the vocabulary:

| Identifier | Term |
|---|---|
| `TableObjectState` | a **Scene Entity** |
| `RuntimeObject.entity` (`pc.Entity`) | a **Live Entity** |
| `TableObjectKind` | the Scene Entity's **Platform kind** |
| `TableObjectTemplate`, `STANDARD_OBJECT_PRESETS` | **Definitions** |
| `TableObjectState.components[]` | **optional Engine Components** |
| `TableObjectState.physics`, `metadata.materialId` | the **intrinsic** Engine Components' authored state |
| `TableObjectState.parentId` | the **parent Scene Entity** |
| `TableObjectState.displayName` | the entity's **human name**; `label` is its **slug** |
| `TableJointState` | a **Joint** (a physics constraint) — never "parenting" |
| `EditSceneSnapshot` | the **scene document** |

The schema type names deliberately keep their original spelling. They are a stable
cross-boundary contract and renaming them would buy nothing; this vocabulary governs
user-facing language and new identifiers, not the wire format.

## Definitions are not in the scene

The most common lifecycle slip is talking about "the object in the asset explorer". There
is no entity in the asset explorer. There is a **Definition** — a model, a material, a
texture, a deck, a script, a preset — and dragging it into the scene *creates* a Scene
Entity from it.

The distinction has a practical edge:

- Editing a **Definition** (say, a material) affects every Scene Entity that references it.
- Editing a **Scene Entity** affects one row in the document.
- Editing a **Live Entity** affects nothing that survives the next rebuild.
