Common problems / Loom Docs

Start with Tools > Loom > Doctor. If Doctor is green but the issue remains, use the symptoms 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

For .tsx and .css edits, Vite should hot reload. If it does not:

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

For bridge changes, run Tools > Loom > Regenerate Types, 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

Current Loom projects allow Vite to move to another port, and Loom-managed servers reserve a separate high loopback port. A manually started npm run dev is independent: Loom does not adopt, restart, or terminate it. Both servers can watch the same UI source without competing for one fixed port.

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

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

Then restart the terminal server. Do not kill an unknown listener merely because it owns port 5173; it may belong to an agent or another project.

While Play is running, use the browser URL shown by Loom Doctor or the status panel when a browser needs live Unity state. A standalone server uses the mock bridge by default.

A new bridge field is missing in TypeScript

Run:

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.
The UI types were regenerated after changing the method.

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

The active LoomView should have 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.