Vibe-HD-2D/docs/ASSET_GUIDE.md

# Asset guide: pixel art, textures and 3D models

How to make art for this engine, written for humans and AI agents alike.
Everything here is reproducible from scripts in `tools/`; never hand-edit a
generated file without also changing the script that produces it.

## 1. What is pixel art and what is 3D

HD-2D mixes two kinds of art. Pick the right one before making anything.

| Thing | Kind | Where it lives | How it is drawn |
| --- | --- | --- | --- |
| Characters, NPCs, monsters | Pixel-art **sprite** | `assets/sprites/` | `BillboardBatch` (camera-facing card) |
| Small props: flowers, grass tufts, tall grass, signs, pickups | Pixel-art **sprite** | `assets/textures/` | `BillboardBatch` |
| Ground, paths, cliff faces | Pixel-art **tiles** (32 × 32) | `assets/textures/ground_*` | `Terrain` texture array |
| Trees, bushes, rocks, bridges, buildings, fences, braziers | **3D model** with higher-res painted textures | `assets/models/scenery.glb` | `ModelBatch` (instanced) |
| Fire, rain, fog, light, water, sparkles | **Effect**, no asset | shaders / `ParticleSystem` / `Weather` | engine code |

Rule of thumb: if it is smaller than the player or is a character, it is a
sprite. If it is scenery the player walks around, it is a 3D model.

## 2. Units and scale

- 1 world unit = 1 terrain tile = **32 pixel-art pixels**. Keep all pixel art
  at this density so pixels line up (`BillboardBatch::sizeForDensity(32)`).
- Art that was upscaled (e.g. the 256 px test sprite is 64 px art × 4) is drawn
  at `32 × factor` px per unit (`sizeForDensity(128)`).
- The engine is **Y-up**; Blender is **Z-up**. The glTF exporter converts, so
  model in Blender with +Z up and the base of the object at Z = 0.
- Reference sizes (world units): player sprite ≈ 1.5 tall; oak ≈ 5.5 tall,
  canopy ≈ 5 wide; pine ≈ 6 tall; bush ≈ 0.9 tall, 1.6 wide; rock ≈ 0.6 tall;
  bridge deck 17 long, 2.6 wide; cliff step 0.5 high per terrain level.
- High-res model textures: aim for roughly 256–512 texels per world unit
  (1024² leaf cards, 512 × 1024 bark, 1024² stone).

## 3. Pixel art (PixelLab)

All pixel art comes from the [PixelLab API](https://api.pixellab.ai/v2/llms.txt)
through `tools/pixellab.py`, driven by the manifest `tools/assets.json`. The
key is `PIXELLAB_API_KEY` in `.env` (never commit it; `.env` is gitignored).

```sh
python3 tools/pixellab.py --list       # x = file exists
python3 tools/pixellab.py              # generate everything missing
python3 tools/pixellab.py flowers      # regenerate one entry (costs credits)
python3 tools/pixellab.py --balance    # check credits before big batches
```

### Manifest entries

Every key except `kind`, `out`, `pick` and `tile_id` is sent to the API as-is,
so any documented endpoint parameter can be used.

**Sprite** (`"kind": "image"`, default) → `POST /create-image-pixflux`, synchronous:

```json
"lantern": {
  "out": "lantern.png",
  "description": "small iron street lantern on a short post, warm glass, game sprite",
  "image_size": {"width": 32, "height": 64},
  "no_background": true,
  "view": "side",
  "outline": "selective outline",
  "shading": "medium shading",
  "detail": "highly detailed",
  "seed": 40
}
```

- Max 400 × 400. Use sizes that are multiples of 16 and match the 32 px/unit
  density (a 1-unit-tall prop is 32 px tall).
- Always `"no_background": true`; sprites must be transparent.
- `"view": "side"` reads best for billboards (the camera looks from the side
  and slightly above). Enums: outline `single color black outline | single
  color outline | selective outline | lineless`; shading `flat | basic | medium
  | detailed | highly detailed shading`; detail `low detail | medium detail |
  highly detailed`.
- Fix the `seed` so regenerating is reproducible.

**Seamless tiles** (`"kind": "tiles"`) → `POST /create-tiles-pro`, async:

```json
"ground_snow": {
  "kind": "tiles",
  "out": "ground_snow.png",
  "pick": 0,
  "description": "1). fresh snow, soft blue shadows 2). snow with footprints 3). snow over grass 4). icy snow",
  "tile_type": "square_topdown",
  "tile_size": 32,
  "tile_view": "top-down",
  "outline_mode": "segmentation",
  "seed": 14
}
```

- Numbered descriptions give one variation group each; the API returns ~16
  tiles saved as `<stem>_<n>.png` (4 per numbered item, in order).
- After the first run the script prints a `tile_id`; **add it to the entry**
  so later runs re-download for free instead of paying again.
- The storage host rejects default user agents; the script already sends one.
- Use only `square_topdown`, 32 px, `top-down` for terrain.

### Sprite rules the engine relies on

- **Feet on the lowest opaque row.** Billboards are planted by the lowest
  pixel with alpha ≥ 128 (`Texture::opaqueBounds`), so empty space below the
  feet is fine but stray pixels below them make the sprite float.
- **No baked ground shadows.** The engine casts real shadows and draws a
  contact blob under the player. PixelLab sometimes paints a grey ellipse under
  objects; regenerate or erase it (alpha 0) before use.
- Hard alpha (0 or 255) is ideal; soft edges are thresholded at 0.5.
- Sprites face **left** by default; the demo mirrors them when walking right.

### Using pixel art in the engine

- Sprite: `BillboardBatch b; b.loadTexture(path);` then push
  `BillboardInstance{pos, sway, size, flip, tint}` and `b.upload()`.
  `sway` 0 = rigid, 1 = grass-like wind and player push.
- Terrain layer: add the file stem to `kLayers` in `demo/DemoScene.cpp` (all
  layers must be the same size) and reference its index from a
  `TerrainMaterial`.

### Characters and animation (not wired up yet)

PixelLab can make consistent characters with 4/8 directions and animations
(`POST /create-character-v3`, `/characters/animations`, then
`GET /characters/{id}/zip` or `/spritesheet`). To support them, add a new
`kind` to `tools/pixellab.py` (submit, poll `GET /background-jobs/{id}` every
5–10 s until `completed`, download) and a sprite-sheet animation path to
`BillboardBatch` (UV rect per frame). Keep the 32 px/unit density.

## 4. High-resolution textures for 3D models

`tools/scenery_textures.py` paints them procedurally with numpy + Pillow into
`assets/models/src/`:

```sh
python3 tools/scenery_textures.py
```

| File | Size | Used for | Notes |
| --- | --- | --- | --- |
| `leaves_oak.png`, `leaves_bush.png` | 1024² RGBA | canopy cards | cluster of leaves on transparency, **hard alpha** |
| `leaves_dense.png` | 1024² RGB | canopy cores | opaque, tileable leaf mass that fills gaps |
| `pine_frond.png` | 1024 × 512 RGBA | pine branches | stem along +u from the left edge |
| `bark.png` | 512 × 1024 | trunks | vertical fibres, tiles horizontally |
| `rock.png` | 1024² | rocks | grey; moss comes from vertex color |
| `cobble.png`, `stone_blocks.png` | 1024² | bridge deck / walls | Voronoi flagstones, staggered blocks |
| `iron.png`, `coals.png` | 512² / 256² | braziers | coals are emissive |

Guidelines:

- Stylized, saturated, painterly (Dragon Quest III HD-2D / Octopath), not
  photographic. Bake no lighting except gentle large-scale variation; the
  engine lights everything.
- Tileable textures must wrap (use `fft_noise`, which is periodic, or draw
  shapes at ±size offsets like `leaf_dense`).
- Cutout textures: threshold alpha to 0/255 (see `leaf_cluster`); the
  transparent pixels' color is bled from neighbours automatically on load.
- Add a new texture: write a function returning a PIL image, save it in
  `main()`, then reference the file name from a Blender `material()`.

## 5. 3D models (Blender)

`tools/blender_scenery.py` builds every model procedurally and exports
**one** `assets/models/scenery.glb` (textures embedded once, one root node per
model). Run it either way:

```sh
blender -b -P tools/blender_scenery.py                  # headless
```

```python
# inside a running Blender, e.g. via the Blender MCP `execute_blender_code` tool
import os; os.environ["HD2D_REPO"] = "/path/to/repo"
p = "/path/to/repo/tools/blender_scenery.py"
exec(compile(open(p).read(), p, "exec"), {"__name__": "__main__", "__file__": p})
```

It only touches its own `HD2D_Scenery` collection and lays models out side by
side along X for inspection (take a viewport screenshot to check). Re-run
`scenery_textures.py` first if textures changed (and `img.reload()` the images
in a live session).

### Building blocks

- `MeshBuilder.face(points, uvs, colors, normals, material_index)` adds a
  polygon with per-corner data; `build(name, materials)` makes the object.
- Helpers: `tube` (tapered trunks/branches with bark UVs), `ico` (icosphere),
  `clump` (leaf core + alpha-tested leaf cards), `box`, `quad_face` (world
  projected UVs), `lathe` (surfaces of revolution: bowls, posts, pots).
- `material(name, image, alpha=False, emission=0.0)` creates the Principled
  material the exporter understands (alpha → `MASK`, emission →
  `emissiveTexture` + strength).

### Adding a model

1. Write `make_thing(name, seed)` returning `mb.build(...)`.
2. Add `("thing", make_thing, seed)` to `MODELS`.
3. Run the script, then load it in the demo:
   `ModelBatch b(library.get("thing"))`, push `ModelInstance{pos, yaw, scale, tint}`, `b.upload()`, add to `scene.models`.

### Conventions the engine depends on

- **Origin at the ground contact point**, +Z up, base at Z = 0 (slightly below
  is fine to avoid gaps on slopes). Long objects run along +X.
- **Vertex color `COLOR_0`**: rgb multiplies the texture (use it for baked
  ambient occlusion and tint, e.g. darker at the base, moss on top); alpha is
  the **wind weight** (0 rigid, 1 fully swaying; scales with height).
- Materials named **`foliage*`** are alpha-tested, double-sided, get wrap
  lighting, sun translucency and soft self-shadowing. Everything else is
  single-sided and back-face culled.
- **Winding must be CCW seen from outside.** Single-sided faces are invisible
  from behind, so a wrongly wound or misplaced face shows up from one side
  only. Check models from several angles, and never put a face across an
  opening (the first bridge had an end wall across its entrance that was only
  visible from outside).
- Foliage: set custom normals pointing away from the canopy center (`clump`
  does this) for soft, rounded shading instead of flat cards.
- **Sockets**: an empty parented to the model becomes `Model::sockets["name"]`
  (model space). Use them for attach points (the bridge exports `fire_0`,
  `fire_1` in its braziers; the demo spawns fires there with
  `ModelInstance::toWorld`).
- Budget: a few thousand faces per model is fine; instancing handles counts.

### Per-batch options (`ModelBatch`)

| Field | Use |
| --- | --- |
| `castShadows`, `inReflections` | turn off for tiny props |
| `windScale` | multiplies the vertex wind weight |
| `groundOcclusion` | strength of the baked contact shadow under each instance (trees 1.0, bushes 0.8, rocks 0.7); rebuild `GroundOcclusion` after moving instances |
| `occluderFade` | dither away where it hides the player (tall trees: on; low props like bridges, rocks, bushes: off) |

Collision is gameplay code, not part of the asset: the demo keeps a list of
circular obstacles and special-cases the bridge deck (its numbers mirror
`BRIDGE_*` in the Blender script; keep them in sync).

## 6. Checking your work

Always look at the result; don't assume it looks right.

```sh
cmake -S . -B build -G Ninja && ninja -C build
./build/hd2d_demo --screenshot out.png --frames 90 --pos X,Z --dist 8 --yaw 30 --set dof=0
./build/hd2d_demo --screenshot rain.png --frames 90 --pos X,Z --rain 1
```

- `--pos` puts the player (and camera target) at world X,Z; `--yaw` and
  `--dist` orbit the camera; `--set dof=0` removes blur for inspection.
- Check every new model from at least two opposite yaws, in rain (wet look,
  wind) and near water (reflection).
- Check sprites at default zoom next to the player for scale and pixel size.