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, True / False, Text, List, Object) with Session, Saved, or Scene lifetime
Scripts	OpalScript classes, Behavior Components, and custom Flow nodes
Asset library	Shared images, audio, prefabs, characters, .ssb bundles, .pfx effects
Art Canvas graph	Persisted Art workspace board (artGraph)
Sound Canvas graph	Persisted Sound workspace board (soundGraph)
Particle Canvas graph	Persisted FX workspace board (particleGraph)
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	Per-object attachments and field values for Health, physics, Inventory, and Behavior 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

Manage scenes in the Scenes dock panel. The top-bar Scene picker provides quick switching.

Action	Use when	Where
New scene	You need a blank level, menu, or screen	+ New Scene in Scenes panel
Duplicate scene	You want a variant of an existing level	More → Duplicate on the row
Rename	The scene name should describe its role clearly	More → Rename on the row (reference-safe — see below)
Set start scene	Choose which scene players see first	☆ / ★ on the row
Reorder	Change authoring order (player path is Go To Scene, not list order)	Drag the row
Delete	The scene is no longer needed	More → Delete on the row (last scene can't be deleted)
Import	Bring in a scene file	Import… in Scenes panel or File → Import Scene…
Search / rescue	Find a scene or re-attach an orphan	Search scenes… / Unassigned → Add to project

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

Rows label the Start and Current scenes explicitly. If loading fails, the panel keeps its last loaded list and offers Retry.

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 by clicking ☆ → ★ on its row in the Scenes panel. List order is authoring order; players start at ★ and move where Go To Scene sends them. For most games, the start scene should be a menu or boot scene that initializes GameState and routes the player to the correct level.

Cameras and simultaneous views

Create a named camera with Create → Camera, then select it to configure the Scene Camera component. New cameras have only this component; their icon and transform controls belong to the editor. Choose Use at scene start in its inspector for the opening shot. Cameras can be renamed, duplicated and deleted through the usual hierarchy commands.

The hierarchy marks each camera Start, Viewport, Standby, or Off. Start provides the opening primary view; Viewport renders an additional view; Standby becomes primary when activated; Off has its component or output disabled. Inspector presets are grouped into Primary view and Additional view. Choose Use at scene start to select the opening camera after setting its primary framing.

For split-screen, use Left half on the startup camera and Right half on a second camera. The right-half preset sets its Output to Additional viewport. For picture-in-picture, keep the startup camera full-screen and choose Inset on the second. Output position and size are fractions of the available canvas, so views resize with the game. Higher viewport order draws above lower views.

Each camera has its own zoom, follow target, smoothing, world offsets, dead zone and bounds. Zero smoothing snaps to the target. Dead zones let a character move within part of the visible frame before the camera follows. Stage or custom bounds prevent the view from moving past a level edge; bounds smaller than the view center it.

The selected camera's frame guide uses the same output clipping, framing and bounds as Play. Its dead zone is centered on that bounded view, and selected cameras show the stage or custom bounds outline.

During Play, pointer input uses the topmost view that accepts input. A drag stays with the camera where it started, even when the pointer leaves that view. Turning off Accept pointer input on an inset lets the view behind receive input. All views share one running world and one screen-space HUD.

Use camera component actions in Flow/Behavior or the typed SceneCamera API for independent Focus, Move To, Zoom To, Follow, Shake and Activate controls. Existing global camera Flow actions address the primary camera. During Play, wheel, pinch and pointer gestures belong to the game and never apply editor camera navigation. A game can implement zoom through its own input and camera actions. Play and the exported player use each camera's framing mode; Arrange keeps its own navigation. The selected camera's frame guide shows its name, zoom and startup status.

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 — or, with the Scene lifetime, values that must not.

Declare them in the Variables dock. Each field has a type (Number, True / False, Text, List, Object) and a lifetime (Session, Saved, or Scene). Full reference: Variables and GameState.

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

Where a project lives depends on which editor you are in:

Editor	Where data goes
Browser	Your Opal account. Sign in on the same account to pick the work up on another device.
Opal Desktop	An ordinary folder on this computer. File → Save Project writes that folder. You can work offline.

On Desktop, File → Cloud Sync… uploads, downloads latest, or syncs the open folder with your account. Deleting the folder removes the local project and leaves any cloud copy in place.

Export .opal backups before a risky rewrite, or whenever you want a file you can reimport with File → Open Project… (browser) or by opening the folder (Desktop).

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
• Variables and GameState
• Opal Desktop
• Objects and hierarchy
• Visual scripting
• Sharing and publishing