# @bellona/blender-agent `@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`, and `typecheck` targets - package metadata for the dedicated `@bellona/blender-agent` library - 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`, and `find emissive materials` against 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 `bpy` calls, 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 `.blend` packaging 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: - `bridge` for WebSocket/stdin RPC execution - `actions` for typed Blender operations - `planning` for natural-language-to-action orchestration - `selection` for semantic object resolution - `scene-context` for current-scene capture - `transactions` for reversible execution - `batch` for headless farm-safe runs - `audit` for exact call logging - `policy` for 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-garment` for shirts, dresses, skirts, and other garment drape setups - `cloth-cape` for pinned cape or banner-style trailing cloth - `rigid-body-prop` for active or passive props with collider pairing - `destruction-preview` for shard, floor, and anchor setup in fast breakage previews - `soft-body-deform` for 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: - `turntable` stages an orbit camera, three-light presentation rig, and square transparent-background render defaults - `product-render` stages a detail-oriented camera with shallow depth of field plus key, fill, rim, and backdrop lift lighting - `hero-shot` stages a closer dramatic lens choice with stronger rim separation and widescreen defaults - `animation-blocking` stages a wider camera and readable low-cost lighting for layout and blocking review - `review-dailies` stages 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.txt` so 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 `.blend` is copied into a package directory with `bpy.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//...`, 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`, and `vrm` - 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-sheet` renders a compact turntable-style multi-angle sheet using a deterministic six-view azimuth set and one composited output image - `clay-render` applies a temporary neutral clay override, renders a still, and restores the original materials afterward - `wireframe-preview` captures a viewport wireframe still for topology review - `uv-preview` exports the active mesh UV layout directly from Blender - `material-id-preview` applies 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-blocking` for object and pose-bone blocking passes with explicit interpolation control - `fcurve-polish` for interpolation, handle, extrapolation, and cycles cleanup - `nla-track-setup` for named track and strip creation with stable blend and timing controls - `retarget-animation` for constraint-and-bake retargeting across Bellona's known skeleton profile vocabulary - `preview-playblast` for 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-groom` for scalp-focused guide curves plus particle-hair scaffold setup - `creature-fur-groom` for dense short-strand fur configuration on creature bodies and pelts - `foliage-growth-curves` for Geometry Nodes vine, sprout, and growth-style curve generation on foliage or terrain surfaces - `stylized-curve-ribbons` for 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`, and `summary` - 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`, or `find` - 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 forearm` or `rear 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`, and `invokeOperator` - `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.1` intent families: `scatter`, `instancing`, `bevel`, `paneling`, `terrain-dressing`, and `growth` - 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`, and `apply_to_object` commands 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-scatter` for terrain-aware vegetation and ground-cover placement - `cables` for repeated wire, pipe, and hose instancing along guide geometry - `kitbash-panels` for hard-surface panel breakup and plating - `debris` for rubble, fragments, and destruction dressing - `modular-facades` for 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`, and `opacity` - 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`, and `material.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-cleanup` - `weighted-normals` - `remesh` - `decimate` - `shrinkwrap` - `bevel` - `boolean` - `modifier-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-armature` - `edit-bones` - `ik-setup` - `fk-setup` - `custom-controls` - `driver-setup` - `corrective-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 ```ts 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()); ```