Common problems / Loom Docs

Run Tools > Loom > Doctor to check setup, then find your symptom below.

The Editor works, but the player build has no UI

The Editor uses the Vite dev server. Player builds load static files from StreamingAssets/Loom.

Check:

The player build ran the UI build hook.
Assets/StreamingAssets/Loom/index.html exists after the build.
npm run build succeeds in the UI directory.
CI has Node.js 22 or 24 LTS with npm 10 or 11 available to Unity.

The UI is blank on first Play

Check the Unity Console for dev server or bridge errors. Then run:

Tools > Loom > Restart Dev Server

If you just upgraded Loom, restart Unity so the Editor loads the new platform plugin.

UI changes do not appear

Vite hot reloads .tsx and .css edits. If it does not:

Reload Play mode.
Run Tools > Loom > Restart Dev Server.
Check DevTools Console for frontend errors.

For bridge changes, stop Play mode and wait for Unity to finish compiling. Loom regenerates the UI contract automatically. Then restart the dev server.

A Unity image shows a placeholder in the external browser

This is expected for Texture2D, Sprite, and RenderTexture bridge state. Unity owns those images, so they render in the embedded game view but not in the separate Editor browser. Use createMockImageSource(url) in mock mode when you need a real image during browser-only UI development.

If the embedded view also has no image, check that the UI uses LoomImage, the source is still referenced by bridge state, the project uses URP, and the target uses Metal, Direct3D 11, or Direct3D 12.

Vite says port 5173 is already in use

Loom’s Vite server uses a separate available local port. A terminal npm run dev can run alongside it. If that terminal server cannot use port 5173, Vite can select another port.

If an older UI project still exits on the conflict, change its Vite setting to:

server: {
  port: 5173,
  strictPort: false,
}

Restart the terminal server. Leave the process using port 5173 running unless you know it belongs to this project.

For live Unity data, open the browser URL shown by Doctor during Play. The terminal server uses mock data by default.

A new bridge field is missing in TypeScript

Stop Play mode and check the Unity Console for C# compilation errors. Loom regenerates the UI contract automatically after recompilation. If the generated files remain stale after a successful compile, regenerate them manually:

Tools > Loom > Regenerate Types

Make sure the bridge class is partial, inherits LoomBridgeBase, and the member is public.

The UI cannot call an action

Check:

The method is public and tagged [BridgeAction].
DTO parameter types follow DTO rules.
Unity finished compiling the changed method outside Play mode, allowing Loom to regenerate the UI contract.

If the promise rejects, inspect both DevTools Console and the Unity Console.

Input does not reach the UI

Check that the scene was set up with:

Tools > Loom > Setup UI in Current Scene

Check that the active LoomView has a LoomInputCapture component. Also check that only one Loom view is active and that the active URP renderer lists LoomRendererFeature in its Renderer Features.

`npm install` fails or hangs

Run npm in the UI directory from a terminal to see the raw error:

cd UI
npm install

Common causes are missing Node/npm, a corrupt node_modules folder, or a lockfile that no longer matches package.json.