autohero/docs/art-bible.md

# AutoHero — Art Bible (Sprite Pipeline)

**Purpose:** Single source of truth for mood, stylization, palette, and perspective so terrain tiles, props, buildings, heroes, NPCs, and enemies read as **one game**, not mixed asset packs. Use this for hand-off to artists, AI prompts, and internal reviews.

**Scope:** Static sprite art (phase 1). Animation adds frames later; this bible still governs silhouette, lighting, and palette on every frame.

**Related:** Content IDs remain defined in [`specification-content-catalog.md`](specification-content-catalog.md). Technical export sizes and keys for generation live in the sprite migration plan (repository plans; do not treat this file as the prompt bank).

---

## 1. Creative direction

| Axis | Direction |
|------|-----------|
| **Genre & mood** | Dark fantasy: dangerous, heavy, lived-in. Not a bright fairy tale. Hope exists as small sparks (lanterns, embers), not candy colors. |
| **Tone** | Brutal but readable: heroes and monsters feel physically convincing and threatening. Environment supports hardness (ruins, metal, harsh nature) without cute simplification. |
| **Stylization** | **Arcane-like:** painterly treatment, **strong silhouettes**, cinematic light and shadow, volume from large forms and careful shading—not from noisy micro-detail on tiny sprites. |
| **Clarity** | Icons and combat readability first: silhouette and value separation beat texture noise at small sizes. |

**English prompt prefix (for consistency across generation briefs):**

```text
Dark fantasy, brutal mood, stylized painterly look inspired by Arcane series,
cinematic lighting, strong readable silhouette, muted desaturated colors with rare accent highlights,
single game asset, transparent background, no text, no watermark, no border.
Isometric 45° or three-quarter view, consistent with tile-based RPG ground plane.
```

**Краткий бриф (RU):** мрачное фэнтези, брутально, стилизация в духе Arcane, приглушённая палитра, один объект, прозрачный фон, изометрия или три четверти, единый ракурс со сценой.

---

## 2. Visual pillars (non-negotiables)

1. **Silhouette first** — Every unit and large prop must read clearly in grayscale; interior line detail is secondary.
2. **One lighting story** — Key light feels directional (often top-left or front-top); rim or bounce sparingly. Avoid flat ambient fill that kills depth.
3. **Painterly, not noisy** — Broad strokes, controlled edges. No high-frequency speckle that turns to mush when scaled down.
4. **Unified detail density** — Tile, prop, and character art share the same “resolution of idea”: no hyper-detailed hero next to blob ground.
5. **Restrained VFX** — Magic, fire, blood, lightning are **accents** (see palette), not full-neon coverage.

---

## 3. Color & palette

### 3.1 Base (majority of each asset)

- **Neutrals:** Deep desaturated browns, cold grays, blue-grays, muted olive and pine greens.
- **Value range:** Favor mid-to-dark; highlights are **narrow** and purposeful (metal edge, wet surface, spell core).
- **Saturation:** Globally **low**; increase saturation only for intentional focal points.

### 3.2 Accents (use sparingly)

Deploy accents to guide the eye: magic (teal, violet, cold blue), fire and embers (warm orange-red, not neon), blood (deep crimson, not bright cherry), metal (cool specular), bioluminescence (subtle cyan-green in swamps).

**Rule:** If the whole sprite feels “colorful,” reduce saturation until the piece matches the base row, then add **one** accent zone.

### 3.3 Avoid

- Acid or toy primaries across large areas.
- Rainbow gradients on materials.
- Pure white (#FFFFFF) or pure black (#000000) except tiny specular hits or deep creases.

---

## 4. Camera, perspective, and ground contact

### 4.1 World alignment

- The game world uses an isometric diamond grid: **96×48 px** per cell (`TILE_WIDTH` × `TILE_HEIGHT` in `frontend/src/shared/constants.ts`).
- Ground tiles are **2:1 rhombus** fills; props and buildings sit on that ground plane.

### 4.2 Single viewpoint

- **Units and buildings:** **Three-quarter / isometric-style 3/4** view, consistent “camera-right” or three-quarter toward the camera (match existing renderer facing conventions; do not mix side-scroller flat with isometric props in the same set).
- **Tiles:** Top-down isometric diamond; texture fills the rhombus; corners may be transparent on a slightly larger canvas if needed.
- **UI weapon icons (HUD):** Not world-isometric; **side or slight top** for readability at 48–64 px (see migration plan).

### 4.3 Anchor

- **Bottom-center** anchor for standing entities and vertical props: feet, trunk base, or building foundation centered on the contact point. Keeps `zIndex` sorting by screen `y` meaningful.

---

## 5. Scale cues (relative to grid)

These are **art targets**, not engine constraints:

| Category | Note |
|----------|------|
| **Tiles** | Art fits the 2:1 rhombus; target canvas per prompt bank (often 96×48 export). |
| **Tall props (trees, ruins)** | Extend above the tile; anchor at ground. |
| **Buildings** | Footprint roughly **~2 tiles wide**; height typically **220–280 px** range in doc prompts. |
| **Player / NPC** | ~**128×160** canvas class; consistent with each other. |
| **Base enemies** | Slightly larger than a human (~10–20%); **elites** ~**+15%** height and stronger silhouette/VFX read. |

Adjust only within the migration plan’s size tables; do not invent new keys without updating the content catalog.

---

## 6. Do / don’t (review checklist)

| Do | Don’t |
|----|--------|
| Match silhouette and value to Arcane-like painterly discipline | Mix unrelated styles (anime flat + gritty realistic) in one asset set |
| Keep ground tiles seamless at edges (where applicable) | Add readable text, logos, or watermarks on textures |
| Use muted palette with rare accents | Cover surfaces with loud saturated gradients |
| Align perspective with §4 | Rotate the same prop to contradictory viewpoints across variants |
| Export **PNG with alpha**, one object per file as per pipeline | Embed borders or frames in the texture |

---

## 7. References (workflow)

- **Primary:** *Arcane* (Netflix)—lighting, silhouette, painterly surfaces, restrained saturation.
- **Use references for:** mood boards and lighting—not for copying identifiable characters or logos.
- **Internal:** Place approved reference stills or links in team channels / design wiki; this repo file stays text-only so it stays easy to diff and version.

---

## 8. Generation pipeline (PixelLab MCP)

**Product decision — hybrid (locked):** The **creative target** stays **painterly, Arcane-like** (sections 1–6). **Execution** for raster sprites in Cursor uses **PixelLab AI MCP** by default. PixelLab outputs are **pixel art**; they still must obey mood, palette, silhouette, and perspective here by **always** prepending the §1 English prompt prefix to every MCP `description`, then appending the row-specific brief from the sprite migration plan.

| Need | MCP tool (names may be prefixed in Cursor, e.g. `mcp_pixellab_*`) | Notes |
|------|-------------------------------------------------------------------|--------|
| Isometric ground / blocky terrain pieces | `create_isometric_tile` | Default `size` in API is 32; target **96×48** world rhombus may require upscale or `create_tiles_pro` with `tile_type` isometric — see [docs/pixellab-mcp-schema.md](pixellab-mcp-schema.md). |
| Props, buildings as sprites | `create_map_object` | Set `width` / `height` when known; optional `background_image` for style matching. |
| Heroes, NPCs, enemies (humanoid or quadruped) | `create_character` | `n_directions` 4 or 8; `size` canvas; quadrupeds need `body_type` + `template`. |
| Animation (phase 2) | `animate_character` | After `character_id` exists; use `get_character` for status and URLs. |

Jobs are **asynchronous**: creation returns quickly — poll `get_isometric_tile`, `get_map_object`, `get_character`, etc., until status is completed, then **persist files immediately** (see [.cursor/rules/pixellab-sprite-pipeline.mdc](../.cursor/rules/pixellab-sprite-pipeline.mdc)). Later, individual textures may be swapped for hand-painted or non-pixel art **without changing content IDs** if anchors and manifest keys stay the same.

**Authoritative tool list and parameters:** [https://api.pixellab.ai/mcp/docs](https://api.pixellab.ai/mcp/docs) (regenerated from server definitions; verify if behavior changes).

---

## 9. Sign-off

Art direction is **locked** for phase-1 sprite replacement when:

- All new sprites are reviewed against §§1–6 and **§8** (MCP descriptions and saved assets),
- Palette and perspective exceptions are documented per asset only when technically required (e.g. HUD icons),
- Placeholders (if used) follow the same muted palette and anchor rules until final art lands.

**Document owner:** Art / creative direction (update this file when palette or perspective rules change).