Manual

Manual

Scenes and prefabs

A scene is a file of entities that the editor opens and your game loads. A prefab is a group of entities saved once and placed as often as you like, each instance following the prefab as it changes.

Scenes

A scene is a .scene file in your project's assets. It lists entities, each with its name, its parent, its transform and visibility, what it is drawn with, and the values of its components. If entities and components are new to you, read Entities, components and systems first.

The file is JSON, so you can read, diff and merge it in version control. Components are written under their full names and fields under the names your code gives them. Files the scene uses are named by their path and their identity, so a model or a texture you move still loads (see Assets, identities and addresses).

{
  "abyssScene": 10,
  "assets": [],
  "entities": [
    { "id": 50975798895298, "name": "Orbits", "transform": {} },
    {
      "id": 184758235794091,
      "name": "Pyramid 1",
      "parent": 0,
      "transform": { "translation.x": 1.8 },
      "components": {
        "Abyss.Orbit.Wobble": { "Height": 0.25, "Speed": 2 }
      }
    }
  ]
}

parent is the parent's position in the file's list, and id is the entity's identity within the scene, the same each time you save.

What a scene saves, and what it leaves out

A scene writes what you chose and leaves out what a load brings back by itself: a field that holds the value a new component starts with, a component another one requires while it holds what the requirement gives it (the Visibility that comes with a mesh), GlobalTransform, and values the engine calculates, such as a camera's aspect ratio. A requirement that a later version of a component adds comes along by itself too, in scenes saved before it was added.

So a field that was left out follows its default: change the value it starts with in your code, and every scene that left it out changes too. For a component whose values must never move, such as balance data, add [SerializeAllFields] in C# or #[reflect(SerializeAllFields)] in Rust. For every component of a project, set this in its project file:

<AbyssForceSerializeAllFields>true</AbyssForceSerializeAllFields>

When you rename a field or a component, add [FormerlySerializedAs] with the old name, so files saved before the rename keep their values:

[AbyssComponent][FormerlySerializedAs("Hitpoints")]public partial struct Health{    [FormerlySerializedAs("Hp")]    public int Current;}

Values are written exactly. A 64-bit whole number, such as a counter, a hash or an id, keeps every digit on its way to the file and back, and a fraction is written as the shortest text that reads back as the same number. An enum is written by name, and a text as its string. A value that is one of several kinds, such as a camera's projection, is written as its kind and what differs in it, so a camera whose field of view alone changed writes its field of view alone.

A mesh, a material or an image read from a file is written as the file's path and identity. A mesh your code made is written by a name, which you give it with world.NameMesh, and a scene that names a mesh nobody supplied says so when it loads; a material your code made is written as its values.

A scene saved by an older version of the engine opens as it always did, and is written in the current form the next time you save it.

Three things are never part of a scene: entities in no scene, which the Hierarchy lists last under Outside Scenes; anything done while the game plays, since Stop puts the scene back as it was at Play; and edits to a material file, which are saved to the .mat file as you make them.

A built game does not read the JSON. The build writes each scene as an .abyscene image that loads many times faster, and you keep editing the .scene.

Make, open and save scenes

  • File ▸ New Scene... (Ctrl+N) offers three templates: Basic, a Main Camera and a Directional Light; 2D, a Main Camera that is a 2D camera; and Empty. Click one to pick it, or move the pick with Up and Down, then double-click it, press Enter or click Create; Escape or Cancel makes none. The new scene takes the open one's place, and is Untitled until the first Ctrl+S asks where to save it.
  • In the Project panel, Scene in the + button's Create menu, or New Scene in a folder's right-click menu, makes NewScene.scene there with a Main Camera and a Directional Light.
  • File ▸ Open Scene... (Ctrl+O), or a double-click on a .scene, opens it in place of the open scene.
  • File ▸ Save Scene (Ctrl+S) and File ▸ Save Scene As... (Ctrl+Shift+S) write it.

A scene with unsaved changes has * after its name. What would lose them asks first: making a new scene, opening another, and quitting, from File ▸ Quit, the window's close button or Alt+F4. Save (Enter) writes the scene, asking where for one never saved, and then goes on; Don't Save (N) goes on without saving; Cancel (Escape) does neither.

Unsaved means the undo history has moved from where you saved: undo back to the save and there is nothing to save, redo and there is again. An instance of a prefab you placed counts as a change until the next save. While the game plays, the * stays as it was at Play, since Stop puts back what was done in play, and quitting stops the game before it asks.

The editor edits one scene at a time. In the Hierarchy, a band with the scene's name heads its entities, its ⋮ menu repeating the save commands. While the game plays, each scene it loads gets a band of its own, with Unload Scene in its menu.

Load scenes while the game plays

Your code loads scenes through context.Scenes in a system, or flow.Scenes in a flow, and gets the scene's SceneId back at once. The file is read on a background thread, then the scene is built a few pieces each frame within a budget, 4 ms unless you change world.SceneLoader.Budget. Until it is complete, no system sees its entities and nothing of it is drawn; then all of it is shown in one frame.

// In a system:SceneId level = context.Scenes.Load(Addresses.Scenes.Level);                       // the others go once it is shownSceneId moons = context.Scenes.Load(Addresses.Scenes.Moons, SceneMode.Additive);   // shown beside the scenes there
float progress = context.Scenes.ProgressOf(level);     // 0 to 1, for a loading barif (context.Scenes.StateOf(moons) == SceneState.Active) { /* all of it is there */ }
context.Scenes.Unload(moons);

Addresses.Scenes.Level is a key the build writes for an addressable scene; see Addresses and labels. The scenes ticked in File ▸ Build Settings... go into the game, and the first one ticked opens when it starts; see Build and run your game.

SceneMode.Single, the default, unloads every other scene once the new one is shown; entities in no scene stay. SceneMode.Additive keeps the others, so you can bring parts of a world in and out beside each other. A load that fails, such as a missing file, is written to the log under scene and leaves no scene behind.

Hold a scene until the player is ready

With hold: true, a scene waits built but unseen, Ready, until you call Activate: for a loading screen that waits for a key press. In a flow, await flow.Loaded(scene) returns Active, Ready for a held scene, or None for one that failed. See C# in a game for flows.

schedule.AddFlow("Next level", async flow =>{    SceneId next = flow.Scenes.Load(Addresses.Scenes.Level2, hold: true);    if (await flow.Loaded(next) == SceneState.Ready)    {        // Built but not shown: wait for the player here, then show it.        flow.Scenes.Activate(next);    }});

Large scenes, a few entities at a time

Showing a scene costs about a millisecond for every 10,000 entities on a fast machine. For a scene big enough for that to be felt, use ScenePace.Gradual: it is shown 64 entities at a time, as many pieces a frame as the budget allows, never a child before its parent, and stays Loading until all of it is shown. Its progress counts those pieces too, and a gradual Single scene unloads the others only once it is all shown, at the same pace.

SceneId city = context.Scenes.Load(Addresses.Scenes.City, pace: ScenePace.Gradual);context.Scenes.Unload(city, ScenePace.Gradual);

An ordinary unload hides the scene in one frame, then despawns it a slice at a time. A gradual one hides nothing first: what is left stays visible until it goes, so set Visibility to Hidden on its top entities if you want it out of sight at once. Either way, the meshes, materials and images the scene loaded go with it unless something else uses them.

Entities and scenes in code

Each entity is in one scene at most, and a child is always in its parent's scene. What your code spawns, prefab instances included, is in no scene unless you say so, and no unload takes it. To spawn into a scene, pass it to context.Commands.Spawn(archetype, count, scene), or move a top entity with context.Commands.MoveToScene(entity, scene); the system declares AndSetScene in its structural access.

Prefabs

A prefab is a .prefab file, the same format as a scene, holding one entity at its top and everything under it. You place instances of it in scenes and in other prefabs. When the prefab changes, every instance is built again with the change, keeping what the scene changed in it.

Prefabs are teal: a teal cube in the Project panel, and teal rows in the Hierarchy for an instance and everything its prefab put under it.

Make a prefab and place instances

Drag an entity from the Hierarchy onto a folder in the Project panel. It is written there with everything under it as a prefab named after it, its top at the origin, and an instance takes the entity's place.

To place an instance, drag a prefab from the Project panel onto a Hierarchy row to put it under that row, below the rows to put it at the top, or onto the Scene panel to put it on whatever is under the pointer. Instance in Scene in its right-click menu does the same. Inside an instance you can add entities, components and other instances; those are the scene's additions.

Edit a prefab on its own

Double-click a prefab in the Project panel, click Open on the Inspector's Prefab row for an instance, or choose Prefab ▸ Open Prefab in an instance's right-click menu. The scene is set aside with its changes and undo history, the Hierarchy lists the prefab's entities with a link back to the scene, and the Scene panel frames the prefab.

What you make or drop goes under the prefab's top entity, whose Transform stays as it is, since each instance places it. Ctrl+S saves the prefab and every instance follows, as they also do when a text editor or a pull changes the file, or when a model is imported again with other settings. Each instance keeps its place among its siblings, so what is picked and what Ctrl+Z undoes follow it. While the game plays, the instances wait for Stop before they follow.

Overrides

What an instance changes of its prefab is an override, marked in teal in the Inspector. The menus name the prefab and the component; here, a prefab Chest and a Point Light:

  • A changed field has a teal dot after its name. Click it, or right-click the row, for Revert to Chest or Apply to Chest.
  • An added component has a teal + before its name, with Revert: Remove Point Light and Apply to Chest in its header's right-click menu.
  • A removed component stays removed. Its header is shown dimmed, with a teal − and its name struck through, and offers Revert: Put Back Point Light.
  • An added entity keeps a plain row in the Hierarchy, and its Prefab row says what it was added to, with Apply and Revert.

Overrides ▾ on the Prefab row lists them all, with Revert and Apply on each line and Revert All and Apply All at the foot. Apply writes into the prefab's file, and every instance follows. Where the instance itself is placed is never an override. Each is one Ctrl+Z, and none works while the game plays.

Variants

A variant is a prefab based on another, with changes, and it follows its base wherever it changed nothing. New Prefab Variant in a prefab's or a model's right-click menu makes Chest Variant.prefab beside it. Dropping an instance onto a Project folder asks whether to make a Variant (Enter), keeping what the instance changed, or an Original that follows nothing.

Variants can have variants. The Inspector's Prefab row names both, Red Chest, a variant of Chest, and applying an override on an instance of a variant asks where it goes: Apply to Red Chest or Apply to Chest.

Nested instances and unpacking

A prefab can hold instances of other prefabs, and a change to the inner prefab reaches every prefab that holds it. Two instances of one prefab inside another are told apart, so an override on a street's second lamp stays on the second lamp. A field that names another entity of the prefab, such as a joint's other body, names that part of its own instance in each one; see EntityRef.

Prefab ▸ Unpack in an instance's right-click menu turns it into the scene's own entities, leaving the instances nested in it as instances; Unpack Completely leaves none. Ctrl+Z packs it again.

Models are prefabs

When the editor imports a model (glTF, GLB, FBX or OBJ), it makes the model's prefab, and you place a model as you place any prefab. Each node of the file is an entity. A file with one node at its top has that node as the prefab's root; a file with several, or with Preserve Hierarchy ticked, gets a root of its own above them, named after the file. Its materials are the file's, or the material files you give them in its import settings. Each entity's identity comes from the model's identity and the names of the nodes above it, so importing again keeps the overrides inside its instances.

Double-click a model to look at its prefab, which is read-only. Change it through its import settings (see Models), or make a variant of it. An instance of a model has no Apply, since its prefab is what the import makes.

Instance prefabs from code

A component with a PrefabRef field shows a slot in the Inspector that takes a prefab or a model. It holds the file's identity, so moving the file never breaks it, and the build packs the prefab whether it is addressable or not.

[AbyssComponent]public partial struct Spawner{    public float Every;    public PrefabRef Enemy;   // a slot in the Inspector}

Load a prefab once, keep its PrefabId in a component or a resource, and make instances with the system's command buffer:

PrefabId enemy = context.Assets.LoadPrefab(spawner.Enemy);   // or by key: LoadPrefab(Addresses.Enemy)if (context.Assets.StateOf(enemy) == AssetState.Loaded) { /* drawn whole from its first frame */ }
ulong made = context.Commands.Instantiate(enemy, position, rotation);   // in no scene, until despawnedulong held = context.Commands.Instantiate(enemy, Vector3.Zero, Quaternion.Identity, parent: hand);context.Commands.Despawn(made);    // all of the instancecontext.Assets.Release(enemy);     // gives back one load

Instantiate returns the instance's top entity at once and builds the instance when the command buffer applies, or once the prefab has loaded. The position and rotation are relative to the parent, the scale is the prefab's, and scene: puts the instance in a scene. The system declares AndInstantiate in its structural access; code that runs between frames, such as a flow, calls world.Instantiate.

Loads are counted: loading a prefab already loaded gives the same id and holds it once more, and Release gives one load back. The prefab goes once no load, entity or waiting instance holds it. The prefab is read on a background thread with what it is drawn with, its meshes, materials and images, so an instance is drawn whole from its first frame.

A scene your game loads lets go of its own loads once its entities hold what they use, so unloading the scene takes with it what nothing else uses. In the editor, Stop lets go of everything the game loaded while it played.

In a built game, the packs hold each model's prefab beside its meshes, and each .prefab that a scene, a PrefabRef field or an addressable key reaches (see Packs). The instances a scene holds are built into the scene's own image, which loads faster than making them one by one.

In the Scripting API