bootBridge

The starter calls bootBridge in UI/src/bridge.ts when the app starts. It connects the UI to Unity or creates a mock bridge for a standalone browser preview. Edit the options in this file to set the UI’s initial values and define how its actions behave in the preview.

Signature: bootBridge(options: LoomBootOptions): Bridge

Example

For the Message property and Ping() action from Install and run Loom, you can configure the existing call like this:

import { bootBridge } from '@loomgui/bridge';

export const bridge = bootBridge({
  initial: { message: 'Ready to preview.' },
  mockActions: ({ state }) => ({
    ping: () => { state.message = 'Pong from the browser mock.'; },
  }),
});

Pass the exported bridge to BridgeProvider so components can access it with useBridge(). The starter already does this in UI/src/index.tsx.

In a standalone browser, clicking Ping the engine runs the mock handler and displays Pong from the browser mock. In Unity, it calls UIBridge.Ping() and displays the response from C#.

Options

Pass an options object with initial and any mock behavior you want to use in browser previews. The option types are exported by @loomgui/bridge and use the state fields and action signatures generated from your C# bridge.

initial

Type: BridgeInitialState.

Give the UI a starting value for every state field in the generated TypeScript. Use the TypeScript names: for example, the C# Message property becomes message. Loom supplies the built-in loom state automatically.

In a browser preview, these values are the starting point for your mocks. When connected to Unity, they let the UI render while it waits for the first game update. The game’s starting values come from C#; initial supplies the UI’s values until that update arrives.

mockActions

Type: MockActionHandlers or MockActionFactory.

Provide a handler for each action you want to use in a browser preview. Match its name and arguments to the generated action. A handler can return a value or a promise; the action called by your component always returns a promise. If the handler throws or rejects, that action call rejects too.

You can pass an object of handlers, or a function that creates them. Use the function form when a handler needs to update state or send an event. In the example above, the function receives state and returns a ping handler that changes state.message.

This function runs once when the mock bridge is created and receives:

If you call an action without a mock handler, Loom logs a warning once for that action and resolves the call with undefined. Provide a handler for any action whose result your UI uses.

mockScenarios

Type: an object with string keys and callbacks of type (api: MockScenarioApi) => void | Promise<void>.

Use scenarios to name states you want to return to in a preview, such as an empty list or a completed level. Each key names a scenario, and its callback receives the same state and fire members as a mock action factory. Callbacks can be asynchronous and run when your preview tooling selects them.

For a preview tool with scenario selection, use createMockBridge directly. Pass the callbacks as its scenarios option. It returns a MockBridge with listScenarios() and runScenario(name). bootBridge returns the shared Bridge type, which exposes the state and actions available to both the game and the preview; scenario controls belong to MockBridge.

Returns

bootBridge returns a Bridge immediately, with your initial values ready to read. It contains the generated state properties and action methods, along with Loom’s built-in loom state. A live connection supplies updates as they arrive from Unity.

Read state in JSX or other Solid reactive expressions so the screen follows those updates. To change something in the game, call a bridge action.

bridge.loom.bridgeReady reports live bridge startup and remains false in mock mode. A screen that waits for this flag before rendering stays hidden in a browser preview. Let the preview render with its initial values, and use the flag for behavior that requires a live Unity connection.

Environment selection

bootBridge chooses the connection when it runs:

mockActions and mockScenarios are used only in mock mode. A failed live connection does not fall back to mocks. For help with connection failures, see Common problems.

When the contract changes

Make sure Play mode is stopped before editing the C# bridge. Once Unity recompiles it, Loom automatically updates the generated TypeScript declarations. Update initial and any affected mock handlers to match, then run npm run typecheck from UI/.

If the dev server is already running, restart it so the UI uses the changed bridge.