feat: add vertex-weight-limit example witnessing the 4-influence skinning cap

[TMHSDigital]

Summary

Third and final example of the "game asset pipeline" arc (after #75, #76): a rigged mech arm — pedestal mount, pauldron, orange armor shells, ribbed flex boots, wrist, claw prongs — with deliberately rich five-bone weight bumps in the boots, pruned to the game-engine max-four-bone-influences cap through the data API.

Contract witnessed

1. Limit-total + normalize without bpy.ops. Each vertex's groups are read, top four kept by weight, the rest dropped with VertexGroup.remove, survivors renormalized. The bpy.ops.object.vertex_group_limit_total context path is unnecessary — and dropping without renormalizing leaves sums at 0.986 (measured 1.438e-02 off unit), a mesh that shrinks under load.
2. The modifier is still exact LBS after pruning — every evaluated vertex equals Σ wᵢ · (pose.matrix @ bone.matrix_local.inverted()) @ rest with weights read back from the mesh's own deform layer (v.groups), not the authoring function (measured lbs_err = 3.0e-07). The weights on the mesh are the contract.
3. Pruning must not damage the pose — evaluated positions pre/post limit held within 0.05 (measured 3.0e-03); Root mount pinned exactly (0.0); pre-limit authoring proven to carry five influences (else vacuous).

Version witness: the vertex-group API (v.groups, VertexGroup.add/remove) is stable between 4.5 LTS and 5.1 — identical measured values on both binaries.

Falsification evidence (temporary breaks in scratch copies, 5.1.2, restored after measurement):

Probe	Break	Exit	Measured
A	limit never applied	4	vertex carries 5 groups after the "limit"
B	dropped but not renormalized	6	weight sums deviate 1.438e-02 from 1.0
C	use_vertex_groups = False	8	evaluated mesh deviates 1.834 from LBS over the limited weights

Visual / contact-sheet gate: vertex-weight-limit-contact-sheet.webp — candidate beside the pinned set (armature-bend, damped-track-aim, bmesh-gear). Per-criterion verdicts: stage darkness ✓, wedge warmth ✓ (pool visible right of subject), subject fill ✓ (fills cell height like the tubes), saturation ✓ (hazard orange + teal ring), thumbnail legibility ✓ (bent mech limb + glowing ring reads at 640×360). Mean luminance: candidate 105.0 vs calibration 139.4 / 100.1 / 143.4 (sRGB luma) — inside the range, not the extreme.

Proven by live run vs inspection:

• Live run, local: check-only exit 0 on .scratch/blender-5.1.2-windows-x64/blender.exe (Blender 5.1.2, hash ec6e62d40fa9) and .scratch/blender-4.5.11-windows-x64/blender.exe (Blender 4.5.11 LTS, hash 4db51e9d1e1e) — identical measured values (verts=1984 pre_max=5 post_max=4 limited_verts=128). Render path exit 0 on both binaries (EEVEE), pixels iterated on this machine (5 drafts: pose, claw, framing, plaque removed). All three probes live on 5.1.2.
• Live run, CI: both smoke series (4.5 LTS, 5.1) on the PR head SHA — see checks below.
• Inspection only: nothing claims otherwise.

Test plan

• Validate (structure/frontmatter), validate-manifest, validate-counts (README substring 26 examples)
• Blender 5.1 smoke — new step runs examples/vertex-weight-limit/vertex_weight_limit.py -- check-only
• Blender 4.5 smoke — same
• Ecosystem drift check; Socket Security checks
• Local binaries used for evidence: .scratch/blender-5.1.2-windows-x64/blender.exe (Blender 5.1.2) and .scratch/blender-4.5.11-windows-x64/blender.exe (Blender 4.5.11 LTS)

Integration: example dir + README, gallery.json entry, plugin manifest, smoke step, top-level README ("Game asset pipeline" category now 3, counts 25→26), generated gallery pages (read character-by-character: card alt and witnesses callout verified full), ROADMAP shipped entry plus restock (triangulate-tangents direction, glTF skinned-mesh export follow-up, degenerate-bevel weld hazard).

🤖 Generated with Kimi Code