> For the complete documentation index, see [llms.txt](https://studio-docs.sandbox.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.sandbox.game/the-editor/how-to-set-up-a-prefab.md).

# How to Set Up a Prefab

Video Link:[How to set up a prefab.mp4](https://drive.google.com/file/d/159rayRZcN1sw1X4n8esTqME_yuuPy_Io/view?usp=drive%5Flink)

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](/best-practices/project-code-fundamentals.md).

### **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.

{% hint style="info" %}
*NOTE: Double-click in the Outliner is the same enter-prefab path described in* [*Editor Orientation*](/the-editor/editor-orientation.md)*. You are editing the shared template, not one copy in isolation.*
{% endhint %}

### **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).

```typescript
import * as ENGINE from '@gnsx/genesys.js';

const pickup = await ENGINE.spawnAsync(
  '@project/assets/prefabs/pickups/health_pickup.prefab.json'
);
world.add(pickup);
```

`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](/working-efficiently-with-ai/set-up-and-use-sandbox-studio-mcp.md).

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

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://studio-docs.sandbox.game/the-editor/how-to-set-up-a-prefab.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.