t1k:unity:base:placeholder-visuals
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | medium |
| Tools | — |
Keywords: demo, greybox, placeholder, POC, primitives, prototype scene
How to invoke
Section titled “How to invoke”/t1k:unity:base:placeholder-visualsPlaceholder Visuals — Playable Demos Without Art Assets
Section titled “Placeholder Visuals — Playable Demos Without Art Assets”Build complete, validated, playable demos using only Unity primitives + URP shaders + procedural materials. Replace any placeholder with a real asset later without touching gameplay code — visuals are decoupled by design.
SSOT for the pattern audit + per-perspective playbooks: references/. Treat the Playability Validation Checklist below as a release gate — a demo that fails any P0 row is not playable.
When to use
Section titled “When to use”| Use it when… | Skip it when… |
|---|---|
| Building a vertical slice / POC / prototype | Shipping production with final art |
| Art team is downstream of gameplay | Synty/asset packs already wired and proven |
| You need to verify gameplay loops before committing to art | The demo already has all the validation rows green |
| Demoing a new system in isolation | The visuals issue is “make art prettier” — not “make game playable” |
Core pattern (universal across 22 demos audited — 14 RPG + 8 Puzzle, 260520-R5)
Section titled “Core pattern (universal across 22 demos audited — 14 RPG + 8 Puzzle, 260520-R5)”- Primitives only —
GameObject.CreatePrimitive(PrimitiveType.{Quad,Cube,Capsule,Cylinder,Sphere}). No 3D models, no Synty. - URP shaders —
Universal Render Pipeline/Unlit(2D / side / iso) orUniversal Render Pipeline/Lit(3D). No custom shaders. - Procedural materials saved to
.mat—GetOrCreateMaterial(name, color)writes once, reuses on re-runs. Naming{Category}_{Subject}.mat(e.g.Item_MGCannon.mat,Enemy_ScrapRunner.mat). - Tool menu pair —
Tools/{DemoName}/Create All Prefabs+Tools/{DemoName}/Setup Scene. Always re-runnable. - Idempotent destroy-by-name scene setup — re-running setup MUST pick up authoring field changes. Never
if (exists) return— always destroy and recreate. - Partial-class file split — keep every file under 200 lines. Split by responsibility:
.cs(entry),.SubScene.cs(ECS authoring),.UI.cs(canvases),.UI.HUD.cs,.UI.Shop.cs, etc. - Color-as-identity — rarity tints (Common=grey, Rare=blue, Epic=purple, Legendary=gold), team tints (red/blue), archetype tints (scrap=orange-red, drone=dusty-red).
- Authoring components attached at prefab-creation time —
instance.AddComponent<XxxAuthoring>()thenPrefabUtility.SaveAsPrefabAssetso bakers see the right SerializeField values.
Procedural sprite generators — go beyond primitives for visualization
Section titled “Procedural sprite generators — go beyond primitives for visualization”Primitives + colored materials get you 60% of the way. For the remaining 40% — items, characters, currencies, abilities — generate procedural sprite PNGs. They cost minutes to write and weeks to replace with real art, but they let a designer/playtester recognize what they’re looking at without text labels.
Always pair an editor generator with the demo so visuals can be regenerated idempotently. Designers should never hand-paint placeholders.
The 3-generator pattern
Section titled “The 3-generator pattern”| Generator | What it makes | Output path | Naming |
|---|---|---|---|
| Character/unit sprite generator | Stickman silhouettes — hero, enemy variants, boss | Sprites/Stickman/ | Stickman_{Role}_{Variant}.png (Hero, Enemy_LightningArcher, Boss_StormcallerZephyrix) |
| Item icon generator | Weapon/armor/accessory/consumable icons, rarity-tinted | Sprites/Items/ | Item_{Era}_{Name}.png (Item_Modern_SteelBlade, Item_Modern_ArcCoat) |
| Currency icon generator | Soft + hard + special currency icons | Sprites/Currency/ | Currency_{Type}.png (Gold, Gem, Soul, RealmShard) |
Each generator is a static Editor class with a [MenuItem] entry. Re-runnable. Idempotent. Reads from the same SSOT data files (CSVs / SOs) the runtime uses, so a CSV-driven name change auto-flows to sprite filenames.
Library utility: DOTSCore.Editor.PlaceholderSpriteUtility (com.the1studio.dots-core/Editor/Utilities/) provides canonical drawing primitives, shape generators, humanoid silhouette draws (DrawMeleeHumanoid, DrawRangerHumanoid, DrawMageHumanoid, DrawBossHumanoid, DrawArrow), and I/O helpers. Always call these instead of duplicating in demo Editor asmdefs. Full API: references/placeholder-sprite-utility.md.
Library utility (prefab half): DOTSCore.Editor.PlaceholderPrefabUtility (com.the1studio.dots-core/Editor/Utilities/) builds the 3D side of the same pipeline — capsule-agent and sphere-pickup placeholder prefabs, flat URP/Lit materials via an idempotent GetOrCreateMaterial, and Addressables registration — pivoted at the ground, with the Unity-capsule height trap documented. Full API: references/placeholder-prefab-utility.md.
MANDATORY PRINCIPLE — Icons over text fallbacks
Section titled “MANDATORY PRINCIPLE — Icons over text fallbacks”Whenever a UI element CAN be represented as an icon, USE the icon. Text fallbacks for visual concepts (lock states, currencies, modifier types, skill kinds, rarity tiers, status effects) are NOT acceptable as a final state — they are placeholders that read as “incomplete UI” to the player.
Concrete rule: if a UI cell has an Image component but no sprite assigned, the engine renders a white square. White squares are a 100%-reliable visual TELL that icon-wiring is incomplete. Audit any demo for white squares before declaring UI done.
Symptoms of the anti-pattern (real bugs found in demos):
- Lock-emoji → “LOCKED” red text fallback. Emoji had no font fallback in TMP; was replaced with red text. Correct fix: generate a red padlock sprite, not a text fallback.
- Realm-card modifier rows showing “+50% XpGainMult” with a white-square Image before each row. The Image cells were placed in scene-setup with no sprite assignment; runtime renders them blank. Each
RealmModifierType(XpGainMult, DropRateMult, EnemyHpMult, EnemyDamageMult, CurrencyDropMult, etc.) needs a dedicated icon sprite. - 4 semi-active skill slots all rendering as grey placeholders. No sprites assigned; user can’t tell which slot is which ability. Generate a skill-icon registry parallel to NamedItemRegistry.
- Placeholder squares in top HUD for currencies (now fixed with currency icons).
- Item-text overflow in narrow equipment cells producing “LRRR / Eeee / Caaa” character-per-line wrap. Replace TMP_Text labels with Image sprites resolved by item-id convention.
Audit gate: before declaring any demo UI done, enter Play mode and screenshot every panel. Any white square or text label that could be an icon is a violation. File the icon as a follow-up generator task before claiming “done”.
Why generated sprites > pure colored quads
Section titled “Why generated sprites > pure colored quads”- Silhouette readability — a stickman silhouette reads as “human” instantly; a colored quad reads as “thing”. Crucial for unit-type recognition under combat conditions.
- Rarity affordance — rarity-tinted item icons (Common grey → Legendary gold) communicate value at a glance without tooltip text.
- No placeholder squares in HUD — currency icons fill the empty square slots in top HUD so the player can read
[Gold 47] [Gem 3]not[square 47] [square 3]. This was a real bug found in a demo HUD. - No item-text overflow in equipment grids — item icons in equipment cells avoid the “LRRR / Eeee / Caaa” character-per-line wrap bug when long item names hit narrow cells. Replace TMP_Text labels with Image sprites resolved by item-id convention. Real ChaosForge bug, same date.
Procedural sprite generator pattern
Section titled “Procedural sprite generator pattern”A generator is a static Editor class with a [MenuItem] that walks its item list, draws each sprite (silhouette + 1-2 accent colors — recognizability, not art), writes PNGs, then AssetDatabase.Refresh() + applies sprite import settings. Paste-and-adapt template: references/demo-audit-2026-05-19.md § “Procedural sprite generator pattern”.
When to swap to real art
Section titled “When to swap to real art”The generator outputs become the swap-in surface for the artist. When real art lands:
- Artist drops new PNG into the same folder with the same filename.
- Sprite import settings already match (pixels per unit, filter, format).
- Demo immediately picks up the new art — zero code change.
- Delete the generator OR keep it for regenerating on schema change (new era, new rarity tier).
Anti-patterns for sprite generation
Section titled “Anti-patterns for sprite generation”| Anti-pattern | Fix |
|---|---|
Hand-paint placeholders in Photoshop, drop in Sprites/ | Always write a generator. Regeneration is part of the demo’s reproducibility contract. |
Generator outputs to Sprites/Items/ but runtime loads from Sprites/Item/ (singular/plural drift) | Generator writes a manifest.json listing all generated sprites; runtime SO reads the manifest at edit-time |
Inline Resources.Load<Sprite>("Item_Modern_SteelBlade") at every call site | Centralize in a single ItemIconResolver ScriptableObject — one entry per item, sprite reference assigned via Editor introspection of the generator’s output folder |
| Generator writes BMP / TGA / huge PNGs | 64×64 to 128×128 PNG, point filter, no compression, mode RGBA32 — keeps repo small and pixel-art-feel |
| Generator hardcodes color list | Read tints from the same CSV / RarityTint SO chain the runtime uses |
Perspective playbooks
Section titled “Perspective playbooks”Pick the matching playbook for the demo’s perspective. Full details in references/perspective-playbooks.md.
| Perspective | Body primitive | Camera | Shader | Notable |
|---|---|---|---|---|
| 3D (BattleDemo) | Capsule/Cylinder/Sphere + mesh-child pivot | Perspective | URP/Lit | LODGroup + Impostor fallback |
| 2D top-down (BattleDemo2D) | Quad XZ-plane | Ortho top-down | URP/Unlit cutout | Alpha-clip 0.5 |
| 2D side-view (RushTank, BattleDemoSideView) | Quad XY-plane | Ortho -Z | URP/Unlit | Tank rolls, world scrolls |
| Isometric (BattleDemoIso) | Quad + billboard shader | Perspective 30° tilt | Billboard shader | Auto-rotates to camera |
Playability Validation Checklist (12 P0 rows — release gate)
Section titled “Playability Validation Checklist (12 P0 rows — release gate)”A demo is NOT playable until every P0 row is green. Run this before declaring any demo “done”.
A. World readability (player can see what’s happening)
Section titled “A. World readability (player can see what’s happening)”- P0-A1 Player avatar visible. The player character/tank/unit is on screen at game start, NOT a single colored block — it has a recognizable silhouette built from 3+ primitives (body + tracks + turret, body + cape + head, etc.).
- P0-A2 Enemies visually distinguishable. Every enemy archetype reads at-a-glance from every other. NOT all red squares. Body shape + accent parts (barrel/spike/rotor/turret) per archetype.
- P0-A3 Ground line + horizon backdrop. Scene has at least 3 environment layers: ground bar, distant silhouettes (mountains/walls/objects), sky. NOT a solid-color void.
- P0-A4 Items / pickups visible + distinct. Each item type has a distinct color OR shape. NOT all identical squares.
B. HUD (player knows the game state)
Section titled “B. HUD (player knows the game state)”- P0-B1 HP bar visible. Player HP rendered as a slider with fill + numeric overlay. Updates on damage.
- P0-B2 Phase / objective text visible. Current phase (Arrange, Rolling, Combat, Shop, Won, Lost…) shown as on-screen text. Updates on phase change.
- P0-B3 Currency / resource counters. Scrap / Gold / XP / Cores — whatever the player earns, shown numerically with a label (“Scrap: 47”, not just “47”).
C. Interaction (player knows what to do)
Section titled “C. Interaction (player knows what to do)”- P0-C1 At least one clickable button per active phase. Every screen the player faces MUST have at least one interactive control with a labeled action (“GO ▶”, “REROLL”, “EXIT SHOP”, “NEW RUN ▶”). NOT silent screens that require unknown input.
- P0-C2 Phase-intro feedback. When a new phase starts, the player gets a visible signal — either a transient banner overlay (“ARRANGE — Drag items to tank”) or a clear UI change. NO silent transitions.
- P0-C3 End-state screens. Win and Lose paths each show a dedicated panel with stats + a “New Run” button. NOT just “game ends, scene freezes”.
D. Setup / re-runability (other developers can run the demo)
Section titled “D. Setup / re-runability (other developers can run the demo)”- P0-D1 One-button scene setup.
Tools/{DemoName}/Setup Scenebuilds the entire scene from scratch with zero Inspector touch-ups required. Re-runnable on every commit. - P0-D2 No null SerializeFields after setup. Every
[SerializeField]ref on every authoring/UI MonoBehaviour is wired by code viaSerializedObject— Inspector should show zeroNone (...)slots afterSetup Scene. - P0-D3 Scene + prefab assets committed.
Scenes/andPrefabs/folders are non-empty in git — a demo showing “Implemented” status with empty asset folders is NOT playable. Audit (260520-R4) found 6/23 demos with empty Scenes/Prefabs despite “Implemented” in Demos.md. Source: review-260520-round4-design-placeholder.md §D3
Anti-patterns that FAIL the checklist
Section titled “Anti-patterns that FAIL the checklist”| Anti-pattern | Why it fails |
|---|---|
| Comment in setup code: “user wires refs in Inspector after re-running setup” | Fails P0-D2. The UI never renders because refs are null. This shipped in RushTank — broke the whole demo until fixed. |
Image + Text on the same GameObject (constructed with typeof(Image), typeof(Text)) | Unity rejects — only one Graphic per GO. Use parent panel + child text. |
| Solid-color clear with no environment quads | Fails P0-A3. Player can’t tell what’s foreground vs background. |
| All enemies same Quad + same red material with only stat differences | Fails P0-A2. Player can’t strategize. Add multi-part silhouettes. |
| Single-quad player avatar | Fails P0-A1. Compose 3+ primitives (body + tracks + turret). |
| Silent phase transitions | Fails P0-C2. Add a RushTankPhaseBanner-style overlay watching the phase singleton. |
Pre-flight
Section titled “Pre-flight”Spawning fix agents from Step 7 of references/validation-script.md requires the Agent tool to be in scope.
ToolSearch(query="select:Agent,TeamCreate", max_results=2)If Agent is absent from both active scope and the deferred-tools listing, bail per skills/t1k-team/references/fork-context-bail.md.
Hard rules
Section titled “Hard rules”Full detail: references/incident-history.md. Read it before acting on this topic.
Normative rules kept inline:
- 10. Per-camera culling-mask layer assignment is MANDATORY for sub-camera env geometry. When a demo uses a secondary camera (RT-bound combat strip, mini-map, overlay) with a restrictive
cullingMask(e.g.,cullingMask = 1 << CombatStripWorldLayer), EVERY env tile / backdrop quad / prop built by the scene-setup tool MUST be assigned that layer with a recursive walk: -
- HP-bar
HealthBarAuthoring.OffsetMUST scale with the unit’s quad height — fixed-constant offsets break on every scale bump. The library’s GPU HP-bar renderer (DOTSCore.UI.HealthBarRenderer) draws the bar atunit.position + (0, Offset, 0). When a demo’s placeholder sprite-on-quad unit lifts its quad’s local position byscale * 0.5fso feet sit at root Y=0 (the canonical pattern documented elsewhere in this skill), the quad’s head TOP lands at rootY = scale. A fixedOffset = 1.2fthen puts the HP bar AT chest level on ascale=4.4unit — visually inside the body, not above the head.
- HP-bar
Reference implementation
Section titled “Reference implementation”Assets/Demos/RPG/RushTankDemo/ is the canonical example (prefab creator, scene setup, HUD, environment, phase banner). Other strong references across the 22-demo census (BackpackCrawler, BattleDemo, BattleDemoIso, the puzzle-grid demos): references/demo-audit-2026-05-19.md § “Reference implementation”.
See references/ for: playability-checklist.md (auditor’s worksheet), perspective-playbooks.md (4 perspectives + shader enforcement), demo-audit-2026-05-19.md (22-demo consensus + divergence + reference file list), validation-script.md (how to run the checklist via t1k unity), wire-original-assets.md (recreations: original assets as replaceable slots, committed vs overlay).
E. Puzzle-specific (grid-based demos only)
Section titled “E. Puzzle-specific (grid-based demos only)”- P0-E1 PuzzleVisualConfig exists and is non-null. Every grid-based demo must have a
PuzzleVisualConfigScriptableObject wired to itsGridSyncBasesubclass. NOT per-cell inline color constants. - P0-E2 Grid cell visuals use shared
PuzzleVisualConfig. All visual parameters (cell size, gap, colors, tile sprites) come from the config — zero hardcoded magic numbers inline in cell-creation code. Source: review-260520-round5-extraction-skills.md §C
Visual change notice
Section titled “Visual change notice”A visible change made with this skill (UI, sprites, 3D, shaders, VFX, animation, lighting, scene layout; audio excluded) follows core rule visual-change-discord-notice:
- Capture OLD before the first edit and NEW after the last (screen:
ScreenCapturein Play mode pert1k-unity-editor-cli, windowed or Xvfb only because rendering is needed; 3D, shader, VFX: same-scene frame grab; 2D asset: the file). - Return the paths and a draft Discord post to the orchestrator, which posts; the PR links the post or carries
visual-notice-waiver: <reason>. Logic only: “no visible change”. No capture: “screenshots pending:”, never a fake image.