polycount-budget-checker

Purpose

Run a focused pass/warn/fail check on per-mesh and total-scene triangle counts vs the pinned budget from mobile-glb-budget (or any other pinned budget). Surface worst offenders and basic topology hints without performing modeling.

Quick start

• read the pinned budget (per-mesh + total-scene)
• enumerate every mesh in the scene plan or measured scene
• compute per-mesh triangle counts vs per-mesh cap
• compute total-scene triangle count vs total cap
• flag worst offenders + give topology hints (no modeling)

When to use

• before render
• before GLB export
• after a mesh change request
• as a sub-check during full quality review
• when mobile-glb-budget is pinned

When not to use

• pinning or negotiating the performance budget itself → use ../mobile-glb-budget/SKILL.md (use mobile-glb-budget)
• material validation → use ../material-quality-checker/SKILL.md (use material-quality-checker)
• lighting validation → use ../lighting-quality-checker/SKILL.md (use lighting-quality-checker)
• composition validation → use ../composition-quality-checker/SKILL.md (use composition-quality-checker)
• broad scene readiness review → use ../scene-readiness/SKILL.md (use scene-readiness)
• classifying render or export artifact evidence → use ../render-export-evidence/SKILL.md (use render-export-evidence)
• fixing topology, decimating, or retopologizing (this skill validates; it never edits or models) → use ../mobile-glb-budget/SKILL.md (this skill validates; it never edits or models)

Trigger phrases

• "is the polycount okay"
• "check triangle budget"
• "what's blowing the budget"
• "topology issue?"

Prerequisites / readiness

• pinned budget known (from mobile-glb-budget or explicit user)
• mesh list known (scene plan or measured scene)

Input schema

Required inputs

Optional inputs

Assumptions to confirm

• The count that matters is the evaluated render mesh (base mesh + full modifier stack at render levels), not the viewport display.
• Every count states its basis (base mesh / viewport / evaluated render mesh); an unknown basis is marked Not Run, never guessed.
• Instances share geometry: count each unique mesh once against the per-mesh cap, and compute base × N callers for the total-scene cost.
• Counts include all visible meshes; hidden / collection-disabled meshes excluded.
• "Triangles" in glTF = primitive triangles after triangulation, not Blender face count.

Output schema

Primary output

A per-mesh row table: mesh name, triangle count, count basis (base / viewport / evaluated render mesh / Not Run), instance count (N), vs per-mesh cap, vs total budget contribution (base × N), validation verdict (Pass / Warn / Fail / Not Run), and advisory topology hint (no edit).

Secondary output

• top-line validation status (Pass / Warn / Fail / Not Run) computed from rows (separate from truth states)
• worst-offender list (top 1–3 meshes by evaluated contribution)
• general topology hints (advisory only, no modeling)

Evidence / caveat output

Runtime status: Not Run | Attempted | Produced | Verified | Failed
Artifact status: Not Produced | Produced | Verified | Failed (default: Not Produced)
Evidence used: <links, paths, logs, or "none">
Limitations: <known gaps, viewport-only caveats, or Scene Simplify notes>

Note: Truth states are downgrade-only (never upgrade). Validation verdicts (Pass / Warn / Fail) are separate from runtime and artifact truth states.

Required laws

• ../../laws/evidence-before-done.md
• ../../laws/non-blender-user-language.md
• ../../laws/no-arbitrary-python-interface.md
• ../../laws/official-runtime-only.md

Official runtime boundary

This skill validates plans or measured scene snapshots. It never decimates, retopologizes, or runs Blender. Hints are advisory.

Operating procedure

1. Read the pinned budget from mobile-glb-budget output (or explicit user input).
2. Read the mesh list, triangle counts, instance counts (N), and stated count basis (base / viewport / evaluated render mesh). If a mesh's count or basis is unknown, mark its row Not Run — never guess.
3. Verify whether counts reflect the evaluated render mesh (base mesh + full modifier stack at render levels, accounting for Subdivision, Multiresolution, Solidify, and Scene Simplify). Flag viewport-only counts as undercounting risks.
4. For each unique mesh, compare its evaluated triangle count once against the per-mesh cap (see references/per-mesh-rules.md).
5. Compute total-scene triangle cost by summing base × N across all instances in the scene, then compare against the total-scene cap.
6. Identify worst offenders (top 1–3 by evaluated count or scene contribution).
7. Generate advisory topology hints per references/topology-hints.md (never model, decimate, or retopologize).
8. Compute top-line validation status (Pass / Warn / Fail) separately from downgrade-only truth states.
9. Hand off rows to scene-readiness (broad review), mobile-glb-budget (budget re-pinning), or render-export-evidence (artifact evidence classification).

Decision tree

Count or count basis (base / viewport / evaluated render mesh) unknown?
  → Mark row Not Run (never guess or fabricate)
Total evaluated triangle count (including base × N instances) > total cap?
  → Fail (whole-scene)
Single mesh > 50% of total cap?
  → Warn (one mesh dominates)
Single mesh > total cap by itself?
  → Fail
Skinned mesh > per-mesh skinned cap?
  → Fail (skinning cost is non-linear)
Hidden / disabled meshes consume budget by accident?
  → Warn (verify exclusion before export)
Counts read at viewport levels while modifiers (Subdivision, Multiresolution, Solidify) render higher?
  → Warn (viewport display undercounts cost; re-read evaluated render mesh)
Scene Simplify enabled at render time?
  → Note in limitations; effective subdivision is lowered so rendered result may be cheaper than modeled

Playbooks

Playbook A: Single-product hero

Use the pinned total and per-mesh caps from mobile-glb-budget. Verify every count states evaluated render mesh basis (accounting for Subdivision, Multiresolution, and Solidify at render levels). Fail any mesh exceeding the pinned per-mesh cap.

Playbook B: Multi-variant configurator

Use the pinned caps from mobile-glb-budget. Verify shared base meshes are counted once per active variant combination, while variant-specific overrides are evaluated per active configuration.

Playbook C: Instanced environment scene

Use the pinned caps from mobile-glb-budget. Instances (such as trees or fence posts) share geometry: validate the unique mesh once against the per-mesh cap, but compute base × N callers for the total-scene triangle cost.

Mode handling

Text-only mode

Read planned counts and stated basis from the scene plan; set Runtime status: Not Run and Artifact status: Not Produced (default). Mark any mesh with an unstated basis as Not Run.

Runtime-ready mode

Read evaluated render mesh counts from the measured scene snapshot and cite the source. Keep validation verdicts (Pass / Warn / Fail) separate from truth states. Truth states are strictly downgrade-only — never upgrade a truth state here; hand off artifact evidence classification to render-export-evidence.

Blocked runtime mode

Do not guess missing or unmeasured evaluated counts; mark affected rows Not Run and record the blocker under Limitations.

Validation checklist

• Pinned budget recorded from mobile-glb-budget
• Every mesh listed with triangle count and instance count (N)
• Count basis stated for every row (base / viewport / evaluated render mesh); unknown basis marked Not Run
• Modifiers with separate viewport/render levels (Subdivision, Multiresolution, Solidify) and Scene Simplify accounted for
• Instances counted once against per-mesh cap and base × N toward total-scene cost
• Per-mesh % of total budget and Pass / Warn / Fail / Not Run verdicts assigned
• Worst offenders highlighted and topology hints kept strictly advisory (no modeling)
• Truth states kept separate from validation verdicts and strictly downgrade-only (default artifact status Not Produced)

Pass / Warn / Fail rubric

Failure handling

• Missing pinned budget → refuse validation; redirect to mobile-glb-budget.
• Mesh count or count basis missing/unknown → mark Not Run for that row; never guess or fabricate.
• User pushes for "Pass" without evaluated counts or basis → restate count-basis requirement and keep Not Run / Warn.
• User requests upgrading Runtime or Artifact truth state to Verified → refuse; truth states are downgrade-only (hand off evidence classification to render-export-evidence).

Troubleshooting

Best practices

• Always pair total-scene and per-mesh caps from mobile-glb-budget; either alone is misleading.
• Reserve 20% headroom against absolute caps.
• Handle instances accurately: instances share geometry (count the unique mesh once against the per-mesh cap), but still compute base × N callers for the total-scene cost.
• Always validate the evaluated render mesh (base mesh + full modifier stack at render levels), never the viewport display, and state the basis on every count.
• Keep validation verdicts (Pass / Warn / Fail) separate from downgrade-only truth states.

Good examples

• "Basis: evaluated render mesh (Subdivision at render level 2). Total: 38K of 50K cap (76%). Per-mesh worst: shoe-upper at 18K (36% of total cap, under 40K per-mesh cap). Instances: lace-eyelet 500 tris × 12 = 6K scene cost. Verdict: Pass."

Bad examples

• "Polycount looks fine." — no numbers.
• "Verified" without measurement.

User-facing response template

Pinned budget: <total triangles cap> | <per-mesh cap> (from mobile-glb-budget)

| Mesh | Tri count | Basis (base / viewport / evaluated render mesh / Not Run) | Instances (N) | Scene cost (base × N) | % of total | Verdict | Hint (advisory) |
|---|---|---|---|---|---|---|---|

Total scene cost: <N> of <cap> (<%>) | Per-mesh worst: <name> at <count> (<basis>)
Top-line verdict: <Pass / Warn / Fail / Not Run>
Runtime status: <Not Run | Attempted | Produced | Verified | Failed>
Artifact status: <Not Produced | Produced | Verified | Failed>
Evidence used: <links, paths, logs, or "none">
Limitations: <gaps, viewport-only warnings, or Scene Simplify notes>
Next: scene-readiness | mobile-glb-budget | render-export-evidence

Anti-patterns

• Decimating inside this skill.
• Inventing triangle counts.
• Counting viewport display triangles and calling it the export cost.
• Marking Verified without measurement.
• Mixing material / lighting / composition checks.

Cross-skill handoff

• [upstream_reference] Pinned budget source → ../mobile-glb-budget/SKILL.md
• [progression] Broad readiness review → ../scene-readiness/SKILL.md
• [progression] Artifact evidence classification → ../render-export-evidence/SKILL.md
• [upstream_reference] Material validation → ../material-quality-checker/SKILL.md
• [upstream_reference] Lighting validation → ../lighting-quality-checker/SKILL.md
• [upstream_reference] Composition validation → ../composition-quality-checker/SKILL.md

Non-goals

• Decimate or retopologize.
• Generate topology recipes.
• Replace scene-readiness.
• Run Blender.

References

• references/per-mesh-rules.md
• references/topology-hints.md
• references/instance-counting-rules.md
• ../../laws/evidence-before-done.md
• ../../docs/skill-system.md