🧩How to Set Up a Prefab
Video Link:How to set up a prefab.mp4
A prefab is a reusable SceneNode tree saved as .prefab.json. Configure it once, place many copies, then change the source so every copy updates. Per-instance Inspector values and placement stay on that copy.
Use a prefab as soon as you would place the same setup more than twice.
What you can do with prefabs
Save a configured node and its child nodes from the Outliner (
Save as Prefab).Place copies by dragging the asset into the scene.
Open the prefab document, edit the source, save, and have placed copies pick up the source.
Override properties on one placed copy without changing the others.
Spawn copies at runtime from TypeScript with
ENGINE.spawn/ENGINE.spawnAsync.Ask the agent (Sandbox Studio MCP) to place or edit prefabs in the open editor, including while you are inside a prefab document.
Do not hand-edit .genesys-scene files to place copies. The editor owns scenes. Prefab JSON can be inspected or edited; class names must stay ENGINE.ClassName or GAME.ClassName. See Project code fundamentals.
Step 1: Place an asset in the scene
Drag the asset you want to reuse into the scene and select it.
Step 2: Add a component
Select the plus button near the Inspector and choose the component the asset needs.
Step 3: Add Character Stats
For this example, add a Character Stats component to the asset.
Step 4: Add a Point Light
Add a Point Light as a second component. This makes it easy to confirm that the prefab keeps more than one configured component.
Step 5: Configure the values
Change the component values as needed. The values you save will become part of the prefab setup.
Step 6: Choose Save as Prefab
Right-click the asset in the Outliner and select Save as Prefab.
Step 7: Name the prefab
Enter a clear name that identifies the reusable asset, then confirm the save.
Step 8: Drag the prefab into the scene
Find the saved prefab in the Assets panel and drag it into the scene.
Step 9: Check the retained components
Select the new instance and review the Inspector. The components and configured values you added are still present.
Where the file lives
The editor writes a .prefab.json file. Put prefabs under assets/prefabs/ (any folder under assets/ works; that path is the convention). Use a fully qualified path everywhere you refer to it in code or JSON: @project/assets/prefabs/....
A simple prefab is a $version document with a $root object. The $bc field is the class to spawn (ENGINE. or GAME.). Nested nodes sit under children (or a nested rootComponent on older dumps). Larger trees may use an $objects array with $id / $ref links instead of one nested $root.
Asset URLs inside the file are fully qualified (@project/... or @engine/...).
Prefer the editor (or the agent in the editor) to create and change prefabs. If you edit the JSON, keep those class and path rules. Do not edit auto-imports.ts or game-data.ts.
Edit the prefab source
Open the prefab document, not a single placed copy.
In the Outliner, double-click the prefab instance. That enters the prefab so you can change its nodes. You can also double-click the
.prefab.jsonasset in the Assets panel.Change the source the same way you would a scene: Inspector values, added nodes, lights, and so on.
Save with
Ctrl+S/Cmd+S.Return to your scene. Placed instances pick up the saved source, except properties you overrode on a specific instance (next section).
Placement (position, rotation, scale) lives on each instance. Changing those on a copy does not rewrite the prefab file.
Override a single instance
Select one placed instance in the scene. Change a property in the Inspector (for example a number field on that node). Save the scene.
That value stays on that instance. The scene stores only properties that differ from the prefab template. Later edits to the prefab source still apply to every property you did not change on this copy.
Instance placement is already an override: moving one copy does not move the others.
A placed instance keeps a prefabPath pointing at the .prefab.json file. The agent can read that path from the open scene through Sandbox Studio MCP.
Spawn copies from code
Use ENGINE.spawn when the prefab is already loaded, or ENGINE.spawnAsync when it may need to load from disk. Pass the fully qualified prefab path. Then parent the returned SceneNode (add it to the world or to another node).
world is the live ENGINE.World. You can also parent.add(pickup) to nest the instance under another node.
Optional spawn options include position, rotation, and scale for that instance.
spawn / spawnAsync also accept a class constructor or a registered class name. A string that is not a registered class is treated as a prefab path.
Ask the agent to place or edit
With Sandbox Studio MCP connected, the agent can place prefabs, set instance properties, and edit the tree while a prefab document is open. Undo includes prefab isolation. Setup: Set up and use Sandbox Studio MCP.
Tell the agent the prefab path (@project/assets/prefabs/...) and where to put it. Do not ask it to patch the .genesys-scene file in your code editor.
PREFAB A reusable saved SceneNode tree (.prefab.json) with configured child nodes and values.
What You've Done
You can save a prefab, place copies in the editor, spawn them from code, edit the source so every copy updates, and change one instance without losing that override when the source changes.
Last updated
Was this helpful?

