# Edit Mode

> Edit Mode is DiceyTable's authoring environment: a scene document you edit directly, with physics frozen by default and nothing uploaded to a server.

- Source: https://diceytable.com/docs/editor
- Last verified: 2026-08-11

**Edit Mode** is where you build a game. It is the same PlayCanvas table players sit at, put
into an authoring state: physics held still, an editable hierarchy on the left, an Inspector
on the right, and an asset explorer underneath. You reach it at `/editor`, or from the Edit
Mode toggle on the `/table` toolbar.

Everything you do in Edit Mode writes to one thing — the **scene document**. Understanding
that single fact explains most of the editor's behavior, so it has [a page of its
own](https://diceytable.com/docs/editor/concepts/document-vs-engine).

Edit Mode is built for a **desktop or tablet**. On a tablet the panels and buttons are
touch-sized and the transform gizmo is operable by finger; opening it on a **phone** shows a
prompt to switch to a larger screen, because the hierarchy, Inspector and gizmos need the
room. The live `/table` itself is fully playable on a phone — only authoring needs the space.

## What you are actually editing

You are not moving PlayCanvas entities around. You are editing a **document**, and the
engine is redrawn from it.

When you drag a die two feet to the left, the editor writes the new position into the scene
document and the runtime rebuilds the die's live entity to match. The live entity is a
render artefact. It is destroyed and recreated whenever the document is re-applied, and
nothing that lives only on it survives that.

This is why the editor can save, version, restore, replicate and export a scene without ever
serializing the engine's scene graph — and why "it looked right until I reloaded" is almost
always a symptom of something written to the engine but not to the document.

## How Edit Mode differs from the live table

| | Live table | Edit Mode |
|---|---|---|
| What you manipulate | A replicated `TableSnapshot` | An `EditSceneSnapshot` — the scene document |
| Physics | Always simulating | **Frozen by default** — entities hold their authored position |
| The hierarchy | Not shown | The full authoring tree: Room, Walls, Lights, Table, Player Zones, Entities |
| Names | Display names only | Both the human `Name` and the machine `Slug`, side by side |
| Where changes go | Broadcast to every peer by the host | Into your local draft until you save a version or publish |

### Frozen vs Live

The viewport toolbar has a **Frozen / Live** pair, and it starts on **Frozen**.

- **Frozen** — entities hold their position. This is what makes authoring deterministic: you
  can place a board, set a die on top of it and reload without everything having settled
  somewhere else overnight.
- **Live** — physics runs, so you can test how entities actually behave.

Frozen is not a "preview off" switch — the scene is fully rendered either way. It only
governs whether the simulation steps. Running a scene script switches Frozen to Live
automatically, because most scripts need physics to observe motion at all.

Frozen mode is the single most commonly misread editor behavior. If an entity refuses to
fall, drop or settle, check this toggle first.

## The vocabulary comes first

DiceyTable borrows PlayCanvas's ECS vocabulary and uses it strictly. That strictness is
load-bearing: **"Component" always means an engine component** — `render`, `rigidbody`,
`collision`, `light`, `camera`, `script` — and never means a thing you place on the table.
A thing you place on the table is an **Entity**.

Read these four pages before the rest of the editor guide. Every other page in the guide,
and the scripting and mod references too, assume you have.

- **[The scene model](https://diceytable.com/docs/editor/concepts/scene-model)** — Entity, Component, System,
  Folder, Tag Group, and the two-tier component split.
- **[Provenance and lifecycle](https://diceytable.com/docs/editor/concepts/provenance)** — Engine vs Platform vs
  Project; Definition vs Scene Entity vs Live Entity.
- **[Document vs engine](https://diceytable.com/docs/editor/concepts/document-vs-engine)** — why the schema
  document is the source of truth, and what that rules out.
- **[IDs, names and tags](https://diceytable.com/docs/editor/concepts/ids-names-tags)** — the three names an
  entity has, which one is an address, and the reserved `dt:` tag namespace.

There is also a [glossary](https://diceytable.com/docs/editor/concepts/glossary) that defines every term the
Developer Docs use, exactly once, with a stable anchor per term.

## What Edit Mode is not

- **It is not a PlayCanvas project editor.** You author a DiceyTable scene document. You do
  not get scenes, script attributes, render layers or the engine's asset registry.
- **It is not a code sandbox with engine access.** Scene scripts and mods address entities
  through the replicated document. `pc.Entity`, `findByTag`, `entity.tags` and engine guids
  are not reachable from either surface.
- **It is not a server-side workspace.** Your draft lives in your browser and, when you
  publish, in your GitHub repository. Model and texture files are never stored on DiceyTable
  servers.
