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:
- Zero-code-change shim (interim). Keep your existing legacy
{ bridge, type, payload }request shape and send it to the gateway's compatibility endpointPOST /v1/legacy-bridge/commands. The gateway translates it into aRemoteCommandEnvelopevia 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 theacceptLegacyBridgeProtocolflag flips OFF at hard cutover (see the timeline). - Native Remote Host SDK (target). Replace the bridge call with the
@bellona/clientRemote 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)#
// 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)#
// 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#
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)#
// 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#
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#
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#
bridge.request('unreal:destroy-actor', { actorId: 'actor-123' });
AFTER — interim shim (approval + dry-run plan synthesized by the shim)#
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#
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#
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