Opal Docs
ArcadeEditorLearnDesktop

Appearance

Troubleshooting ​

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

Search this page: press Ctrl+K (or Cmd+K on Mac) and type the exact warning or field name — Block taps behind, Arm Delay, Continuous Collision, Sensor, GameState — to jump straight to the fix. Every section below is anchored to its error string.

The Editor Does Not Open ​

In the browser, open:

text
https://opal-engine.com/create

If the page does not load, try another browser, disable blockers for the site, or hard-refresh.

For Opal Desktop, download the app from opal-engine.com/download. The preview is unsigned, so your operating system may ask you to approve it before opening. Install newer versions from that page — project folders and preferences are preserved.

Sign-In Or Publishing Fails ​

Check:

  1. You are on opal-engine.com and signed in.
  2. The browser is not blocking cookies or local storage for the site.
  3. The project has saved before publishing.

Publishing to the arcade needs a signed-in account in the browser editor. On Desktop, use File → Cloud Sync… to put the folder on your account, then publish from /create.

The Docs Page Looks Wrong Or Missing ​

Docs live at:

text
https://opal-engine.com/docs/

Hard-refresh if a page looks stale or unstyled.

My Project Or Scene Disappeared ​

Check:

  1. You are signed into the same account you used when you last edited (browser), or you still have the project folder (Desktop).
  2. The Project picker is on the project you expect — switching projects hides the other project's scenes.
  3. The Scenes panel Unassigned section for a scene that is not in the current project.
  4. You have a .opal backup to import with File → Open Project…, or a cloud copy to download with File → Cloud Sync… / Download a Cloud Project… on Desktop.

Clearing site data in the browser does not delete account projects, but it can sign you out. Deleting a Desktop project folder removes the local project and leaves its cloud copy available.

Local Project Storage Changed In Another Tab ​

A static editor that saves projects in browser storage shows this notice when another tab updates or removes its local database. The open scene stays available, but saving from that tab is unavailable. Keep the tab open while you copy any unsaved changes, then reload to use the current storage version.

Project Asset Folder Could Not Sync ​

When using a local project asset folder, sync failures appear in the Assets panel or the Console. Check that the local server is running and the folder is accessible, then return focus to the editor or open the asset folder again to retry. Background polling also retries changed files after a failed sync.

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 runs on Opal's servers. If it is unavailable, try again in a moment, or use crop, padding, outline, and trim in Pixel Studio — those still work without background removal.

Apple Vision "Did Not Find A Subject" ​

The Apple Vision model in the Pixels Cutout menu wants a photo-like image with one clear foreground object. Pixel art, tiny sprites, flat colour, and layers that are already transparent usually come back with no subject, and the Cutout hint says so. Pick BiRefNet Lite or BEN2 in the model list instead; both are trained on flat art and sprites. A message that asks you to install the Command Line Tools means the helper itself could not run or compile, which is a different problem.

See Pixel Studio.

Bake Animation Needs Two Frames ​

Bake animation in Pixel Studio writes PNG frames plus an .ssb. It needs two or more drawing frames. For a still, use Bake PNG instead. Clip timing lives on the .ssb or in Art Canvas — Pixel Studio frames are onion-skin columns, not a duration timeline.

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.

Particle Canvas Preview Or Save Is Empty ​

Check:

  1. An Emitter feeds the chain, and Save is wired to the last modifier (or to Combine).
  2. Burst or Rate on Emitter is not zero.
  3. Render has a primitive or a sprite asset.
  4. You are looking at the FX preview dock, not the scene — the canvas never binds onto a selected object.
  5. After baking, pick the .pfx on Spawn VFX or a Particle Emitter and press Play.

See Particle Canvas.

A Tap Or Click Event Does Not Fire — Interactable, Block taps behind, On Tap ​

Check:

  1. The object has Interactable (or an On Tap graph that adds it). Confirm Receives taps 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 (Block taps behind on, draw order, Sorting Group). A full-screen panel with Interactable silently eats every tap beneath it — turn Block taps behind off only for overlays that should pass taps through.
  5. Play mode is running (edit mode does not run gameplay Flow).
  6. The Flow overlay shows whether the event fires — if On Tap flashes but Add Counter doesn't, the execution wire is severed.

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.

Recipes: Input and controls — touch joystick workarounds for touch, Testing and debugging — recipe 1 for the 2-minute tap debug.

A Collision Event Does Not Fire — Collider 2D, Rigid Body 2D, Sensor, Continuous Collision, Arm Delay, Ignore Owner ​

Check:

  1. Both objects have Collider 2D where needed.
  2. Moving physical objects have Rigid Body 2D.
  3. Sensor vs blocker matches the intended event — Sensor on fires On Sensor Enter, not On Collision Start.
  4. Collider bounds overlap in Play mode — select the object, toggle C to see the shape editor.
  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 (default 0.08 s — firing point-blank can hit before arming), and confirm Ignore Owner is not filtering the intended target. See Physics and collisions — recipe 4.

A Graph Branch Goes The Wrong Way — GameState, GameState.score, Get Variable, Variable at least ​

Check:

  1. The condition node's inspector values — is the threshold 5 but the live value 4.9?
  2. GameState / object variable names and capitalization (declare them in Variables or the object Variables card). score ≠ Score.
  3. Expression vs literal mode — a Flow condition should use Get Value / Variable at least, or =GameState.score in a Flow expression. HUD labels use Data bindings → GameState; do not paste a UI template onto a Flow node. See Variables and GameState.
  4. Whether a component field is being changed elsewhere in the same frame.
  5. Whether Scene Flow and Object Flow both write the same GameState key — one overwrites the other.

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. Recipe: Testing and debugging — recipe 2.

A Saved Variable Did Not Persist — lifetime, Saved, Clear saved data ​

Check:

  1. The Lifetime column on that row is Saved, not Session or Scene. Session fields reset when play starts; Scene fields reset on every scene enter.
  2. You did not click Clear saved data in the Variables panel, and no Flow Clear Saved Variables ran.
  3. You are on the same project (browser account, or the same Desktop folder). Saved data is keyed per game, not globally.
  4. Stop flushed the save — a crash mid-play can miss the last write. Play again and confirm the Value column after Stop → Play.

See Variables and GameState.

A Script Does Not Apply Or Run — Save & Apply, last-known-good, GetComponent ​

Check:

  1. You used Save & Apply (Cmd/Ctrl+S or Cmd/Ctrl+Enter). Typing keeps a local draft; pausing does not apply it.
  2. Diagnostics in Script Studio — a failing compile does not replace last-known-good. The last good build keeps running until a clean apply.
  3. The component is attached and enabled on the object you are testing, and Play is running.
  4. GetComponent<T>() uses an OpalScript class name or a native type (Health, RigidBody2D, …). opal.component declarations are not typed lookup targets.
  5. Native names such as Health / health are reserved — rename a colliding class and give it an unused component id.

Start at Scripts. Language and apply rules: Script Studio, lifecycle.

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.

Published Game Or Docs Look Stale ​

Try:

  1. Confirm you published the latest project (or that you are looking at the page you just edited).
  2. Hard-refresh the browser, or open the public link in a new private window.
  3. Wait a moment and reload — cached assets can lag a fresh publish.