---
name: blender-addon-extension-development
description: Route and implement source changes in the OVRTX Blender add-on. Use when adding Blender properties or UI, render settings, scene or USD conversion, interactive edits, render sequences, sensor products, viewport presentation, diagnostics, or tests.
license: "Apache-2.0"
metadata:
author: "Max Bickley"
version: "0.1"
team: "omniverse"
domain: "physical-ai"
tags:
- blender
- omniverse
- ovrtx
- addon-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:
| Feature |
Start here |
Continue through |
Required tests |
| Blender property or panel |
addon/ovrtx_blender_example/properties.py |
ui.py, engine.py, typed request/composition module |
focused property and panel tests such as tests/test_rtpt_scene_properties.py and tests/test_rtpt_render_panel.py |
| Render setting |
properties.py::RTPT_RENDER_SETTINGS and RtptSettingSpec |
render_requests.py::RenderRequest, ovrtx_scene_composition.py, view_update_stream.py, runtime_scheduler.py |
test_rtpt_scene_properties.py, test_rtpt_render_product_authoring.py, test_rtpt_live_change.py |
| Material graph/OpenPBR |
materialx_openpbr_conversion.py::scene_layer_from_materials |
texture_materialization.py, blender_signal_translation.py::_material_scene_layer_from_scene |
test_materialx_openpbr_conversion.py, test_texture_materialization.py, test_render_requests.py |
| Scene object/topology |
scene_generation.py::SceneGenerationOwner |
_stock_export, _compile_add_on_opinions, topology reconciliation, topology_edit_fallback.py |
test_scene_generation.py, test_scene_generation_contract.py, test_topology_edit_fallback.py |
| Interactive value edit |
blender_signals.py and blender_signal_translation.py |
blender_interactive_edit_builders.py, interactive_edit_planner.py, value_edit_conversion.py, interactive_edit_workflow.py, runtime_scheduler.py |
corresponding test_blender_*, test_interactive_*, test_value_edit_conversion.py |
| Session or sequence |
render_requests.py::RenderRequest |
ovrtx_session.py, ovrtx_session_controller.py, runtime_scheduler.py, engine.py |
test_ovrtx_session.py, test_ovrtx_session_controller.py, test_runtime_scheduler.py, test_final_render_on_rpc_thread.py |
| Product/pixel result |
render_requests.py and direct_sdk_client.py::PublicSdkRenderClient |
pure typed result/error models in ovrtx_runtime_client.py, consumed by the direct SDK client; scheduler publication and engine.py presentation; additional AOVs require explicit future admission |
test_render_requests.py, test_direct_sdk_client.py, scheduler and presentation tests |
| Viewport upload/display |
viewport_handoff.py and viewport_presentation.py |
viewport_render_thread.py, engine.py |
test_viewport_handoff.py, test_viewport_presentation.py, test_viewport_render_thread.py |
| Preflight/diagnostics |
preflight.py or the owning module's diagnostics model |
user_messages.py, ui.py |
test_addon_preflight.py, test_user_messages.py, focused diagnostics test |
For a specialized route, use the matching extend-ovrtx-* skill when present.
Classify ownership before coding
Write down these decisions in the implementation plan:
- Identify the Blender signal and the normalized add-on-owned value.
- Classify it as durable USD topology, durable USD value, same-session runtime
value, session identity, worker-startup configuration, or presentation-only.
- Identify the typed request/result boundary. Do not pass arbitrary
dictionaries across an existing dataclass boundary just to avoid modeling it.
- Decide whether omission means
INHERIT, whether an explicit value means
OVERRIDE, and how reset returns to inherited behavior.
- Identify the observable acceptance result: authored USD, effective setting,
typed product, rendered pixels, or an explicit rejection diagnostic.
Implementation
- Add pure normalized types and conversion policy in a focused module. Reject
unsupported input explicitly; do not silently approximate topology or units.
- Add Blender properties and registration in
properties.py and __init__.py
only when the feature is user-configurable.
- 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.
- 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.
- Add UI after the typed path works. Display effective state and rejection or
fallback reason, not only the requested value.
- 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 focused affected-code checks first. Run the relevant complete suite once at
an integration/phase boundary, reusing unchanged-artifact evidence. Current graph
qualification uses representative checks with each invocation/batch below ten
minutes; exhaustive benchmarking is separately deferred.
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.
1---2name: blender-addon-extension-development3description: Route and implement source changes in the OVRTX Blender add-on. Use when adding Blender properties or UI, render settings, scene or USD conversion, interactive edits, render sequences, sensor products, viewport presentation, diagnostics, or tests.4license: "Apache-2.0"5metadata:6 source: https://skillmd.com/skills/nvidia-omniverse/blender-addon-extension-development7 author: "Max Bickley"8 version: "0.1"9 team: "omniverse"10 domain: "physical-ai"11 tags:12 - blender13 - omniverse14 - ovrtx15 - addon-development16---17# Blender add-on extension development1819## When to Use2021Use when adding Blender properties or UI, render settings, scene or USD conversion, interactive edits, render sequences, sensor products, viewport presentation, diagnostics, or tests.2223## Boundary2425Work in the distributed source checkout and use its documented add-on and26runtime interfaces. Start with an add-on implementation and use a minimal27capability probe before reporting a missing runtime capability.2829Use paths below relative to the source root. Preserve guarded `bpy` imports so pure30modules and tests remain importable outside Blender. Keep all worker calls on the31existing serialized session-owner/render thread.3233## Instructions3435Choose the narrowest route before editing:3637| Feature | Start here | Continue through | Required tests |38| --- | --- | --- | --- |39| Blender property or panel | `addon/ovrtx_blender_example/properties.py` | `ui.py`, `engine.py`, typed request/composition module | focused property and panel tests such as `tests/test_rtpt_scene_properties.py` and `tests/test_rtpt_render_panel.py` |40| Render setting | `properties.py::RTPT_RENDER_SETTINGS` and `RtptSettingSpec` | `render_requests.py::RenderRequest`, `ovrtx_scene_composition.py`, `view_update_stream.py`, `runtime_scheduler.py` | `test_rtpt_scene_properties.py`, `test_rtpt_render_product_authoring.py`, `test_rtpt_live_change.py` |41| Material graph/OpenPBR | `materialx_openpbr_conversion.py::scene_layer_from_materials` | `texture_materialization.py`, `blender_signal_translation.py::_material_scene_layer_from_scene` | `test_materialx_openpbr_conversion.py`, `test_texture_materialization.py`, `test_render_requests.py` |42| Scene object/topology | `scene_generation.py::SceneGenerationOwner` | `_stock_export`, `_compile_add_on_opinions`, topology reconciliation, `topology_edit_fallback.py` | `test_scene_generation.py`, `test_scene_generation_contract.py`, `test_topology_edit_fallback.py` |43| Interactive value edit | `blender_signals.py` and `blender_signal_translation.py` | `blender_interactive_edit_builders.py`, `interactive_edit_planner.py`, `value_edit_conversion.py`, `interactive_edit_workflow.py`, `runtime_scheduler.py` | corresponding `test_blender_*`, `test_interactive_*`, `test_value_edit_conversion.py` |44| Session or sequence | `render_requests.py::RenderRequest` | `ovrtx_session.py`, `ovrtx_session_controller.py`, `runtime_scheduler.py`, `engine.py` | `test_ovrtx_session.py`, `test_ovrtx_session_controller.py`, `test_runtime_scheduler.py`, `test_final_render_on_rpc_thread.py` |45| Product/pixel result | `render_requests.py` and `direct_sdk_client.py::PublicSdkRenderClient` | pure typed result/error models in `ovrtx_runtime_client.py`, consumed by the direct SDK client; scheduler publication and `engine.py` presentation; additional AOVs require explicit future admission | `test_render_requests.py`, `test_direct_sdk_client.py`, scheduler and presentation tests |46| Viewport upload/display | `viewport_handoff.py` and `viewport_presentation.py` | `viewport_render_thread.py`, `engine.py` | `test_viewport_handoff.py`, `test_viewport_presentation.py`, `test_viewport_render_thread.py` |47| Preflight/diagnostics | `preflight.py` or the owning module's diagnostics model | `user_messages.py`, `ui.py` | `test_addon_preflight.py`, `test_user_messages.py`, focused diagnostics test |4849For a specialized route, use the matching `extend-ovrtx-*` skill when present.5051## Classify ownership before coding5253Write down these decisions in the implementation plan:54551. Identify the Blender signal and the normalized add-on-owned value.562. Classify it as durable USD topology, durable USD value, same-session runtime57 value, session identity, worker-startup configuration, or presentation-only.583. Identify the typed request/result boundary. Do not pass arbitrary59 dictionaries across an existing dataclass boundary just to avoid modeling it.604. Decide whether omission means `INHERIT`, whether an explicit value means61 `OVERRIDE`, and how reset returns to inherited behavior.625. Identify the observable acceptance result: authored USD, effective setting,63 typed product, rendered pixels, or an explicit rejection diagnostic.6465## Implementation66671. Add pure normalized types and conversion policy in a focused module. Reject68 unsupported input explicitly; do not silently approximate topology or units.692. Add Blender properties and registration in `properties.py` and `__init__.py`70 only when the feature is user-configurable.713. Carry the normalized value through `RenderRequest` or the appropriate edit72 intent/result type. Include it in identity/digests only when it changes the73 composed session.744. Author durable USD through scene generation or composition. Route supported75 same-session values through the established edit/update stream. Replace the76 generation or session for topology and unsupported live writes.775. Add UI after the typed path works. Display effective state and rejection or78 fallback reason, not only the requested value.796. Add unit tests at each boundary and one included fixture/probe that observes80 the actual product with the installed runtime when available.8182## Architectural invariants8384- Keep Blender callbacks and UI code free of blocking runtime calls.85- Submit runtime work through `RuntimeScheduler`/`OvrtxSessionController`; do not86 instantiate another worker client in a property callback or operator.87- Keep current-scene generation separate from exact-stage validation. Exact-stage88 requests must not replace source materials, lights, or topology.89- Preserve `SceneGenerationOwner.replace`/`accept`/`reject`: a failed candidate90 must leave the last accepted generation usable.91- Keep material, lighting, color, and viewport presentation ownership singular.92 Do not compensate for a renderer problem by mutating source material values.93- Make cached keys depend on every input that changes output, and test both reuse94 and invalidation.95- Return typed results for non-image products; do not force point clouds or AOVs96 through an RGBA-only result model.97- Never report success from an accepted API call alone. Check the composed stage,98 effective state, product metadata, and visible/numeric output as applicable.99100## Validation101102Run focused affected-code checks first. Run the relevant complete suite once at103an integration/phase boundary, reusing unchanged-artifact evidence. Current graph104qualification uses representative checks with each invocation/batch below ten105minutes; exhaustive benchmarking is separately deferred.106For Blender-dependent behavior, run the documented included Blender fixture.107For runtime-dependent behavior, use the documented runtime interface and record108versions, request, response, diagnostics, and a caller-selected artifact path.109110Test success, inheritance/reset, invalid input, missing optional capability,111cache invalidation, session replacement or reuse, cancellation/shutdown, and112plain-Python import behavior where relevant.113114## Escalation gate115116Report a runtime capability gap only when the smallest documented-interface117probe shows that the typed operation cannot be expressed, is rejected by a118compatible runtime, or cannot return enough metadata to distinguish success119from false success. Missing add-on routing, USD authoring, threading, UI,120conversion, caching, or diagnostics remains add-on work.121122## Handoff123124Return changed paths and symbols, focused and full-suite results, fixture125or visual evidence, compatibility notes, and exactly one boundary decision:126`addon-only` or `runtime-capability-missing` with the minimal probe.127