Scenes and prefabs

A scene describes a complete level or screen. A prefab stores a reusable part: a character, door, vehicle or decoration.

Both roles use PackedEntity, a saved entity tree. The role comes from the source file path, not a separate root class. You can run a prefab separately or place a scene inside another tree. Choosing a role helps organize the project.

1. Prepare the crate prefab

1. Use File to create a new prefab document with an Entity3D root.
2. Name the root Crate. Add a child MeshInstance3D named Visual.
3. Create a BoxMesh in the child's Mesh property. Keep Scale = (1, 1, 1).
4. Save the document as asset://Props/Crate.rprefab.

Crate (Entity3D)
└── Visual (MeshInstance3D, BoxMesh)

This is only a visible object. To stop a character, the crate needs a physics body and collision shape; a mesh alone does not create collision. See 3D movement.

2. Place two instances

Open Main.rscene from your first project. This is the main level, not Main.rprefab.

1. Open Assets with Ctrl + Space and find Props/Crate.rprefab.
2. Drag the file onto the Main root in the hierarchy. Repeat.
3. Name the instances CrateLeft and CrateRight.
4. Set their Position to (-1.5, 0.5, 0) and (1.5, 0.5, 0). With the default BoxMesh height of 1, the crates will sit above the ground rather than halfway inside it.
5. Save Main.rscene and press F6. The camera must see both crates.

Main (Entity3D)
├── Camera3D
├── …
├── CrateLeft [Crate.rprefab]
└── CrateRight [Crate.rprefab]

3. Distinguish the template from an override

To check this, open Crate.rprefab, move Visual up by 0.2, and save. Both meshes in the level move relative to their roots; the CrateLeft and CrateRight roots remain in their separate positions.

An instance's override can hide a change to the template. Select that particular property and restore the template value with the Inspector's reset/revert action. Do not delete the entire instance to reset one field. Save both the source prefab after editing it and the level after changing an instance.

A resource may be shared

Separate tree instances do not imply separate copies of every Material, Mesh or other Resource. Two meshes can reference one material: changing its Albedo then affects both.

For an independent color, make the material unique/duplicate it in the Inspector and assign the copy to the intended mesh. If each instantiation needs its own resource automatically, see ResourceLocalToScene and nested duplication behavior in the resources guide. Copying a top-level resource does not guarantee copying every nested object.

Creating objects in code and saving

A loaded PackedEntity is a template; Instantiate() creates a separate tree. It enters the level after AddChild(). Set coordinates and other values required by _Ready() before adding it to the tree.

For a complete example with a marker, rotation, object limit and deletion, see runtime objects. Changes in the running game are not automatically written to Main.rscene or Crate.rprefab; progress needs a save file.

If something goes wrong

Change a document's role using the editor's operations. Renaming its extension in a file manager does not update project references and dependencies by itself.