Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/facepunch/sbox-public/llms.txt

Use this file to discover all available pages before exploring further.

Prefabs are reusable GameObject templates saved to disk as .prefab assets. Instead of rebuilding the same object — say, an enemy with a model, health component, and AI — every time you need it, you design it once as a prefab and spawn copies at will. This page explains what prefabs are in s&box, how to create them, how to instantiate them from code, and how prefab instances and nesting interact.

​
What is a prefab?

A prefab is a saved snapshot of a GameObject hierarchy stored in a PrefabFile asset (.prefab). It captures the object’s name, transform, components, and children. When you spawn a prefab at runtime, the engine clones the template into a live GameObject that you can modify without affecting the original asset. Internally, the live copy is called a prefab instance. The instance knows which prefab it came from (PrefabInstanceSource) and tracks overrides via a diff/patch system, so editor changes to the prefab can be pushed to existing instances.

​
Creating a prefab

Prefabs are created and edited in the s&box scene editor:
1

Build your GameObject

Set up the GameObject in the scene — add components, configure properties, add children.
2

Save as prefab

Right-click the GameObject in the hierarchy and choose Save as Prefab. The editor writes a .prefab file to your project’s asset folder.
3

Reference the asset

Drag the .prefab file into a [Property] field of type PrefabFile or GameObject on any component, or reference it by path in code.

​
Instantiating a prefab at runtime

Use GameObject.Clone to spawn a prefab. The static overloads accept a file path or a PrefabFile resource; the instance overload clones any existing GameObject. 
// Simplest form — spawn at the world origin
var instance = GameObject.Clone( "prefabs/enemy.prefab" );
Clone always returns a fully initialised GameObject. All components on the instance and its children will receive their OnAwake and OnEnabled calls in the same frame batch.

​
Cloning an existing GameObject

Clone is also available as an instance method. Call it on any live GameObject to create a deep copy, preserving the full component and child hierarchy. 
// Clone in place (at the same transform)
var copy = existingObject.Clone();

// Clone to a specific world position
var copy = existingObject.Clone( new Vector3( 500, 0, 0 ) );

// Clone with full control
var copy = existingObject.Clone(
    transform: new Transform( pos, rot ),
    parent:    someParent,
    startEnabled: true
);
References between components within the hierarchy are rewired automatically — a component on the clone that references another component on the same original will end up pointing to the corresponding component on the clone.

​
Prefab instances

A cloned prefab is called a prefab instance. You can inspect this state at runtime: 
// True if this GameObject was cloned from a prefab
bool isInstance = go.IsPrefabInstance;

// True if this is the root of the instance (not a child within one)
bool isRoot = go.IsPrefabInstanceRoot;

// The path of the prefab asset this instance came from
string source = go.PrefabInstanceSource; // e.g. "prefabs/enemy.prefab"

​
Breaking from a prefab

Once you call BreakFromPrefab(), the object loses its link to the source asset. It becomes a standalone GameObject. Editor overrides are no longer tracked and future changes to the prefab asset will not propagate. 
go.BreakFromPrefab();
// go is now a plain GameObject with no prefab link

​
Refreshing from the source

If you want to reset an instance back to the current state of its source prefab, call UpdateFromPrefab(): 
go.UpdateFromPrefab();
UpdateFromPrefab() discards any runtime modifications made to the instance. Use it only when you deliberately want to reset to the prefab’s saved state.

​
Nested prefabs

A prefab can contain other prefab instances as children — this is called nesting. The engine tracks nested instances separately so that overrides on the outer prefab do not corrupt the inner one. 
OuterEnemy (prefab instance root)
├── Body (part of OuterEnemy prefab)
└── Weapon (nested prefab instance root → weapon.prefab)
    └── Barrel (part of Weapon prefab)
At runtime:
  • OuterEnemy.IsPrefabInstanceRoot → true
  • Weapon.IsNestedPrefabInstanceRoot → true
  • Weapon.OutermostPrefabInstanceRoot → OuterEnemy
If you reparent a nested prefab root out of its containing prefab, the engine automatically converts it to a full (non-nested) prefab instance so that it keeps a complete link to its source asset.

​
Reading a prefab without cloning

If you need to inspect the prefab’s GameObject template without spawning it into the scene, use GetPrefab: 
// Returns the cached PrefabScene — do not modify it
var template = GameObject.GetPrefab( "prefabs/enemy.prefab" );
Log.Info( template.Name );
The object returned by GetPrefab is the engine’s internal cache. Never modify it or add components to it; always call Clone to get a usable copy.

​
Next steps

Scene and GameObject

Understand how the hierarchy, transforms, and enabling work.

Components

Add behaviour to your prefabs with the component lifecycle.

Build docs developers (and LLMs) love

Get started for freeTalk to us