Skip to content

Prefabs

Build something once, such as a coin, a door or a styled button, save it as a prefab, and place copies of it in any scene.

A prefab is a file in the project, prefabs/<name>.prefab.json. It holds an entity and its children with every component, exactly as a scene save writes them, so a button keeps its style, tags and children. A placed prefab is an instance: the scene saves only a link to the file, and reopens it from the file.

Make a prefab

In the hierarchy, right-click the entity and choose:

  • Make Prefab to save it and its children as prefabs/<its name>.prefab.json. The entity in the scene stays as it is.
  • Make Prefab and Link to save it the same way and put an instance of the new prefab in its place.
  • Make Prefab As... to pick the file yourself.

Place a prefab

From a menu. The hierarchy's Add entity menu and the Entity menu have a Prefabs group listing the project's prefab files. Pick one to place an instance under the selected entity, or at the top of the scene when nothing is selected.

By dragging. Drag a .prefab.json from the Files tab and drop it on the Scene view. It lands where you let go: on top of the object under the pointer, such as a box, otherwise on the ground, otherwise a little way in front of the camera when the pointer is over the sky.

You can also drag a prefab's tile from the Assets dock onto the hierarchy:

  • onto the middle of a row, to place it inside that entity,
  • onto the top or bottom part of a row, where a line shows, to place it just before or after that row,
  • onto the empty space below the rows, to place it last at the top of the scene.

Placing a prefab, either way, is one undo step. Undo leaves the prefab file alone.

Instances in the hierarchy

An instance's row in the hierarchy is marked as a link, and the rows inside it, which come from the prefab file, are dimmed. Studio doesn't save edits to those dimmed rows, because the scene keeps only the link.

When the prefab file changes on disk, the scenes that use it reload with the new version.

Select a .prefab.json in the Files tab to see what it holds in the Prefab Viewer, with a still preview.

"Beside, not in it"

Because a scene saves an instance as its link alone, anything you add inside an instance would be lost on save. So when you aim inside one, Studio puts the new entity beside the instance instead, under the same parent, and a message says so:

Cube is beside Coin, not in it: a save writes a prefab's instance as its link alone.

That happens when you:

  • add an entity from the Add entity menu or the Entity menu with an instance selected,
  • duplicate with Ctrl+D (Cmd+D on a Mac),
  • place an imported asset or drop a prefab with an instance selected,
  • drag an entity onto an instance in the hierarchy.

Dragging one of a prefab's own entities out of its instance doesn't work either: it stays where it is, and a message says why. Nor does dropping something between two of a prefab's own rows: nothing goes in, and a Part of a Prefab message says why.

What isn't there yet

  • You can't edit a prefab's own entities from an instance, or give one instance different values from the others.
  • A drop lands on models only: it doesn't see terrain, and a prefab centred on its own origin sits half into the surface.
  • Dropped onto the side of a box or a wall, a prefab is raised to the height of the hit and overlaps the wall, rather than sitting out from its face.