Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🧩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.

  1. 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.json asset in the Assets panel.

  2. Change the source the same way you would a scene: Inspector values, added nodes, lights, and so on.

  3. Save with Ctrl+S / Cmd+S.

  4. 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.

NOTE: Double-click in the Outliner is the same enter-prefab path described in Editor Orientation. You are editing the shared template, not one copy in isolation.

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?