Skip to content

docs: factual corrections in bmesh, depsgraph, headless and addon-scaffolding skills/rules #358

Closed

Description

@TMHSDigital

Several confident statements in agent-facing content are wrong. They train agents on an incorrect mental model even where the recommended practice is fine. Verified by API-doc grep and runtime probes on 5.2.1 LTS / 4.5.11 LTS.

1. always-free-bmesh rationale

  • Files: rules/always-free-bmesh.mdc:2,11-19, claude/blender-rules.md, snippets/bmesh-load-edit-free.py:2, skills/mesh-editing-and-bmesh/SKILL.md:~72.
  • Claim: GC "cannot free the underlying C memory… leaks and eventually crashes Blender", and calling free() on a from_edit_mesh bmesh "double-frees and crashes".
  • Reality:
    • The official BMesh.free() docs say the BMesh "is freed automatically, typically when the script finishes".
    • On 5.2.1, free() on an edit-mode bmesh returned normally, the bmesh re-acquired, and the mesh was intact.
  • Fix: Keep the try/finally practice, but justify it with deterministic release (tracebacks, globals and closures keep wrappers alive) and fail-fast on use-after-free.

2. mesh-editing-and-bmesh

  • :~149 and :~267: float64 into foreach_set "silently writes garbage on some platforms". Probe: it round-trips at float32 precision (max error 1.19e-8). It is correct, just slower.
  • :~130: "Skip [do_unlink] and Blender will refuse to delete". remove(object, *, do_unlink=True) already defaults to True.

3. depsgraph-and-evaluated-data

  • :~67-69,188: each to_mesh() without clear "exhausts memory fast", and "in some 5.x builds… crashes". The docs say the object owns one temp mesh ("To force free it use to_mesh_clear()"), and the crash claim is unsourced.
  • Missing: to_mesh(preserve_all_data_layers=True, depsgraph=dg). Without it, exporters lose vertex groups and other non-display layers. That is the more common real bug.

4. headless-batch-scripting

  • :~36: says the script receives only the args after --. It receives the full argv, which the code then slices.
  • :~204: calls render.render "one of the few bpy.ops calls that work in --background", contradicting :~84.
  • :~71-72: blames a "file dialog" for export_scene.obj failing. It was removed in 4.0.
  • Missing: --factory-startup and --python-exit-code N, which the repo's own smoke harness depends on.

5. addon-scaffolding vs bl-info-migration

  • skills/addon-scaffolding/SKILL.md:~202: "also keep bl_info for 4.5 fallback". With blender_version_min = "4.5.0", bl_info buys nothing; it only matters for 4.1 and older or for legacy-folder installs, as skills/bl-info-migration/SKILL.md:~226 correctly says.
  • skills/bl-info-migration/SKILL.md:~231: says "4.0 or earlier" where it should be 4.1.

Done when

Each item is corrected, claude/ is regenerated, and the PR lists the probe for each runtime claim.

Activity

  1. added a commit that references this issue on Oct 5, 2026
    040e994
  2. TMHSDigital commented on Oct 5, 2026

    @TMHSDigital
    OwnerAuthor

    Closed by #414. One correction to this issue's own text: item 3 claimed exporters lose vertex groups without to_mesh(preserve_all_data_layers=True). Measured on 4.5.11 LTS and 5.2.1 LTS, a default to_mesh() of a subsurfed object keeps its vertex groups, so #414 did not add that warning.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions