minhdv-zz/tb-hoidz

Gradient Mapping for Blender

Workflow revision 15. Reply in the user's language. Use the connected Blender MCP and maintained scripts/gm_core.py (version 8+); preserve its mapping algorithm.

Read only what this phase needs

For base mapping, read references/base-api.md and references/reference-quality.md once per available context. Do not load helper source or the full workflow just to discover APIs. Inspect a targeted signature/docstring for undocumented arguments; read only the relevant source function if needed.

references/workflow.md is the extended reference for presets, optional plan keys, QA explanations and historical examples: read relevant sections on demand. SKILL_DIR is this entrypoint's folder. Read references/detail.md only after base approval. Reuse documents already in context unless changed or missing after compaction.

Scope and safeguards

• /tb-hoidz authorizes preparation, planning, zones, base mapping, comparison and QA. Combine a concise plan and palette-assignment notice in the brief opening update, then continue without intermediate confirmation; follow the communication rules below. Stop after the completed base for user approval before detail mapping. Geometry additions require the user's choice of detail, cut method and triangle cost; existing approvals persist.
• Reuse the supplied concept and target, otherwise selected meshes if unambiguous. Ask only for missing inputs. Never invent a concept, replace the asset or import duplicates by default.
• Record bpy.data.filepath at run start as the working save target. Edit the live objects. A changed file starts a new context; an unsaved file requires the user's first save location.
• Every face belongs to a zone; one strip per zone, U collapsed at its center, at least 2 px U/V margins. Combine top-light normals and height, not height alone by default. Use appropriate hard/smooth normals and material response. Preserve geometry during base mapping.
• Store plan, private memberships/evidence, baseline triangles, signatures, QA and exceptions scene-locally. Persistent JSON, image exports and benchmark reports are optional, not default deliverables. save_plan defaults to the skill folder: use explicit writable storage instead.

Communication and preview

Default to minimal chat narration: do the authorized work and internal checks, then report the completed result. Combine the plan, intended palette assignment and any known fallback into one short opening update. During work, avoid routine milestone messages, color tables, QA dumps and repeated preview explanations. Give only brief progress updates required by higher-priority runtime instructions, or report a blocker, required user decision or material scope change promptly.

Keep full evidence, candidates and reports scene-local; return compact tool summaries for decisions. Prefer internal visual inspection when the tool explicitly supports it. If a tool automatically displays images in chat, accept that limitation, use only necessary captures and do not embed those images again in commentary or the final response. Never invent a hidden-preview mode or skip required visual QA to keep the chat quiet. Use one mapped overview by default; additional captures must resolve an uncertainty or verify a meaningful correction.

Finish with one concise report covering the saved file and dirty state, QA outcome, material limitations and pending details. Ask for base approval at the existing checkpoint. If saving or a required check fails, report the actual incomplete state. Minimal narration alone does not establish a speed or token saving.

Base mapping

1. Connect and prepare. Call get_addon_status once and get compact scene facts: working path, meshes, world bounds, face/triangle counts and materials. Batch independent reads. Import helpers from this skill's absolute scripts directory in each Blender call using them. On first import, put that directory first in sys.path, evict gm modules from other paths, reload gm_core, and print its verified path/version once (base-api.md). Later calls import without reloading. Run ensure_palette; include fallback, relink or material creation in the final report unless it needs a user decision now. Ask before updating a differing team palette's skill copy. The opening update covers palette assignment before prepare_model(..., assign_material=True); avoid a separate routine announcement.
2. Identify materials before mapping. In one initial discovery batch where practical, gather parts, bounds, original UV groups and world-space normal summaries for the target objects. Store memberships and evidence privately; summarize only decision-relevant parts. Focus deeper PCA/depth/adjacency checks on ambiguous or mixed parts and representative families, then reuse verified evidence. Additional discovery is allowed for unresolved boundaries. Combine geometric clues with concept position; discovery precedes semantic assignment. Audit uncertain dominant parts before assigning them. A thin bounding box may describe a broad sheet or a diagonal rope: inspect principal dimensions and surface extent plus semantic position. Shape hints are evidence, never material labels. Capture surface_groups(..., uv_seams=True) before overwriting UVs on mixed shells. Verify one representative and matching structure before reusing a rule for repeats. Resolve pane/rim, cavity/surface and wrap/mast boundaries during base. Complete the small-part material gate in reference-quality.md for every part or structurally verified family; small size does not exempt a part. Uncertain assignments require focused discovery before mapping.
3. Plan and assign. Use reference-quality.md for measured or explicitly estimated concept colors, material and value hierarchy. Batch full-safe-V searches with suggest_zone_colors; retain 2–3 candidates and chosen colors privately; emit only a compact tool summary and issues needing a decision. Assign zones from the verified material audit and check unassigned faces and uncertain boundaries before mapping. Do not use a blanket default material to make coverage pass; temporary assignments remain explicitly uncertain until checked. Preserve verified memberships. List missing emblems/planks as future details.
4. Map and compare. Apply the plan, then show_texture(light="FLAT"). Validate palette and preview material before inspecting color; avoid an initial all-pink screenshot. A pre-map image must answer a specific geometry question: use verified plain solid or temporary zone colors. Inspect one comparable 512–640 px overview after mapping. Complete a semantic boundary review of the audited families, including small fittings and interfaces hidden or unreadable in the overview. Use targeted views only where needed. Correct affected objects/zones only and check neighbors. Optional actual-light fitting is for a concrete unresolved mismatch, not a default whole-asset pass. Another capture must resolve an issue or verify a meaningful correction.
5. Final QA and save. Finish planned color and boundary corrections before final QA. During mapping, use compact coverage, boundary and affected-zone checks rather than whole-asset final QA. After the last change, run qa and qa_faces on every target once. A repair prompted by QA invalidates affected results: rerun the whole-object helpers on affected targets, and expand to all users for shared dependency changes; never save using stale QA. Fix failures; inspect and document intentional warnings/exceptions. Verify coverage, margins, active/render UV, actual palette shader links, normals/light and unchanged base topology. Record reference comparison and material-gate outcome separately: data QA does not prove correct material assignment or visual similarity. Do not mark a base fully verified while uncertain assignments remain; record any genuine reference/topology limitation explicitly. Finalize temporary previews, pack the palette, leave texture visible and execute the guarded save in base-api.md. Report saved path/dirty state, pending details and ask for base approval.

Cache and output discipline

• Run state_signature + compare_state once per dependent batch before cache reuse. Missing signatures are unverified. Geometry changes invalidate memberships; UV changes invalidate original-UV evidence. Shared normal/palette/material/transform/light changes expand scope. Refresh signatures after accepted edits. Do not repeat signatures between independent reads in one unchanged batch.
• Keep full parts, face memberships, palette data, candidates and QA in the scene. Return aggregate counts plus at most 12 decision-relevant part rows by default; expand only for a named unresolved region or a user request. Never print the full palette map/strip catalog, candidate list, face/vertex catalog or scene cache. Filter empty apply_plan zones; return mapped face totals and changed strips, not raw helper reports. Final QA output covers every target with failure/issue counts and actionable warnings; retain detailed passing reports privately.
• Emit one MCP result representation: structuredContent when available, otherwise text content. Forward image blocks separately. Do not stringify both duplicate representations or image data.
• Batch independent reads and compatible object operations; keep dependent checks/edits sequential. Avoid unchanged screenshots, scene dumps and connection polling. No token/time savings claims without comparable measurements.

Execution efficiency

• Load the palette map once per execute batch. Cache part_evidence by verified face membership; do not recompute PCA separately for center and size. Batch compatible reads and corrections while keeping decisions reviewable. Preserve the maintained mapping algorithm.
• Before capture, establish image/shader validity, shading, light and framing together. Collect concrete mismatches from the overview and batch independent fixes before verification. For local edits, preserve and verify UV/zone data outside scope and check neighboring boundaries; expand scope for shared dependencies.
• Store lightweight run metrics scene-locally: target/baseline identity, stage seconds, actual tool-call/capture counts and final QA status. Use time.perf_counter() around existing discovery, mapping/corrections and QA/save work; count actual tool calls in orchestration. Add no calls merely to measure. Mark unavailable metrics and distinguish Blender execution time from end-to-end elapsed time. Benchmark only when requested on the same concept/model/initial state, comparing quality as well as time. Do not equate output bytes with token savings.

Saving and recovery

For color/UV edits use session Undo and Blender's existing backup policy; no separate recovery file. Updating the working file is authorized, but filesystem boundaries still apply. Resolve the permitted save route once and reuse it. Prefer the connected Blender tool when permitted. If elevation is required, request it only for the concrete guarded save after QA. Do not rediscover server source or implement raw TCP per run. An approved fallback must use configured live host/port, never a guessed port or a route bypassing denial.

Before geometry edits, save one recovery copy to sibling _backup/<working_stem>_gm_recovery.blend with copy=True; reuse only this skill-owned slot. For that recovery save only, record preferences.filepaths.save_version, temporarily set it to 0, and restore in finally. Do not persist preferences, change working-save policy or remove user backups. Verify authorization and successful recovery save before cutting; stop geometry work if it fails.

Direct bpy edits may leave is_dirty=False: require a successful explicit save operator, matching resulting filepath and post-save dirty check. Preserve rollback state on failure. If visual capture is unavailable, complete data QA, mark visual fidelity unverified and identify the region for live review.