Saving & Opening Projects
A Awaken project is your working file - the complete, editable state of everything in the editor, saved as a single binary .awaken file. This is what you save while you work; the game exports are read-only artifacts built from it.
Where a game.html carries only the assets a game uses (compacted and lossy-quantized for size), a .awaken project carries everything: every imported mesh and texture byte, the whole scene library, prefabs, materials, scripts, the skeletal-animation library (skeletons, clips, rig-space clips, skins), particle effects, UI animation clips, imported fonts, render settings, and import-source folder paths - the full source of truth you keep coming back to. You cannot open a game.html in the editor; you always keep the .awaken.
The .awaken format
A .awaken file is a compact binary container - a glTF-.glb-style layout - not JSON:
- A small JSON metadata chunk holds the scene graph and all the structured data.
- One binary blob holds every mesh buffer and texture's raw bytes, referenced from the metadata by
[offset, length]- no base64, no number-array JSON, so it stays compact and fast even for a large imported world.
The current format is PROJECT_VERSION = 3. Version 3 persists the skeletal-animation library (skeletons, baked clips, the rig-space clip library, and skins) and particle-effect blueprints - without it a rig and its clips evaporated on reload. Version 2 stores mesh geometry quantized (positions Uint16 over the mesh AABB, normals octahedral Int8, UVs Uint16 over the UV bbox - roughly 32 → 12 bytes per vertex); version 1 stored raw Float32. Quantization is lossy but idempotent - a value already on the grid re-quantizes to the same index, so re-saving never compounds error. Indices and vertex colours are kept exact, and decodeProject dequantizes back to Float32 on load, so the in-memory scene and the renderer's vertex layout are identical regardless of version. Full field list on Data Formats.
NOTE
The workspace dock layout is deliberately not restored from the project. It is a per-machine preference kept in localStorage, so opening a colleague's project never clobbers your panel arrangement.
Saving in place (Chromium) vs download/upload
Awaken uses the browser's File System Access API to save a project in place to a real file on disk - like a native app's Save, with no browser storage quota and no risk of eviction. The GB of asset bytes live in that on-disk file, never in browser storage.
This API is Chromium-only. On Firefox and Safari, Awaken falls back to the classic web pattern:
| Chromium (File System Access) | Firefox / Safari (fallback) | |
|---|---|---|
| Save | Writes back to the same file, no dialog | Downloads a new project.awaken each time |
| Save As | Native save-file picker | Same download |
| Open | Native open-file picker | Hidden <input type="file"> upload |
| Reopen on reload | Yes (handle remembered) | No |
Reopen on reload
When you save or open on Chromium, Awaken stores the tiny FileSystemFileHandle in IndexedDB (under the key projectHandle). On the next launch it prompts "Reopen last project '‹name›'?"; accepting re-grants permission (a single click, since the API requires a user gesture) and loads the file. Only the handle is stored in IndexedDB - the heavy asset bytes stay in the on-disk file, so there is no storage-quota risk. See Launching the Editor.
Saving, and the ⌘S habit
Save with ⌘S (Ctrl+S on Windows/Linux), or File ▾ → Save Project. ⇧⌘S / File ▾ → Save Project As… picks a new file. Save works from anywhere in the editor - even from a text field - and pre-empts the browser's own Save dialog.
The project name in the Toolbar shows a • dot while you have unsaved edits, and its tooltip reads "- unsaved" / "- saved".
📸 Screenshot - save as img/shipping-project-dirty.png
The Toolbar project-name area showing a filename with the unsaved • dot, with the hover tooltip reading "project.awaken - unsaved".
Auto-save is off - save explicitly
IMPORTANT
Awaken does not auto-save. Persisting a project rewrites the entire file - every mesh and texture, potentially hundreds of MB - atomically. Doing that on a timer thrashed the disk and Chrome's swap temp files, so it was removed. Save deliberately with ⌘S.
Two guards protect your work despite the lack of auto-save:
- Unsaved-changes warning. A
beforeunloadguard fires the browser's native "Leave site?" prompt if you try to close or reload the tab while the project is dirty. - No save during Play. Save is blocked while the game is playing - persisting mid-Play would bake transient runtime state (physics positions, accumulated rotations) into the saved scene. Stop first, then save; the pre-play scene is restored on Stop.
Opening a project
File ▾ → Open Project… opens the file picker (Chromium) or the fallback upload input. A large project is read and decoded through a progress dialog with distinct phases - Reading file → Decompressing → Loading meshes → Loading textures → Building scene → Compiling scripts - so a multi-second load never looks frozen. Scripts are recompiled from their TypeScript source on open; any that fail to compile are reported to the Console without blocking the rest of the load.
Opening a project replaces the current editor state entirely (scene, scene library, prefabs, materials, scripts) - it is not a merge.
See also
- Data Formats & Versions - the
.awakencontainer layout andPROJECT_VERSION - Export game.html - how a shipped game differs from a saved project
- Launching the Editor - reopen-last-project on startup
- Toolbar & Menus - the File menu and the unsaved-changes indicator