2026-06-12 11:57:33 +01:00
# Brokkr Provider Contract
Provider id: `brokkr.creative_tool_broker`
CultMesh base URI: `cultmesh://brokkr`
2026-10-22 20:14:59 +02:00
Eve is deprecated, and Thing 2 is its successor (`thing2:ruling:eve-dashboards-quarantined` , 2026-10-22). Brokkr advertises no operator-dashboard surface; it publishes typed CultMesh state meanwhile.
2026-06-12 11:57:33 +01:00
## Tool Kinds
- `unity-editor`
- `blender-editor`
## Capability Families
2026-06-12 16:30:41 +01:00
- `cultcache.mirror.publish`
- `cultcache.intent.watch`
2026-06-12 11:57:33 +01:00
- `host.status.read`
- `scene.tree.read`
2026-06-12 16:30:41 +01:00
- `component.state.read`
2026-06-12 11:57:33 +01:00
- `selection.read`
- `asset.catalog.read`
2026-06-15 01:24:18 +01:00
- `asset.scriptable_object.create`
2026-06-12 16:30:41 +01:00
- `asset.prefab.instantiate`
- `asset.prefab.variant.create`
- `gameobject.create`
- `component.attach`
- `component.property.write`
2026-09-29 14:49:09 +02:00
- `editor.assets.refresh`
- `editor.lifecycle.write`
- `editor.view.capture`
2026-06-12 16:30:41 +01:00
- `command.receipt.publish`
## Mirror Documents
- `brokkr.unity.host_snapshot.v0` at `unity/host/current`
- `brokkr.unity.command_intent.v0` at `unity/commands/{commandId}`
- `brokkr.unity.command_receipt.v0` at `unity/receipts/{commandId}`
- `brokkr.unity.snapshot_receipt.v0` at `unity/receipts/snapshots/{observedAt}`
- `brokkr.unity.quest_route.v0` at `unity/quest-routes/{routeId}`
- `brokkr.unity.warped_video_frame.v0` at `unity/quest/video/{frameId}`
2026-06-13 19:55:59 +01:00
- `brokkr.blender.host_snapshot.v0` at `blender/host/current`
- `brokkr.blender.command_intent.v0` at `blender/commands/{commandId}`
- `brokkr.blender.command_receipt.v0` at `blender/receipts/{commandId}`
2026-06-14 23:52:27 +01:00
- `brokkr.sync.session.v0` at `sync/sessions/{sessionId}`
- `brokkr.sync.object_binding.v0` at `sync/bindings/objects/{bindingId}`
- `brokkr.sync.var.v0` at `sync/vars/{syncVarId}`
- `brokkr.sync.timeline_binding.v0` at `sync/bindings/timelines/{bindingId}`
- `brokkr.sync.receipt.v0` at `sync/receipts/{receiptId}`
## Sync Organ
Brokkr owns sync correspondence and policy documents. Editor hosts still own
scene mutation. A sync record can request or describe a lane, but it is not real
editor state until Unity or Blender publishes accepted command receipts and a
fresh host snapshot.
Primary sync documents:
- `brokkr.sync.session.v0` : shared sync session and mode.
- `brokkr.sync.object_binding.v0` : Unity GameObject to Blender object/collection
correspondence.
2026-06-15 03:06:55 +01:00
- `brokkr.sync.var.v0` : per-lane sync options such as transform, parent,
material, component property, custom property, timeline frame, camera lens,
or Cinemachine virtual camera.
2026-06-15 02:37:03 +01:00
Editor surfaces may also publish ad hoc sync vars with an explicit kind,
paths, authority, enabled flag, and interpolation. The daemon executes
implemented kinds and preserves unsupported kinds as typed sync policy for
external consumers.
2026-06-14 23:52:27 +01:00
- `brokkr.sync.timeline_binding.v0` : Blender scene/action timeline to Unity
Timeline/Cinemachine correspondence.
- `brokkr.sync.receipt.v0` : daemon sync pass receipts.
2026-06-12 13:26:14 +01:00
2026-06-15 00:46:05 +01:00
Operational commands:
A3: brokkr-command, the caller CLI, with every intent field and a real CultLib root
Re-landed from the donor as a fresh file (read with git show, not merged).
Changes from the donor: the CultLibRoot default is ..\..\CultLib instead of a
directory that does not exist; every field of brokkr.unity.command_intent.v0
has a --kebab option (the donor mapped six of seventeen), and unknown options
are refused before anything is written; keys come from BrokkrCommandLedger;
exit is 0 accepted, 1 other receipt, 2 usage error or timeout; readHost opens
the store read-only and prints the agent-commands flag; a timeout says when
the editor reports the sink off. The intent gains the capture fields at keys
13-16, which the CLI needs and A4's executor will read.
Tests run the built CLI as a process against the editor probe: field mapping,
fresh id per invocation, exit code from the receipt, timeout leaves only the
intent, unknown option writes nothing, and every action name reaches the
editor once with one receipt.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-29 14:26:23 +02:00
- `dotnet run --project brokkr-command/Brokkr.Command.csproj -- --unity-cache .brokkr/unity-editor.ccmp --action readHost`
- `dotnet run --project brokkr-command/Brokkr.Command.csproj -- --unity-cache .brokkr/unity-editor.ccmp --action createGameObject --name Marker --local-position 0,1,0`
2026-06-15 00:46:05 +01:00
- `brokkr-daemon sync-once --unity-cache .brokkr/unity-editor.ccmp --blender-cache .brokkr/blender-editor.ccmp`
- `brokkr-daemon sync-loop --unity-cache .brokkr/unity-editor.ccmp --blender-cache .brokkr/blender-editor.ccmp --interval-ms 500`
A3: brokkr-command, the caller CLI, with every intent field and a real CultLib root
Re-landed from the donor as a fresh file (read with git show, not merged).
Changes from the donor: the CultLibRoot default is ..\..\CultLib instead of a
directory that does not exist; every field of brokkr.unity.command_intent.v0
has a --kebab option (the donor mapped six of seventeen), and unknown options
are refused before anything is written; keys come from BrokkrCommandLedger;
exit is 0 accepted, 1 other receipt, 2 usage error or timeout; readHost opens
the store read-only and prints the agent-commands flag; a timeout says when
the editor reports the sink off. The intent gains the capture fields at keys
13-16, which the CLI needs and A4's executor will read.
Tests run the built CLI as a process against the editor probe: field mapping,
fresh id per invocation, exit code from the receipt, timeout leaves only the
intent, unknown option writes nothing, and every action name reaches the
editor once with one receipt.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-29 14:26:23 +02:00
`brokkr-command` is a caller. Each invocation writes one intent through the
directory store (every intent field has a `--kebab-case` option; `--view` and
`--output` fill the capture fields), waits for the receipt, and exits 0 for
`accepted` , 1 for any other status, and 2 for a usage error or a timeout. It
never writes receipts, host snapshots or the agent-commands flag.
2026-06-15 00:46:05 +01:00
`sync-loop` owns scheduling only. It repeatedly invokes the same sync decision
primitive as `sync-once` , writes command intents and sync receipts through the
mirrors, and prints per-pass telemetry to stdout.
2026-06-15 02:23:55 +01:00
Each daemon pass writes the same `brokkr.sync.receipt.v0` document into both
editor mirror stores at `sync/receipts/{receiptId}` . Unity and Blender editor
panels may display the latest receipt, but the daemon remains the owner of pass
status.
2026-06-15 00:46:05 +01:00
Implemented sync lanes:
2026-06-15 03:15:20 +01:00
- Missing counterpart materialization for enabled object bindings. When an
authority side has an object and the target side does not, Brokkr emits
`createObject` or `createGameObject` and waits for the next host snapshot
before applying per-lane mutations.
2026-06-15 00:46:05 +01:00
- Unity GameObject transform to Blender object transform.
- Unity GameObject active state to Blender object visibility.
2026-06-15 03:06:55 +01:00
- Unity GameObject parent id to Blender object parent through `setObjectParent` .
2026-06-15 02:50:50 +01:00
- Unity Renderer material name to Blender object material assignment through
`assignMaterial` .
2026-06-15 01:49:02 +01:00
- Blender object visibility to Unity GameObject active state through
`setGameObjectActive` .
2026-06-15 03:06:55 +01:00
- Blender object parent name to Unity GameObject parent through
`setGameObjectParent` . The Blender parent must have an object binding so
Brokkr can resolve the Unity parent object id.
2026-06-15 01:40:51 +01:00
- Unity serialized component property to Blender object custom property through
2026-06-15 02:43:36 +01:00
`setObjectCustomProperty` . The syncvar kind may be `component-property` or
`custom-property` ; authority and paths determine direction. It uses
`unityPropertyPath =
2026-06-15 01:40:51 +01:00
Component.Type::propertyPath` and ` blenderPropertyPath = customProperties.name`.
2026-06-15 00:46:05 +01:00
- Blender object transform to Unity GameObject transform.
2026-06-15 01:13:51 +01:00
- Blender object material name to Unity Renderer material assignment through
`assignMaterial` .
2026-06-15 00:46:05 +01:00
- Blender scene frame to Unity timeline time through `setComponentProperty` .
- Blender scene camera transform/FOV to a Unity Cinemachine virtual camera
GameObject/component. The FOV write uses `componentType =
Cinemachine.CinemachineVirtualCamera` and property path ` m_Lens.FieldOfView`.
2026-06-15 01:03:02 +01:00
- Blender object custom property to Unity serialized property through
2026-06-15 02:43:36 +01:00
`setComponentProperty` . The syncvar kind may be `custom-property` or
`component-property` ; authority and paths determine direction. It uses
`blenderPropertyPath =
2026-06-15 01:03:02 +01:00
customProperties.name` and ` unityPropertyPath = Component.Type::propertyPath`
when a Unity component should receive the value.
2026-06-15 00:46:05 +01:00
2026-06-12 13:26:14 +01:00
## Unity Command Actions
2026-06-12 16:30:41 +01:00
All Unity writes use `brokkr.unity.command_intent.v0` and receive
`brokkr.unity.command_receipt.v0` .
2026-06-12 13:26:14 +01:00
- `createGameObject`
- `attachComponent`
2026-06-15 00:20:44 +01:00
- `setGameObjectTransform`
2026-06-15 01:49:02 +01:00
- `setGameObjectActive`
2026-06-15 03:06:55 +01:00
- `setGameObjectParent`
2026-06-12 13:26:14 +01:00
- `setComponentProperty`
- `instantiatePrefab`
- `createPrefabVariant`
2026-06-15 01:13:51 +01:00
- `assignMaterial`
2026-06-15 01:24:18 +01:00
- `createScriptableObject`
A4: admission policy and the editor lifecycle actions
BrokkrCommandPolicy (Runtime, pure, tested outside Unity) is consulted by
BrokkrEditorService before every BrokkrUnityCommandExecutor.Execute; it is the
only call path into the executor. The per-project allowed-action list defaults
to scene mutation plus lifecycle; createScriptableObject, createPrefabVariant
and saveScene are shipped denied (parked Q4 = A), and an action the list does
not name is denied. A denial gets a receipt with status denied and a reason.
The window's buttons write intents like any other caller, so operator and
agent share the gate.
Re-landed from the donor as fresh code: refreshAssets, setEditorPlayState,
setEditorPaused, captureEditorView, and the play-state fields on the host
snapshot (keys 14-17). The donor's captureEditorView wrote to any rooted
outputPath; it now resolves the path through one function that accepts only a
plain relative .png path under <project>/.brokkr/captures and refuses drive
letters, rooted or UNC paths, stream suffixes and any .. segment on every host
OS, and dimensions are bounded to 8192. requestedBy joins the intent (key 17)
and is echoed on the receipt (key 6). saveScene is new.
The window gains an Allowed Actions field bound to a per-project preference.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-29 14:44:31 +02:00
- `refreshAssets`
- `setEditorPlayState`
- `setEditorPaused`
- `captureEditorView`
- `saveScene`
2026-06-12 13:26:14 +01:00
2026-06-12 16:30:41 +01:00
Unity owns the mutation. Brokkr advertises the command surface; Verse clients
write typed command intents; Unity executes recognized intents and publishes
2026-06-15 00:46:05 +01:00
receipts. `setComponentProperty` writes the target object by default; when
`componentType` is present, Unity resolves that component on the target
GameObject and writes the serialized property there.
2026-06-15 01:49:02 +01:00
`setGameObjectActive` uses `targetObjectId` and boolean `value` .
2026-06-15 03:06:55 +01:00
`setGameObjectParent` uses `targetObjectId` and `parentObjectId` ; an empty
`parentObjectId` reparents the GameObject to the scene root.
2026-06-15 01:30:32 +01:00
`instantiatePrefab` uses `assetPath` as the source prefab, `name` as the
optional instance name, and `parentObjectId` as the optional parent.
`createPrefabVariant` uses `assetPath` as the source prefab and `value` as the
destination prefab path.
2026-06-15 01:24:18 +01:00
`createScriptableObject` uses `componentType` as the ScriptableObject type and
`assetPath` as the destination asset path.
A4: admission policy and the editor lifecycle actions
BrokkrCommandPolicy (Runtime, pure, tested outside Unity) is consulted by
BrokkrEditorService before every BrokkrUnityCommandExecutor.Execute; it is the
only call path into the executor. The per-project allowed-action list defaults
to scene mutation plus lifecycle; createScriptableObject, createPrefabVariant
and saveScene are shipped denied (parked Q4 = A), and an action the list does
not name is denied. A denial gets a receipt with status denied and a reason.
The window's buttons write intents like any other caller, so operator and
agent share the gate.
Re-landed from the donor as fresh code: refreshAssets, setEditorPlayState,
setEditorPaused, captureEditorView, and the play-state fields on the host
snapshot (keys 14-17). The donor's captureEditorView wrote to any rooted
outputPath; it now resolves the path through one function that accepts only a
plain relative .png path under <project>/.brokkr/captures and refuses drive
letters, rooted or UNC paths, stream suffixes and any .. segment on every host
OS, and dimensions are bounded to 8192. requestedBy joins the intent (key 17)
and is echoed on the receipt (key 6). saveScene is new.
The window gains an Allowed Actions field bound to a per-project preference.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-29 14:44:31 +02:00
`refreshAssets` forces an AssetDatabase refresh. `setEditorPlayState` and
`setEditorPaused` take boolean `value` ; the editor service restarts from
`[InitializeOnLoad]` after the resulting domain reload and keeps draining.
`captureEditorView` renders `viewKind` (`scene` or `game` ) to a PNG at `width`
by `height` (0 means the camera size, at most 8192). `outputPath` is a plain
relative path ending in `.png` , resolved under `<project>/.brokkr/captures/` ;
anything else is denied. `saveScene` saves the open scenes.
### Admission
Before any intent runs, `BrokkrCommandPolicy` checks it against the project's
allowed-action list (window field "Allowed Actions", per project). By default
scene mutation and editor lifecycle actions are allowed; the asset-writing
actions `createScriptableObject` and `createPrefabVariant` , and `saveScene` ,
are not, and an action the list does not name is denied. A denied intent gets a
receipt with `status: denied` and the reason in `message` , so a refusal is as
visible as an acceptance. `requestedBy` on the intent names the caller and is
echoed on the receipt; admission never reads it. The window's buttons write
intents like any other caller, so the operator and an agent pass the same gate.
2026-06-12 13:26:14 +01:00
2026-09-29 14:21:29 +02:00
## Unity Command Transport
Commands reach the editor through the project's directory store at
`<project>/.brokkr/unity-editor.ccmp` (`.records/` beside it). There is no
network listener: admission starts at filesystem permissions, and the editor sees
a written intent on its next pull, about once a second.
The editor executes intents only while the operator has enabled agent commands
for that project (window toggle "Agent Commands"). The flag is off by default
and installing the package never turns it on. The host snapshot carries it as
`agentCommandsEnabled` , so a caller can see why nothing executes.
A command id is single-use. Every writer mints a fresh `commandId` for each
act, and a receipt at `unity/receipts/{commandId}` answers exactly that id.
Once an id has a receipt, the editor never executes it again, whatever is
later written under it: reusing an answered id is a caller defect, and its
receipt is the answer that stands. A writer that repeats an intent mints a new
id for each repetition.
2026-06-13 19:55:59 +01:00
## Blender Command Actions
All Blender writes use `brokkr.blender.command_intent.v0` and receive
`brokkr.blender.command_receipt.v0` .
- `createObject`
- `deleteObject`
- `setObjectTransform`
2026-06-15 00:46:05 +01:00
- `setObjectVisibility`
2026-06-15 03:06:55 +01:00
- `setObjectParent`
2026-06-15 01:40:51 +01:00
- `setObjectCustomProperty`
2026-06-13 19:55:59 +01:00
- `selectObject`
- `assignMaterial`
2026-11-07 12:43:45 +00:00
- `importGltf`
- `setCamera`
- `setLight`
- `setWorld`
- `renderStill`
2026-11-10 17:54:18 +00:00
- `createNodeGroup` , `addNode` , `removeNode` , `linkSockets` , `unlinkSockets` , `addModifier` ,
`removeModifier` , `setModifierInput` (Geometry Nodes graphs; fields in
`surfaces/blender/docs/node-actions.md` )
2026-06-13 19:55:59 +01:00
Blender owns the mutation. Brokkr advertises the command surface; Verse clients
write typed command intents; Blender executes recognized intents and publishes
receipts.
2026-06-15 03:06:55 +01:00
`setObjectParent` uses `targetObjectName` and optional `parentObjectName` ; an
empty parent reparents the object to the Blender scene root.
2026-06-13 19:55:59 +01:00
2026-10-22 20:14:59 +02:00
## Operator Views
2026-06-12 13:26:14 +01:00
2026-10-22 20:14:59 +02:00
Eve is deprecated, and Thing 2 is its successor (`thing2:ruling:eve-dashboards-quarantined` , 2026-10-22). Brokkr advertises no operator-dashboard surface; it publishes typed CultMesh state meanwhile. The scene graph, component state, asset library, command affordances and command receipts are mirrored documents; a future Thing 2 view over them does not own editor truth.