The Scene Model

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. 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.