> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Placing scenes

A scene can be placed inside another scene, as many times as you like, and each copy works like an entity. Make a fence once as a scene of its own, place it ten times in the level, and when you change the fence's collider in its scene, all ten fences get the new collider. Each copy keeps what you changed on it, such as its position.

Use it for anything that exists more than once (coins, enemies, trees, barricades) and for parts of a game you want to build on their own, such as a pause menu.

![A placed coin selected. The card under its name says which scene it came from](/images/editor/placed-scene.png)

## Make a scene to place

There are two ways:

- Right-click an entity in the hierarchy and choose **Save as Scene**. The entity and everything under it are saved as `Scenes/<name>.cairnscene`, and the entity becomes the first placed copy of it.
- Make a new scene with **+ New** in the Assets panel, build it, and save it.

A scene with one top entity is placed as that entity: a fence is one **Fence** in the hierarchy. A scene with several top entities comes in under one more entity, named after the scene. That entity is not in the scene's file, so its name, position and anything you add to it belong to the copy.

Only the entities come along. The placed scene's own render settings are used only when it is the open scene.

## Place it

- Drag the scene from the Assets panel into the viewport. It lands where you let go.
- Right-click it in the Assets panel and choose **Place in scene**.
- Right-click in the hierarchy and open **Place Scene**. Type to narrow the list, and press Enter to place the first one left. From a row's menu the copy goes under that row.

![The Place Scene menu in the hierarchy, with a search box](/images/editor/place-scene-menu.png)

Double-click a scene to open it, as before.

A scene cannot be placed inside itself, or inside a scene it holds. The editor says so in the console.

## Change every copy

Select any copy and press **Open** on its card. The editor opens the scene it came from and shows the way back over the viewport, as **Main > Coin**. Change what you need and save. Click **Main** and the level opens again, with every copy changed.

![Inside the coin's scene, with the way back to Main over the viewport](/images/editor/placed-scene-open.png)

If the level has unsaved changes, the editor asks first, as it does before opening any scene. Going back reads the level from its file again, so its undo history starts again.

A scene with no sun and no sky, as a part saved to be placed usually is, gets a light of the editor's while you edit it. The light is not saved and the game never sees it.

## Change one copy

Change a copy in the level as you would any entity. What you change stays that copy's own, and later changes to its scene reach it everywhere else. The card counts the copy's own changes and has:

| Control                     | What it does                                                           |
| --------------------------- | ---------------------------------------------------------------------- |
| Open                        | Opens the scene the copy came from                                     |
| Apply                       | Writes this copy's changes to its scene, so every other copy gets them |
| Revert                      | Drops this copy's changes and goes back to what its scene says         |
| Unpack, in the **...** menu | Cuts the tie: the entities become ordinary ones                        |

Apply is one undo step that puts back both the scene file and the level. A copy's top entity always keeps its own position and rotation.

## From a script

A script places a copy while the game runs with `Scene.Instantiate`, and `entity.Instance` says which scene an entity was placed from:


**Lua**

```lua
-- file: Assets/Scripts/Spawner.lua
local Spawner = {}

Spawner.Fields = { Zombie = Field.Scene() }

function Spawner:OnStart()
	local zombie = Scene.Instantiate(self.Zombie, Vec3(4, 0, 0))
	print(zombie.Instance == self.Zombie)   --> true
end

return Spawner
```


**TypeScript**

```ts
export = DefineScript({
  Fields: { Zombie: Field.Scene() },

  OnStart() {
    const zombie = Scene.Instantiate(this.Zombie, Vec3(4, 0, 0));
    print(zombie.Instance === this.Zombie);
  },
});
```


Scripts inside a placed scene work as they do anywhere. A `Field.Entity` that points at another entity of the same scene points at that entity in the same copy, so a zombie's script finds its own arm and not another zombie's.

## A menu in its own scene

Build a pause menu as a scene whose top entity is a UI Canvas, with nothing of the level around it. Place it in the level once, switch it off, and have the pause script switch it on. See [UI and text](/guide/features/ui.md#a-menu-in-its-own-scene).

While you edit the level, the **Game UI** switch over the viewport hides every canvas, so a menu or HUD that is on does not cover the level. It changes nothing in the scene or the game.

![Coin Run's HUD drawn over the level while it is edited](/images/editor/viewport-game-ui-on.png)

![The same view with Game UI off: the level behind the HUD shows](/images/editor/viewport-game-ui.png)

## In the file

A scene file stores a copy as only what it changed:

```yaml
- Entity: 13050716652590719703
  Instance:
    {
      Scene: 17713027099137978319,
      Root: 13050716652590719703,
      Source: 1029384756102938008,
    }
  Name: Coin 3
  Transform:
    Translation: [0, 0, 2]
```

So a change to the placed scene reaches every copy that did not change the same thing. A copy that deleted an entity of its scene lists it under `RemovedFromPrefab`, and an entity the scene gains later appears in every copy.

## Agents

An agent places a scene with `scene.place` and saves an entity as one with `entity.save_as_scene`. To change every copy it changes the placed scene's file directly, without opening it, by giving `file` to an entity command:

```json
{
  "command": "entity.update",
  "file": "Scenes/Fence.cairnscene",
  "entity": "Fence",
  "data": { "BoxCollider": { "Size": [6, 2, 0.3] } }
}
```

The copies in the open scene follow at once. `entity.get` and `entity.list` say which scene a copy came from, `scene.uses` lists where a scene is placed, and `entity.scene_changes`, `entity.apply_to_scene`, `entity.revert_to_scene` and `entity.unpack_scene` do what the card does. See [Commands](/agents/commands.md).

## Prefabs from before

Cairn used to have prefabs, `.cairnprefab` files. They are scenes now. When the editor opens a project that has them, it renames each to `.cairnscene`, with its `.meta` file so its ID and everything that uses it stay, and rewrites scripts that name one by path or use `Field.Prefab`. If a new name is taken it renames nothing and says which file is in the way. The old `prefab.*` agent commands still work.

## An example

Zombie Survival, among the samples in the hub, is built this way. Its barricade is one scene, `Scenes/Barricade.cairnscene`, placed in three doorways. Each copy's script has its own **Section** and **Cost**, which is all that differs between them, and the game script finds the copies by their tag. Its pause menu is a scene of its own with its own canvas, placed once and switched off, and the zombies, bullets and pickups are scenes the scripts place while the game runs.

## Good to know

- A copy of a whole placed copy is another copy. A copy of part of one is ordinary entities.
- A scene with a copy of a scene that cannot be read does not load. Nothing is half-read.
- Copies in scenes that are not open follow when those scenes are next opened.