@bellona/blender-agent is the runtime foundation for the Phase 71
Blender-native agent track. It now includes the first production control-surface
piece: a Blender RPC bridge that can drive bpy execution over either an
interactive WebSocket addon session or a headless stdin/stdout process session.
What This Task Establishes#
- Nx project wiring with
build,test,lint, andtypechecktargets - package metadata for the dedicated
@bellona/blender-agentlibrary - a versioned runtime capability surface for transport, action domains, and execution modes
- a Blender RPC bridge with WebSocket transport for interactive addon sessions
- a Blender RPC bridge with stdin/stdout transport for headless Blender runs
- generated Python bootstrap script support for line-based stdin RPC sessions
- a typed action schema covering object, mesh, armature, modifier, material, node, camera, light, and render operations
- deterministic RPC command descriptors and validation for planner-emitted actions
- a deterministic natural-language planner that converts grounded Blender edit instructions into typed action sequences, confidence scores, tool calls, and clarification fallbacks
- a deterministic operator-recovery layer that turns low-confidence plans, blocked transactions, and Blender operator failures into concrete recovery hints and retry guidance
- smoke-test coverage for Blender addon panels, addon command registration, stdin/headless execution, and representative agent execution scenarios
- a semantic selection resolver that grounds queries like
select all door handles,isolate left forearm, andfind emissive materialsagainst scene objects, materials, and collections - a deterministic current-scene context capture workflow that snapshots active scene, active object, selection, collections, materials, modifiers, constraints, and linked-file references
- a reversible transaction layer with deterministic previews, dry-run support, Blender undo checkpoints, and rollback execution metadata
- a headless batch execution mode that schedules render-farm and automated post-processing jobs over the existing transaction and RPC surfaces
- an execution audit log that captures exact RPC or
bpycalls, operator parameters, timing, and before/after file-state diffs on the same execution path used by transactions and batch jobs - a Blender-side permission policy layer that blocks destructive object, modifier, material, and collection-unlink operations until explicit approval tokens are supplied
- a Geometry Nodes authoring compiler that turns structured intents like
scatter, instancing, bevel, paneling, terrain dressing, and growth into
deterministic node-graph plans plus executable
geometry_nodes.*RPC steps - a Geometry Nodes diff/merge layer that turns graph changes into reviewable hunks over metadata, interfaces, nodes, links, and warnings, then rebuilds executable plans from only the accepted edits
- a Geometry Nodes template library for reusable foliage scatter, cables, kitbash panels, debris, and modular facade procedural setups built on the same deterministic authoring compiler
- a shader and material graph authoring layer that targets Principled BSDF,
accepts MaterialX standard-surface style parameters, and compiles them into
deterministic
material.*node execution plans - a deterministic modifier and mesh cleanup macro layer covering UV cleanup, weighted normals, remesh, decimate, shrinkwrap, bevel, boolean, and modifier-stack repair with transaction-backed execution
- a deterministic rig generation and editing macro layer for armatures, constraints, drivers, IK/FK setup, custom controls, and corrective shape scaffolding
- a deterministic animation blocking and polish macro layer for blocking keyframes, F-curve cleanup, NLA setup, profile-based retarget baking, and viewport preview playblasts
- a deterministic groom, hair, fur, and curve-generation macro layer for character hair, creature fur, foliage growth curves, and stylized ribbon or tuft curves
- a deterministic physics setup macro layer for cloth garments and capes, rigid-body props and destruction previews, and basic soft-body deformation previews
- a deterministic validation layer that checks generated Geometry Nodes graphs, rig plans, and physics plans for editability, naming clarity, and production-readable review surfaces
- a deterministic scene-graph authoring layer that expands prompts or structured scene specs into Blender scene, collection, and parent-child hierarchy operations with naming conventions
- a deterministic scene-placement workflow that stages existing Blender assets with real-world scale normalization, snap-target placement, orientation rules, and collision review before transforms are applied
- a deterministic camera and lighting staging layer that compiles standard presentation and review presets into executable camera rigs, light rigs, and render-ready defaults
- a deterministic Blender Asset Browser and kitbash assembly layer that syncs Oshun library metadata into catalogs, registers asset libraries, and imports metadata-matched kitbash pieces into assembly roots
- a deterministic
.blendpackaging workflow that emits dependency manifests, reproducible rebuild recipes, missing-file checks, and optional sidecar copies for linked assets - a deterministic exporter-validation workflow that checks Blender-side export readiness for GLB, FBX, USD, VRM, and engine-target handoff presets before publish or external import
- a deterministic publish-to-library workflow that pushes Blender exports back into the Isis asset library with ingestion, provenance, thumbnails, and benchmark metadata
- a deterministic render-preview and review-sheet layer for contact sheets, clay renders, wireframe previews, UV layouts, and material-ID stills
- a module catalog mapped to the upcoming Blender-agent task sequence so later work extends one coherent runtime instead of fragmented utilities
- smoke-test coverage that validates the package scaffold and exported manifest
Runtime Shape#
The runtime manifest intentionally declares the core control-surface areas that
arrive in the remaining 71.12.1 tasks:
bridgefor WebSocket/stdin RPC executionactionsfor typed Blender operationsplanningfor natural-language-to-action orchestrationselectionfor semantic object resolutionscene-contextfor current-scene capturetransactionsfor reversible executionbatchfor headless farm-safe runsauditfor exact call loggingpolicyfor destructive-action permissions
Every module carries:
- the owning Phase 71 task id
- a readiness status
- a short implementation responsibility statement
The bridge module is now marked implemented. The remaining modules stay
planned until their respective tasks land.
The actions module is also now marked implemented. It provides a single
typed contract for the execution bridge and for the future
natural-language-to-action planner.
The planning module is now marked implemented. It deterministically maps
plain-English Blender requests onto the typed action schema and only falls back
to clarification when a safe target or parameter cannot be resolved.
The selection module is now also marked implemented. It provides one
deterministic semantic grounding layer for both direct selection queries and the
planner's object/material target resolution path.
The scene-context module is now also marked implemented. It projects the
existing @bellona/blender scene, object, collection, and material managers
into one normalized snapshot shape that the planner and later transaction/audit
layers can reuse directly.
The transactions module is now also marked implemented. It plans and
executes checkpointed Blender transactions over the typed action schema, blocks
destructive live execution until preview approval is explicit, and records
rollback-ready metadata for downstream audit and policy layers.
The batch module is now also marked implemented. It runs headless-only job
pipelines for farm-safe render and post-processing work, reusing the same RPC
bridge and transaction executor rather than branching into a separate runtime.
The audit module is now also marked implemented. It wraps the same bridge
used by transactions and batch execution so exact call payloads, operator
kwargs, timing, and file-state deltas are captured in one authoritative audit
stream instead of being reconstructed after execution.
The policy module is now also marked implemented. It classifies destructive
actions and raw unlink intents into explicit permission scopes, then enforces
approval requirements from the same transaction and batch runtime path.
The Geometry Nodes authoring surface is now also implemented as the first
71.12.2 automation layer. It compiles structured procedural intents into one
inspectable graph blueprint and one exact execution plan instead of hiding node
creation behind opaque imperative logic.
The Geometry Nodes diff/merge layer is now also implemented. It compares two generated node-graph plans at the metadata, interface, node, link, and warning levels, then lets downstream review tools accept only the hunks they want while rebuilding the executable RPC step list from that merged plan.
The Geometry Nodes template library is now also implemented. It packages the most common procedural setups as reusable presets that still expand into the same inspectable authoring plans and exact bridge commands, so later diff, merge, and validation work operates on one shared graph model.
The shader-material graph authoring layer is now also implemented. It normalizes
Principled-oriented material requests and MaterialX-compatible standard-surface
parameters into one inspectable shader graph, then compiles that graph into
exact material.create, material.add_node, material.set_node_*,
material.link_nodes, and material.assign calls.
The modifier and mesh cleanup macro layer is now also implemented. It expands high-level cleanup intents into deterministic typed Blender actions for modifier-stack work plus deterministic Python UV passes where the current action schema does not yet expose unwrap and packing operations.
The rig generation and editing macro layer is now also implemented. It expands
armature, constraint, driver, custom-control, and corrective-shape workflows
into deterministic typed actions, direct constraint.* and driver.* calls,
and targeted Python scaffolds for Blender-only rigging surfaces.
The animation blocking and polish macro layer is now also implemented. It keeps
blocking, polish, NLA sequencing, retarget baking, and playblast preview
automation on one inspectable plan shape that mixes typed render actions with
exact animation.*, nla.*, and targeted bpy execution where Blender's
animation surfaces are still operator-driven.
The groom, hair, fur, and curve-generation macro layer is now also implemented. It keeps fast hair and fur scaffolding on deterministic curve and particle surfaces, while reusing the existing Geometry Nodes growth planner for foliage and other curve-driven growth setups instead of inventing a separate procedural runtime.
The physics setup macro layer is now also implemented. It keeps cloth and
soft-body setup on the existing modifier action surface while using targeted
bpy scaffolds for rigid-body world configuration, passive collider pairing,
and collision-object enablement that the current action schema does not yet
model directly.
Physics Setup Macros#
The physics macro layer covers five deterministic workflows:
cloth-garmentfor shirts, dresses, skirts, and other garment drape setupscloth-capefor pinned cape or banner-style trailing clothrigid-body-propfor active or passive props with collider pairingdestruction-previewfor shard, floor, and anchor setup in fast breakage previewssoft-body-deformfor cushions, blobs, and other basic deformable prop previews
Cloth and soft-body workflows emit transaction-backed modifier actions so they stay inspectable in the same preview and approval flow used elsewhere in the package. Rigid-body workflows use exact Python scaffolds because the active action schema does not yet describe rigid-body world creation, cache tuning, or passive-vs-active body configuration.
Automation Validation Rules#
The validation layer provides one deterministic review pass across the generated automation surfaces in this package:
- Geometry Nodes plans are checked for readable tree names, duplicate node aliases, unresolved links, group input/output boundaries, and interface documentation
- rig macro plans are checked for readable labels, unique action and operation ids, non-empty generated work, and destructive editability risks
- physics macro plans are checked for named cloth or soft-body modifiers, required rigid-body Python scaffolds, avoidance of modifier-apply during setup, and readable operator-facing labels
Validation runs can be invoked per plan or as a batch suite so downstream review tools and smoke tests can block obviously uneditable or unreadable generated automation before it reaches artists.
Scene Graph Authoring#
The scene-graph authoring layer accepts either prompt-derived intents or a fully structured scene spec and expands them into executable Blender work:
- scene creation and activation RPC steps
- collection creation, nested collection linking, and collection visibility or render-exclusion setup
- object creation for empties, primitives, cameras, lights, and existing-object reuse
- parent-child hierarchy actions for scene roots, hero subjects, assembly groups, and review layouts
- deterministic naming conventions applied to scenes, collections, and objects
Prompt mode stays deterministic by mapping known scene intents such as product render, turntable, hero shot, animation blocking, kitbash assembly, and interior layout into standard collection and hierarchy templates. Structured mode accepts an explicit collection tree and object graph so downstream Blender automation can build repeatable layouts without reparsing natural language.
Scene Placement Workflow#
The scene-placement workflow keeps asset staging deterministic and reviewable instead of hiding it behind ad hoc transform edits:
- placement requests normalize each asset against explicit target dimensions or category-based real-world presets such as chair, table, lamp, door, and prop
- snap targets support floor, wall, ceiling, surface-top, world-origin, custom-point, and object-anchor placement modes
- orientation rules keep placement predictable for upright props, wall-mounted assets, flat-laid items, or targets that must face a review point
- collision checks review planned AABB occupancy against both existing scene inventory and earlier placements in the same batch, with block, warn, or ignore policies per asset
Successful placements compile into the same transaction-backed
object.set_transform actions used elsewhere in the package, so preview,
approval, rollback, and audit behavior stays consistent with the existing
runtime.
Camera And Lighting Staging Presets#
The staging preset layer turns the common Phase 71 scene modes into one deterministic rig compiler over the existing action schema:
turntablestages an orbit camera, three-light presentation rig, and square transparent-background render defaultsproduct-renderstages a detail-oriented camera with shallow depth of field plus key, fill, rim, and backdrop lift lightinghero-shotstages a closer dramatic lens choice with stronger rim separation and widescreen defaultsanimation-blockingstages a wider camera and readable low-cost lighting for layout and blocking reviewreview-dailiesstages both a primary review camera and a safety camera with balanced review lighting, while warning that viewport dailies should still be rendered through the preview-playblast macro
Preset planning derives shot distance, focus distance, and light placement from the supplied subject bounds so staging stays tied to real scene scale instead of fixed hand-tuned values disconnected from the asset under review.
Asset Browser And Kitbash Workflows#
The asset-browser integration layer connects Blender-side asset browsing to Oshun library metadata instead of relying on manual path setup:
- Oshun catalog metadata is projected into
blender_assets.cats.txtso Blender sees the same catalog paths already defined upstream - asset-library registration is scripted against Blender preferences so the asset browser can mount Oshun library roots deterministically
- kitbash assembly slots select assets by family, theme, catalog, module family, preferred ids, and required tags rather than brittle filename heuristics
- imported assets can be linked or appended, then parented and transformed into one assembly root through the existing transaction layer
This keeps library browsing, metadata-backed selection, import behavior, and assembly staging on one inspectable workflow surface that downstream publish and review steps can reuse directly.
Blend Packaging Workflow#
The .blend packaging layer turns a live Blender scene plus linked-file
inventory into a portable, reviewable package descriptor:
- the source
.blendis copied into a package directory withbpy.ops.wm.save_as_mainfile(..., copy=True)so the active session is not rebound to the packaged path - linked dependencies are normalized by kind, path, packed state, and usage so one dependency manifest can distinguish copied sidecars, reference-only dependencies, packed assets, and missing files
- copy mode assigns deterministic sidecar destinations under
linked-assets/<kind>/..., including duplicate-filename disambiguation for collisions that would otherwise overwrite each other - missing-file checks can block package execution entirely when a source scene is incomplete, while still emitting a rebuild recipe that describes the exact package inputs expected once the scene is repaired
- rebuild metadata records the source blend path, package layout, dependency snapshot, and exact packaging mode so downstream automation can recreate the package without reverse-engineering a prior bundle
This keeps .blend handoff packaging deterministic and inspectable rather than
relying on one-off artist scripts or opaque archive steps.
Exporter Validation Workflow#
The exporter-validation layer turns export preflight into a typed Blender-side review surface instead of a loose checklist:
- raw format targets cover
glb,fbx,usd, andvrm - engine-target presets cover Unreal static and skeletal handoff, Unity generic and humanoid handoff, Godot glTF handoff, web viewer delivery, and VRChat avatar review
- static checks use the captured scene context to flag missing linked files, absent mesh content, generic object naming, and format- or preset-specific rig requirements before Blender execution is touched
- a deterministic Python probe verifies exporter operator availability, saved file state, missing image datablocks, armature and bone coverage, shape-key presence, and transform hazards such as non-unit or negative scale
- final reports merge the static review and live Blender probe into one per-target finding set with explicit errors and warnings, so downstream export tools can gate handoff on a machine-readable preflight result
This keeps export validation inside the same inspectable automation path as the rest of the Blender-agent package instead of relying on ad hoc artist judgment.
Library Publish Workflow#
The library-publish layer turns Blender export handoff into one Isis-aware publish transaction:
- a primary exported artifact plus optional companion files are uploaded through the Isis asset-library community upload and ingestion path instead of an ad hoc local-only manifest
- provenance records are generated with the same Isis provenance planner used elsewhere in the repo, including Blender export and library-publish steps in the post-process chain
- thumbnails can be supplied directly or captured from Blender through a deterministic Python viewport-render scaffold before upload
- benchmark metadata is assembled from ingestion technical profile, Blender scene context, linked-file state, thumbnail output, and per-stage publish timings so review tools can compare the delivered asset against budgets
- the final publish manifest ties together asset id, category, collection, export artifact payloads, provenance storage key, and benchmark summary in one reviewable object
This keeps Blender-originated asset publishing aligned with Isis ingestion and traceability rules instead of treating publish as only a file transfer.
Render Preview And Review Sheets#
The review-sheet layer turns Blender-side inspection output into one pass-based workflow instead of scattered ad hoc scripts:
contact-sheetrenders a compact turntable-style multi-angle sheet using a deterministic six-view azimuth set and one composited output imageclay-renderapplies a temporary neutral clay override, renders a still, and restores the original materials afterwardwireframe-previewcaptures a viewport wireframe still for topology reviewuv-previewexports the active mesh UV layout directly from Blendermaterial-id-previewapplies deterministic flat-color material overrides, renders a still, and restores the scene state afterward
Offline still passes reuse transaction-backed render actions, while Blender-only inspection surfaces such as viewport wireframe and UV export run through exact Python scaffolds so execution order stays explicit and review output remains inspectable in tests.
Animation Blocking And Polish Macros#
The animation macro layer covers five deterministic workflows:
keyframe-blockingfor object and pose-bone blocking passes with explicit interpolation controlfcurve-polishfor interpolation, handle, extrapolation, and cycles cleanupnla-track-setupfor named track and strip creation with stable blend and timing controlsretarget-animationfor constraint-and-bake retargeting across Bellona's known skeleton profile vocabularypreview-playblastfor fast viewport OpenGL preview renders with bounded frame range, output, and camera control
Retarget planning is based on the same standard skeleton vocabulary already used in Bellona's mocap package, so Mixamo, Unreal Mannequin, OptiTrack Baseline, and Xsens MVN naming patterns can auto-map into one deterministic bone-pair list before the bake scaffold is generated.
Groom Hair And Curves#
The groom macro layer covers four deterministic workflows:
character-hair-groomfor scalp-focused guide curves plus particle-hair scaffold setupcreature-fur-groomfor dense short-strand fur configuration on creature bodies and peltsfoliage-growth-curvesfor Geometry Nodes vine, sprout, and growth-style curve generation on foliage or terrain surfacesstylized-curve-ribbonsfor direct curve-object creation tuned for ribbons, tufts, swirls, and spikes
Character hair and creature fur reuse the existing curve-creation RPC plus Cycles hair tuning hooks, then finish the Blender-native particle setup through targeted Python scaffolds. Foliage growth reuses the same Geometry Nodes growth compiler already present in the package, so procedural review and execution stay on one shared graph model.
Action Schema#
The action schema is designed as a discriminated union with three guarantees:
- every action has a stable
domain,operation,command, andsummary - every supported action maps deterministically to one RPC command descriptor
- every action can be validated before execution or planner handoff
The current schema covers:
- object lifecycle, transforms, parenting, activation, and selection
- mesh edit-mode, extrusion, bevel, subdivide, merge, normal, smooth, and join operations
- armature creation, bone creation, parenting, renaming, and transform edits
- modifier add, update, remove, apply, and reorder operations
- material creation, assignment, PBR property edits, texture assignment, and deletion
- shader-node add/remove/property/input/link/unlink operations
- camera create, activate, and settings updates
- light create and settings updates
- render execution, cancelation, engine configuration, settings, and output
This gives the upcoming planner and selection tasks one authoritative action contract instead of ad hoc command payloads.
Natural-Language Planner#
The planner is intentionally deterministic rather than generative. It does four things in order:
- splits multi-clause instructions into executable sub-clauses
- matches each clause against grounded intent patterns such as primitive creation, modifier edits, material assignment, light/camera changes, and render execution
- resolves scene targets against the supplied scene context
- emits typed actions, exact RPC tool calls, confidence scores, and clarification questions when grounding fails
The planner currently supports:
- object creation, duplication, deletion, rename, move, and scale intents
- mesh bevel, subdivide, shade smooth, and related direct-edit intents
- armature creation
- modifier add intents with extracted numeric properties
- material creation, assignment, and base-color edits
- shader-node addition for common node types
- camera creation and activation
- light creation
- render engine switches and frame/animation render requests
When multiple safe interpretations exist, the planner can emit alternatives. For example, a direct mesh bevel can include a non-destructive bevel-modifier alternative.
Semantic Selection Resolver#
The selection resolver is designed for scene grounding rather than free-form language generation. It:
- infers selection mode such as
select,isolate, orfind - infers the target domain across objects, materials, and collections
- matches names, aliases, tags, traits, parent names, and collection names
- applies side-aware scoring for queries like
left forearmorrear wheel - supports trait-oriented material lookups such as
emissive materials - returns ranked matches, confidence, and explicit ambiguity warnings
The natural-language planner now uses the same resolver internally for object and material grounding so semantic terms behave consistently across workflows.
Operator Recovery Hints#
The operator-recovery layer turns uncertain planning and failing execution into deterministic operator-facing guidance. It currently:
- flags low-confidence planner output before unsafe execution proceeds
- converts planner clarifications and alternatives into explicit next-step questions and fallback plans
- explains transaction blockers such as destructive preview gating and permission-policy approvals
- pattern-matches common Blender failure signatures such as
poll()context errors, missing active-object state, selection mismatches, and missing modifiers - emits ordered recovery suggestions such as switching mode, restoring selection, reactivating the target object, retrying a specific operator, or falling back to explicit Python when operator state remains unstable
Scene Context Capture#
The scene-context capture workflow provides one deterministic runtime snapshot of the current Blender state. It gathers:
- active scene id and scene name
- active object and selected objects
- object visibility and selectability
- collection membership and collection visibility flags
- per-object modifiers, constraints, and material bindings
- material traits such as emissive or transparent
- linked-file references gathered through a deterministic Python probe
The module also includes projection helpers that turn the captured snapshot into the planner and semantic-selection context shapes, so later tasks can consume the same scene state without rewriting adapter-specific mapping code.
Transaction Layer#
The transaction layer is designed to keep Blender-agent execution reversible by default. It provides:
- deterministic transaction previews with per-action risk classification
- explicit destructive-edit gating before live execution
- dry-run planning that captures preflight context without mutating Blender
- undo checkpoints created before the transaction and after each successful action
- automatic rollback attempts when a later action fails
- explicit rollback entrypoints that can reuse prior transaction metadata
The transaction executor runs directly on the existing typed action schema and RPC bridge, so planner output, checkpointing, dry runs, and future audit/policy work all share one execution path.
Headless Batch Execution#
The headless batch execution workflow is designed for render farms and automation workers that should never depend on interactive Blender state. It provides:
- headless-session validation before any batch work starts
- deterministic batch planning with per-job transaction previews
- mixed job steps covering typed transactions, Python automation, and operator calls
- dry-run support for scheduler validation without mutating Blender
- stop-on-error execution semantics suitable for render and post-processing pipelines
Because transaction steps route through the existing transaction layer, batch jobs inherit the same preview gating, undo-checkpoint behavior, and rollback metadata as direct agent-driven execution.
Execution Audit Log#
The execution audit module is designed to stay attached to the real execution bridge. It provides:
- exact command capture for
request,executePython,executePythonFile, andinvokeOperator bpy.ops.*-style call rendering for operator execution, including the exact kwargs payload sent through the bridge- per-call timing with start time, completion time, duration, success, and error state
- pre/post file-state probes that capture active file path, dirty state, and Blender data-block counts, then emit a structured diff
- transaction and batch correlation so downstream systems can slice the audit stream per transaction, job, or whole batch run
Wrap the bridge once with createBellonaBlenderAuditedBridge(...), then pass
that same audited bridge into transaction or batch execution. The resulting
transaction and batch result objects expose the matching auditEntries slice
for that unit of work.
Permission Policy#
The permission-policy module provides one deterministic gate for destructive Blender edits. It currently covers:
- object deletion
- modifier application
- material overwrite and destructive node edits
- collection unlink intents classified from raw RPC, operator, or Python calls
The default strict policy marks those scopes as review, which means live
execution is blocked until matching approval tokens are provided. Transaction
execution returns status: "blocked" with a structured permission result, and
headless batch execution keeps those jobs in a planned state rather than
silently mutating Blender.
Geometry Nodes Authoring#
The Geometry Nodes authoring module sits one level above the low-level
geometry_nodes.* bridge commands already exposed by @bellona/blender. It:
- compiles structured intents into deterministic node trees with stable aliases, interface sockets, links, and warnings
- supports the six Phase
71.12.2.1intent families:scatter,instancing,bevel,paneling,terrain-dressing, andgrowth - emits an execution plan that resolves alias-to-node-ID mappings while sending
exact
geometry_nodes.create_tree,add_input,add_output,add_node,set_node_property,set_node_input,link_nodes, andapply_to_objectcommands through the bridge
This keeps graph authoring inspectable for later diff/merge work in 71.12.2.3,
while already being executable today for deterministic procedural setup
generation.
Geometry Nodes Diff And Merge#
The diff/merge layer is designed for reviewable procedural edits rather than opaque command streams. It provides:
- metadata hunks for
treeName, summary, intent kind, and applied object - interface hunks for added, removed, or updated group inputs and outputs
- node hunks keyed by stable node aliases
- link hunks keyed by exact socket-to-socket edges
- warning hunks for review notes added or removed between revisions
Selective merge applies only the hunks a reviewer accepts, then rebuilds the
create-tree, add-input, add-output, add-node, set-node-*,
link-nodes, and apply-to-object execution plan so accepted graph edits can
run immediately without hand-editing RPC payloads.
Geometry Nodes Template Library#
The template library builds on the authoring compiler rather than introducing a second procedural system. It currently ships five reusable presets:
foliage-scatterfor terrain-aware vegetation and ground-cover placementcablesfor repeated wire, pipe, and hose instancing along guide geometrykitbash-panelsfor hard-surface panel breakup and platingdebrisfor rubble, fragments, and destruction dressingmodular-facadesfor architectural panel-plus-module facade generation
Each template instantiates one or more deterministic authoring plans, keeps tree
names stable, and can execute directly through the same geometry_nodes.*
bridge path used by hand-authored structured intents.
Shader Material Graph Authoring#
The shader-material graph authoring layer targets Principled BSDF as the Blender execution surface while keeping its input schema aligned with common MaterialX standard-surface terminology. It provides:
- normalized Principled controls for base, metalness, roughness, transmission, coat, sheen, emission, alpha, subsurface, IOR, and anisotropy
- MaterialX-style parameter bindings such as
base_color,specular_roughness,coat,sheen_color, andopacity - deterministic texture-driven graph generation with Texture Coordinate, Mapping, Image Texture, and Normal Map nodes
- explicit approximation notes when a MaterialX color-oriented control must be collapsed into a scalar Principled tint control
- exact bridge execution over
material.create,material.set_blend_mode,material.set_shadow_mode,material.set_backface_culling,material.add_node,material.set_node_property,material.set_node_input,material.link_nodes, andmaterial.assign
This keeps material generation reviewable in the same way as the Geometry Nodes track while still targeting the Blender-native Principled shader model for deterministic execution today.
Modifier And Mesh Cleanup Macros#
The modifier and mesh cleanup layer provides one deterministic entrypoint for common corrective passes that artists regularly chain together by hand. It currently ships built-in macros for:
uv-cleanupweighted-normalsremeshdecimateshrinkwrapbevelbooleanmodifier-stack-cleanup
The planner emits typed Blender actions for mesh shading, modifier add/update,
modifier reorder, modifier removal, and modifier application, then routes those
actions through the existing transaction layer so preview gating, checkpoints,
rollback, and audit hooks remain consistent with the rest of the agent. UV
cleanup is handled via deterministic bpy.ops.uv.* Python snippets until the
typed action schema grows explicit UV operations.
Rig Generation And Editing Macros#
The rig macro layer provides one deterministic entrypoint for common armature and rig authoring work. It currently ships built-in macros for:
generate-armatureedit-bonesik-setupfk-setupcustom-controlsdriver-setupcorrective-shapes
The planner uses typed armature and object actions wherever the current schema already covers the operation, routes constraint and driver configuration through the existing raw RPC bridge, and falls back to explicit Python only for custom control shape assignment and corrective shape-key driver scaffolding. That keeps rig setup reviewable while still covering Blender-native workflows that are not yet first-class typed actions.
Example#
import {
BLENDER_RPC_BRIDGE_WORKFLOW,
BLENDER_AGENT_RUNTIME_WORKFLOW,
createBellonaBlenderAction,
planBellonaBlenderActionsFromPrompt,
createBellonaBlenderRpcBridge,
createBellonaBlenderAgentProjectManifest,
createBellonaBlenderAgentRuntimeCapabilities,
} from '@bellona/blender-agent';
const capabilities = createBellonaBlenderAgentRuntimeCapabilities();
const manifest = createBellonaBlenderAgentProjectManifest();
const bridge = createBellonaBlenderRpcBridge({
transport: {
kind: 'websocket',
connectionConfig: {
host: '127.0.0.1',
port: 9876,
},
},
});
const action = createBellonaBlenderAction({
id: 'create-cube',
domain: 'object',
operation: 'create-primitive',
payload: {
primitive: 'cube',
},
});
console.log(BLENDER_AGENT_RUNTIME_WORKFLOW);
console.log(BLENDER_RPC_BRIDGE_WORKFLOW);
console.log(capabilities.transports);
console.log(manifest.modules.map((module) => module.id));
console.log(action.command);
console.log(
planBellonaBlenderActionsFromPrompt({
instruction: 'Add a bevel modifier with offset 0.05 to Cube',
sceneContext: {
activeObjectId: 'cube-id',
activeObjectName: 'Cube',
objects: [{ id: 'cube-id', name: 'Cube', type: 'MESH' }],
},
}).toolCalls
);
console.log(await bridge.connect());