Scenes & Game Structure

A Scene is a saved snapshot of your world (every object, its components and its hierarchy) and a Project is the bundle of scenes plus every asset and setting they need. This section explains how Awaken organises your game.

What a Scene is

At runtime your game lives in a single World: an in-memory container of entities and components (see GameObjects & Components). A Scene is that World serialized to JSON so it can be saved, reopened and shipped.

The on-disk shape is small and explicit:

{
  "version": 5,
  "entities": [
    { "id": 0, "name": "Ground", "parent": null, "static": true, "components": { "Transform": {}, "MeshRenderer": {} } },
    { "id": 1, "name": "Sun",    "parent": null, "components": { "Transform": {}, "Light": {} } }
  ]
}

Every entity records its id, name, parent link, an optional active / static flag, and a map of component data. Entities are written in the World's order, which is also the Hierarchy's sibling order and the order UI elements stack in, so a save, load and save again produces the same bytes. Two optional top-level fields are editor bookkeeping the engine never reads: view2d: true opens the scene in the 2D Scene view, and nextPart is a prefab's next part id (see Prefabs).

The version field is the scene format version, currently SCENE_VERSION = 5 (packages/core/src/serialize.ts). Older scenes are migrated forward on load: steps 1 to 4 cover collider and multi-script format changes, and 5 marks scenes that carry linked prefab instances, so a v4 scene's instances load unlinked. A scene written by a newer build loads best-effort with a console warning rather than being rejected.

File ▸ New Scene (and a fresh editor) starts from a seeded default scene: a ground slab, a directional Sun and a Main Camera, so the Game view shows something straight away.

The multi-scene model

A game is rarely one scene. Awaken keeps a Scene Library: a named collection of scene snapshots. Exactly one of them is loaded into the live World at a time (the current scene); the others wait in the library until you open them.

Opening a library scene replaces the live World wholesale: the previous contents are discarded (save first if you want them), selection is cleared, and undo history is cleared. Scenes share the project's asset pool, so a mesh or material imported once is available to every scene.

Each scene also keeps its own render effect stack (sky, fog, bloom, grade and the rest of Render Settings's effect cards). Opening a scene switches the editor to that scene's stack, and an imported pack attaches its look to its own primary scene rather than to whatever you have open.

At runtime, scripts switch scenes with api.loadScene(name); the same library backs both the editor and the shipped game.

The Entry Scene

The Entry Scene is the scene an exported game boots into, marked with a ★ in the Asset Browser's Scenes list. The first scene you save to the library becomes the entry scene automatically. To change it, open the scene you want and choose File ▸ Set "<name>" as Entry.

With no entry scene set, the exported game boots the scene that was open in the editor when you exported. The exported game also takes its render effects from the entry scene, not from the scene you have open.

Saving, opening and deleting scenes

Action	Where	What it does
Save Scene to Library…	File menu	Prompts for a name and snapshots the live World into the library under it (create or overwrite), then makes it the current scene. Blocked during Play, so the play-time world is never captured.
Open	Click a scene in the Asset Browser	Asks to confirm, then replaces the live World with that scene and marks it current. Blocked during Play.
Delete	Right-click a scene in the Asset Browser	Removes it from the library as an undoable step; if it was the current or entry scene, that pointer is cleared (undo puts it back).
Set as Entry	File menu	Marks the current scene as the one the exported game boots into.

There is no rename command in the editor yet: save the scene under the new name, set it as entry if the old one was, and delete the old one.

How a Project bundles everything

A Project is more than its scenes. Saving writes a .awaken project file (see Saving & Opening Projects) holding a Project Bundle:

• the Scene Library, the entry-scene pointer, and each scene's render effects,
• Prefabs (reusable object subtrees, see Prefabs),
• Scripts, including editor scripts, plugins and script libraries,
• Materials, shader graphs, subgraphs and compute shaders,
• meshes and textures (every one you imported, used or not),
• the skeletal-animation library (skeletons, clips, rig-space clips, skins), animation graphs and particle effects,
• render textures, render layer names, Simulations and the update graphs they run,
• terrain assets, stored as heightfields rather than meshes,
• sounds, fonts, UI images and UI animation clips,
• Render Settings, Project Settings (Time and Quality) and App Settings,
• plugin data, and each asset's import-source folder for the Asset Browser's Folder view.

The project format is versioned as PROJECT_VERSION = 15 (packages/assets/src/persist.ts):

Version	Added
v15	Each RGBA texture stored as a PNG file instead of deflated pixels (a 3072 x 2048 photo-like atlas: 14.9 MB to 9.4 MB, lossless)
v14	The open scene stored once (sceneRef names its library copy) and baked clips as exact float64 binary spans (Crown Quest's project: 59.4 MB to 22.7 MB)
v13	Font faces carry family, weight, style and licence
v12	Simulations and the Time settings
v11	Render textures and render layer names
v10	Compute shaders
v9	App Settings
v8	UI images
v7	Texture pixels deflated
v6	Each script's uses list
v5	Each script's language; the v4 modules map folded into scripts
v4	Native module assets
v3	Skeletal assets and particle-effect metadata
v2	Meshes quantized (positions u16, normals octahedral i8, UVs u16)

A build refuses a project newer than itself rather than open it and drop what it cannot read on the next save. Because a project keeps your whole imported asset pool, you can drop an unused import into a scene later.

Shipping a game is a separate step, and that is where pruning happens: only the meshes, textures and clips the shipped scenes and prefabs reference are packed. See Export to a game file.

In this section

• GameObjects & Components - the entity/component model, every registered component type, and how reflection drives the Inspector and serialization.
• Transforms & Hierarchy - position/rotation/scale, local vs world space, parenting, world order and cycle rejection.
• Prefabs - saving a subtree as a reusable template, linked instances, variants and dependencies.
• 2D Games - the 2D Scene view, sprites, Shape 2D and 2D physics.
• Terrain - the engine's heightfield terrain type, api.terrain, and what ships.
• Static Objects & Batching - the Static flag, index-merge batching, and when to use it.
• Editing Operations - selection, duplicate, copy/paste, delete, isolate, folders, and the undo/redo command stack.

See also

• Core Concepts - the mental model of the engine.
• Saving & Opening Projects - the .awaken container itself.
• Export to a game file - turning the entry scene into a shipped game.
• Data formats - the exact JSON shapes.