Skip to content

ROADMAP.md

Latest commit

 

History

History
227 lines (189 loc) · 35.5 KB

ROADMAP.md

File metadata and controls

227 lines (189 loc) · 35.5 KB
Raw

Roadmap

Current: v0.78.13

Themes are listed in order. Shipped themes note the release they landed in (for reference, not a commitment); upcoming themes are intentionally not pinned to a version number, so shipping another example or skill never forces a roadmap renumber. The release pipeline derives the actual version from conventional-commit types.

Theme Skills Rules Templates Snippets Status
Foundation 8 4 1 10 Shipped (v0.1.0)
Materials, drivers, migration 12 6 2 17 Shipped (v0.2.0)
Examples and demos (smoke-gated) 12 6 2 17 Shipped (v0.3.0)
More examples (turntable, SDF remesh) 12 6 2 17 Shipped (v0.4.0)
5.2 LTS targeting, GN modifier inputs 12 6 2 17 Shipped
VSE COLOR strip intrinsic size (undocumented 5.2) 13 6 2 17 Shipped
Modal operators, USD, mathutils — — — — Upcoming
AI asset pipeline: post-generation cleanup 14 8 2 21 Shipped (v0.54.0)
AI asset pipeline: engine export presets 15 9 2 24 Shipped
AI asset pipeline: headless template 15 9 3 24 Shipped
AI asset pipeline: high-to-low bake 16 9 3 27 Shipped
AI asset pipeline: live-session bridge (spike) - - - - Upcoming
Stable — — — — Upcoming

v0.1.0 - Foundation

The 8 skills:

  • addon-scaffolding -- Extensions Platform manifest, file layout, register/unregister symmetry
  • operators -- bpy.types.Operator lifecycle, bl_idname, redo, defensive context handling
  • ui-panels -- bpy.types.Panel declarative draw(), layout primitives, conditional UI
  • custom-properties -- bpy.props annotations, PropertyGroup, PointerProperty, storage tradeoffs
  • mesh-editing-and-bmesh -- when to use bpy.data vs bpy.ops vs bmesh, foreach_set, depsgraph eval
  • headless-batch-scripting -- blender --background --python, temp_override, argparse after --
  • slotted-actions-animation -- Blender 5.x Slotted Actions, channelbag, 4.5 LTS fallback bridge
  • geometry-nodes-python -- programmatic GN tree construction, interface sockets, NODES modifier

The 4 rules:

  • prefer-data-over-ops-in-loops
  • always-free-bmesh
  • target-extensions-platform-format
  • type-annotate-props-and-defend-context

The 1 template:

  • extension-addon-template -- Extensions Platform format, register_classes_factory, PointerProperty binding, symmetric register/unregister

The 10 snippets:

  • canonical-object-creation.py
  • canonical-object-deletion.py
  • depsgraph-evaluated-mesh.py
  • bmesh-load-edit-free.py
  • temp-override-context.py
  • foreach-set-vertices.py
  • register-classes-factory.py
  • pointerproperty-binding.py
  • cross-version-property-delete.py
  • action-ensure-channelbag-for-slot.py

v0.2.0 - Materials, drivers, migration

The 4 new skills:

  • procedural-materials-and-shaders -- node tree construction for Principled BSDF, emissive, node groups; cross-version socket-name handling for Specular IOR Level
  • depsgraph-and-evaluated-data -- evaluated_get plus to_mesh plus to_mesh_clear lifetime contract, OBJ-style exporter worked example
  • drivers-and-app-handlers -- driver expressions, bpy.app.driver_namespace escape hatch, application handler pattern with @persistent, the new 5.1 exit_pre handler
  • bl-info-migration -- three-step migration from legacy bl_info to Extensions Platform, before-and-after diff, dual-format pattern

The 2 new rules:

  • prefer-temp-override-over-context-copy -- bpy.context.copy() deprecation in 4.x, removal in 5.x, temp_override replacement
  • use-foreach-set-for-bulk-data -- per-element Python loops over mesh data versus foreach_set and foreach_get

The 1 new template:

  • headless-batch-script-template -- argparse after --, mesh iteration, modifier apply via temp_override, glTF export, explicit exit codes

The 7 new snippets:

  • principled-bsdf-material.py
  • driver-with-custom-function.py
  • app-handler-registration.py
  • shader-node-group.py (cross-version interface vs inputs/outputs)
  • foreach-get-vertices.py
  • version-branch-skeleton.py
  • usd-export-evaluation-mode.py

Audit pass on v0.1.0 content: standards-version markers bumped from 1.9.1 to 1.9.4 across all skills, rules, AGENTS.md, CLAUDE.md, and ROADMAP.md. Verified the bpy_extras.anim_utils.action_ensure_channelbag_for_slot import path against the current Blender 5.1 API reference and removed the stale "verify before production" caveat in slotted-actions-animation/SKILL.md.

AI asset pipeline track

Provider-agnostic GLB-in / engine-ready-out. This repo does not generate meshes.

  • Post-generation cleanup skills. Import and unit-scale normalization, transform apply and origin, poly-budget decimate, LOD chain, collision mesh. Phase 1 shipped in v0.54.0 as ai-mesh-cleanup, four snippets, two rules.
  • High-to-low normal bake. Delivered. Skill bake-high-to-low, snippets setup_bake_target_image.py / bake_normal_high_to_low.py / save_baked_image.py, witness examples/bake-normal-high-to-low/. Cycles CPU cage bake; statistical gates, not byte-identity. UV transfer and atlas packing remain a later phase. Template integration remains a later phase.
  • Engine export presets. Delivered. Unity (Y-up glTF), Godot (Z-up glTF, meters), Unreal (centimeter glTF bake and FBX global_scale). Skill engine-export-presets, three snippets, rule use-correct-axis-rna-per-exporter, witness examples/export-preset-axis/. Draco remains opt-in via gltf_draco_export.py.
  • ai-asset-pipeline-template/. Delivered. Third template. Headless: GLB path in; LOD set, convex or box collider, engine-preset export; explicit CI exit codes. Pattern: templates/headless-batch-script-template/.
  • Live-session agent bridge. Research spike, not a committed deliverable. MCP server or socket listener so an agent can execute against a running Blender instance instead of blind --background scripts. Built on templates/extension-addon-template/. Needs its own design pass. Unpinned.

Candidate pool (next content)

Not committed; target list for the next content version. (v0.3.0 shipped the smoke-gated examples/ track.)

  • Showcase sibling tree + shipping-crate pilot SHIPPED as showcase/shipping-crate/ — budget-conformance crate composing bake, LOD, collider, Unity glTF; --skip-decimate exits 9 on the LOD1 ratio band; DECIMATE COLLAPSE ratios diverge on 5.2 vs 4.5/5.1

  • Round stone well showcase SHIPPED as showcase/stone-well/ — running-bond brick well, shingled pyramid roof, windlass/rope/bucket; --skip-decimate exits 9 on the LOD1 ratio band

  • Wooden barrel showcase SHIPPED as showcase/wooden-barrel/ — bulged staves, four iron hoops, lid heads; --skip-decimate exits 9 on the LOD1 ratio band

  • Campfire showcase SHIPPED as showcase/campfire/ — two-course fire ring, log tripod; --skip-decimate exits 9 on the LOD1 ratio band

  • Market stall showcase SHIPPED as showcase/market-stall/ — timber frame, slatted counter, striped awning; --skip-decimate exits 9 on the LOD1 ratio band

  • Procedural terrain or landscape showcase using Geometry Nodes scatter SHIPPED as showcase/terrain-scatter/ — GN sine-hill Mesh Grid, Index-jittered Instance-on-Points scatter replaced with bevelled masonry; --skip-decimate exits 9 on the LOD1 ratio band

  • Hero prop with a more complex silhouette (lantern or treasure chest) as a second showcase piece SHIPPED as showcase/street-lantern/ and showcase/treasure-chest/ — hanging iron lantern with muntined amber cage; slatted chest with iron bands and an open lid; --skip-decimate exits 9 on the LOD1 ratio band

  • Timber watchtower showcase SHIPPED as showcase/watchtower/ — corner posts through a plank platform, lower-bay X-braces, hatch ladder, coursed shake roof; --skip-decimate exits 9 on the LOD1 ratio band

  • Two-wheel wooden cart showcase SHIPPED as showcase/cart/ — slatted bed, shafts, spoked wheels, iron hubs and axle; --skip-decimate exits 9 on the LOD1 ratio band

  • Wrought-iron park bench (slatted seat, scrolled legs) as a game-prop showcase piece SHIPPED as showcase/park-bench/ — scrolled iron legs, slatted seat and back; --skip-decimate exits 9 on the LOD1 ratio band

  • Wooden wheelbarrow (staved tray, single wheel, handles) as a game-prop showcase piece SHIPPED as showcase/wheelbarrow/ — staved U-tray, iron straps, spoked wheel, rear legs; --skip-decimate exits 9 on the LOD1 ratio band

  • Blacksmith anvil on a timber stump as a game-prop showcase piece SHIPPED as showcase/anvil/ — London-pattern horn, face, heel, waist, hooped stump; --skip-decimate exits 9 on the LOD1 ratio band

  • Staved wooden water trough on a stand as a game-prop showcase piece SHIPPED as showcase/water-trough/ — watertight U-hull, plank ends, contained water, iron straps, trestle legs; --skip-decimate exits 9 on the LOD1 ratio band

  • Hitching post with iron ring as a game-prop showcase piece SHIPPED as showcase/hitching-post/ — square post, pyramidal cap, cross-arm, iron shoe, bands, two rings; --skip-decimate exits 9 on the LOD1 ratio band

  • Grindstone on a timber trestle as a game-prop showcase piece SHIPPED as showcase/grindstone/ — stone wheel, A-frame trestle, iron axle, hubs, crank; --skip-decimate exits 9 on the LOD1 ratio band

  • Cast-iron village hand pump as a game-prop showcase piece SHIPPED as showcase/hand-pump/ — wooden plinth, column, spout, handle, wooden grip; --skip-decimate exits 9 on the LOD1 ratio band

  • Timber fingerboard signpost as a game-prop showcase piece SHIPPED as showcase/signpost/ — square post, pyramidal cap, two painted boards, iron shoe and straps; --skip-decimate exits 9 on the LOD1 ratio band

  • Blacksmith bellows as a game-prop showcase piece DROPPED — leather bag never read; removed from the showcase tree rather than shipping a crate-shaped miss

  • Chopping block with embedded axe as a game-prop showcase piece SHIPPED as showcase/chopping-block/ — hooped timber stump, kerf, embedded axe; --skip-decimate exits 9 on the LOD1 ratio band

  • Wooden bucket with iron bands and a rope bail as a game-prop showcase piece SHIPPED as showcase/wooden-bucket/ — overlapping staves, sealed bottom, iron hoops, ears, rope bail; --skip-decimate exits 9 on the LOD1 ratio band

  • Wall-mounted torch sconce as a game-prop showcase piece SHIPPED as showcase/wall-torch/ — coursed stone plaque, iron bracket and cup, wooden haft, emissive flame; --skip-decimate exits 9 on the LOD1 ratio band

  • Wooden tavern stool (turned legs, round seat, stretchers) as a game-prop showcase piece SHIPPED as showcase/tavern-stool/ — round seat, turned splayed legs, stretchers, iron ferrules; --skip-decimate exits 9 on the LOD1 ratio band

  • Cast-iron cooking cauldron on a tripod as a game-prop showcase piece SHIPPED as showcase/iron-cauldron/ — bulged open pot, bail, timber tripod, hook; --skip-decimate exits 9 on the LOD1 ratio band

  • Wooden ladder (rungs, stiles, iron shoes) as a game-prop showcase piece SHIPPED as showcase/wooden-ladder/ — raked stiles, six rungs, iron shoes and straps; --skip-decimate exits 9 on the LOD1 ratio band

  • Bound hay bale as a game-prop showcase piece SHIPPED as showcase/hay-bale/ — bevelled loaf, end nap, two sisal twine belts; --skip-decimate exits 9 on the LOD1 ratio band

  • Wooden yoke (oxbow, iron rings) as a game-prop showcase piece

  • Butter churn (staved tub, lid, dasher) as a game-prop showcase piece

  • Small modular kit showcase on recognizable geometry (modular-kit-snap contract) SHIPPED as showcase/fence-kit/ — tiling post-and-rail section (AABB X is the tile width; does not re-witness the snap contract); --skip-decimate exits 9 on the LOD1 ratio band

  • Custom ID-property delete witness SHIPPED as examples/cross-version-property-delete/ — IDs built via bpy.data.objects.new (not active_object); property_unset is TypeError and leaves the key; del removes it on 4.5 LTS and 5.x

  • USD export evaluation_mode witness SHIPPED as examples/usd-export-evaluation-mode/ — probed wm.usd_export on CI Linux portables 5.2.1 (9e2066aef7ef) and 4.5.13 (daeeeca98fb0); TESSELLATE+VIEWPORT 26/24, TESSELLATE+RENDER 98/96; BEST_MATCH writes the 8-vert catmullClark cage so the mode is silent

  • Repeat Zone / For Each Element pairing witness SHIPPED as examples/gn-zone-iterate/ — pair_with_output is load-bearing (unpaired evaluates 0 verts); Repeat 8×(1+N) with X-centers at k×STEP; For Each 8×P with Z-centers at i×STEP; For Each main Geometry is a passthrough (6 verts); count-only is insufficient (--no-offset still 32 verts, one X-center)

  • Geometry Nodes bundle round-trip SHIPPED as examples/gn-bundle-roundtrip/ — 5.x RNA NodeCombineBundle (GeometryNodeCombineBundle undefined on 5.2); closed form 8/6 + x [0.5, 2.5] + bundle_mark=0.314159; 4.5 SKIP via catalog min_version 5.0 (experimental flag off evaluates empty; --force-run hits 5.x RNA undefined)

  • Tighten inverted smoke canaries: assert the expected [FAIL] marker text (skipped on ... should run / missing post-exit sidecar) alongside wrapper exit 1, so a canary that dies for the wrong reason does not satisfy the gate

  • exit_pre sidecar witness SHIPPED as examples/exit-pre-sidecar/ — 5.1+ handlers.exit_pre writes $BDT_SMOKE_SIDECAR; harness --expect-sidecar + sidecar_contains=exit_pre-ok after process exit; 4.5 SKIP min_version 5.1; --force-run is AttributeError; --silent-handler / --no-handler missing sidecar; --wrong-text / --write-in-main / --atexit-instead wrong contents

  • N-gon / unapplied-scale / coincident-vert pathology witnesses SHIPPED as examples/ngon-triangulate/, examples/unapplied-scale-gltf/, examples/coincident-vert-weld/ — two-stage pre-assert then handling; no gallery stills (defects not thumbnail-legible); --no-dissolve / --identity / --no-duplicate red on detection; --skip-triangulate / --bake / --weld red on handling

  • Overlapping / mirrored UV islands as a shipped pathology (not lightmap --falsify): SAT hits matching a constructed overlap, then glTF TEXCOORD survival. Deferred — lightmap-uv-channel already owns the zero-overlap gate.

  • Vendor CC0 asset fixtures (Kenney, Quaternius, ambientCG only — no aggregators) as .glb not .blend, with per-fixture provenance records mirroring the Free-Game-Dev-Assets frontmatter schema. Permitted only where the assertion is an invariant over the fixture rather than a measurement of it. Deferred pending a decision on repo weight and CI fetch policy.

  • Falsification flags on shipped examples (Phases 6–8 --skip-delete / --unpair-* / --bypass, Phase 9 --silent-handler / --wrong-text, Phase 10 --no-dissolve / --identity / --no-duplicate) were proven local-Windows only — chat and .scratch, not CI history. Decide later whether a cron should exercise them or whether flags in the scripts are sufficient record.

  • Fleet Pages facelift + examples support RESOLVED differently (2026-07-03): the meta-repo migration was dropped — the fleet template only scaffolds new tools, and each tool's site evolves independently after that. This repo vendored the site build into scripts/site/, redesigned landing + gallery as the Blender-viewport system (see docs/gallery/DESIGN_NOTES.md), added the examples grid, nav link, and full hero stats locally. scripts/build_gallery.py and examples/gallery.json are now permanent, not a prototype awaiting lift-and-shift.

  • modal-operators skill -- invoke returning RUNNING_MODAL, the modal() event handler, modal cancellation patterns

  • usd-pipelines skill -- USD export options, evaluation_mode, instancing, the USD vs glTF tradeoffs

  • mathutils-patterns skill -- mathutils.Vector, Matrix, Quaternion, common transforms, the @ operator

  • Blender 5.2 LTS sweep SHIPPED as targeting + smoke matrix (5.2 + 4.5 on PRs, 5.1 weekly) plus examples/gn-modifier-inputs/ — NodesModifier dict assignment raises TypeError on 5.2; RNA mod.properties.inputs.<id>.value is the replacement

  • Additional snippets for asset library scripting, EXR baking, multi-file extensions

  • UV-layer authoring witness SHIPPED as examples/uv-layer-grid/ — create_grid(..., calc_uvs=True) silent no-op without a pre-existing UV layer; closed-form UV fill + explicit assignment fallback; dual-panel render (flat texel (0,0) vs neon checker)

  • Image save-format witness SHIPPED as examples/png-exr-alpha/ — float→PNG is RGBA16 and false-unpremultiplies as if associated-alpha (closed-form err 0.98 at RGB 0.02 / a=1/255); OpenEXR preserves float RGBA; byte→PNG is straight RGBA8; EXR color_mode='RGB' drops alpha

  • Attribute domain witness SHIPPED as examples/attribute-domain-shear/ — POINT vs CORNER semantics on an 8-wedge pinwheel with one shared hub: CORNER authoring exact (hub corners disagree by face, err ≤ 1e-6), naive per-wedge POINT loop shears to the last write at hub + ring verts, measured deviation == palette closed form (0.751031); byte-identical on 4.5.11 and 5.1.2; crisp-vs-smeared dual pinwheel still — companion to color-attribute-wheel

  • Light-linking collection witness SHIPPED as examples/light-link-studio/ — the API is obj.light_linking on the light OBJECT (ld.light_linking is an AttributeError on both versions); linked ratio 4.0x at projected-center luminance samples, unlink raises the decoy 244–251% with 0.0% hero drift in the same two-render check; EEVEE Next honors linking too (5.5x on 4.5.11, 5.9x on 5.1.2), Cycles pinned for deterministic samples

  • VSE sequences-to-strips witness SHIPPED as examples/vse-cut-list/ — .sequences removed on 5.x (4.5 bridges to .strips), new_effect end kwarg frame_end= (4.5) vs length= (5.x), frame_final_* deprecated in favor of left_handle/right_handle/duration, TRANSFORM effect type removed, GAMMA_CROSS clamps to the source overlap, effect strips consume inputs only when stacked above them, same-scene scene strips render transparent; save/reload round-trip + tiny-render pixel witness. 5.2 COLOR width/height bake (not in the python_api notes) taught in skills/vse-python/; the example --check-pixels path is the witness (set scene resolution before new_effect)

  • glTF export round-trip witness SHIPPED as examples/gltf-export-roundtrip/ — export_yup bakes (x,y,z)→(x,z,−y) into vertex data with no node rotation (probed identical on 4.5.11 and 5.1.2), export_apply ships the evaluated mesh (one disk vertex per evaluated loop), TEXCOORD_0 is V-flipped on disk, per-triangle material bindings survive; exporter/importer RNA signatures byte-identical between 4.5.11 and 5.1.2 (guarded against future renames); Mesh.calc_normals() removal on 5.x surfaced during authoring

  • LOD decimate chain witness SHIPPED as examples/lod-decimate-chain/ — Decimate COLLAPSE evaluated through the depsgraph is non-destructive (obj.data keeps closed-form counts), evaluated tris hit ratio × base within 5% (measured 0.0–0.44%), silhouette bbox survives within 1e-3 (measured 7.7e-6); a stacked Decimate halves the effective ratio, an aggressive 0.02 ratio collapses the nose tip — both caught failure modes

  • Vertex weight limit witness SHIPPED as examples/vertex-weight-limit/ — the 4-influence engine cap enforced via the data API (v.groups + VertexGroup.remove + renormalize); unit sums (measured 3e-8), pose preserved (4.9e-3), exact LBS from the mesh's own deform layer (2.7e-7), Root mount pinned

  • Triangulate + tangent-space witness SHIPPED as examples/triangulate-tangents/ — calc_tangents aborts on any ngon (back cap must be an explicit fan); mikktspace matches the edge/UV-delta formula within welding tolerance on smooth fields (2.3e-6 measured); planar UVs on a cylindrical wall collapse tangents onto normals (dot 0.998); MeshUVLoopLayer handle dangles across calc_tangents() on 4.5 (471 phantom flips, silent exit 0) while the mikktspace math is byte-identical on 4.5.11 and 5.1.2

  • UV-handle lifetime snippet: re-fetch attribute/UV layers by name after any CustomData-reallocating call (calc_tangents, VertexGroup.add, modifier edits) — held handles dangle silently on 4.5, survive by luck on 5.1 (found authoring triangulate-tangents; confirmed harder authoring lightmap-uv-channel: iterating a held MeshUVLoopLayer.data after edit-mode UV ops segfaults 4.5.11 headless, EXCEPTION_ACCESS_VIOLATION 5/5, survives on 5.1.2)

  • glTF skinned-mesh export witness: follow-up to gltf-export-roundtrip + vertex-weight-limit SHIPPED as examples/gltf-skin-roundtrip/ — skins[0].joints names every bone, JOINTS_0/WEIGHTS_0 with unit sums (3e-8), weights bit-exact, rest matrices to 2.4e-07, deformation to 4.8e-07; exporter welds duplicate loops (sorted-multiset comparisons mispair — compare by rest-key); unparented skinned meshes make the exporter bind an armature by name

  • Degenerate-bevel weld hazard SHIPPED as examples/degenerate-bevel-weld/ — at offset == min_dim/2 the bevel band collapses to exactly 12 zero-area faces (4 min-axis edges × 3 segments) with 16 coincident verts (4 × (segments+1)) and min_area down 3.2e5×; a stdlib GLB re-parse counts 32 degenerate triangles crossing the export boundary (MEASURED regression constant) versus 0 for the safe mesh — the loops an engine merge-by-distance welds; byte-identical on 4.5.11 and 5.1.2

  • Modular kit snap witness SHIPPED as examples/modular-kit-snap/ — tiling corridor segment: 16 boundary verts on x ∈ {0, TILE} within 1e-6 m, end rings coincident under the tile offset (nearest-key match), linked-duplicate joint deviation 0.0, shell bbox == declared tile (dev 0.0), manifold except the 16 open-end edges, 20 detail parts contained inside the tile; unsnapped probe (3 mm skew, 2 mm nudge) fails at exits 3/4 with measured errors; sorted-zip ring matching mispairs displaced verts — match by nearest key (authoring hazard, fixed); byte-identical on 4.5.11 and 5.1.2

  • Lightmap UV channel witness SHIPPED as examples/lightmap-uv-channel/ — two-channel UV contract on a market cart: per-part UVMap/UVLight with active/active_render re-asserted after the ops (edit-mode UV ops clear both flags; uv_layers.new() never moves them), UV0 drift 0.0 (clobber trap measured 2.068), every UV1 loop in [0,1], 0 overlapping islands via independent binned strict-SAT (15 hits when falsified), min island distance 0.00401 vs nominal margin 0.002 (MARGIN_DIV × 0.01 semantics measured live); held MeshUVLoopLayer.data after edit-mode UV ops segfaults 4.5.11 (5/5, EXCEPTION_ACCESS_VIOLATION), silent no-op pack without prior unwrap; byte-identical on 4.5.11 and 5.1.2 (3680 islands)

  • Socket attach-point witness SHIPPED as examples/socket-attach-points/ — named SKT_ empties as the spawn contract on a survey drone: 7 socket world matrices within 1.788e-07 of the authored transform with orthonormal right-handed bases (Gram 3.576e-07, det err 2.980e-07), socket +Z == the mount pad's Newell normal (1.794e-07) by a quaternion-swing construction independent of the Gram-Schmidt basis, origin on the mount-face centroid (6.687e-08), documented up-axis fallback for the +Z/−Z mounts, module seating offset exactly 0.0 with strictly identity local matrices, rigid invariance under a re-pose (2.384e-07); transform_apply on an Empty root preserves world matrices (2.235e-07) but clears 7/7 matrix_parent_inverse and pushes the root scale down into every child (0.35 for an applied 1.35) — both halves asserted; a child left selected during the apply drifts sockets 2.335 m; bm.normal_update() does not fix inward winding (recalc_face_normals does — the lofted fuselage rendered as a flat white panel); no-parent-inverse probe jumps 0.690128 m; byte-identical on 4.5.11 and 5.1.2

  • Vertex-colour AO witness SHIPPED as examples/vertex-color-ao/ — baked occlusion in a colour attribute on a stone village well, checked against a closed form rather than a captured value: the cosine-weighted hemisphere integral for an infinitely wide wall of height H at distance d is AO = 1 − ½(1 − 1/√(1+k²)), k = H/d, matched to 6.760e-04 across k = 60.0…0.60 (gate 2.5e-03, QMC noise ~1/√n at 4096 samples); unoccluded plate bakes to exactly 1.0; strictly monotone 0.508301 → 0.928467; asset values in [0,1] with spread 1.0; BYTE_COLOR is sRGB-encoded 8-bit, not linear (0.735 → 0.7379107, peak round-trip error 3.782e-03, matching an independent encode/quantise/decode model to 3.189e-07) while FLOAT_COLOR is exact; both survive depsgraph evaluation at deviation 0.0; bmesh.ops.bevel offsets along cached face normals and flips outward past 90° of staleness (12 mm below ground on a ring of boxes, fixed by normal_update()); point-domain AO needs subdivision or the crevice gradient never reaches the attribute; color_attributes enumeration order differs between 4.5.11 and 5.1.2 — look up by name; byte-identical on 4.5.11 and 5.1.2 (6966 verts)

  • High-to-low tangent normal bake SHIPPED as examples/bake-normal-high-to-low/ — Cycles CPU type='NORMAL' cage bake onto a DECIMATE COLLAPSE hatch; statistical gates (detail frac 0.7211 / MAD 0.09356 vs flat 0.0000 / 0.00277); --flat-source exits 5; RNA identical on 4.5.11, 5.1.2, 5.2.1; byte-identity is not the contract

  • UV atlas utilization witness — coverage/wasted-texel closed forms for a packed lightmap atlas (the non-overlap, unit-square, margin, and active/active_render contracts shipped in lightmap-uv-channel; utilization is the remaining unbuilt slice of the old "UV atlas pack" candidate)

  • VSE use_linear_modifiers removal SHIPPED as examples/vse-linear-modifiers/ — bool on 4.5.11 and 5.1.2, AttributeError on 5.2.1; --assume-present red only on 5.2; pathology, no gallery still

  • GN Compare / Random Value socket identifier rename SHIPPED as examples/gn-socket-rename/ — A_INT / Min_001 present on 4.5.11 and 5.1.2, absent on 5.2.1; enabled-name lookup wires all three; --legacy-ids red only on 5.2

  • Evaluated mesh datablock evaluated_get().data.name is generic Mesh on 4.5.11 and 5.1.2 and equals the source name on 5.2.1 (to_mesh().name stays the source name on all three) SHIPPED as examples/eval-mesh-datablock-name/ — evaluated_get().data.name is Mesh on 4.5.11 and 5.1.2, SourceMesh on 5.2.1; to_mesh().name stays SourceMesh on all three; --assume-distinct-names red only on 5.2; pathology, no gallery still

  • MeshAutomaskingSettings move: old Brush automasking attributes gone on 5.2 SHIPPED as examples/mesh-automasking-settings/ — type absent on 4.5.11 and 5.1.2, present on 5.2.1; old Brush attrs gone; --assume-brush-attrs red only on 5.2; pathology, no gallery still

  • GAMMA_CROSS blend-curve witness SHIPPED as examples/vse-gamma-cross/ — the cross blends in a gamma-0.5 space: ((1-t)·√A + t·√B)² with t = (frame − start)/duration, never 1 inside the effect; mid-cross dips 0.115 below the sRGB lerp from crimson/teal (closed form (0.341, 0.349, 0.463) confirmed per frame); AgX-default sampling poisons the fit (0.146 red-channel error, view_transform='Standard' mandatory); deleting a consumed input orphans-and-deletes the effect — follow-up to vse-cut-list

  • Falsy bpy_prop_collection trap snippet: an empty collection is falsy, so editor.strips or editor.sequences silently falls through to the legacy accessor on an empty timeline — always branch on hasattr; likely generalizes across the API (found authoring vse-cut-list)

  • Collision compound witness SHIPPED as examples/collision-hull-proxy/ — game-prop collision as a compound of convex pieces, each a bmesh.ops.convex_hull of a coarse sec(π/n)-inflated cage (containment 4.4e-08, watertight, positive signed volume, Euler 2, per-piece 255-face budget: body 70, caps 60×3, compound 250); a hull of the dense render mesh measures 380 faces — over budget — which is why pipelines hull cages; proud details cost cage rows, concave grooves are free; byte-identical on 4.5.11 and 5.1.2

  • Custom-normals / shade-by-angle witness SHIPPED as examples/custom-normals-shade/ — the post-4.1 shading contract: use_auto_smooth/use_custom_normals/calc_normals are AttributeError on BOTH 4.5.11 and 5.1.2; set_sharp_from_angle sharp sets match an independent dihedral recompute exactly (188/388 edges, 3 meshes); evaluated normal welds/splits exact (0.0 dev); custom split normals survive depsgraph evaluation within int16 quantization (1.407e-04, not float-exact); divergence: the legacy shade_auto_smooth operator CANCELS headless on 4.5 ("Asset loading is unfinished", mesh untouched, no exception) while 5.1 FINISHES with the Smooth-by-Angle NODES modifier — the data API is the portable path

  • Sky Texture / sun_elevation witness SHIPPED as examples/sky-texture-sun-elevation/ — World ShaderNodeTexSky → Background; sky_type is NISHITA on 4.5 and MULTIPLE_SCATTERING on 5.1 (NISHITA gone); dust_density is 4.5-only (aerosol_density on 5.1); zenith EXR rise 8°→55° measured 2.25x (5.1.2) / 1.50x (4.5.11), gate ≥ 1.25; dual-elevation gallery diptych

  • Grease Pencil Line Art contour witness SHIPPED as examples/gp-lineart-contour/ — GPv3 + modifiers.new(..., "LINEART"); source_object clear → 0 strokes; contour+crease off → 0; restore recovers 10 strokes / 34 points on 4.5.11 and 5.1.2; thickness is 4.5-only (AttributeError on 5.1; portable radius)

  • Camera DOF + focus_distance witness: cam.dof.use_dof, focus plane vs defocus variance on high-freq cards (Stage deviation — depth needs background content)

  • Volumetric scatter optical-depth witness: Volume Scatter density → Beer–Lambert transmittance along a known path (Cycles; Stage deviation)

  • Freestyle SVG / line-set witness: Freestyle line set on a silhouette (full render pass; prefer Line Art first)

  • prop-origin-transform witness SHIPPED as examples/prop-origin-transform/ — origin to base center + data-API scale apply + matrix_parent_inverse for a bolted accessory; scale (1,1,1), local min.z==0, world AABB delta 0, bare jump ~0.43 m, MPI err ~3e-8; stale matrix_world until view_layer.update(); byte-identical on 4.5.11 and 5.1.2

  • Goldberg polyhedron topology witness SHIPPED as examples/soccer-ball-goldberg/ — soccer ball as a truncated icosahedron: bmesh icosphere cut at 1/3 per edge, faces ordered by link-topology walks; closed forms 60/90/32 + Euler 2, census 12×5+20×6, uniform degree 3, edge dev 6.5e-06, planarity 1.9e-06 (independent Newell normal), circumsphere dev 9.0e-06, panels bound by face vertex count (enumeration-order probes exit 13); float32 noise floor ~9e-6 → 3e-5 gates; byte-identical on 4.5.11 and 5.1.2

  • Mirror-modifier symmetry witness: half-model completed by Mirror evaluated through the depsgraph SHIPPED as examples/car-mirror-symmetry/ — generic hatchback loft (14 stations × 9-point half-rings); datablock keeps the half (126/231/106, 28 centerline), evaluated is exactly 2n−c (224/434/212), watertight Euler 2, ±X partner dev 0.0; wheels/lamps mirror about origins parked on the plane; probes: merge off → 252 (exit 5), centerline off-plane → 27≠28 (exit 4), axis off → 126 half-car (exit 5), applied → exit 3; byte-identical on 4.5.11 and 5.1.2

  • Chess-piece lathe witness: a turned piece (rook/pawn) via Screw modifier or bmesh spin from an authored profile — evaluated verts == profile × steps (minus pole merges), ring radii match the profile closed form, axis of revolution exact

  • Dice-pair per-face witness: material/attribute assignment driven by face normal direction, opposite-faces-sum-to-7 as an independently computed invariant, pip placement from a closed-form lattice

  • Bicycle-wheel radial witness: spokes via radial Array with object offset — exact angular spacing, spoke count, hub/rim concentricity, every evaluated spoke endpoint on its computed rim coordinate

  • mesh-hygiene-audit witness SHIPPED as examples/mesh-hygiene-audit/ — engine-ingest topology checklist on a stepped street electrical pedestal: no ngons, no loose verts, manifold edges (exactly 2 faces), no zero-area faces (min_area printed), positive signed volume, Euler V−E+F==2 (24/44/22, volume 0.989248); byte-identical on 4.5.11 and 5.1.2; dual-panel dirty vs clean still

  • Gallery framing recomposition worklist DRAINED: all four recomposition cases restaged and gated with check_framing — depsgraph-export (0.984x/touch→0.812x; cube+dome recentered, aim-based camera), vertex-weight-limit (touch B→0.867y; more frontal camera, lower aim, base in frame), triangulate-tangents (0.334x→0.833y; 2x-class move-in plus Key/Glint trim that also cleared a pre-existing dome blowout), text-version-stamp (0.663x→0.719x; moved in with aim on the stamp center, dead third gone). The seven marginal cases were camera-nudged in the preceding sweep; deviations documented in #108 (damped-track-aim, wave-displace); sky-texture-sun-elevation is a measurement artifact (world subject — report-only if wired). Remaining: nothing on the framing worklist — future examples inherit the gate at authoring time.

Asset sheets committed before 2026-07-25 are not comparable

The neutral asset-sheet harness sized its camera from the subject's bounding box diagonal, which cropped tall subjects and shrank wide ones, so panels in one sheet were at different effective scales. It now solves the required distance from the real field of view on both axes. Sheets committed before this fix (modular-kit-snap, lightmap-uv-channel) show mis-scaled panels and must not be cited as evidence for or against an asset; re-render them if that comparison is ever needed.

Asset-quality survey worklist (measured 2026-07-24, gallery_asset_quality floors)

Full-gallery floor survey after the gate landed (feat/asset-quality-gate). 26 of 42 examples pass all floors. The 14 below-floor entries, with measured numbers — every one is a contract-vehicle or display subject (testcard TV, VSE monitors, text bars, swatch/display rigs, single honest primitives), not a game asset meant for reuse, so none is a remodeling mandate; the floors exist to catch future asset-type examples at authoring time. Two non-mesh subjects (curve-bevel-arc, grease-pencil-rosette) are not measurable by the floors (curve/GP data, no mesh hero). Re-survey after any example remodel.

  • naming (default datablock names): gltf-skin-roundtrip (3 parts), gn-sdf-remesh (Torus), turntable (Suzanne)
  • materials (multi-part, single material): armature-bend (3 parts/1 mat — vertex-color weight bands are the honest display), degenerate-bevel-weld (2/1), driver-wave (16/1, also edge90 1.0), shape-key-blend (3/1, also edge90 1.0)
  • edge90 (raw right angles, 1.0): depsgraph-export (also naming + materials), image-pixels-testcard, png-exr-alpha, temp-override-join, text-version-stamp, vse-cut-list; vse-gamma-cross at 0.92
  • reference: gallery best-modeled measure collision-hull-proxy 0.044, custom-normals-shade 0.288, vertex-weight-limit 0.150, lod-decimate-chain 0.019; calibration details in docs/VISUAL-STYLE.md § Asset quality

Future (uncommitted)

  • Asset library and asset browser scripting skill
  • Cycles vs EEVEE Next render API skill
  • Geometry Nodes 5.x feature parity (volumes, fields)
  • Animation rigging from Python (constraints, drivers across bones)