Prefabs — save, instance, and unpack

tutorial lesson Intermediate ⏱ 6 min vgai 0.1.0

Prerequisites: Take the editor tour

What you'll learn

• Recognise a prefab instance by its Prefab banner
• Save an entity as a reusable .prefab.json from the save dialog
• Unpack an instance back into plain editable entities

What you'll build: The prefab workflow on the tutorial scene — instance banner, context menu, save dialog, unpack.

Walkthrough — Prefabs — save, instance, and unpack · generated by site/media/lessons/learn-prefab.lesson.ts (4 steps)

A prefab is an entity (with its children, components, and physics) saved to a reusable .prefab.json. Drop it into any scene to get an instance linked back to that file. This scene ships two pillar instances of prefabs/pillar.prefab.json.

Follow along in the live web editor

Open the scene these steps use — no install: ▶ Open the editor-tutorial scene (it has the PillarLeft / PillarRight prefab instances). Selecting instances, the context menu, Save-as-Prefab, and Unpack all work in the browser (saved prefabs go to your browser storage).

Steps

1. Spot an instance. Selecting PillarLeft shows a blue Prefab banner in the inspector (Prefab · pillar) with Open and Unpack — that’s how you know an entity is a linked instance, not a one-off.

   

   An instance carries a Prefab banner linking it to its .prefab.json.

2. The instance context menu. Right-clicking an instance offers Unpack Prefab (break the link) and Open Prefab (edit the source asset in prefab mode).

   

   Unpack Prefab / Open Prefab on an instance.

3. Author a new prefab. Right-clicking a plain entity offers Save as Prefab…, which opens the save dialog — pick a folder and name, and it writes prefabs/StandardBox.prefab.json.

   

   Save any entity (and its subtree) as a reusable .prefab.json.

4. Unpack an instance. Unpack replaces the instance with plain, editable copies of its contents — here PillarLeft becomes a normal entity (white), while PillarRight stays a linked instance (blue).

   

   Unpacked: PillarLeft is now plain; PillarRight is still an instance.

Save, instance, unpack — and overrides

“Save as Prefab…” (SceneHierarchy.tsx → PrefabSaveDialog.tsx) serialises the entity’s whole subtree to .prefab.json. Dragging that asset into a scene creates an instance (blue in the tree). An instance can carry per-instance overrides (e.g. a moved transform) on top of the shared source, and prefabs can be nested. Unpack (store.unpackPrefab) bakes the current result into plain entities and drops the link.

Recap

New functionality

• Identified a prefab instance by its banner
• Opened the Save-as-Prefab dialog on a plain entity
• Unpacked an instance into plain entities

New concepts & skills

• a prefab is an entity subtree saved to a reusable .prefab.json
• instances link back to the source (blue in the tree) and can override / nest
• Unpack bakes an instance into plain entities and drops the link

Next lesson → Edit ops

On Your Own!

Extend what you built:

• Save a decorated entity as a prefab, then drag two instances into the scene
• Open a prefab (Open Prefab) and edit the source — every instance updates
• Unpack one instance and leave another linked; compare how edits propagate

See also

• Edit ops · Scenes & prefabs (manual)