# Prefab Editor

> The 3D .prefab.json editor — arrange a body and bolt-on parts, weld or join them with hinges and springs, and place snap points on the result.

- Source: https://diceytable.com/docs/editor/item-editors/prefab
- Last verified: 2026-10-07

A **prefab** is a configured piece built from one or more models: a **body**, any **parts**
bolted onto it, the **joints** that connect them (hinges, fixed joints, springs), and the
**snap points** where other pieces land on it. Placing a prefab puts the whole thing on the
table at once — a box with a lid that swings, a card rack with a slot for each card, a board
with a hinged flap.

It lives in a `<name>.prefab.json` file, usually under `models/`:

```
models/rack.glb              a model, untouched
models/rack.prefab.json      the prefab — place THIS
```

## Three things called "prefab", and which one this is

The word is overloaded in this editor, and the three are genuinely different:

| | What it is | How many table entities |
|---|---|---|
| **Prefab** (this page) | a body **plus** parts, joints and snap points | one, plus one per part |
| [Model assembly](https://diceytable.com/docs/editor/interface/hierarchy) (`.assembly.json`) | ONE model built from several part `.glb`s | one |
| Scene prefab (`Prefabs (N)`, no file) | a reusable single-entity template | one |

The distinction is not cosmetic. **A hinge joins two rigid bodies**, so a lid that swings has
to be its own entity — which an assembly, being one model with one body, cannot give it.

Going the other way: a prefab's **body may be an assembly**. Composing several meshes into one
rigid shape is the assembly's job, and a prefab does not repeat it.

## Creating one

Every route writes the document and opens it in a new tab.

| Start from | How | The body is |
|---|---|---|
| Nothing | Explorer **New ▸ Prefab** | a plain block — pick the real body in the **Body** card |
| A model (project or built-in) | right-click the model tile ▸ **Create prefab…**, or its tile button | that model |
| A scene prefab (a one-object template such as a play mat) | right-click it in `Prefabs` ▸ **Build 3D prefab from this…** | its model, or the built-in piece it was made from |
| A piece on the table | select it ▸ **Snap points** panel ▸ **Attach snap points…** | its model (opens the existing prefab if there is one) |

A prefab made from a model lands beside it (`models/rack.prefab.json`); one made from a
built-in piece lands at `models/<preset-id>.prefab.json`. **Create prefab** refuses rather than
replace a prefab that already exists at that path — a prefab carries authored joints and snap
points, and a menu item should not be able to throw those away silently. The other routes pick a
free name.

The `Prefabs` folder lists every `.prefab.json` in the project, so that is where you reopen one.

## The 3D view

The left of the tab is a live 3D view of the prefab exactly as it will be placed: the body at
the origin, every part where the document puts it, snap points as rings (the tick shows the
facing a snapped piece takes), and joints as markers on their axis — orange for a hinge,
purple for a fixed joint, pink for a spring. Markers draw through the models, so a slot inside
a tray or a hinge behind a lid stays visible.

| To | Do |
|---|---|
| Orbit | drag on empty space |
| Pan | right-drag, or Shift-drag |
| Zoom | scroll |
| Select | click a part, ring or joint marker (or its card on the right) |
| Move | **Move** (W): drag an arrow to slide along that axis, or the yellow square to slide across the ground |
| Turn | **Rotate** (E): drag a ring. A snap point only turns about up; a joint's rings turn its axis |
| Fit everything | **Frame** (F) |
| Remove the selection | Delete |
| Undo / redo | Ctrl+Z / Ctrl+Y (also the buttons in the header) |

**Snap** in the toolbar rounds moves to a grid step (shown in your editor unit) and turns to
15°. It is a view setting and is never saved.

The body has no gizmo: it **is** the origin of prefab space, and moving it would only move
every other number. Everything you place is measured from it.

## The outline

The right of the tab lists one card per body, part, joint and snap point. Clicking a card (or
the thing itself in the view) opens it and puts the gizmo on it; every value the gizmo changes
is a field here too, for exact numbers.

### Body

The **name** (which becomes the placed entity's label), the **model**, its **scale**, its
**body type**, and **Weld parts**.

The model picker offers this project's models — `.glb`, `.gltf` and `.assembly.json` — and
every built-in piece, in one list. A built-in body spawns exactly the piece it would spawn on
its own, with the collider and container configuration that make it what it is, and its scale
*multiplies* the built-in's own rather than replacing it.

| Body type | Use it for |
|---|---|
| **Static** | a fixture — a rack, a box, a board. The default, and the anchor a hinged part swings from. |
| **Kinematic** | something a script moves. |
| **Dynamic** | a piece players pick up and throw. |

**Weld parts** joins every *rigid* part (one no joint names) into the body as a single physics
body with a combined shape — a die thrown at it bounces off the whole thing and nudges it.
Off, rigid parts still ride with the body, but they are not pushed back by what hits them.

### Parts

Extra models bolted onto the body, each with its own position, rotation, scale and body type.
Choose one in **Add a part…** and press **Add part**: it lands at the origin, selected, ready
to drag into place. Parts come from the same list as the body.

How a part is held depends on whether a joint names it:

| | On the table |
|---|---|
| **Rigid** (no joint) | its own entity, parented to the body: moving the prefab moves it. Welded into the body when **Weld parts** is on. |
| **Jointed** | its own **dynamic** body, *not* parented, held to the other end by the joint — which is what lets a lid actually swing. Its authored body type is overridden. |

Removing a part also removes every joint that names it.

### Joints

A joint ties two parts together — the body and a part, or two parts. Select a part, choose the
joint type in the toolbar, and press **Add joint**: the new joint connects the body to that part
(or to the first part, if none is selected), with its pivot at the part's origin.

| Type | Behaviour |
|---|---|
| **Hinge** | turns about its **axis** through its **pivot** — a lid, a door, a flap |
| **Fixed (weld)** | locks two separate bodies together; they can still break apart under enough force |
| **Spring** | ties them elastically |

Each joint has a **pivot** (a point in prefab space — a lid's hinge belongs on its back edge)
and an **axis** (the direction it turns about; **X axis**, **Y axis** and **Z axis** set the
common ones, or turn it with the rings in the view). A hinge can **limit its swing** to a range
of degrees either side of the pose it is placed in — a lid that opens to 110° and no further.
**Parts collide** is off by default, because a lid that collides with its own box jams.

The **body keeps its own type** when a joint names it, so a static box with a hinged lid stays
put while the lid swings. A joint naming the same part twice, or a part that no longer exists,
is refused on save rather than written and quietly ignored.

### Snap points

Where a dropped piece lands on this prefab — the reason many prefabs exist. **Add snap point**
puts the first one at the origin and each next one beside the last, with the same facing and
radius, so a row of slots builds up by pressing it repeatedly; then drag each ring into place.

Each has a name, a **position**, a **rotation** and a **snap radius** (the catchment — the ring
in the view). All of them are **relative to the prefab**: move or turn a placed copy and its
slots go with it, which a [scene snap point](https://diceytable.com/docs/editor/interface/hierarchy#the-snap-points-folder)
cannot do. The radius scales with the placed prefab, so a rack at half size gets slots with
half the catchment.

This tab is the **only** place these points are edited. A placed copy's inspector shows how
many it has and links back here, but does not change them: the points belong to the prefab, so
editing them from one copy would silently rewrite every other copy.

## Saving

Edits live in the tab until you press **Save**, and **Save Draft** / **Publish** flush them for
you. The document is validated first; a prefab with problems lists them under the header and
cannot be saved. Undo covers the tab's own unsaved edits.

Copies already on the table keep the version they were placed from. Place the prefab again to
get the saved version.

## Placing one

Drag the prefab tile to the table, or click its **Place** button. That spawns the body, one
entity per part, and every joint between them — and the joints are saved with the scene, so
they are still there after a reload and when the game is published.

Each placement gets its own namespaced ids, so two copies of the same box on one table are
independent. The prefab rests on the table's **live play surface**, so it lands correctly on a
tall table pack as well as the default one.

> A jointed part is not parented to the body (a parented entity cannot swing), so moving the
> body in Edit Mode leaves it where it was until the game runs and the joint pulls it back into
> place. Place the prefab where you want it rather than dragging it afterwards.
