Eve library

Bridge Migration Guide (180.C.38.03)

Guide

Revision 1

On this page

Status: 180.C.38.03 — migrating consumers from the OLD apps/bellona/bridge-blender / bridge-unreal services to the NEW Remote Host command envelopes.

This guide executes the migration-examples section of the bridge coexistence and deprecation plan (180.C.16.15). See also the parallel-operation guide (180.C.38.02) and the deprecation timeline (180.C.38.04).

Two migration paths#

You have two ways off the old bridges, in increasing order of effort and value:

  1. Zero-code-change shim (interim). Keep your existing legacy { bridge, type, payload } request shape and send it to the gateway's compatibility endpoint POST /v1/legacy-bridge/commands. The gateway translates it into a RemoteCommandEnvelope via the 38.01 shim (libs/bellona/remote-protocol/src/bridge-compat.ts, translateLegacyBridgeRequest) and dispatches it through the real pipeline. This buys time but every call is counted as legacy usage (remote_gateway.legacy_bridge.usage.count) and is refused once the acceptLegacyBridgeProtocol flag flips OFF at hard cutover (see the timeline).
  2. Native Remote Host SDK (target). Replace the bridge call with the @bellona/client Remote SDK (createBellonaRemoteClient, libs/bellona/client/src/remote/client.ts). This is the only supported long-term path.

The before/after examples below show BOTH the interim shim payload and the target SDK call for each command.

Command mapping (legacy → Remote Host)#

The shim covers every legacy command that has a Remote Host equivalent today. Commands without parity (e.g. blender:set-frame, unreal:load-level, unreal:execute-console-command) stay on the loopback bridge until their replacement stage lands; the shim FAILS LOUD on them (UnsupportedLegacyBridgeCommandError) rather than silently dropping them.

Legacy command Remote Host command Risk
blender:get-scene-info blender.scene.info read-only
blender:create-object blender.object.create_primitive safe-mutation
blender:import-asset blender.asset.import safe-mutation
blender:export-asset blender.asset.export safe-mutation
blender:render blender.render.capture safe-mutation
unreal:get-world-info unreal.world.query read-only
unreal:spawn-actor unreal.actor.spawn safe-mutation
unreal:destroy-actor unreal.actor.destroy destructive (needs approval)
unreal:set-actor-property unreal.actor.set_property safe-mutation
unreal:call-blueprint-function unreal.blueprint.call_function safe-mutation
unreal:set-material-parameter unreal.material.set_parameter safe-mutation

The authoritative source for this table is LEGACY_BRIDGE_COMMAND_MAP in libs/bellona/remote-protocol/src/bridge-compat.ts (and SUPPORTED_LEGACY_BRIDGE_COMMAND_TYPES).

Example 1 — Blender: create a cube#

BEFORE (legacy @bellona/bridge-blender WebSocket command)#

ts
// Old: a flat bridge-core command on ws://127.0.0.1:9001/blender
bridge.request('blender:create-object', {
  type: 'mesh',
  name: 'Hero',
  location: [1, 2, 3],
  rotation: [0, 0, 0],
  scale: [2, 2, 2],
});

AFTER — interim shim (no payload rewrite)#

ts
// POST http://127.0.0.1:4070/v1/legacy-bridge/commands
await fetch('http://127.0.0.1:4070/v1/legacy-bridge/commands', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    bridge: 'blender',
    type: 'blender:create-object',
    payload: { type: 'mesh', name: 'Hero', location: [1, 2, 3], scale: [2, 2, 2] },
    context: {
      sessionId: 'session:studio-1',
      deviceId: 'device:workstation-7',
      issuedByParticipantId: 'participant:director-jo',
      idempotencyKey: 'create-hero-0001',
      issuedAt: new Date().toISOString(),
      consumerId: 'studio-bellona-bridge-blender-route-map',
    },
  }),
});
// The gateway translates this to a `blender.object.create_primitive` envelope.

AFTER — target Remote Host SDK#

ts
import { createBellonaRemoteClient } from '@bellona/client';

const client = createBellonaRemoteClient({ baseUrl: 'http://127.0.0.1:4070' });

await client.blender.run({
  id: 'command:create-hero-0001',
  sessionId: 'session:studio-1',
  issuedByParticipantId: 'participant:director-jo',
  idempotencyKey: 'create-hero-0001',
  issuedAt: new Date().toISOString(),
  target: { deviceId: 'device:workstation-7', commandName: 'blender.object.create_primitive' },
  riskClass: 'safe-mutation',
  rollbackStrategy: 'undo_stack',
  arguments: {
    name: 'Hero',
    primitiveType: 'cube', // legacy 'mesh' maps to 'cube'
    transform: {
      location: { x: 1, y: 2, z: 3 },
      rotationEuler: { x: 0, y: 0, z: 0 },
      scale: { x: 2, y: 2, z: 2 },
    },
  },
});

Example 2 — Unreal: spawn an actor#

BEFORE (legacy @bellona/bridge-unreal WebSocket command)#

ts
// Old: a flat bridge-core command on ws://127.0.0.1:9003/unreal
bridge.request('unreal:spawn-actor', {
  className: 'StaticMeshActor',
  location: { x: 10, y: 20, z: 30 },
  rotation: { pitch: 0, yaw: 90, roll: 0 },
});

AFTER — interim shim#

ts
await fetch('http://127.0.0.1:4070/v1/legacy-bridge/commands', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    bridge: 'unreal',
    type: 'unreal:spawn-actor',
    payload: {
      className: 'StaticMeshActor',
      location: { x: 10, y: 20, z: 30 },
      rotation: { pitch: 0, yaw: 90, roll: 0 },
    },
    context: {
      sessionId: 'session:studio-1',
      deviceId: 'device:workstation-7',
      issuedByParticipantId: 'participant:director-jo',
      idempotencyKey: 'spawn-prop-0001',
      issuedAt: new Date().toISOString(),
      consumerId: 'studio-bellona-bridge-unreal-route-map',
    },
  }),
});

AFTER — target Remote Host SDK#

ts
await client.unreal.run({
  id: 'command:spawn-prop-0001',
  sessionId: 'session:studio-1',
  issuedByParticipantId: 'participant:director-jo',
  idempotencyKey: 'spawn-prop-0001',
  issuedAt: new Date().toISOString(),
  target: { deviceId: 'device:workstation-7', commandName: 'unreal.actor.spawn' },
  riskClass: 'safe-mutation',
  rollbackStrategy: 'undo_stack',
  arguments: {
    actorClass: { className: 'StaticMeshActor' },
    transform: {
      location: { x: 10, y: 20, z: 30 },
      rotation: { pitch: 0, yaw: 90, roll: 0 },
      scale: { x: 1, y: 1, z: 1 },
    },
  },
});

Example 3 — Unreal: destroy an actor (a destructive command)#

A destructive command requires approvalRequired: true plus a dry-run plan, per the protocol's RemoteCommandEnvelopeSchema invariants. The interim shim synthesizes these for you (it derives a stable dryRunPlanId from the idempotency key); the native SDK call must supply them.

BEFORE#

ts
bridge.request('unreal:destroy-actor', { actorId: 'actor-123' });

AFTER — interim shim (approval + dry-run plan synthesized by the shim)#

ts
await fetch('http://127.0.0.1:4070/v1/legacy-bridge/commands', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    bridge: 'unreal',
    type: 'unreal:destroy-actor',
    payload: { actorId: 'actor-123' },
    context: {
      sessionId: 'session:studio-1',
      deviceId: 'device:workstation-7',
      issuedByParticipantId: 'participant:director-jo',
      idempotencyKey: 'destroy-actor-0001',
      issuedAt: new Date().toISOString(),
    },
  }),
});
// Shim sets approvalRequired=true, metadata.dryRunSupported=true,
// metadata.dryRunPlanId='dry-run-plan:destroy-actor-0001'.

AFTER — target Remote Host SDK#

ts
await client.unreal.run({
  id: 'command:destroy-actor-0001',
  sessionId: 'session:studio-1',
  issuedByParticipantId: 'participant:director-jo',
  idempotencyKey: 'destroy-actor-0001',
  issuedAt: new Date().toISOString(),
  target: { deviceId: 'device:workstation-7', commandName: 'unreal.actor.destroy' },
  riskClass: 'destructive',
  approvalRequired: true,
  rollbackStrategy: 'undo_stack',
  metadata: { dryRunSupported: true, dryRunPlanId: 'dry-run-plan:destroy-actor-0001' },
  arguments: { actorId: 'actor-123' },
});

Response handling#

The shim also restores the LEGACY response shape so your existing response code keeps working during the interim: translateRemoteResponseToLegacy(legacyType, result) (libs/bellona/remote-protocol/src/bridge-compat.ts) maps a Remote Host result back to the old { objectName, objectType, success } / { actorId, actorName, className, success } shapes. When you adopt the native SDK, read the RemoteCommandDispatchRecord / RemoteCommandView returned by client.<engine>.run(...) instead.

Verification#

bash
cd libs/bellona/remote-protocol && npx vitest run src/bridge-compat.test.ts
cd apps/bellona/remote-gateway && npx vitest run src/legacy-bridge.test.ts src/app.test.ts