# IRON STRIKE — Help Guide

> **In-browser manual:** open [help.html](help.html) from the main menu (**📖 HELP**) or the pause screen, or visit it directly in your browser.

A fast-paced top-down tank arena. Survive endless waves, command AI squadmates, use tactical abilities, pick upgrades between waves, and chase the high score.

---

## Getting Started

### Run the game

Use a **local HTTP server** (recommended — loads HD sprites correctly):

```bash
cd tank
python3 -m http.server 8080
```

Open [http://localhost:8080](http://localhost:8080) in your browser.

> Opening `index.html` directly (`file://`) may block sprite loading. If tanks look like simple shapes, use the server method above.

### Your first mission

1. Pick a **tank class** (Phantom / Frost / Vanguard).
2. Set **AI SQUAD** (0–4 teammates; default **2**) if you want backup.
3. Optionally toggle **AUTO FIRE** so the main gun fires without holding Space.
4. Optionally toggle **AI PILOT** to let the computer fly your tank (disables manual controls and Auto Fire).
5. Open **SETTINGS** to adjust volume, screen shake, and **game speed**.
6. Click **DEPLOY**.
7. Clear each wave, pick an upgrade, and survive as long as you can.

---

## Controls

| Input | Action |
|-------|--------|
| **W** / **A** / **S** / **D** | Move tank hull |
| **Space** | Fire main gun (hold; not needed when **Auto Fire** is on) |
| **Auto Fire** (menu) | Toggle — turret fires continuously while a target is locked |
| **Right click** / **E** | Homing missile |
| **Shift** | Boost dash (~2s cooldown) |
| **Q** | Deploy mine (max 3 by default, arms after ~0.8s) |
| **F** | EMP burst — stuns and damages nearby enemies |
| **P** | Pause / resume |
| **⏸ PAUSE** (HUD) | Same as **P** — button on the right HUD rail |

Movement and turret aiming are **independent** — the turret auto-locks the **nearest enemy** while you strafe with WASD. The **crosshair** snaps to your locked target; it glows while firing.

**Auto Fire** (main menu) hides the need to hold Space — the gun fires whenever a target is locked.

The **mouse** is not used to aim. You still need it for the HUD **⏸ PAUSE** button and **right-click** missiles. The system cursor stays visible during play.

---

## Performance & battery

| Situation | What happens |
|-----------|----------------|
| **Combat** | Full-speed canvas rendering (most GPU/CPU use) |
| **Pause** | Gameplay stops; canvas draws **once** then idles |
| **Upgrade shop** | Frozen battlefield behind the shop overlay |
| **Main menu** | Canvas throttled to ~30 FPS |
| **Tab in background** | Game fully idles until you return |

**Tips:** Pause when taking a break. Lower **Game Speed** reduces simulation work (not menu draw rate). Close the tab to stop the game entirely.

---

## Main Menu

| Option | Description |
|--------|-------------|
| **Tank class** | Phantom (green), Frost (cyan), Vanguard (gold) — cosmetic hull colors |
| **AI SQUAD** | Choose **0–4 AI teammates** that fight alongside you |
| **DEPLOY** | Start a new run |
| **AI PILOT** | Replaces **your** controls with AI (separate from squad) |
| **AUTO FIRE** | Fires automatically at the nearest enemy — no need to hold Space |
| **SOUND** | Toggle audio on/off |
| **SETTINGS** | Volume, screen shake, game speed |
| **HELP** | Opens this combat manual in the browser |
| **Achievements** | Unlockable medals (persist across runs) |
| **High score** | Best run stored in your browser |

Load status under the logo: **HD TANK SPRITES READY**, **STANDARD SPRITES READY**, or **PROCEDURAL**.

---

## Settings

Open **⚙ SETTINGS** on the main menu.

| Setting | Description |
|---------|-------------|
| **Master Volume** | 0–100% audio level |
| **Screen Shake** | 0–200% impact camera shake intensity |
| **Game Speed** | Simulation speed during combat (saved automatically) |

### Game speed options

| Speed | Multiplier | Best for |
|-------|------------|----------|
| **SLOW** | 0.5× | Learning controls, studying enemy patterns |
| **NORMAL** | 1× | Default experience |
| **FAST** | 1.75× | Shorter sessions, more action |
| **SUPER** | 2.5× | Veteran players |
| **LIGHTNING** | 4× | Maximum chaos — great with AI Pilot |

Speed applies during deploy, combat, and the upgrade shop. It does **not** affect the main menu or pause screen. Combo slow-motion still triggers on top of your chosen speed. Changing speed mid-combat shows a brief on-screen toast.

---

## AI Squad & AI Pilot

These are **separate features** — you can mix and match.

### AI Squad (0–4 teammates)

Squadmates are AI-controlled friendly tanks that fight alongside you.

| Slot | Callsign | Hull color |
|------|----------|------------|
| 1 | WARDEN | Cyan |
| 2 | SPEAR | Gold |
| 3 | BLADE | Green |
| 4 | HAVOC | Cyan |

- Each ally uses the same smart AI as AI Pilot (dodging, leading shots, ability use).
- Enemies target the **nearest friendly** — you or a squadmate.
- **Ally deaths do not game over** — they respawn at the start of the next wave.
- HUD shows **SQUAD x/y** when squadmates are active.
- Your choice (0–4) is saved in your browser.

### AI Pilot

When enabled, the AI controls **your** tank instead of WASD / Space / Shift:

- Auto-aims with predictive leading shots
- Dodges bullets, kites threats, uses walls for cover
- Fires missiles, mines, EMP, and boost tactically
- Picks upgrades automatically in the shop (`AiUpgrade`)
- Toggle on the main menu before **DEPLOY** — hides the **Auto Fire** button while active

**Tip:** Run AI Pilot at **LIGHTNING** speed to watch high-intensity auto-battles. Or use manual controls with a full squad for a commander feel.

---

## HUD (Heads-Up Display)

The battlefield fills the **left side** of the screen. All combat UI sits in a **right-side panel** (~200px wide) so the play area stays as large as possible. The **COMBO** banner appears over the play area center when you chain kills.

### Right HUD rail (top → bottom)

| Element | Description |
|---------|-------------|
| **SCORE** | Total points this run (animates upward) |
| **WAVE** | Current wave number |
| **KILLS** | Tanks destroyed |
| **RANK** | Title based on waves survived (see Scoring) |
| **THREAT** | Current danger level (see Scoring) |
| **SQUAD** | Alive AI teammates / total (when squad is active) |
| **AI PILOT** badge | Shown when AI Pilot controls your tank |
| **RADAR** | Minimap — walls, enemies, allies, sweep line |
| **⏸ PAUSE** | Pause combat (also **P**) |
| **ARMOR** | Health bar — 0 ends the mission |
| **BOOST** | Dash cooldown |
| **MISSILE** | Homing missile cooldown |
| **MINES** | Active mine count / max, deploy cooldown |
| **EMP** | EMP cooldown |
| **Power-up bar** | Active timed buff and remaining duration |

### Play-area overlay

| Element | Description |
|---------|-------------|
| **Crosshair** | Tracks your locked enemy; glows green while firing (Space or Auto Fire) |
| **Laser sight** | Dashed line from your turret to the locked target |
| **COMBO** | Kill streak multiplier — chain kills quickly for bonus score and slow-motion |

---

## Gameplay

### Objective

Survive as many waves as possible. Enemies spawn from the top and sides. Clear every hostile to finish the wave, choose **one upgrade**, then face the next wave. Every **5th wave** spawns the **WARLORD** boss.

### Wave flow

1. **Deploy sequence** (~3 seconds) — systems check
2. **Mission briefing** — enemy types, wave modifier, threat level
3. **Countdown**, then combat
4. **Wave clear bonus:** +100 × wave number
5. **Upgrade shop** — pick one of three random options
6. Next wave

### Arena

- Battlefield size: **2400 × 1800**
- **Top and bottom** border walls; **open left and right** for wider flanking
- Random clusters of **destructible** (orange tint) and **indestructible** cover
- Breaking destructible walls: **+5 score** each and new firing lanes

### Combat

- Bullets leave glowing trails and are blocked by walls
- **Critical hits** (purple glow) deal double damage — ~12% base chance, upgradeable
- **Combos** multiply score for rapid kills; high combos trigger slow-motion and banner text
- **Elite** enemies (gold ring) have extra health and score
- **Boss waves** (every 5th): **WARLORD** — huge, high damage, bonus score on kill

### Tactical abilities

| Ability | Key | Notes |
|---------|-----|-------|
| **Mines** | Q | Proximity damage; limited slots; arms after ~0.8s |
| **EMP** | F | Stuns and damages enemies in a radius |
| **Missile** | E / RMB | Homing rocket with strong AoE on impact |
| **Boost** | Shift | Short dash with ~2s cooldown |
| **Supply drop** | — | Mid-wave crate every 3rd wave from wave 2+; becomes a power-up |

### Wave modifiers

Non-boss waves may roll a special condition:

| Modifier | Effect |
|----------|--------|
| Standard Ops | No modifier |
| Armored Column | Enemies +25% armor |
| Hyper Assault | Enemies +20% speed |
| Bounty Hunt | Double kill score |
| Combat Fog | Reduced visibility |
| Swarm Tactics | +4 extra enemies |

---

## Wave Upgrades

After each cleared wave, choose **one** of three random upgrades:

| Upgrade | Effect |
|---------|--------|
| **REINFORCED PLATING** | +30 max armor and instant repair |
| **AP ROUNDS** | +20% damage |
| **TURBOCHARGER** | +15% move speed |
| **AUTO-LOADER** | +25% fire rate |
| **WARHEAD CACHE** | Missile ready + 15% faster recharge |
| **LASER SIGHT** | +8% critical hit chance (caps at 45%) |
| **NANO REPAIR** | Passive armor regen (+3/sec) |
| **CLAYMORE KIT** | +1 mine capacity, 20% faster deploy |
| **EMP OVERCHARGE** | +30% EMP radius, 25% faster recharge |

Upgrades stack across waves for the duration of the run.

---

## Enemy Types

| Type | Color | Role | Base score |
|------|-------|------|------------|
| **Scout** | Orange | Fast harasser — Wave 2+ | 100 |
| **Standard** | Red | Balanced all-rounder | 200 |
| **Heavy** | Dark red | Slow, high armor — Wave 3+ | 400 |
| **Sniper** | Purple | Long range — Wave 4+ | 350 |
| **WARLORD** | Crimson | Boss — every 5th wave | 1200 (+500 bonus) |

Each kill also adds **+10 × current wave**. Combo multipliers and **Bounty Hunt** increase totals further.

---

## Power-Ups

~22% drop chance from destroyed enemies. Supply crates also grant one. Collecting any power-up: **+50 score**.

| Power-Up | Icon | Effect | Duration |
|----------|------|--------|----------|
| **REPAIR** | ♥ | +40 armor | Instant |
| **TURBO** | » | +60% move speed | 8s |
| **SHIELD** | ◈ | 80% damage reduction | 6s |
| **RAPID FIRE** | ⚡ | 2.5× fire rate | 10s |
| **OVERCHARGE** | ✦ | 2× damage | 8s |

Only one timed buff is shown in the HUD at a time.

---

## Scoring & Ranks

### Rank titles (by wave reached)

| Wave | Rank |
|------|------|
| 1 | RECRUIT |
| 2–3 | SERGEANT |
| 4–6 | LIEUTENANT |
| 7–9 | CAPTAIN |
| 10–14 | COMMANDER |
| 15+ | LEGEND |

### Threat levels

| Condition | Threat |
|-----------|--------|
| Waves 1–2 | MODERATE |
| Waves 3–5 | ELEVATED |
| Waves 6–9 | HIGH |
| Waves 10+ | EXTREME |
| Boss wave | CRITICAL |

### High scores

Beat your personal best to enter **initials** on the leaderboard (top 5 saved per browser).

---

## Achievements

Unlocked permanently in your browser:

| Achievement | How to unlock |
|-------------|----------------|
| First Blood | Destroy your first tank |
| Tank Hunter | 10 kills in one run |
| Annihilator | 50 kills in one run |
| Survivor | Reach wave 5 |
| Veteran | Reach wave 10 |
| Warlord Slayer | Destroy the WARLORD boss |
| Kill Streak | Reach a 5× combo |
| Trap Master | Kill an enemy with a mine |
| Untouchable | Clear a wave without taking damage |
| Sharpshooter | 10 critical hits in one run |

---

## Menus & Screens

| Screen | Actions |
|--------|---------|
| **Main menu** | DEPLOY, tank class, AI squad, AI pilot, auto fire, settings, help, achievements |
| **Pause** (**P** or **⏸ PAUSE** on HUD) | Resume, Help, or Abort Mission — combat frozen, low GPU use |
| **Upgrade shop** | Pick one enhancement after each wave |
| **Game Over** | Retry, main menu; enter initials on new record |

---

## Tips & Tactics

1. **Use cover** — Break destructible walls for firing lanes and score.
2. **Strafe** — Movement is separate from the auto-aiming turret; keep moving.
3. **Try Auto Fire** for a more arcade feel; use Space for manual burst control.
4. **Save boost** for escapes and breaking sniper aim.
5. **Prioritize snipers and the WARLORD** — They out-damage you at range.
6. **Deploy mines** at choke points when retreating.
7. **Save missiles** for elites, groups, and bosses.
8. **EMP** when surrounded — buys time to reposition.
9. **Chain kills** for combo score multipliers.
10. **Watch RADAR** for flankers from the open left/right sides.
11. **Pick armor or regen upgrades** if you keep dying between waves.
12. **AI squadmates draw fire** — flank while they engage.
13. **Start on SLOW speed** when learning; ramp up once comfortable.
14. **Bounty Hunt waves** are ideal for score chasing — push aggressively.

---

## Troubleshooting

| Problem | Solution |
|---------|----------|
| **DEPLOY does nothing** | Hard-refresh (`Cmd+Shift+R` / `Ctrl+Shift+R`). Use `python3 -m http.server`, not `file://`. Check browser console (F12). |
| **No HD sprites** | Serve over HTTP; ensure `assets/craftpix/` exists. |
| **No sound** | Click DEPLOY first (browser gesture required). Unmute tab. Check SETTINGS volume. |
| **Scores / achievements reset** | Stored per browser origin; clearing site data removes them. |
| **Game too fast / slow** | Open SETTINGS and change Game Speed. |
| **Lag at LIGHTNING speed** | Drop to SUPER or FAST; close heavy browser tabs. |
| **High GPU/CPU while paused** | Fixed in v2.4 — pause freezes the canvas after one draw. Hard-refresh if still high on an old build. |

---

## For developers

| Resource | Contents |
|----------|----------|
| **[README.md](README.md)** | Full module map (**51** JS files), script order, combat input flow, render scheduling, extension guide |
| **`assets/LICENSE.txt`** | Sprite credits and licenses |
| **`window.__ironStrikeGame`** | Live game instance in browser console (debug) |

### Key modules (v2.4)

| Layer | Modules |
|-------|---------|
| Orchestration | `game.js`, `StateMachine`, `GameLoop`, `RenderScheduler`, `CombatUpdate`, `MenuFlow` |
| Combat input | `InputRouter`, `PlayerCombat`, `CrosshairController`, `TargetingService` |
| Tanks | `TankControl`, `TankDraw`, `tank.js`, `ai-player.js`, `AiThreat`, `AiUpgrade` |
| UI | `ui-bindings.js`, `UiController`, `HudManager`, `GameRenderer` |

**Rule of thumb:** change manual aim/fire in `PlayerCombat` + `TargetingService`; change AI tactics in `ai-player.js`; change DOM meters in `hud.js`; change reticle in `crosshair-controller.js`; change draw/tick rate in `render-scheduler.js`.

Syntax-check: `find js -name '*.js' | sort | xargs -I{} node --check {}`

---

## Requirements

- Modern browser (Chrome, Firefox, Safari, Edge)
- JavaScript enabled
- Keyboard (WASD, Space, Shift, E, Q, F, P)
- Local HTTP server for full sprite support

---

*Good luck, commander. Hold the line.*