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 all the assets they need. This section explains how Awaken3D 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:
json
{
"version": 4,
"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. The version field is the scene format version - currently SCENE_VERSION = 4. Older scenes are migrated forward automatically on load (v1→v4 covers collider and multi-script format changes), and a scene authored by a newer build loads best-effort with a console warning rather than being rejected.
A brand-new project starts from a seeded default scene - a ground slab, a directional Sun, and a Main Camera - so the Game view works out of the box.
The multi-scene model
A game is rarely one scene. Awaken3D 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 sit 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 to keep them), the hierarchy collapses, and undo history is cleared. Scenes share the project's asset pool, so a mesh or material imported once is available to every scene.
At runtime, scripts can switch scenes too via api.loadScene - 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. It is marked with a star in the library. The first scene you save becomes the entry scene automatically; you can reassign it at any time. If you never set one, the export has no defined starting point - so always confirm the star is on the scene you want players to see first.
📸 Screenshot - save as img/world-scene-library.png
The Scene Library panel with three named scenes, one flagged as the Entry Scene (star), and the current scene highlighted.
Saving, opening & renaming scenes
Scene-library operations are:
| Action | What it does |
|---|---|
| Save Scene | Snapshots the live World into the library under a name (create or overwrite) and makes it the current scene. Save is blocked while in Play mode - the transient play-time world is never captured. |
| Open Scene | Replaces the live World with a library scene, clears selection and undo history, and marks it current. |
| Rename Scene | Renames a library entry; the current-scene and entry-scene pointers follow the rename. |
| Delete Scene | Removes a library entry; if it was the current or entry scene, that pointer is cleared. |
| Set as Entry Scene | Marks which scene the exported game boots into. |
How a Project bundles everything
A Project is more than its scenes. When you save a .awaken project file, Awaken3D writes a Project Bundle containing:
- the Scene Library and the entry-scene pointer,
- Prefabs (reusable object subtrees - see Prefabs),
- Scripts and Materials (referenced by id from components),
- the meshes and textures actually used by those scenes and prefabs,
- global Render Settings,
- and asset source folders for the Asset Browser.
The project format is versioned as PROJECT_VERSION = 3. It stores meshes quantized (positions as u16, normals octahedral-i8, uvs u16) to keep files small - the change that landed in v2 - and v3 adds persisted skeletal assets (skeletons, clips, rig-space clip library, skins) and particle-effect metadata. A project keeps your whole imported asset pool - every mesh and texture you've brought in, even ones no scene uses yet - so the project stays fully editable and you can drop an unused import into a scene later.
Shipping a self-contained game is a separate step that bundles the game's content into a single playable file - and there the pruning happens: only the meshes and textures the shipped scenes actually reference are packed. See Export to a game file.
In this section
- GameObjects & Components - the entity/component model, the registered component types, and how reflection drives the Inspector and serialization.
- Transforms & Hierarchy - position/rotation/scale, local vs world space, parenting, and cycle rejection.
- Prefabs - saving a subtree as a reusable template, instancing it, and resolving its dependencies.
- Static Objects & Batching - the Static flag, index-merge batching, and when to use it.
- Editing Operations - selection, duplicate, copy/paste, delete, isolate, and the undo/redo command stack.
See also
- Core Concepts - the mental model of the engine.
- GameObjects & Components - what fills a scene.
- Export to a game file - turning the entry scene into a shipped game.
- Data formats - the exact JSON shapes.