Scene and prefab files
A scene is a JSON file named *.scene.json under the project’s asset folder. It is the same SceneData that SceneSerializer reads, so a game loads the file the editor wrote without any editor code.
{ "version": 3, "entities": [ { "uid": "00000000-0000-4000-8000-000000000003", "order": "a0", "components": { "name": { "value": "Tinted Crate" }, "position": { "x": 220, "y": 0, "z": 0 } } }, { "uid": "00000000-0000-4000-8000-000000000004", "parent": "00000000-0000-4000-8000-000000000003", "order": "a0", "components": { "name": { "value": "Badge" }, "position": { "x": 0, "y": -90, "z": 0 } } } ]}(Shortened: the editor writes one field per line.)
What the editor writes
Section titled “What the editor writes”- Entities sorted by
uid. Each names the entity it hangs under as itsparent(a root has none) and its place among its siblings as itsorder: a short key compared as plain text,a0beforea1beforeb00. Moving an entity changes its ownorder, or itsparentandorder, and no other entity: one line in a diff. Siblings with the same key stand byuid, and one with noorderafter those with one, in the order of the file. - Components sorted by key, fields in schema order.
- Shortest numbers. A
Float32is written as the shortest decimal that reads back to the same value:0.1, not0.10000000149011612. - Tabs and a final newline.
fileIdlast, in a scene, a prefab, and the other files of the asset folder the editor saves: the file’s own id, which stays when the file is moved, so a value that carries it finds the file. It is the editor’s: a game passes over it. An older file may also end withreferences, which the editor drops at its next save (Missing and moved files).
Together these give the property that matters for version control: opening a scene and saving it without changes writes the same bytes. A diff shows what was edited and nothing else.
Scene files are machine-written. Keep formatters away from them (for Prettier, add the asset folder’s *.json to .prettierignore). Editing one by hand is fine; the next save from the editor puts it back into this form.
What is kept that the editor does not understand
Section titled “What is kept that the editor does not understand”- Components no plugin registers. If a scene uses a component the edit world does not know (its script does not load, a Package is taken out, or a branch has not been merged), the editor keeps it beside its entity, warns once for each file (when the file is opened, or when a paste or a prefab placed brings it in), and writes it back unchanged on save. A copy of the entity (Duplicate, Paste, Create Prefab, a prefab placed) has it too. So does a paste from another project: the clipboard cannot tell where a copy came from, so its components are kept, and named at the paste. Removing the entity removes it. A game that loads the scene passes over it.
- Fields a component no longer has. If a component in the file has a field its code does not (it was renamed or taken out), the editor keeps that field beside the component’s own, warns once for each file, and writes it back on save while the entity has that component. A copy of the entity (Duplicate, Paste, Create Prefab) has it too, and Apply to Prefab leaves it in the prefab. Removing the component removes it. A field renamed without
formerlystarts at its default; with it, the file’s value is read under the new name (Renaming a field or a key). A game that loads the scene passes over such a field. - Other top-level keys and metadata, such as
resources, are written back as they were. - A file an older release wrote. Where a release changes more than a name (a field moved to another component), a scene or prefab file saved before it is brought to today’s
versionas the game or the editor reads it, and the editor writes today’s at its next save. A file of a newerversionthan the editor’s is not opened, and a game does not load it.- Version 2 to 3: a scene’s hierarchy was the
parentandchildrencomponents, with pointers between siblings; it becomes each entity’sparentandorder, keeping every parent’s children in the order they had. The fivepixi:keys becomesprite,renderLayer,colorOverlay,spriteSheetandnineSlice, in scenes and prefabs, and in a prefab instance’s overrides. The file changes once, at its first save.
- Version 2 to 3: a scene’s hierarchy was the
Editor-only data
Section titled “Editor-only data”Components whose serial key starts with editor: exist for the editor. They are stored apart from the entity, so a game that loads the file never sees them:
{ "version": 3, "entities": [{ "uid": "a1", "components": { "name": { "value": "Spawn Point" } } }], "metadata": { "editor": { "components": { "a1": { "editor:note": { "text": "check collision here" } } } } }}Entity identity
Section titled “Entity identity”Every entity has a uid. References between entities (an entity’s parent, and any field of type Entity) store UIDs. The editor keeps UIDs stable: undoing a delete restores the same UID, and only copies (duplicate, paste) get new ones, with references inside the copied group pointing at the copies.
Scene files loaded together never share a UID: a game refuses a file with a UID that an entity of the world has, before anything of it is spawned. Two levels may use the same UID, since a switch unloads one before it adds the other; a level and the shared scene may not. A level’s entity field may name an entity of the shared scene by its UID. It is resolved as the level loads, so the game loads the shared scene first (Scenes).
Assets in component fields
Section titled “Assets in component fields”A field that refers to an asset stores the URL the game loads it from: the project’s assetBaseUrl plus the asset’s path, such as /assets/textures/crate.png.
When an asset is renamed or moved in the editor’s Assets panel, the editor updates these URLs: in every other scene, prefab, settings, tileset, clip and effect file directly (only the URL changes, the rest of the file keeps its bytes), and in the open scene as an undo step. The editor writes such a URL with the file’s id after it (?id=), and the game, the built game and the editor load the file by that id: a file moved outside the editor, in a file manager or with git mv, is found where it is now. A URL without an id is not changed; the editor lists it under missing files (Missing and moved files).
Prefab files
Section titled “Prefab files”A prefab is a JSON file named *.prefab.json: a tree of nodes, each with components and children. It is the PrefabData that PrefabSerializer.deserialize() turns into a prefab the game can spawn.
{ "version": 3, "root": { "id": "6f1c2a9e-5b7d-4c3a-9e21-0d4f8a7b6c55", "components": { "example:spin": { "speed": 2, "clockwise": true }, "position": { "x": 0, "y": 0, "z": 0 } }, "children": [ { "id": "b2a4c6e8-1f3d-4a5b-8c7d-9e0f1a2b3c4d", "slotName": "moon", "components": { "position": { "x": 70, "y": 0, "z": 0 } }, "children": [] } ] }}(Shortened in the same way.)
| Field | Meaning |
|---|---|
id | Identifies the node across edits. The editor writes it; a file without ids (version 1) gets them on its first save. |
slotName | The name code uses to reach a child of a spawned prefab: spawned.get('moon'). Children only. |
components | By serial key, sorted, as in a scene. |
children | Child nodes, in order. |
Opened in the editor, a prefab is edited like a scene: its nodes are entities in the hierarchy, and the slot name of a child is the “Prefab Node” section in the inspector. Three things differ from a scene:
- One root. A prefab is a single entity with what is inside it. The editor refuses to save a prefab document that has several root entities, and says so.
- No references to entities. A field that points at another entity is left out: a template has no entities to point at.
- Editor-only data only for what it holds. A prefab that holds instances of other prefabs keeps their links under
metadata.editor, as a scene does. A prefab that holds none has nometadata.
As with scenes, saving an unchanged prefab writes the same bytes, and components no plugin registers, and fields a component no longer has, are written back unchanged.
Prefab instances in a scene
Section titled “Prefab instances in a scene”Adding a prefab file to a scene puts its nodes into the scene as ordinary entities with new UIDs. The scene file holds them in full, so the game loads the scene without knowing about prefabs. What ties them to the prefab is editor-only data:
"metadata": { "editor": { "components": { "a1": { "editor:prefabInstance": { "source": "prefabs/orbiter.prefab.json" }, "editor:prefabLink": { "source": "prefabs/orbiter.prefab.json", "node": "7c9e…", "overrides": "+name example:spin.speed position.x position.y", "removed": "" } }, "a2": { "editor:prefabLink": { "source": "prefabs/orbiter.prefab.json", "node": "f02b…", "overrides": "", "removed": "" } } } }}| Key | Meaning |
|---|---|
node | The id of the prefab node the entity stands for. |
overrides | What the instance changed, space separated: key.field for a field, +key for a component it added, -key for one it removed. Written on save. |
removed | On the root: the ids of the prefab nodes this instance deleted. |
An instance follows its prefab file. When the file changes, every field, component, and node an instance did not change itself is taken from the file again. Where an instance stands is its own: its root’s position and rotation are never taken from the file and never in overrides, as in Unity, so moving or turning the prefab’s root moves no instance already placed. Its scale, and where each of its parts stands, follow the file.
- Scene files that are not open are rewritten as soon as the prefab file changes, whoever changed it: the editor, an agent, or a text editor. This needs the editor to be running. Run Update Prefab Instances from the command palette for prefabs that changed while it was not.
- A scene is brought in step when it is opened. If that changed anything, it opens with unsaved changes.
- The open scene follows at once when it has no unsaved changes, and after its next save when it has.
An entity added inside an instance is kept. An entity of an instance cannot be moved within it or out of it; the instance moves as a whole. Unpack Prefab Instance turns an instance into plain entities.
In the inspector, a field the instance changed has a bold label and a border in the accent colour. The component’s “More” menu has Revert to Prefab, and Apply to Prefab, which writes the component into the prefab file. Apply is one undo step: Undo puts the prefab file back as it was, and the scene’s instances with it. If the file was changed elsewhere since, that change is kept, and the scene follows it once saved.
A prefab inside a prefab
Section titled “A prefab inside a prefab”Open a prefab and add another prefab to it (Add to Prefab in the assets panel, or a drop on the hierarchy or the scene view). It is an instance, placed under the prefab’s root, and it follows its file the way an instance in a scene does: bold labels for what the outer prefab changed, Revert to Prefab, Apply to Prefab.
The outer prefab’s file still holds every node in full, so the game spawns it without knowing what it was built from. The children keep the slot names their own prefab gave them. The links are beside the nodes, keyed by node id:
{ "version": 3, "root": { "id": "b1", "components": {}, "children": [{ "id": "a1", "components": { "…": {} }, "children": [] }] }, "metadata": { "editor": { "components": { "a1": { "editor:prefabInstance": { "source": "prefabs/lot.prefab.json" }, "editor:prefabLink": { "source": "prefabs/lot.prefab.json", "node": "7c9e…", "overrides": "+name position.x", "removed": "" } } } } }}A change travels through the files. When the inner prefab changes, the editor rewrites every prefab file that holds it, then every prefab file that holds one of those, and then the scenes. As with scenes, this needs the editor to be running; Update Prefab Instances catches up afterwards.
A scene knows only the prefab that was added to it. Inside its instance, the entities of the inner prefab are nodes of the outer one: Apply to Prefab there writes to the outer prefab, as its change to the inner one. To change the inner prefab, open it.
A prefab cannot hold itself, directly or through a prefab it holds. The editor refuses to add one, and refuses to save a prefab that came to hold itself another way.
There is no scene inside a scene. What every level needs at once, such as the camera, is in the Project’s shared scene (sharedScene); what each level has a copy of, such as the player, is a prefab added to each.
A prefab defined in code is followed too. Its source reads code:<key>, with the key it has in the project’s prefabs. A change to its code reloads the editor; the scene that opens has followed, and the scene files that are not open are rewritten then. It has no file, so Apply to Prefab and Open Prefab are not offered for it: change the code.
The root’s position is a field like any other: an instance left where the prefab puts it moves when the prefab’s root moves.