polycount-budget-checker

name	polycount-budget-checker
description	Validate per-mesh and total-scene triangle counts against the pinned budget; flag worst offenders and topology hints without modeling.

polycount-budget-checker

Purpose

Run a focused pass/warn/fail check on per-mesh and total-scene triangle counts vs the pinned budget from glb-mobile-performance-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 glb-mobile-performance-budget is pinned

When not to use

• material validation (use material-quality-checker)
• lighting / composition validation (other quality checkers)
• broad readiness (use blender-scene-quality-checker)
• to fix topology (this skill validates, it does not edit)

Trigger phrases

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

Prerequisites / readiness

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

Input schema

Required inputs

Input	Why it is required
Pinned budget (per-mesh + total-scene caps)	Anchors the check
Mesh list (name + triangle count)	Scope of the check

Optional inputs

Input	Use
Scene scope context	Single product vs environment changes per-mesh expectations
Animation flags per mesh	Skinned meshes have stricter caps

Assumptions to confirm

• Triangle counts are post-decimation (final), not pre-decimation source.
• 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: name, triangle count, vs per-mesh cap, vs total budget contribution, verdict, hint (no edit).

Secondary output

• top-line status (Pass / Warn / Fail) with totals
• worst-offender list (top 1–3 meshes)
• general topology hints (no modeling)

Evidence / caveat output

Runtime status: Not Run | Attempted | Produced | Verified | Failed | Blocked / Not Run
Artifact status: Not Run | Not Produced | Produced | Verified | Failed
Evidence used: <links, paths, logs, or "none">
Limitations: <known gaps>

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 pinned budget from glb-mobile-performance-budget output (or user input).
2. Read mesh list with triangle counts.
3. For each mesh, compute % of total budget consumed.
4. Apply per-mesh cap rules (see references/per-mesh-rules.md).
5. Sum scene triangle count vs total cap.
6. Identify worst offenders (top 1–3 by absolute count).
7. Generate topology hints (advisory only) per references/topology-hints.md.
8. Compute top-line status; flag any Fail.
9. Hand off to blender-scene-quality-checker (broad review) or glb-mobile-performance-budget (re-budget) if needed.

Decision tree

Total triangle count > 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)

Playbooks

Playbook A: Single-product hero (mid-mobile)

Total cap 50K; single mesh ≤ 40K (80% headroom rule); under 4 meshes typical. Fail any mesh over 80%.

Playbook B: Configurator with 5 variants (high-mobile)

Total cap 100K; verify shared geometry; only variant-specific overrides count toward variant budget.

Playbook C: Environment scene (low-end Android)

Total cap 25K; instance heavy meshes (trees, fence posts) so they share geometry; per-instance triangle count = base mesh × N is the scene cost.

Mode handling

Text-only mode

Read counts from scene plan; mark Artifact status: Not Run.

Runtime-ready mode

Read counts from measured scene snapshot; cite tool used. Never upgrade to Verified without recorded measurement.

Blocked runtime mode

Skip rows that depend on measurement; mark explicitly.

Validation checklist

• Pinned budget recorded
• Every mesh listed with triangle count
• Per-mesh % of total budget computed
• Verdicts assigned per mesh
• Worst offenders highlighted
• Topology hints advisory only (no modeling done)
• Top-line status from rows

Pass / Warn / Fail rubric

Verdict	Criteria
Pass	All meshes under per-mesh cap; total under cap with 20% headroom; no single mesh dominates.
Warn	Total within 80–100% of cap; one mesh dominates (>50% of total); skinned mesh near per-mesh cap.
Fail	Total over cap; single mesh over total cap; skinned mesh over per-mesh cap; missing budget.

Failure handling

• Missing budget → refuse; redirect to glb-mobile-performance-budget.
• Mesh count missing → mark Not Run per row; do not fabricate.
• User pushes for "Pass" without checks → restate requirement.

Troubleshooting

Problem	Response
Total over cap	Identify worst offenders; recommend decimation / texture detail trade.
One mesh over per-mesh cap	Recommend split into multiple primitives or LOD.
Skinned mesh expensive	Reduce bone influences per vertex (clamp ≤ 4); reduce bone count.
Hidden meshes counted	Verify export options exclude hidden/disabled collections.

Best practices

• Use total + per-mesh caps together; either alone is misleading.
• Reserve 20% headroom against absolute caps.
• Treat instances as shared geometry; count once, not per-instance.
• Keep this skill narrow.

Good examples

• "Total 38K of 50K cap (76%). Per-mesh worst: shoe-upper 18K (47% of total). All under per-mesh cap. Verdict: Pass with one Warn (shoe-upper dominates)."

Bad examples

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

User-facing response template

Pinned budget: <total triangles cap> | <per-mesh cap>

| Mesh | Tri count | % of total | Verdict | Hint (advisory) |
|---|---|---|---|---|

Total: <N> of <cap> (<%>) | Per-mesh worst: <name> at <count>
Top-line: <Pass / Warn / Fail>
Limitations: <gaps>
Next: blender-scene-quality-checker / glb-mobile-performance-budget

Anti-patterns

• Decimating inside this skill.
• Inventing triangle counts.
• Marking Verified without measurement.
• Mixing material / lighting / composition checks.

Cross-skill handoff

• Pinned budget source → ../glb-mobile-performance-budget/SKILL.md
• Broad readiness review → ../blender-scene-quality-checker/SKILL.md
• Material validation → ../material-quality-checker/SKILL.md
• Lighting validation → ../lighting-quality-checker/SKILL.md
• Composition validation → ../composition-quality-checker/SKILL.md

Non-goals

• Decimate or retopologize.
• Generate topology recipes.
• Replace blender-scene-quality-checker.
• 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