Skip to content

t1k:unity:base:placeholder-visuals

FieldValue
Modulebase
Version5.116.6
Effortmedium
Tools—

Keywords: demo, greybox, placeholder, POC, primitives, prototype scene

/t1k:unity:base:placeholder-visuals

Placeholder 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.

Use it when…Skip it when…
Building a vertical slice / POC / prototypeShipping production with final art
Art team is downstream of gameplaySynty/asset packs already wired and proven
You need to verify gameplay loops before committing to artThe demo already has all the validation rows green
Demoing a new system in isolationThe 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)”
  1. Primitives only — GameObject.CreatePrimitive(PrimitiveType.{Quad,Cube,Capsule,Cylinder,Sphere}). No 3D models, no Synty.
  2. URP shaders — Universal Render Pipeline/Unlit (2D / side / iso) or Universal Render Pipeline/Lit (3D). No custom shaders.
  3. 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).
  4. Tool menu pair — Tools/{DemoName}/Create All Prefabs + Tools/{DemoName}/Setup Scene. Always re-runnable.
  5. Idempotent destroy-by-name scene setup — re-running setup MUST pick up authoring field changes. Never if (exists) return — always destroy and recreate.
  6. 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.
  7. 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).
  8. Authoring components attached at prefab-creation time — instance.AddComponent<XxxAuthoring>() then PrefabUtility.SaveAsPrefabAsset so 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.

GeneratorWhat it makesOutput pathNaming
Character/unit sprite generatorStickman silhouettes — hero, enemy variants, bossSprites/Stickman/Stickman_{Role}_{Variant}.png (Hero, Enemy_LightningArcher, Boss_StormcallerZephyrix)
Item icon generatorWeapon/armor/accessory/consumable icons, rarity-tintedSprites/Items/Item_{Era}_{Name}.png (Item_Modern_SteelBlade, Item_Modern_ArcCoat)
Currency icon generatorSoft + hard + special currency iconsSprites/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):

  1. 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.
  2. 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.
  3. 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.
  4. Placeholder squares in top HUD for currencies (now fixed with currency icons).
  5. 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.

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”.

The generator outputs become the swap-in surface for the artist. When real art lands:

  1. Artist drops new PNG into the same folder with the same filename.
  2. Sprite import settings already match (pixels per unit, filter, format).
  3. Demo immediately picks up the new art — zero code change.
  4. Delete the generator OR keep it for regenerating on schema change (new era, new rarity tier).
Anti-patternFix
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 siteCentralize 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 PNGs64×64 to 128×128 PNG, point filter, no compression, mode RGBA32 — keeps repo small and pixel-art-feel
Generator hardcodes color listRead tints from the same CSV / RarityTint SO chain the runtime uses

Pick the matching playbook for the demo’s perspective. Full details in references/perspective-playbooks.md.

PerspectiveBody primitiveCameraShaderNotable
3D (BattleDemo)Capsule/Cylinder/Sphere + mesh-child pivotPerspectiveURP/LitLODGroup + Impostor fallback
2D top-down (BattleDemo2D)Quad XZ-planeOrtho top-downURP/Unlit cutoutAlpha-clip 0.5
2D side-view (RushTank, BattleDemoSideView)Quad XY-planeOrtho -ZURP/UnlitTank rolls, world scrolls
Isometric (BattleDemoIso)Quad + billboard shaderPerspective 30° tiltBillboard shaderAuto-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.
  • 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”).
  • 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 Scene builds 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 via SerializedObject — Inspector should show zero None (...) slots after Setup Scene.
  • P0-D3 Scene + prefab assets committed. Scenes/ and Prefabs/ 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-patternWhy 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 quadsFails P0-A3. Player can’t tell what’s foreground vs background.
All enemies same Quad + same red material with only stat differencesFails P0-A2. Player can’t strategize. Add multi-part silhouettes.
Single-quad player avatarFails P0-A1. Compose 3+ primitives (body + tracks + turret).
Silent phase transitionsFails P0-C2. Add a RushTankPhaseBanner-style overlay watching the phase singleton.

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.

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:
    1. HP-bar HealthBarAuthoring.Offset MUST 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 at unit.position + (0, Offset, 0). When a demo’s placeholder sprite-on-quad unit lifts its quad’s local position by scale * 0.5f so feet sit at root Y=0 (the canonical pattern documented elsewhere in this skill), the quad’s head TOP lands at root Y = scale. A fixed Offset = 1.2f then puts the HP bar AT chest level on a scale=4.4 unit — visually inside the body, not above the head.

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 PuzzleVisualConfig ScriptableObject wired to its GridSyncBase subclass. 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

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: ScreenCapture in Play mode per t1k-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.