# Finding and Selecting Entities

> How to search the Hierarchy by name, id or #tag, what the eye and lock icons toggle, and how selection ties the Hierarchy to the viewport.

- Source: https://diceytable.com/docs/editor/working/hierarchy-and-selection
- Last verified: 2026-09-14

The Hierarchy is the left-hand tree in [Edit Mode](https://diceytable.com/docs/editor). It is an **authoring view of
the scene document** — not the engine's scene graph — so selecting a row always means
selecting a [Scene Entity](https://diceytable.com/docs/editor/concepts/glossary#scene-entity) or
[Folder](https://diceytable.com/docs/editor/concepts/glossary#folder) by its stable [id](https://diceytable.com/docs/editor/concepts/ids-names-tags#id-the-address),
never a `pc.Entity` by guid. See [Document vs engine](https://diceytable.com/docs/editor/concepts/document-vs-engine)
for why that distinction matters.

![The Hierarchy tree showing folders and entities available for selection, filtering and tag-based navigation](https://diceytable.com/docs/editor/working/hierarchy-and-selection.webp)

## Selecting something

Click a row to select it. Selection is shared across the shell: the same row highlights in
the Hierarchy, the viewport frames its gizmo, and the Inspector on the right switches to that
row's fields. Selecting a row in the viewport (clicking an entity on the table) selects the
matching Hierarchy row too — the two are the same selection, not two selections kept in sync.

Only rows with a transform behind them are selectable as "objects" in the sense the toolbar
and context menu mean it. [Folders](https://diceytable.com/docs/editor/concepts/scene-model#folder) (`Room`, `Walls`,
`Lights`, `Table`, `Player Zones`, `Entities (N)`) and
[Tag Groups](https://diceytable.com/docs/editor/concepts/scene-model#tag-group) (`seat-group-0`) can be selected to
see a summary in the Inspector, but they have no transform to move, and no Duplicate, Hide or
Lock action — those are object-only.

That holds for multi-selections too. Ctrl/Cmd-click and Shift-click in the Hierarchy, and
Ctrl/Cmd-click or a box dragged over empty space in the viewport, all build the same selection: the
rows highlight, the entities glow, the gizmo attaches to every unlocked member, and the Inspector
adds a `SELECTION (N)` panel. It is its own page: see
[Multi-select](https://diceytable.com/docs/editor/working/multi-select).

## Filtering the tree

The filter box above the tree (placeholder: *"Filter by name, id or #tag…"*) matches every row
against a single needle, case-insensitively:

- **Plain text** matches the row's [displayName](https://diceytable.com/docs/editor/concepts/ids-names-tags#displayname-for-humans),
  its internal `id`, its `stableId` (the structural id folders and tag-group rows carry, e.g.
  `seat-group-0`), and its tags — as substrings.
- **A leading `#`** narrows the match to **tags only**, so `#seat-group` selects every row
  tagged `seat-group` and nothing else. This is deliberate: tags are the preferred grouping
  mechanism (`docs/memory/playcanvas-ecs.md`), and the `#` form is how you search by them
  without also matching stray text.

A row's descriptive **subtitle** — the `card · pos 0.0, 0.0, 0.0`, `4 walls`,
`1.0×1.0`-style caption shown under some rows — is **deliberately not matched**. Subtitles
embed positions, sizes, counts and intensities, so substring-matching them would make a short
or numeric query (typing `0`) hit nearly the whole tree. Anything a subtitle used to be the
only way to find (a seat group's stable id, its `#seat-group` tag) is matched structurally
through `stableId`/tags instead, so nothing findable is lost by this rule.

A row is kept if it matches, or if any descendant matches — matching a deeply-nested entity
keeps every ancestor visible as the path down to it, and a filtered tree force-expands so the
match is actually on screen rather than inside a collapsed folder.

## The eye icon — hide

The eye icon toggles `metadata.enabled` on a table entity — the **same field** the `ENTITY`
header's `Enabled` checkbox in the Inspector controls (`TableEditModeShell.tsx` — the hierarchy
eye state and the Inspector's `Enabled` checkbox both read
`object.metadata?.enabled !== false`). It is not a separate hierarchy-only concept; it is a
shortcut to the entity-level control described in
[The Scene Model](https://diceytable.com/docs/editor/concepts/scene-model#intrinsic-components-render-collision-rigidbody).

Disabling an entity this way turns it, and every [component](https://diceytable.com/docs/editor/concepts/scene-model#component)
on it, off. In **Edit Mode only**, a disabled entity still renders as a dim wireframe ghost
rather than disappearing outright, so you can still find and re-enable it without hunting
through the Hierarchy blind — Play mode never does this.

Clicking the eye on a **folder row** (`Entities (N)`, `Lights (N)`, …) hides or shows every
table entity underneath it in one click; the icon reflects whether every descendant is
currently hidden.

## The lock icon — lock

The lock icon toggles `locked`, a real field on the entity's authored state (not a
`metadata` convention). A locked entity:

- becomes a **static** physics body — nothing, including a thrown die, can push it — instead of
  its authored body type,
- cannot be picked up, dragged, or attached to the transform gizmo,
- stays fully visible and interactive to everything except the pointer/gizmo.

Lock is for "stop me from accidentally moving this" — a table surface prop, a fixed marker —
without hiding it or removing it from the scene.

## Keyboard and the context menu

Right-clicking an object row opens a context menu with Duplicate (`Ctrl+D`), Copy/Paste, Hide
and Lock — the same actions as the toolbar and the eye/lock icons, gated to object rows only.
`Delete`/`Backspace` deletes the selected node when focus is not inside a text field, for every
deletable kind (`object`, `seat-zone`, `seat-group`, `light`, `poster` — Room/Table/groups/
surfaces/walls are structural and cannot be deleted this way). With several entities selected it
deletes all of them after one confirmation, and `Ctrl+C` / `Ctrl+D` likewise copy or duplicate
the whole selection.

## Common mistakes

- **Hiding something and then wondering why it's still visible.** In Edit Mode a hidden entity
  is a dim wireframe ghost, not invisible — that is deliberate, so you don't lose track of it.
  It will be fully invisible once you switch to the live table.
- **Locking an entity and then trying to drag it.** A locked entity will not respond to the
  pointer or the transform gizmo at all — check the lock icon before assuming a drag is broken.
- **Typing a number into the filter expecting it to match a position.** Subtitles (which carry
  numeric positions/sizes) are not searched on purpose — search by name, id or `#tag` instead.
- **Assuming "hide" and "delete" are related.** Hiding never removes anything from the scene
  document; it only sets `metadata.enabled = false`. Nothing about a hidden entity's identity,
  tags or transform changes.
