Prefabs

A Prefab is a saved object subtree you can stamp into a scene over and over - a reusable template for anything from a single crate to a fully-scripted first-person player. This page explains how prefabs are saved, instanced, and how their dependencies are resolved.

What a prefab is

A prefab is a serialized subtree: an object, all of its descendants, and all of their components, captured as a small SceneJSON blob and stored in the project's prefab library under a name. It is the same on-disk shape as a scene - just a fragment of one rather than the whole world.

Prefabs are part of the Project Bundle, so they travel with your project, and a single prefab can also be exported as a self-contained .awakenpkg package - right-click it and choose Export as package… - that bundles the prefab plus every asset it references, for sharing between projects or publishing to the Asset Store.

Save as Prefab

Select an object in the Hierarchy, right-click it, and choose Save as Prefab. The whole subtree under that object is snapshotted into the prefab library, named after the object (or Prefab{n} if it has no name). The prefab now appears under Prefabs in the Asset Browser.

📸 Screenshot - save as img/world-save-as-prefab.png

The Hierarchy right-click context menu with "Save as Prefab" highlighted on a multi-object player rig.

Instancing a prefab

There are several ways to drop a prefab into the current scene, all of which produce one undoable step:

• Drag the prefab from the Asset Browser into the Viewport - it lands at the cursor, snapped to the surface (or ground plane) under the drop point.
• Drag it onto the Hierarchy, or double-click it in the Asset Browser - it lands at the camera focus point (where you're looking).
• Select the prefab and press Add to Scene in its Inspector preview.

Each instance is an independent deep copy. Object-valued fields are cloned on instantiate, so a script mutating one instance's transform (a rotator, a mover) never corrupts the prefab or its siblings.

📸 Screenshot - save as img/world-prefab-inspector.png

The prefab Inspector: a rotatable textured 3D preview on top, the referenced scripts/materials listed as clickable chips below, and the "Add to Scene" button.

No live link

Instancing is a one-time stamp. Instances have no live connection back to the prefab - editing the prefab does not propagate to instances already placed, and there is no per-instance override system. To update placed copies, delete and re-instance, or edit each one directly.

Auto-binding entity-ref parameters

Scripts often need to point at another object - a first-person controller needs the camera, for example. When those references are exposed as component-filtered entity parameters, instancing auto-binds them: for each unset entity-ref parameter, if the scene contains exactly one matching object, that object is bound automatically.

So dropping a "First Person Player" prefab into a scene that has a single Camera wires the player's camera slot to it with no manual step. When there are zero or more than one candidates the binding is left unset - the choice is ambiguous, so it's yours to make in the Inspector. The same auto-bind runs when you assign a script directly to an object.

Prefab dependencies

A prefab does not embed the assets it uses - it references them by id. That keeps prefabs small and lets several prefabs share one script, material, graph, or effect. The trade-off is that a prefab is only fully functional if those assets exist in the project.

A prefab's dependencies are collected from the components in its subtree (deduplicated, order-stable). This one walk drives two things: what a self-contained .awakenpkg package bundles, and what the importer must resolve when you bring in a references-only .awakenprefab (the older portable form that points at its dependencies by id):

Dependency	Read from	File to locate
Scripts	every entry in a Script component's script list (and the legacy single-script field on pre-v4 prefabs)	.awakenscript
Materials	a MeshMaterial component's material id	.awakenmat
Anim graphs	an AnimStateMachine component's graph id - builtin: graphs are always available and are skipped	.awakenanimgraph
Particle effects	a ParticleEmitter component's effect id	.awakenfx

The .awakenfx case is easy to miss because nothing looks broken without it: an emitter whose effect id isn't in the project imports "successfully" and then simply emits nothing, silently. The starter Fire prefab is exactly this shape - one object with a ParticleEmitter pointing at the fire effect and no geometry of its own - so importing Fire.awakenprefab without Fire.awakenfx gives you an invisible, inert object.

The Locate Dependency flow

When you import a .awakenprefab whose dependencies aren't already in the project, Awaken3D walks the missing list - scripts, then materials, then anim graphs, then particle effects - and opens a Missing script / Missing material / Missing animation graph / Missing particle effect dialog for each:

• Locate… lets you pick the matching file; it is imported through the normal import path (so a located .awakenscript compiles, a .awakenmat validates), and Awaken3D checks that the file actually provides the requested id - a wrong file is reported rather than silently failing at Play.
• Skip imports the prefab anyway - it loads and can be placed, but stays inert for that dependency until you add the asset later.
• Whatever is still missing at the end is listed in the Console as Imported prefab "Name" - unresolved: <ids>. That line is the record of what to go and find; check it after every prefab import.

Multiple missing-dependency requests are queued and shown one at a time, so importing several prefabs at once never drops a prompt.

Avoiding the prompts

Two shapes of import resolve everything by themselves:

• Drop the prefab together with its dependency files (or the whole starter-content folder) in one go. Dependencies in the same drop are imported before the prefab, so there is nothing left to locate. A prefab dropped on its own still prompts.
• A self-contained package - a .awakenpkg (from Export as package… or the Asset Store) carries the prefab plus every asset it references. It merges straight in, skipping any id the project already has, with no prompts at all. Older binary .awakenprefab packs import the same way (both are content-sniffed, so a plain JSON .awakenprefab still takes the Locate flow above).

See also

• Scenes & Game Structure - the SceneJSON shape a prefab reuses.
• Asset Browser - where prefabs live and how you drag them out.
• Hierarchy panel - Save as Prefab lives in the right-click menu.
• Script parameters - exposing the entity-ref fields that auto-bind.
• Import overview - how .awakenprefab and its dependencies are brought in.