---
description: AutoHero game spec — align code and content with docs/specification.md (combat, loot, progression, UX)
alwaysApply: true
---

# AutoHero — specification alignment

**Source of truth:** `docs/specification.md`. When adding mechanics, content, balance, or UI copy, match names, tiers, and numbers there. If something is ambiguous, extend the spec deliberately rather than contradicting it.

## Core product

- Idle/incremental **isometric** RPG; player auto-moves, fights, loots, upgrades.
- Combat is **timer-based** using `next_attack_at` (intervals), not frame-tied button spam.

## Combat tuning (fixed constants)

| Constant | Value |
|----------|--------|
| `agility_coef` | `0.03` |
| `MIN_ATTACK_INTERVAL` | `250` ms |
| Target attack rate | ~**4 attacks/sec** max |

## HP and death rules (§3.3 — critical)

- Hero HP **persists between fights** — no auto-heal after victory.
- **Level-up does NOT restore HP** unless an explicit mechanic says so.
- Allowed HP restoration sources: Healing buff, Resurrection buff, revive mechanic, or explicitly described enemy/buff/mode mechanic.
- Death = meaningful pause/tempo loss, not a free reset of combat consequences.

## Weapons (type multipliers)

- **Daggers:** speed `1.3×`, damage `0.7×`
- **Swords:** speed `1.0×`, damage `1.0×`
- **Axes:** speed `0.7×`, damage `1.5×`
  Named weapon lists and rarities: 15 items in spec §5.2.

## Armor

- **Light:** `0.8×` Defense; bias Agility/Speed
- **Medium:** `1.0×` Defense; bias Constitution/Luck
- **Heavy:** `1.5×` Defense; bias Constitution/Strength; **−30% Speed**
  Sets: Assassin's, Knight's, Berserker's, Ancient Guardian's (spec §6.2).

## Enemies and abilities

- **7** base enemy archetypes and **6** elite types with level bands, crit/skill behavior, and procs (Poison, Burn, Stun, summons, etc.) per spec **§4**. Do not replace these with unrelated mob themes without updating the spec.

## Buffs / debuffs

- **8** buffs and **6** debuffs; effects and magnitudes (e.g. Rage +100% damage, Shield −50% incoming, Stun blocks attacks 2s) per spec **§7**.

## Loot and gold (§8)

- Rarity tiers and approximate drop frequency: Common **75%**, Uncommon **20%**, Rare **4%**, Epic **0.9%**, Legendary **0.1%** (spec §8.1).
- Gold per tier: Common **5–15** … Legendary **1000–5000** (spec §8.2 table).
- **Gold is always guaranteed** per kill — every victory must award gold.
- Equipment items are **optional extra drops**, not a replacement for gold.
- Luck buff boosts loot but does not override guaranteed gold.
- Reward model: `gold always, item sometimes`.

## Progression

- XP to next level: piecewise curve **v3** per `docs/specification.md` §9.1 (not the legacy single-exponential shortcut).
- XP formula is **identical for online and offline** progression — no simplified offline rules.
- Stat growth on level-up must use the **same canonical path** in all modes.
- Phases (early/mid/late/endgame level bands and pacing goals): spec **§9.2**
- After level **100** — Ascension points: `AP = (Max_Level - 50) / 10` (spec §9.3)

## Meta / retention (reference)

- Daily tasks, weekly challenges, achievement names: spec **§10**. Implement semantics consistently with listed goals.

## Visual / rarity (UI)

| Rarity | Color / VFX |
|--------|----------------|
| Common | Gray |
| Uncommon | Green + glow |
| Rare | Blue + particles |
| Epic | Purple + strong particles |
| Legendary | Gold + gold beam |

## UX principles

- One screen = full game; **icons and color over text**; player stays in flow; **no blocking loads**; **mobile-first**; clear **pause/play** (spec §12).
- UI must **honestly show hero state** — never visually hide HP loss with auto-healing the server/mechanic didn't grant.
- UI must **clearly show reward model** — gold on every victory, items only on actual drops.

## Balance philosophy

- Early game generous; mid balanced; late slow; post-100 Ascension/seasons (spec §13). Tune curves to these phase goals.

## Out of scope for MVP (do not block on)

- Raids, guilds, pets, crafting, PvP duels, seasonal events — future extensions (spec §14).