Projects and scenes

A project is the whole game. A scene is one screen, level, menu, room, or test area inside that game. Most editor work is scene-local, but the project decides which scenes exist, which scene starts first, and which shared systems are available everywhere.

Project contents

An Opal project stores:

Part	Purpose
Scene list	Ordered scenes that make up the game
Start scene	The scene loaded first in Play mode and exported builds
GameState variables	Global typed values (number / bool / text) such as score, lives, quest text
Project components	Custom components authored in the Components workspace
Scripts	Project JavaScript helpers / behavior scripts
Asset library	Shared images, audio, prefabs, characters, .ssb bundles
Art Canvas graph	Persisted Art workspace board (artGraph)
Sound Canvas graph	Persisted Sound workspace board (soundGraph)
Publishing metadata	Arcade slug / remix settings on the hosted portal

Projects are selected from the Project picker in the top bar. Use separate projects for separate games, not for separate levels of the same game.

Scene contents

Each scene stores:

Part	Examples
Object hierarchy	Sprites, groups, UI roots, spawners, cameras
Inspector data	Names, transforms, visibility, interaction flags, object variables
Components	Health, Collider 2D, Rigid Body 2D, Inventory, custom components
Object Flow	Per-object rules such as On Tap or On Collision
Scene Flow	Scene-wide rules such as On Scene Start or Go To Scene
Animation data	Motion clips, skeleton references, state machines
Runtime settings	Background, camera, physics options, scene music (scene.audio)
UI document	In-game HUD / menu tree for that scene

Think of a scene as a self-contained playable composition. Objects in the scene can reference shared project assets, but the scene owns their placement, settings, components, and graph rules.

Creating scenes

Open the Scene picker in the top bar.

Action	Use when
New scene	You need a blank level, menu, or screen
Duplicate scene	You want a variant of an existing level
Rename	The scene name should describe its role clearly
Reorder	The project scene list should match the game flow
Delete	The scene is no longer needed

Use names that remain clear in graphs: Main Menu, Level 1, Battle Test, Credits, Win Screen.

Choosing a start scene

The start scene is the entry point for:

• Play mode
• Fullscreen play
• Exported game bundles
• Static player builds

Set the start scene from the project or scene controls. For most games, the start scene should be a menu or boot scene that initializes GameState and routes the player to the correct level.

Scene transitions

Scene transitions are usually handled in Scene Flow:

1. Open the Scene Flow workspace.
2. Add an event such as On Scene Start, On Custom Event, or a win condition.
3. Wire it to a Go To Scene action.
4. Select the target scene.

Use Scene Flow for global navigation. Use Object Flow when a specific object triggers navigation, such as a button, door, portal, or pickup.

Scene renames are reference-safe: when you rename a scene, Opal updates Go To Scene actions in every project scene, including the open scene's latest unsaved Flow edits. Project Health also reports empty, missing, or ambiguous transition destinations before export or publishing. Click a transition problem to open its scene and focus the exact Flow node.

GameState variables

GameState variables belong to the project, not to a single scene. They are useful for values that must survive scene changes.

Good GameState variables:

Variable	Type	Purpose
score	Number	Shared score across levels
lives	Number	Player lives
hasKey	Bool	Unlock state used by multiple scenes
currentQuest	Text	Simple quest or state label

Prefer object variables for values that only matter to one object instance. Prefer component fields for values already modeled by a component, such as Health hp.

Autosave and storage

Opal autosaves scene and project data as you edit.

Mode	Where data goes
Hosted portal	Account-backed server storage
Local dev server	Server data folder (.opal-data/) via the /api — LAN devices can share it
No server API	Browser IndexedDB fallback per origin / profile

IndexedDB storage is real, but local to that browser. Export .opal backups before clearing site data or switching machines.

Recommended project structure

For small games:

Main Menu
Level 1
Level 2
Win Screen
Lose Screen

For larger games:

Boot
Main Menu
World Map
Level 01 - Meadow
Level 02 - Cave
Combat Test
Credits

Keep experiment scenes in the same project while you are building. Rename or remove them before publishing so scene pickers and graphs stay easy to read.

Related docs

• Getting started
• Objects and hierarchy
• Visual scripting
• Sharing and publishing