# The Scene Model

> Entity, Component, System, Folder and Tag Group — the five composition nouns DiceyTable uses, and why Component never means a thing you place on the table.

- Source: https://diceytable.com/docs/editor/concepts/scene-model
- Last verified: 2026-07-27

DiceyTable describes every noun in a scene along **three orthogonal axes**. Not one list —
three. Every noun gets a coordinate on each of them.

| Axis | Question it answers | Values |
|---|---|---|
| **Provenance** | Who defined it? | Engine · Platform · Project |
| **Lifecycle** | What stage is it at? | Definition · Scene Entity · Live Entity |
| **Composition** | What kind of thing is it? | Entity · Component · System · Folder · Tag Group |

The first two axes are covered on [Provenance and
lifecycle](https://diceytable.com/docs/editor/concepts/provenance). This page is the third one, and it is the axis
people get wrong, because PlayCanvas already owns the word *Component* and it is tempting to
reuse it for the things you put on a table.

Do not. **In DiceyTable, a thing you put on the table is an Entity.**

## The five composition nouns

| Term | Rule |
|---|---|
| **Entity** | A container with a transform and no behavior of its own. Every Hierarchy row with a transform is an Entity. |
| **Component** | Data and behavior attached to one Entity. **Only ever `render`, `rigidbody`, `collision`, `light`, `camera`, `script`, `sound`, `element` or `screen`.** Never used for anything else, in code, in the UI, or in these docs. |
| **System** | Owns every instance of one component type and processes them in batches. Engine-internal; never exposed in the editor. |
| **Folder** | A Hierarchy grouping row that is *not* an Entity and has no transform — Room, Walls, Lights, Table, Player Zones, Entities. |
| **Tag Group** | A set of Entities defined by a shared tag, such as `seat-group`. Not a parent; membership is by tag. |

### Entity

An Entity is a container. It has a transform — position, rotation, scale — and by itself it
does nothing. Behavior comes from the Components attached to it, and in DiceyTable's case
most of the behavior actually lives in the runtime rather than on the entity at all.

A card, a die, a token, a board, a bag, a wall, a seat zone, a light: each of those is an
Entity. In the Hierarchy they appear under the **`Entities (N)`** folder, whose count is
every entity in the scene, not just the un-parented ones — the folder answers "how many
entities are in this scene?", and nesting must not change that answer.

Entities can be parented to each other. Parenting is a transform and organization
relationship: a parent's position and rotation propagate to its children for free, and a
parent's scale multiplies every descendant's world scale. Chains are capped at a depth of
**8**, following PlayCanvas's own advice to keep hierarchies shallow.

### Component

A Component adds data and behavior to exactly one Entity. The word is reserved for the
engine's component types and nothing else.

Two consequences follow, and both matter when you are reading the Inspector:

- The Hierarchy folder holding your table entities is **`Entities (N)`**. It was once called
  `Components (N)`, which was plainly wrong — it contains Entities.
- Inspector sections that are *not* engine components (`PIECE`, `DIE SETTINGS`, `SOUND SETS
  (BUILT-IN)`, `SOUND OVERRIDES`) are **Platform panels**, and the Inspector gives them a
  different header accent so you can tell at a glance which is which.

### System

A System owns all instances of one component type — `app.systems.rigidbody` owns every
rigidbody — and processes them in batches. That batching is why an ECS is fast. You never
touch a System from the editor, a scene script or a mod; it is listed here only so the word
has a definition when you meet it in PlayCanvas's own documentation.

### Folder

A Folder is a Hierarchy row with **no transform and no entity behind it**. Room, Walls,
Lights, Table, Player Zones and Entities are Folders. You cannot move a Folder, parent
something to it, or address it from a script — it is a section header for the authoring
tree.

The Hierarchy's `TYPE` column shows `folder` for these rows rather than their internal kind,
because the internal kind would be a lie about what the row is.

### Tag Group

A Tag Group is a set of Entities that share a tag. The `seat-group` rows in the Hierarchy
are the built-in example: the entities in a seat group are not children of anything, they
just carry the same tag. The `TYPE` column shows `tag group`.

The distinction from a Folder is that a Tag Group has *members*, and membership is
computed. The distinction from parenting is that a Tag Group is not a parent — moving a
"group" does not move its members, because there is nothing to move.

## The Hierarchy's node kinds

The Hierarchy panel is an authoring view. Each row's `TYPE` token tells you which
composition noun it is:

| Row | `TYPE` token | What it genuinely is |
|---|---|---|
| `Room` | `folder` | Folder (scene section) |
| `Floor` / `Ceiling` | `entity` | Entity with `render` + `collision` |
| `Walls` | `folder` | Folder |
| `North Wall` | `wall` | Scene Entity |
| A poster | `poster` | Scene Entity |
| `Lights (3)` | `folder` | Folder |
| `Key Light` | `light` | Scene Entity with a `light` component |
| `Table` | `folder` | Folder |
| `Player Zones (N)` | `folder` | Folder |
| `seat-group-0` | `tag group` | Tag Group (`#seat-group`) |
| `Zone 1` | `seat-zone` | Scene Entity |
| `Name Label` | `seat-label` | Scene Entity |
| **`Entities (N)`** | `folder` | Folder |
| `chess-board` | `entity` | Scene Entity |

The column keeps the *specific* type where the specific type is honest, and falls back to
`folder` / `tag group` / `entity` where it would not be.

## Two tiers of Component: intrinsic and optional

DiceyTable splits engine components into two tiers. **This is a decision, not an
inconsistency**, and it is worth understanding because it is the first thing that looks odd
in the Inspector: `RENDER`, `RIGIDBODY` and `COLLISION` are always present and cannot be
removed, while `LIGHT` and `CAMERA` appear only if you add them.

### Intrinsic components — `render`, `collision`, `rigidbody`

Every Scene Entity has all three. Their authored state lives where it always has — in
`physics` and in `metadata.materialId` on the entity — rather than in a component list.
They are **configured and disabled, never removed**, which follows the engine's own guidance
that disabling a component is cheaper than removing and recreating it.

`RIGIDBODY` and `COLLISION` each have a real enable flag (`physics.rigidbodyEnabled` and
`physics.collisionEnabled`; absent means enabled). Disabling `rigidbody` takes the body out
of the simulation without discarding its authored mass, friction and shape. Disabling
`collision` makes the entity pass-through while staying visible and grabbable.

`RENDER` has **no enable checkbox**. Visibility is owned end-to-end by one writer — the
system that also encodes card-face and hidden-information rules — and a second writer would
fight it. The entity's own **`Enabled`** toggle in the `ENTITY` header is the control.

### Optional components — `light` and `camera`

These are listed in the entity's `components[]` array: a discriminated union, capped at
**8 entries**, at most one per type, addable and removable. Today the addable set is
exactly:

```
light · camera
```

`script` is **not** in that list. A scene script is attached through `metadata.scriptId` and
its own `SCRIPT` Inspector section — there is one attachment story, not a modern one and a
legacy one.

### Why not one unified list?

Unifying would mean migrating `ObjectPhysics` and `metadata.materialId` into `components[]`
— a breaking change to the most-touched shape in the codebase, in exchange for cosmetic
tidiness. The two-tier split is honest, it matches how the entity model already works, and
it matches what the Inspector already shows you.

### Which component types are exposed, and why

A type becomes addable only when four gates pass:

| Gate | Requirement |
|---|---|
| **G1** | An authored shape exists in the shared schema. |
| **G2** | The runtime re-applies it on every document rebuild. |
| **G3** | It survives equality comparison → delta → host migration → save and load. |
| **G4** | Adding it cannot destabilise physics or change authority. |

| Component | Verdict |
|---|---|
| `render`, `collision`, `rigidbody` | **Intrinsic** — configure and disable, never remove |
| `script` | Exposed, via `metadata.scriptId` and the `SCRIPT` section |
| `light` | Exposed — addable and removable |
| `camera` | Exposed, with guardrails: added **disabled**, priority pinned strictly below the table camera, and at most one enabled entity camera at a time |
| `sound` | **Not exposed** — superseded by the spatial-sound system; use `SOUND OVERRIDES` |
| `element` / `screen` | **Not exposed** — world-space UI is owned by the table's UI state |
| `anim`, `particlesystem` | **Not exposed** — no runtime support |

Unsupported types are shown grayed out in the **`+ ADD COMPONENT`** popover with a one-line
reason rather than hidden, so "why can't I add a particle system?" answers itself.

## Say this, not that

This table is normative. New UI strings, identifiers and documentation prose follow it.

| Say | Not | Why |
|---|---|---|
| Entity / Scene Entity | Component, Piece, Object (as a type label) | "Component" is taken by the engine |
| `Entities (N)` folder | `Components (N)` | It contains Entities |
| Engine Component | Component, unqualified, where ambiguity is possible | Disambiguates from Platform panels |
| Platform panel | Component, for `DIE SETTINGS`, `SOUND OVERRIDES`, `PIECE` | Those are not engine components |
| Live Entity / `guid` | "the entity", when you mean the `pc.Entity` | Distinguishes it from the authored row |
| Scene Entity / `id` | "the entity", when you mean the document row | `id` is the only stable key |
| Folder | Group, when the row has no transform | A Folder is not an Entity |
| Tag Group | Group, when membership is by tag | A Tag Group is not a parent |
| Definition / Template / Preset | "the object", in the asset explorer | It is not in the scene |
| **Parenting** | Grouping, welding, joining | Parenting is transform and organization |
| **Joint** | Parenting, welding | A Joint is a physics constraint between two dynamic bodies |
| **Weld** (compound) | Parenting, joint | A Weld is one physics body for a rigid sub-assembly |

### Words that are retired

- **"Component"** as a synonym for a thing on the table. It is an engine component or it is
  nothing.
- **"Piece"** and **"Object"** as *formal* terms. Both are fine in ordinary prose and
  marketing copy. Neither is a type label in the UI, an identifier in new code, or a term in
  these docs.

## Parenting, welding and joints are three different things

They are easy to confuse because all three make several entities behave as one. The
one-line rule:

> **Parenting** gives a child a parent transform, and makes it kinematic.
> **Weld** merges children into the parent's single compound rigidbody.
> **Joints** connect two independently-dynamic bodies with a physics constraint.

Each has its own page later in this guide. What matters here is that they are distinct
nouns and the docs never use one to mean another.
