Troubleshooting

This page lists common problems and the first checks to make.

The Editor Does Not Open

If you are using the hosted portal, open:

https://opal-engine.com/create

If you are developing locally:

npm install
npm run dev

Then open:

http://127.0.0.1:5173/

If the port is busy, stop the other process or start the server on another port.

Sign-In Or Publishing Fails

Check:

1. You are on the hosted site, not a static/offline mirror.
2. You are signed in.
3. The server has the required auth environment variables.
4. The browser is not blocking cookies or local storage for the site.
5. The project has saved before publishing.

Publishing to the arcade requires the hosted/server API. Static copies can edit locally but cannot publish to the portal.

The Docs Page Looks Wrong Or Missing

On the hosted site, docs should open at:

/docs/

For local editor testing, build static docs once:

npm run docs:build:local

For live docs authoring, run:

npm run docs:dev

My Project Or Scene Disappeared

Check which storage mode you were using.

Mode	Check
Hosted portal	Confirm you are signed into the same account
Local dev server	Confirm the same server data folder is running
No server API (IndexedDB fallback)	Confirm the same browser profile and site origin are being used
Different machine	Import a .opal or scene backup if needed

IndexedDB-fallback scenes live in that browser's IndexedDB. Clearing site data can remove them.

Imported Assets Are Missing

Try:

1. Open the asset library and confirm the asset exists.
2. Check the Problems panel for missing references.
3. Re-import the file if it was deleted from project storage.
4. Check browser console messages for failed asset URLs.

Background Removal Is Unavailable

Background removal uses server-backed tooling and model dependencies. It is not available without the Node server.

Use the hosted portal or a local dev server with the required model setup. Crop, padding, outline, shadow, and normal asset import can still work without background removal.

Art Canvas Preview Or Save Is Empty

Check:

1. A source node is wired into Animation.
2. Animation is wired into Preview and/or Save .ssb.
3. Slice Sheet columns, rows, margin, spacing, and count produce at least one frame.
4. A Sprites node contains at least one image.
5. The Save node is connected to an Animation, not directly to frames.
6. If using an existing .ssb, the bundle still exists in the asset library.

See Art Canvas.

Sound Canvas Preview Or Save Fails

Check:

1. A source node (Sample, Mic, Tone, or Noise) feeds the chain.
2. Preview and/or Save are wired to a renderable input.
3. Sample or Mic has a chosen or recorded asset (no missing badge).
4. The pipeline is under the two-minute render cap — trim long sources earlier.
5. After re-baking over an existing asset, play-test again so the runtime picks up the new WAV.

See Sound Canvas.

A Tap Or Click Event Does Not Fire

Check:

1. The object has Interactable (or an On Tap graph that adds it). Confirm enabled is on.
2. The graph is attached to the correct object (Object Flow, not a different instance).
3. The event type matches the gesture (tap vs drag vs long-press).
4. Another object is not covering it (blocksBehind, draw order, Sorting Group).
5. Play mode is running (edit mode does not run gameplay Flow).
6. The Flow overlay shows whether the event fires.

For UI buttons, confirm the UI layer is visible, the button's Event name matches a Scene/Object Flow listener, and input is not blocked by an overlay panel.

A Collision Event Does Not Fire

Check:

1. Both objects have Collider 2D where needed.
2. Moving physical objects have Rigid Body 2D.
3. Sensor vs blocker settings match the intended event.
4. Collider bounds overlap in Play mode.
5. Collision groups do not filter each other out.
6. The event graph is listening on the correct object (Rigid Body / Collider collision events or component handlers).

For Projectile sticks that never weld: enable Continuous Collision (CCD) on the rigid body, wait past Arm Delay, and confirm Ignore Owner is not filtering the intended target.

See Physics and collisions.

A Graph Branch Goes The Wrong Way

Check:

1. The condition node values in the inspector.
2. GameState / object variable names and capitalization (declare them in Variables or the object Variables card).
3. Expression mode vs literal mode — Flow = expressions do not bind a bare GameState.score identifier; use Get/Set variable nodes or UI self.score bindings.
4. Whether a component field is being changed elsewhere.
5. Whether Scene Flow and Object Flow both update the same state.

Use small test graphs while isolating the problem. Open Graph Explorer (Graph dock) for prefab / event / asset maps when the hierarchy alone is not enough.

Published Build Opens The Wrong Scene

Set the project's start scene, test from that start scene, publish again, and open the public page in a new tab.

Also check whether a Scene Flow On Scene Start rule immediately changes scenes.

Public Site Shows Old Files

Try:

1. Confirm your latest code/docs changes were pushed.
2. Confirm the server deploy pulled the latest commit (npm run deploy on the box).
3. Hard-refresh the browser.
4. Check browser cache or Cloudflare cache if the public route still shows old assets.

Related Docs

• Getting started
• Art Canvas
• Sound Canvas
• Physics and collisions
• Input and controls
• Testing and debugging
• Sharing and publishing