# Theriapolis — Tactical Tile Art Request

This document lists every tactical-scale sprite the engine needs. Tiles are
streamed in-game from a chunked tactical map; placeholder squares stand in for
each tile until you provide the real art.

> **Roadmap note (post-Phase-4 Wang autotiling).** The current renderer uses
> per-tile sprites with a soft *colour-blend* edge softening between dissimilar
> surfaces ("Option B" — see [TacticalRenderer.cs](Theriapolis.Game/Rendering/TacticalRenderer.cs)).
> When the final art set is ready, we plan to upgrade to *full Wang
> corner-based autotiling* ("Option C") using Pixellab's `create_topdown_tileset`
> tool, which produces a 16-tile transition set per terrain pair. At that
> point each terrain *pair* (grass↔dirt, grass↔water, sand↔shallowwater, etc.)
> will need its own 16-tile transition strip, and the per-tile sprites listed
> below become the *base* references the transition tiles blend out to.
> No action needed from artists for that yet — flagged here so the plan isn't
> lost between phases.

## Specifications

- **Resolution:** 32×32 pixels per tile, exactly. The renderer scales each
  sprite to one in-engine "world pixel"; at the camera's tactical zoom
  threshold the sprite displays 1:1, and it upscales (with crisp pixel-art
  filtering) up to ~3.1× at maximum zoom.
- **Format:** PNG, 32-bit RGBA.
- **Surface tiles:** opaque. They tile horizontally and vertically against
  copies of themselves; please design seamlessly so adjacent tiles don't show
  visible joins.
- **Decoration tiles:** transparent background. They composite on top of the
  underlying surface tile, so anything outside the actual prop should be
  transparent (alpha 0).
- **Variants (optional):** if you provide multiple variants for a tile, name
  them `<tile>_0.png`, `<tile>_1.png`, … `<tile>_N.png` (zero-indexed). The
  engine picks one per cell from a deterministic per-tile RNG, so the same
  cell always shows the same variant. If you supply a single `<tile>.png`
  with no suffix, every cell uses it.
- **Style:** chunky, painterly pixel-art is the target. Saturated but earthy
  colors. No outlines on surface tiles; soft outlines OK on decorations.
- **Lighting:** assume a top-down view with diffuse overhead light (no strong
  directional shadow). Decorations may cast a small drop shadow that fades
  into transparency.

## Directory layout

Drop the finished files into the project at:

```
Content/Gfx/tactical/
    surface/
        grass.png
        grass_0.png  grass_1.png  ...   (optional variants)
        dirt.png
        ...
    deco/
        tree.png
        tree_0.png   tree_1.png   ...   (optional variants)
        bush.png
        ...
```

Filenames are lowercase and exactly match the names below.

---

## Surface tiles

Each surface fills an entire 32×32 tile. Decorations and props are NOT part of
the surface tile — those are separate, listed under **Decorations** further
down.

### Grasslands & light vegetation

| Filename | Description |
|---|---|
| `grass.png` | Short, healthy meadow grass — the default ground for temperate plains. Mixed greens with subtle blade detail; should feel like trampled, well-grown turf. |
| `tallgrass.png` | Knee-high grasses and wild herbs, denser and slightly taller than `grass`. Still walkable but visibly thicker; muted yellow-green tones suit late-summer scrub. |
| `dirt.png` | Bare earth, packed and a little dry. Used for trails, worn ground around settlements, and exposed soil at biome edges. |

### Forest floor

| Filename | Description |
|---|---|
| (forest floors reuse `grass.png` and `dirt.png`) | Forest interiors are a mix of these two surfaces with `tree`/`bush` decorations on top — no separate forest-floor surface needed. |

### Mountains, hills, rocky terrain

| Filename | Description |
|---|---|
| `rock.png` | Exposed bedrock, weathered grey with cracks and faint moss in the seams. The default surface for alpine and cliff biomes. |
| `gravel.png` | Loose, small stones mixed with grit. Used for footpaths, dry creek beds, and rocky scree slopes. |

### Wetlands & water-edge

| Filename | Description |
|---|---|
| `marsh.png` | Sodden, half-submerged ground threaded with reedy growth. Dark, mossy greens and standing-water highlights; the default for wetland biomes. |
| `mud.png` | Wet, slick mud — the surface of mangrove flats, riverbanks after rain, and tidal pools when the tide is out. |
| `shallowwater.png` | Wadeable water perhaps an inch or two deep. The bed should be visible through the water, with small ripple highlights on the surface. |
| `deepwater.png` | Open water that the player cannot wade through. Solid blue with subtle wave patterns and no visible bed. Used for river centers, lakes, and the ocean. |

### Desert & dry biomes

| Filename | Description |
|---|---|
| `sand.png` | Fine, wind-rippled sand in pale tan — used for beaches, desert flats, and tidal flats below the high-tide line. The ripple pattern should tile cleanly. |

### Cold biomes

| Filename | Description |
|---|---|
| `snow.png` | Fresh, undisturbed snowpack with a faint blue cast in the shadows. The default for tundra and high-altitude alpine surfaces. |

### Built environment (settlements, roads, interiors)

| Filename | Description |
|---|---|
| `cobble.png` | Rounded paving stones set in mortar — the standard street and plaza surface for towns and cities. Worn smooth in the centers of stones. |
| `floor.png` | Interior wood-plank floor for buildings. Simple straight planks with subtle grain; reads as "indoor" at a glance. |
| `wall.png` | Building exterior wall, top-down view — looks like the top of a thick stone-and-mortar wall, not the side. Used as the perimeter outline of placeholder building footprints. |

---

## Decorations

Decorations sit on top of a surface tile and have a transparent background.
The engine renders them as a single 32×32 sprite centered in their cell.

### Vegetation

| Filename | Description |
|---|---|
| `tree.png` | Single mature tree seen from above — a roughly circular canopy of leaves with a hint of trunk visible through gaps. Color depends on biome but a generic temperate-deciduous green is fine for the base sprite. |
| `bush.png` | A low, broad shrub — smaller and lower-canopy than a tree, walkable-but-slow. Reads as a clump of foliage when seen from above. |
| `flower.png` | A small cluster of wildflowers — a few bright dots of color (pink/yellow/white) on green stems. Decorative only, no gameplay effect. |
| `crop.png` | A patch of cultivated grain or vegetables, neat and orderly compared to wild grass. Used in farmland near settlements. |
| `reed.png` | A tuft of tall water-edge reeds, vertical strokes of green and tan. Sits on `marsh` or `shallowwater` to suggest a riverbank or pond fringe. |
| `snag.png` | A dead, broken tree stump or fallen log — weathered grey wood with no foliage. Adds character to forest edges and old burn scars. |

### Rocks

| Filename | Description |
|---|---|
| `rock.png` (deco) | A small loose stone or two scattered together — clearly walkable around or over. Distinct from the `rock` surface tile (which is bedrock filling the whole cell). Save this in `deco/rock.png` to disambiguate. |
| `boulder.png` | A single large rounded boulder taking up most of the cell. Impassable; the player must walk around it. Add a soft drop shadow on the bottom-right. |

---

## Variant guidance

You don't need to provide variants for everything, but they make the world
look hand-crafted instead of stamped. Highest-impact places to add variants:

- **`grass_0` … `grass_3`** — even slight color shifts dramatically reduce
  the "wallpaper" effect in open meadows.
- **`tallgrass_0` … `tallgrass_2`** — different blade angles and clumping.
- **`dirt_0` … `dirt_2`** — patches of pebbles, faint cart-rut grooves, etc.
- **`tree_0` … `tree_3`** — different canopy shapes/sizes; mix of broadleaf
  and conifer if you want.
- **`flower_0` … `flower_2`** — different flower colors.

Anything else can be a single sprite for now.

---

## Biome reference (which tiles show up where)

This is for context only — you don't need to author per-biome variants. The
engine composites surfaces and decorations dynamically based on the biome of
each underlying world tile.

| Biome | Primary surface | Common decorations |
|---|---|---|
| Temperate Grassland | `grass`, `tallgrass` | `bush`, `flower` |
| Temperate Deciduous Forest | `grass`, `dirt` | `tree`, `bush`, occasional `snag` |
| Boreal Forest | `dirt`, `grass` | `tree` (read as conifer in art) |
| Subtropical Forest | `grass`, `tallgrass` | `tree`, `bush` |
| Forest Edge | `grass` | `bush`, sparse `tree` |
| Mountain Forested | `rock`, `dirt` | `tree`, `rock` (deco) |
| Mountain Alpine | `rock`, `snow` | `boulder`, `rock` |
| Foothills | `grass`, `rock` | `bush`, `rock` |
| Cliff | `rock` | `boulder` |
| Tundra | `snow`, `dirt` | `rock` (deco) |
| Cold Desert | `sand`, `dirt` | `rock` |
| Scrubland | `dirt`, `grass` | `bush`, `rock` |
| Wetland | `marsh` | `reed` |
| Marsh Edge | `mud`, `grass` | `reed` |
| Mangrove | `mud`, `shallowwater` | `tree`, `reed` |
| Tidal Flat | `mud` | (none) |
| Beach | `sand` | (none) |
| Coastal | `grass`, `sand` | `bush` |
| River Valley | `grass` | `bush`, `reed` |
| Settlements (any biome) | `cobble`, `dirt` | (none — buildings come later) |
| Inside buildings | `floor` | (none) |
| Settlement perimeter | `wall` | (none) |

---

## Summary checklist

**Surfaces (14):** `grass`, `tallgrass`, `dirt`, `rock`, `gravel`, `marsh`,
`mud`, `shallowwater`, `deepwater`, `sand`, `snow`, `cobble`, `floor`, `wall`

**Decorations (8):** `tree`, `bush`, `flower`, `crop`, `reed`, `snag`,
`rock` (deco — note the duplicate name; this one goes in `deco/`), `boulder`

**Total minimum tiles:** 22 (one PNG per row above). Variants are bonuses on
top of that.