Blender Addon Extension Development

Blender add-on extension development

When to Use

Use when adding Blender properties or UI, render settings, scene or USD conversion, interactive edits, render sequences, sensor products, viewport presentation, diagnostics, or tests.

Boundary

Work in the distributed source checkout and use its documented add-on and runtime interfaces. Start with an add-on implementation and use a minimal capability probe before reporting a missing runtime capability.

Use paths below relative to the source root. Preserve guarded bpy imports so pure modules and tests remain importable outside Blender. Keep all worker calls on the existing serialized session-owner/render thread.

Instructions

Choose the narrowest route before editing:

For a specialized route, use the matching extend-ovrtx-* skill when present.

Classify ownership before coding

Write down these decisions in the implementation plan:

1. Identify the Blender signal and the normalized add-on-owned value.
2. Classify it as durable USD topology, durable USD value, same-session runtime value, session identity, worker-startup configuration, or presentation-only.
3. Identify the typed request/result boundary. Do not pass arbitrary dictionaries across an existing dataclass boundary just to avoid modeling it.
4. Decide whether omission means INHERIT, whether an explicit value means OVERRIDE, and how reset returns to inherited behavior.
5. Identify the observable acceptance result: authored USD, effective setting, typed product, rendered pixels, or an explicit rejection diagnostic.

Implementation

1. Add pure normalized types and conversion policy in a focused module. Reject unsupported input explicitly; do not silently approximate topology or units.
2. Add Blender properties and registration in properties.py and __init__.py only when the feature is user-configurable.
3. Carry the normalized value through RenderRequest or the appropriate edit intent/result type. Include it in identity/digests only when it changes the composed session.
4. Author durable USD through scene generation or composition. Route supported same-session values through the established edit/update stream. Replace the generation or session for topology and unsupported live writes.
5. Add UI after the typed path works. Display effective state and rejection or fallback reason, not only the requested value.
6. Add unit tests at each boundary and one included fixture/probe that observes the actual product with the installed runtime when available.

Architectural invariants

• Keep Blender callbacks and UI code free of blocking runtime calls.
• Submit runtime work through RuntimeScheduler/OvrtxSessionController; do not instantiate another worker client in a property callback or operator.
• Keep current-scene generation separate from exact-stage validation. Exact-stage requests must not replace source materials, lights, or topology.
• Preserve SceneGenerationOwner.replace/accept/reject: a failed candidate must leave the last accepted generation usable.
• Keep material, lighting, color, and viewport presentation ownership singular. Do not compensate for a renderer problem by mutating source material values.
• Make cached keys depend on every input that changes output, and test both reuse and invalidation.
• Return typed results for non-image products; do not force point clouds or AOVs through an RGBA-only result model.
• Never report success from an accepted API call alone. Check the composed stage, effective state, product metadata, and visible/numeric output as applicable.

Validation

Run the focused pure-Python tests first, then the complete tests suite. For Blender-dependent behavior, run the documented included Blender fixture. For runtime-dependent behavior, use the documented runtime interface and record versions, request, response, diagnostics, and a caller-selected artifact path.

Test success, inheritance/reset, invalid input, missing optional capability, cache invalidation, session replacement or reuse, cancellation/shutdown, and plain-Python import behavior where relevant.

Escalation gate

Report a runtime capability gap only when the smallest documented-interface probe shows that the typed operation cannot be expressed, is rejected by a compatible runtime, or cannot return enough metadata to distinguish success from false success. Missing add-on routing, USD authoring, threading, UI, conversion, caching, or diagnostics remains add-on work.

Handoff

Return changed paths and symbols, focused and full-suite results, fixture or visual evidence, compatibility notes, and exactly one boundary decision: addon-only or runtime-capability-missing with the minimal probe.