The Interface
The Hierarchy Panel
Edit Mode's authoring tree — filter and tag pills, folders and seat folders, Seat Template and Snap Points rows, eye and lock, context menus.
On this page8 sections
The Hierarchy is the middle panel of the left column and the main way you select things. It
is an authoring view of the scene document, keyed by id — not the PlayCanvas scene
graph. That distinction has consequences, and they are explained on Document vs
engine.
(open full size)Top to bottom the panel holds: a filter box, the tag pills, the Show engine entities
toggle, the tree itself, and — when that toggle is on — a second, read-only engine tree.
The tree#
The tree is built by buildSceneNodes and rendered by SceneTree. It always has the same
skeleton:
Game (dice — see the Inspector's Game panel)
Room
├─ Floor
├─ Walls
│ └─ North Wall … (posters nest under their wall)
├─ Ceiling
├─ Lights (N)
│ └─ Key Light …
├─ Sounds (N)
│ └─ Rain … (sound emitters)
└─ Table
├─ Player Zones (N)
│ ├─ Seat Template … (a name label, zones, card-holder definitions and piece groups)
│ └─ seat-group-0 … (zones and a name label — detached seats only)
├─ Entities (N)
│ ├─ Red … (a seat folder: what the seat template stamped for that seat)
│ ├─ Scenery … (your own folders)
│ └─ your entities, nested by parent
└─ Snap Points (N)
├─ Deck slots … (your own folders)
├─ Board (64) … (a grid, with its generated points inside)
└─ Discard … (points placed one at a time)
Each row shows an icon, an optional color swatch, the row's name, and a TYPE token at the
right. The token is not always the row's internal kind: grouping rows report folder,
seat groups report tag group, and an entity reports entity. A typed seat zone reports its
zone type (hand, area, hidden, scripting, …) instead of seat-zone, and a template's
card-holder row reports the kind it will generate. The mapping and the reason for it are on
The scene model.
Three details worth knowing:
Entities (N)counts every entity in the scene, not just the un-parented ones. Parenting something must not change the answer to "how many entities are here?".- Rows show the human name. The label is
objectDisplayName()—displayNameif set, otherwise the slug. See IDs, names and tags. - A broken parent link still renders. An entity whose
parentIdis dangling, self-referential or part of a cycle is drawn as a root row rather than disappearing. Showing it in the wrong place beats hiding it. (Both load paths prune such links on the next load.)
The tree changes shape in a purpose-built editor#
The skeleton above is what plain /editor shows. Each
editor mode assembles a different tree
rather than filtering this one — which is why a mode can promote a row to the top level, not
just hide it.
The Game Editor (/editor/game/{id}) is the clearest example. A game is composition: it
picks a room and a table and lays out seating and entities. It does not edit a wall. So Room
and Table collapse to two assignable leaf rows, and the two folders that used to nest
under Table are promoted to the top level:
Game Dice, players, debug overlays and scene scripts
Room Noir Parlour 1.2.0
Table Hex Wargame 2.0.1
Player Zones (10)
├─ Seat Template …
└─ seat-group-0 …
Entities (14)
└─ your entities, nested by parent
Snap Points (64)
└─ Board (64) …
Six rows instead of nineteen, and none of the twelve scenery rows a game author cannot meaningfully edit there.
Game is where the game-wide settings live. Clicking Room here opens the assign
inspector rather than plain /editor's Room settings, so the settings that are about the game
as a whole moved to their own row: Dice, Debug Visibility, Game Settings (player
counts) and Scene Scripts. See the Game panel.
Plain /editor has the Game row too, but there it carries only Dice. Its Room row still
holds the other three. The promotion is the load-bearing part: collapsing Table by filtering
would have taken Player Zones and Entities down with it.
The subtitle carries the assigned pack and its pinned version, and it is also where a problem with that pin becomes visible:
| Row reads | Means |
|---|---|
Room (default: Modern Room) (greyed) |
No pack assigned, so every peer uses the platform default — Modern Room for a room, Square Table (Table (default: Square Table)) for a table. A normal state, not an empty slot. Opening a game writes these defaults in as pins, so you mostly see this after Remove |
Room Noir Parlour 1.2.0 |
Pinned to that exact version |
Room Noir Parlour 1.2.0 · 1.3.0 available |
A newer version exists. It is an offer; nothing updates itself |
Room com.mattb.noir-parlour 1.2.0 unavailable |
No published pack answers to that id any more. The pin is kept — nothing was changed for you |
Room com.mattb.noir-parlour 1.2.0 (no name, no badge) |
The registry could not be read, so the pin was never checked. The inspector says so and offers Try again — this is not the unavailable case, and nothing is claimed about the pin |
Clicking either row opens its assign inspector.
Nothing is migrated and nothing is destroyed. A scene with hand-edited room internals — extra lights, posters, a moved wall — keeps every byte when you open it in the Game Editor. Only the rows are hidden, and the Room Editor is the way back to them.
The other three editors do the mirror of this. The Room Editor drops the table spine entirely and groups everything a room pack owns under three rows:
Room (the shell, and the props in it)
├─ Floor
│ └─ Openings (0)
├─ Walls
│ └─ North Wall
│ ├─ Openings (1) (a window belongs to the wall it is cut into)
│ └─ posters …
├─ Ceiling
│ └─ Openings (1)
└─ Decor (N)
Lights (N)
├─ Key Light …
└─ Old Chapel (2) (lights found inside a scenery model)
Sounds (N)
└─ Rain … (sound emitters)
Environment (sky, fog, the ground outside)
└─ Environment Scenery (N)
Three things there are worth stating plainly, because each replaced an earlier arrangement:
- Openings live under the surface they pierce. Each of the floor, the ceiling and the four
walls carries its own
Openings (N)folder, and the folder is rendered even when it is empty. A hole's coordinates are in its surface's basis and its size is bounded by that surface's extent, so filing them all in one room-wide folder made you choose the surface twice — once to find the wall, and again in a dropdown. - The
Roomrow owns the whole shell, includingDecor, and its inspector carries the global show/hide switches for floor, walls and ceiling. Hiding the built-in box so your own model can be the room used to take six visits to six panels. Environment Sceneryis a child ofEnvironment. The sky, the ground outside and the buildings standing on it are one subject at two distances.
Lights stays at the top level, because it is the one thing that belongs to both the room and
the world outside it. Sounds sits beside it for the same reason: rain on a window and birds
outside belong to neither the shell nor the scenery alone. Its rows are
sound emitters, with the TYPE token
sound emitter. They are not entities.
The Table Editor shows Model, Colliders (N), Triggers (N), Play Surface
and Seat Ring under one Table row; and the Asset Editor
shows Prefabs (N), Decks (N), Materials, Textures and Scripts — pieces, with no room,
no table, no player zones and no seat template, because an Asset pack owns none of those.
Rows in the Asset Editor carry a badge when the published document would refuse them: a
prefab bound to a script the pack does not ship reads missing script, a script attached to no
prefab reads orphan, and a deck that does not ride inside the document reads not bundled.
They are shown and named rather than dropped — a refusal first met at publish time has already
spent an immutable version.
The Seat Template row#
Player Zones sorts one Seat Template row first, above the seat groups, and renders it
whether or not a template exists — an author has to be able to see that the concept exists
before they have used it. With none defined it reads "Seat Template — not defined" and is
greyed; with one it carries TYPE token template and holds the template's name label, its
seat-local zones, its card-holder definitions and its starting-layout pieces (not the
entities those generate — those are real Scene Entities and live under Entities (N) like
anything else).
Pieces are listed by group. Pieces with the same model, colour, material and scale share one
row, such as Marble Black (10), which expands to its pieces. A piece unlike every other stays a
plain row. A group row reports TYPE folder, and a piece row reports the kind it generates
(custom, token, …). A group whose seats each get their own model or material carries a
per seat badge. See Platform panels.
It is not a seat: no color swatch, never claimable, and its rows carry their own kinds so
nothing keyed on a real seat's world transform can reach them. Its stableId is seat-template,
so the filter finds it by name or by that id.
Each seat group then carries a linked or detached badge — but only when a template
exists. With no template every seat is detached by definition, and badging all ten would be
noise rather than information, so a template-less scene renders exactly the tree it always did.
A linked seat renders no children. Its zones and label are the template's, so there is
nothing seat-specific to select, and ten linked seats would otherwise produce ~40
near-duplicate rows all saying the same thing. Select the seat group itself to reach its group
transform, color and label-text override; select the Seat Template row to edit the geometry.
A detached seat shows its zones and label exactly as before.
See Player Zones and seat templates for what linking means, and Platform panels for the fields on each row.
Variant marks#
For a game with variants, the tree shows one variant at a time — the one chosen in the top bar. Switching variants swaps the whole tree.
While a non-base variant is on screen, an entity row that differs from the base carries a
small mark before its TYPE token:
| Mark | Meaning | Hover text |
|---|---|---|
only here |
Only this variant has this entity. It was added while editing this variant. | Only this variant has this entity |
changed |
The base has this entity too, and this variant has its own version of it. | This variant has its own version of this entity |
| (no mark) | The entity is the base's, unchanged. | — |
Three things the marks do not show, and where to find them instead:
- Entities this variant has removed are not in the tree at all — a removed entity is not part of this variant's scene. They are listed, and can be restored, in the Variants dialog under Removed from.
- Only entity rows are marked. A variant with its own seats, zones, snap points, table or scene scripts shows them in the tree with no mark; the dialog lists those per group.
- The base variant shows no marks. It is what the others are compared against.
The marks are computed when the editor records a change, so one can appear a moment after the edit that caused it. Select a marked entity to act on it — the Inspector's Variant row offers Revert, Apply to all and Remove here.
Folders are shared by every variant. An entity that exists only in another variant keeps its place
in its folder, so switching variants never un-files anything; the folder simply shows fewer rows.
Entities (N) counts the entities in the variant on screen.
Folders in Entities and Snap Points#
Both sections can be organised into folders. A folder is organisation only: it has no transform, it is not an Entity, and filing a piece in one changes nothing about the piece — not its position, not its parent, not its physics. That is what separates it from parenting, which does move children with their parent.
Clicking a folder selects everything in it. The folder row becomes the Inspector's
target, and its contents become the multi-selection — so the gizmo, the arrow keys,
Ctrl+D, the SELECTION panel and GROUP EDIT all act on the whole set at once. A folder
whose contents are all selected is highlighted like a selected row. Ctrl/Cmd+click on a
folder is additive: it adds its contents to the selection, or removes them when they were all
in already.
Each folder row shows a count pill — the number of entities (or snap points, grid cells included) inside it, however deeply nested.
Giving a folder's entities a seat. Click the folder, then pick a seat in GROUP EDIT's Seat row: every
entity in it, subfolders included, now belongs to that seat — one undo step.
Clear seat takes it off again. See Multi-select § Seat. An entity
row whose entity has a seat shows a small round dot in the seat's colour after its name (hover it for the
seat's name) — round, so it never reads as the square swatch of a seat row itself.
Making folders:
| How | What happens |
|---|---|
Select entities or snap points and press Ctrl+G |
They move into a new folder, which is selected with its name ready to type |
| Right-click → Group Selection | The same, from the Hierarchy or the viewport |
New Folder in the Entities or Snap Points inspector, or right-click the section |
An empty folder at the top of the section |
| Right-click a folder → New Subfolder | An empty folder inside it |
A new folder is created where its contents already were: grouping three pieces that were
all inside Board makes the new folder inside Board. Selection works from either side —
pick pieces in the viewport (click, Ctrl+click, drag a box), right-click one of them, and
Group Selection groups all of them.
Filing by drag and drop. Drag any row onto a folder to file it there; a selected row
drags the whole selection. Folders drag into other folders too, and a folder cannot be
dropped into itself or one of its own subfolders. Dropping onto the section row
(Entities (N) or Snap Points (N)) takes rows back out of their folders — on Entities
it also detaches them from any parent, as it always has. An entity moved into a folder is
detached from its parent first, because a parented child always shows under its parent.
In the Snap Points section, a folder holds loose points and whole grids. A grid's
cells never leave their grid, so selecting a cell and grouping files its grid. Moving a
folder's selection with the gizmo moves its grids as blocks.
Renaming — double-click the folder, press F2 while it is selected, or use the Name
field in its Inspector. Enter commits, Escape cancels.
Removing folders:
- Ungroup (
Ctrl+Shift+G, or the folder's Inspector) removes the folder and puts everything it held back where the folder was. Nothing is deleted. - Delete Folder and Contents (
Delete, the context menu, or the Inspector) deletes the folder and everything in it, after a confirmation naming how many entities or points that is. Entities go with their children. - Remove from Folder (context menu) takes a row out of its folder without deleting it.
Duplicating a filed entity puts the copy in the same folder.
Seat folders
When the seat template stamps entities onto seats —
the ten marbles of each Chinese checkers player, a card holder per seat — Entities gives
every seat that has any a folder of its own, named and coloured like the seat. Inside it,
each piece group of two or more pieces gets a subfolder (Marble Black (10)); a piece
unlike every other stays a plain row. Seat folders start collapsed — hiding sixty marble
rows is their point — and your own folders start expanded.
Seat folders are derived, not stored: they follow the template, so they cannot be renamed, deleted or dragged, and a seat piece stays in its seat's folder rather than being filed in one of yours. Clicking one selects everything in it, exactly like any other folder.
The Snap Points folder#
Snap Points (N) is a sibling of Entities, never a child of it. A snap point is a
placement rule the table owns — it is what decides where a dropped piece lands — and it is
not a Scene Entity. Its TYPE token reads snap grid or snap point accordingly, never
entity and never component.
The folder has two kinds of child:
- A grid (
snap grid) is an authored block: a centre, a row and column count, a spacing per axis, a yaw and a radius. Its label carries how many points it generates, and those points are nested inside it — they belong to the grid, so deleting the grid row deletes them with it. - A point (
snap point) directly in the folder was placed on its own with the snap-point tool.
Selecting either attaches the transform gizmos, the same ones every other selection uses:
| Gizmo | On a point | On a grid |
|---|---|---|
| Move | its position | the grid's centre |
| Rotate | the facing a snapped piece is turned to | the yaw of the whole block |
| Scale | its snap radius | the two cell spacings |
Scale on a grid moves the cells apart; it never adds or removes one. Rows and columns are typed in the Inspector, so a drag cannot quietly change how many points a grid generates.
A generated point's geometry is read-only, and its panel says which grid owns it. Its
position, facing and radius come from the grid's layout, so an edit here would be discarded
by the next regeneration. Its name is editable, because generation preserves labels on
purpose — that is how a chessboard's squares come to be called a1.
Snap radius is the catchment a dropped piece is pulled into, and it is the one number both the drop rule and the viewport read. Turn on Show radii in the snap-point flyout to see it drawn as a disc on the table while you work.
A grid whose authored rows × columns exceeds the 1000 points a grid may generate is badged
truncated rather than silently shown at its real size — the same rule the Table Editor's
collider rows follow.
Scripts read a point's name with
world.getSnapPointAt, which is how a move
log prints "Matt moved White Pawn from e2 to e4".
Lights that came in inside a model#
A GLB can carry lights, and a building model routinely does. When you place one as environment
scenery, any lights inside it appear in Lights under a folder named after the placement, with
the TYPE token model light rather than light.
They are not the same thing as a light you added. The model owns where they are; the document records only your overrides — on/off, colour, intensity, range and shadow casting — so re-importing the model keeps your settings and moving the lamp in the model moves the light. There is no position field and no Delete, for the same reason.
Shadow casting is off by default whatever the model says. Shadow views are the number that can refuse a publish, so a light inside imported scenery has to be asked for one explicitly. The Lights folder shows the room's budget.
Expansion#
Room, Table, Walls, Lights, Sounds, Environment, Player Zones, Seat Template,
Snap Points, Entities and your own folders start
expanded — a collapsed template row would leave Player Zones looking like it holds no geometry
at all once its seats are linked. So does
any entity row that has children — an entity only has children when something is
parented to it, and collapsing those by default made parenting look like deletion.
Everything else — seat folders included — starts collapsed. Dropping rows into a collapsed
folder opens it. Your manual toggles are per-row and last for the session.
The filter#
An input with the placeholder Filter by name, id or #tag…. Escape inside the box clears
it; a × button appears next to it while any filter is active.
What it matches, per sceneNodeMatchesNeedle — all case-insensitive substring matches:
| Matched | Example |
|---|---|
| The row's displayed name | chess |
The entity id |
a fragment of the id |
The row's stableId, where it has one |
seat-group-0 |
| Any of the row's tags | hero |
What it deliberately does not match: the subtitle. Subtitles embed positions, sizes,
counts and intensities, so substring-matching them would make short or numeric queries hit
almost every row — typing 0 would "match" the whole tree. Everything addressable that a
subtitle used to advertise is now carried structurally in stableId and tags, so nothing
findable was lost.
The #tag form#
A leading # narrows the query to tags only. #seat-group selects every row carrying
that tag and nothing else. A bare # while you are still typing filters nothing.
How filtering shapes the tree#
- A row is kept if it matches or any of its descendants match, so the path to a match stays visible.
- A kept group's children are themselves filtered — you do not get a matching folder's entire contents back.
- An empty query filters nothing.
- While any filter is active the tree force-expands, so a match nested six levels down is visible without clicking.
- If nothing matches, the tree is replaced by
No matches.
The tag pills#
Below the filter, one pill per author tag present anywhere in the scene, sorted alphabetically, each showing the number of entities carrying it. Clicking a pill toggles it.
- Multiple pills are ANDed. Clicking
herothenblueshows blue heroes, not everything blue or heroic. The pills are a narrowing tool. - A
clearpill appears once at least one is active. - A pill whose tag no longer exists anywhere — you deleted or untagged the last entity carrying it — is dropped automatically, so the tree can never filter down to nothing with no visible cause.
- The pill list is built from authored tags. Reserved
dt:platform tags are not authorable and never appear as pills; they show as dimmed, non-removable chips in the Inspector'sTAGSfield. See thedt:namespace.
Active pills also feed the Inspector's GROUP EDIT panel, which can scope a bulk edit to
"everything tagged this". Tag authoring and bulk tag operations are covered in Tags and
groups.
Row controls: eye and lock#
Each row can carry up to two icon buttons on its right-hand side.
The eye — visibility#
Shown on entity rows always, and on a group row whenever its subtree contains at least one entity. Toggling a group's eye acts on every entity in its subtree, and the group's eye reads "off" only when every one of them is hidden.
Hiding writes metadata.enabled = false on each affected entity and pushes the change to
the runtime live, without re-applying the whole scene. It is the same flag as the
Inspector's ENTITY → Enabled checkbox, and per PlayCanvas semantics disabling an entity
disables everything on it.
The lock — protect from editing#
Shown on entity rows only. It writes the real schema field locked and is pushed live:
a locked entity gets a static body, and the runtime's gizmo and selection guards refuse to
drag it. A locked row keeps its icon permanently visible so locked entities scan at a
glance.
Selection#
- Click selects the row and makes it the Inspector's target.
Ctrl/Cmd+click adds or removes an entity row from the multi-selection.Shift+click selects the range between the anchor row and the clicked row, in visible order.
Modifier clicks mean nothing on section folders (Entities, Room, …) and seat-group rows.
A folder you made, or a seat folder, is different: clicking it selects its contents, and
Ctrl/Cmd+click adds them to the selection — see Folders.
Dropping the primary selection promotes another member, so the Inspector never goes blank
while rows are still selected.
Dragging an entity row onto another entity parents it; dragging onto the Entities folder
detaches it to the root. A row that is part of the multi-selection drags the whole
selection. The drop target renders differently for a legal and an illegal target, and a
rejected drop reports its reason rather than silently doing nothing.
Both of those are their own topic: Multi-select and Parenting.
The context menu#
Right-clicking a row selects it first — unless it is already part of a multi-selection, which
is kept — then opens a menu at the pointer. Right-clicking a piece in the viewport opens
the same menu for that entity. (A right-drag orbits the camera and opens nothing.) It closes on
Escape or on any pointer-down outside it, keeps itself inside the viewport near an edge,
focuses its first enabled item on open, and supports ArrowUp/ArrowDown. Its header shows
the row's name, with the row's id as the tooltip.
(open full size)The item list depends on what you right-clicked.
Entity rows (and lights and posters)#
| Item | Shortcut | Enabled when |
|---|---|---|
| Rename | F2 |
Entity, light or poster — anything with a name field. Focuses and selects the Inspector's name field. |
| Duplicate | Ctrl+D |
Entity rows |
| Detach from parent | — | Entity rows that have a parent |
| Group Selection | Ctrl+G |
Always — groups the selection into a new folder |
| Remove from Folder | — | Entity rows filed in a folder |
| Copy | Ctrl+C |
Entity rows |
| Paste | Ctrl+V |
Entity rows, when the clipboard holds something |
| Focus | — | Always |
| Hide / Show | — | Entity rows; label flips with current state |
| Lock / Unlock | — | Entity rows; label flips with current state |
| Delete | Delete |
Deletable kinds only |
Detach from parent is always non-destructive: the entity keeps its own authored physics, and the parent keeps its other children.
Focusdoes not move the camera. It calls the runtime'sselectObject, which re-asserts selection, glow and gizmo. Camera framing is not implemented behind this item. This is reported as a bug — see the same note on the transform rail.
Folder rows#
| Item | Shortcut | Does |
|---|---|---|
| Rename | F2 |
Edits the name in place |
| New Subfolder | — | An empty folder inside this one |
| Select Contents | — | Selects everything inside |
| Group into New Folder | Ctrl+G |
Wraps this folder in a new one |
| Ungroup | Ctrl+Shift+G |
Removes the folder, keeps its contents |
| Remove from Folder | — | Moves a nested folder up to the section root |
| Delete Folder and Contents | Delete |
Deletes the folder and everything in it, after a confirmation |
A seat folder offers only Select Contents. The Entities (N) and Snap Points (N) rows
offer New Folder and Group Selection; snap-point and grid rows offer Group Selection,
Remove from Folder and Focus.
Seat-group rows#
Add Zone · Focus · Delete Player Zone — the last deletes the whole seat, every zone
plus its name label, behind a confirmation.
Seat-zone and seat-label rows#
Focus · Delete.
Seat-template rows#
The Seat Template row and its children fall through to the generic menu with only Focus
enabled. A template's zones and card-holder definitions are deleted from the Inspector
(Delete Zone, Delete Card Holder) rather than from the tree, because deleting a template
holder also removes the entities it generated on every linked seat — a consequence the tree row
cannot show you.
What is deletable#
isDeletableKind allows exactly: entities, seat zones, whole seat groups, room lights and
posters — plus your own folders, which Delete removes together with their contents.
Room, Table, the section folders, seat folders, surfaces, walls, seat labels and every
seat-template row are structural and cannot be deleted here.
Show engine entities#
A checkbox above the tree: "Show the live PlayCanvas entity graph (read-only debug view)."
Turning it on appends a second tree below the authoring tree, showing the real
pc.Entity graph with a refresh control. It is off by default and persisted per user in
localStorage under diceytable.editor.showEngineEntities.
It is deliberately kept out of the authoring tree: the engine graph is full of internal entities, explodes an imported model into dozens of rows, and its guids change on every rebuild. Nothing in it is addressable from a scene script or a mod.
The per-entity equivalent is the Inspector's read-only ENTITY (ADVANCED) section —
Entity (Advanced).
What the Hierarchy writes#
| Control | Written where |
|---|---|
| Filter, tag pills, expansion | Nothing — view state only |
Show engine entities |
localStorage only |
| Eye | metadata.enabled on each affected entity, plus a live runtime push |
| Lock | locked on the entity, plus a live runtime push |
| Drag to reparent | parentId, via a reparent intent |
| Folders — group, file, rename, ungroup | hierarchyFolders on the scene document. Editor-only: never replicated, and never rebuilds the viewport |
| Context menu | Depends on the item — rename, duplicate, delete, detach, hide, lock all write the document |
