Core Concepts ​
A glossary of the words this whole manual uses - Project, Scene, GameObject, Component, Prefab, Material, Script, Play mode, and the Player - with each term linking to its full page.
Awaken borrows its vocabulary from Unity and Unreal, so much of this will feel familiar. What's worth learning is how the pieces nest: a Project contains Scenes, a Scene is a tree of GameObjects, each GameObject is a bag of Components, and a Script is just one kind of component that runs code. Everything else - Prefabs, Materials, the Static flag, Play mode - hangs off that spine.
📸 Screenshot - save as img/guide-concepts-nesting.png
The Hierarchy and Inspector side by side, showing the nesting these terms describe: a Scene of GameObjects in the Hierarchy tree, and the selected GameObject's Components (Transform, MeshRenderer, …) listed in the Inspector.
Project ​
A Project is the whole thing you're working on - all your scenes, imported assets, materials, prefabs, and scripts - persisted as a single binary .awaken file (current project version 3, which persists skeletal-animation assets and particle effects alongside quantized meshes). This is your editable source of truth, distinct from the game.html you export to ship. See Saving & Opening Projects.
Scene ​
A Scene is one arrangement of objects - a level, a menu, a title screen. It's a tree of GameObjects plus its render settings, serialized to a versioned graph (current scene version 4, with automatic migration of older versions on load). A project can hold many scenes in its scenes library. See Scenes & Game Structure.
Entry Scene ​
The Entry Scene is the one scene an exported game boots into - the first thing a player sees. You mark it with File ▸ Set … as Entry (a ★ marks it in the Asset Browser); scripts move between scenes at runtime with api.loadScene(name). Without a designated entry, a build has no defined starting level. See Scenes & Persistence.
GameObject / Entity ​
A GameObject is any thing in a scene - a cube, a light, a camera, the player. Under the hood it's an Entity: a lightweight, recyclable handle (an id plus a generation counter, so stale references are detectable). The GameObject API is a friendly façade over the data-oriented ECS. On its own an entity is empty; what it is comes entirely from the components attached to it. See GameObjects & Components.
Component ​
A Component is a bag of plain data attached to an entity - Transform, MeshRenderer, Light, RigidBody, and so on. Each is registered with a reflection schema (field names + types), and that one schema powers three things at once: the Inspector UI, serialization, and the Add Component menu - so a new component type gets an editor and gets saved with zero extra work. The component types the editor knows (its Add Component menu) are Transform, MeshRenderer, MeshMaterial, Light, Camera, Animator, AnimStateMachine, Ragdoll, BoneAnchor, RigidBody, Collider, AudioSource, Script, Tag, UINode, UIAnimator, and ParticleEmitter. See the Component Reference.
Transform ​
The Transform is the component that gives an object a position, rotation (a quaternion), and scale - and a place in the hierarchy. Parent an object under another and it inherits the parent's transform, so moving the parent moves the children. Nearly every object has one. See Transforms & Hierarchy.
Prefab ​
A Prefab is a reusable GameObject template - build one object (or a whole sub-tree), make a prefab from the selection, and stamp out instances of it across your scenes. Prefabs are saved with the project and shipped in the export, and scripts can spawn them at runtime with api.spawn(prefabName, …). See Prefabs.
Asset ​
An Asset is a piece of imported or authored content that objects reference - a mesh, a texture, a material, a prefab, or a scene. Assets live in the Asset Browser and are stored once in the project (and, for what a game needs, embedded self-contained in the export). See the Asset Browser and Importing Assets.
Material - preset vs hook-based ​
A Material controls how a surface looks. Awaken has two kinds:
- Preset (data) materials - the everyday case: the MeshRenderer component carries PBR values like base color, an albedo texture, metallic and roughness directly as fields. No shader authoring, no separate asset; you fill in fields. This is what importers produce.
- Hook-based materials - for custom looks, a Material asset provides small WGSL hook snippets (e.g. a
vertexPositionhook for displacement) that Awaken splices into the standard shader template at marked points, plus typed params that become Inspector controls. An object opts in by adding a MeshMaterial component naming that asset. This is a real shader escape hatch without hand-writing a whole pipeline.
The two coexist: MeshRenderer always supplies the PBR fields; MeshMaterial is the optional reference to a hook-based Material asset on top. Params marked per-object can be overridden per entity from the MeshMaterial component, so one Material can serve many objects.
Hook-based materials are authored in the Shader Editor; the mechanics are in Materials & Hook Shaders.
Script / ScriptBehavior ​
A Script is a component that runs your TypeScript gameplay code. You write a ScriptBehavior class (lifecycle hooks like onStart / onUpdate) in the Code Panel, compile it, and attach a Script component naming that behavior. The code talks to the engine through the api object - input, timers, physics, spawning, scene loading, UI. A script's public number / string / boolean / Entity fields are auto-discovered and become per-instance Inspector parameters. Scripts run in Play mode and in the shipped game (compiled ahead-of-time at export). See Scripting Overview and the ScriptApi Reference.
Static flag ​
The Static flag (a per-object checkbox in the Inspector header) marks an object as non-moving scenery. Turning it on lets the engine optimise it three ways: draw-call batching, cached shadows, and treating its collider as a fixed (immovable) physics body. Only mark objects that genuinely never move. See Static Objects & Batching.
The Volume / effects stack ​
Post-processing in Awaken is modelled as an inspector-like stack of optional effects, mirroring Unity's post-process Volume: you add and remove effects - bloom, SSAO, colour grade, vignette, fog - and absent effects pack neutral values (a pure pass-through). Distinct from this are engine settings (shadows, batching, GPU cull), which are flat toggles, not effects. Configure both in Render Settings; the effects themselves are documented in Post-Processing (Volume).
Play mode ​
Play mode runs your scene live inside the editor. Pressing â–¶ Play serializes (snapshots) the world, then ticks the runtime; â– Stop restores that snapshot exactly, so play-time motion never persists into your saved scene. It's a live sandbox - you can even edit while playing, and Awaken asks whether to keep those edits on Stop. Because Play runs the same runtime the export runs, Play is a faithful preview of the shipped game. See Preview & Play.
The Player ​
The Player (@awaken/player) is the standalone runtime that runs a saved scene without the editor - the shell inside your exported game.html. It's a thin wrapper over the exact same @awaken/runtime the editor's Play mode ticks, which is what makes edit == play == ship literally true. See The Player Runtime.