Loom Docs
loomgui.com ↗

Symptoms → causes

“Loom version mismatch” on startup

Loom is loading a native plugin and a Unity package from different releases. Loom ships as a single package, so this almost always means Unity is still loading an old binary from Library/PackageCache/ after a package update.

Fix: Delete <Project>/Library/PackageCache/com.loomgui@*/Plugins/ and restart Unity. The package reinstalls on the next launch.

The built game shows no UI (but the Editor works)

The UI runs from a live dev server in the Editor, but a player build loads a pre-built bundle from StreamingAssets/Loom/. If that bundle wasn’t produced, the game ships with no UI even though everything works in the Editor.

The UI bundle is built automatically during the player build. The usual reasons it doesn’t end up in the game:

  1. Node.js isn’t installed for the user running the Editor. The build step runs npm; without Node it fails. Confirm with Loom → Doctor → “Node.js found”. Install Node 20+ and relaunch Unity.
  2. UI dependencies were never installed. Run Loom → Sync UI Dependencies before building. (A current build aborts with a clear error in this case rather than shipping an empty UI.)
  3. A custom vite.config outDir. It must be dist; the build copies UI/dist into StreamingAssets. See Player builds.

Check the Unity Console during the build for [Loom] lines: Running npm install / Copying UI/dist -> StreamingAssets/Loom indicate the UI build ran; an error there tells you which step failed.

The built game’s UI freezes on the first frame (Editor works)

The UI renders its first frame (the initial state) then never updates: progress bars stay at 0, the screen never changes, buttons don’t react, even though the game is clearly running. In the Editor everything works.

Cause: your UI bundle contains two copies of solid-js. Solid’s reactivity is per-instance, so the bridge updates state in one copy while your components are wired to the other, so nothing re-renders. The Editor’s dev server automatically collapses solid to one copy; a production build does not, so this only shows up in player builds.

Fix: in your UI’s vite.config.ts, dedupe solid:

export default defineConfig({
  plugins: [solid(), loom()],
  resolve: {
    dedupe: ['solid-js', 'solid-js/web', 'solid-js/store'],
  },
  // ...
})

Rebuild the player. To confirm the fix, your UI/dist bundle should contain a single solid copy. Projects scaffolded with Loom → Setup UI Project include this dedupe by default.

The Splash screen never advances

The bridge isn’t getting state updates. Common causes:

  1. No Loom UI component in the scene. Did you add a Loom UI component to a startup-scene GameObject (or run Loom → Setup UI in Current Scene)? Confirm via Hierarchy: there should be a LoomUI component present.
  2. Bridge class doesn’t inherit LoomBridgeBase. The [Bridge] class must inherit LoomBridgeBase; the source generator errors if it doesn’t, and the bridge won’t register.
  3. The dev server is serving a stale or wrong UI. Run Loom -> Restart Dev Server, then Play again. Loom reclaims its own orphaned dev server from a previous session automatically; restarting forces a clean one.

“The type or namespace name ‘Bridge’ could not be found”

The source generator hasn’t run. From the Unity menu, Loom -> Regenerate Types. If that doesn’t help, check that your C# class is partial and the [Bridge] attribute is exactly [Bridge] (not [Loom.Bridge] etc.).

npm install hangs forever

Usually a registry resolution issue. The bundled tarballs are at file:./.loom/... paths, which don’t need network. If you have other deps in UI/package.json pointing at the public registry, those do. Check that the registry URL in your .npmrc is reachable.

After Editor restart, the first Play shows a blank UI

A known startup race on the very first Play after a fresh Editor launch. Workaround: Stop, Play again. Will be fixed in a future plugin release.

“Mobile Dependency Resolver required” warning on opening the project

This is a Unity Editor warning unrelated to Loom; it surfaces because some package in your project (probably an analytics or ads SDK, not Loom) has declared a dependency on the Mobile Dependency Resolver. You can dismiss the warning; Loom is unaffected.