snakePlus/README.md

# Snake Plus (Nintendo DS)

> **Snake with a twist** — A homebrew Snake game for the Nintendo DS developed in modern C++ with `libnds` and `devkitPro`.

---

## Features

- **Classic Gameplay with a Twist:**
  - Classic grid-based snake action wrapped on a 32×24 playfield with edge-wrapping.
  - **Normal Apples:** Boost length and score (+10), with flashing animation and pickup sounds.
  - **Rotten Apples:** Shrink snake length by 1; shrinking below length 2 results in Game Over! Rendered with custom 8x8 pixel art featuring bruised amber decaying skin, dark rot cavities, a withered twig stem, and festering green mold spores with 60 FPS bioluminescent respiration. Despawn after 80 ticks.
  - **Cursed Apples:** Invert steering controls (Up ↔ Down, Left ↔ Right) for 40 ticks, requiring quick reflexes and adapted steering. Despawn after 90 ticks if avoided, allowing new curses to spawn later.
- **Dual-Screen Layout:**
  - **Top Screen:** Real-time scoreboard, status alerts (*"CONTROLS INVERTED!"*), pause overlay, and optional debug stats.
  - **Bottom Screen:** Smooth 2D hardware sprite rendering using DS Sub-engine OAM.
  - **LCD Swap:** Switch top and bottom screens on the fly with the **R** shoulder button.
- **Audio & Sound Effects:**
  - Background tracker music ([`0rigin.xm`](sounds/0rigin.xm)) powered by MaxMod 9.
  - Sound effects for movement, pickups, rotten/cursed explosions, pause, and game over.
  - On-the-fly music toggle from the menu or pause screen.
- **Game Modes & Progressive Intensity:**
  - **Normal Mode:** Starts at 5.0 Hz, scaling smoothly up to 13.0 Hz as apples are consumed.
  - **Hard Mode:** Starts at 5.0 Hz and scales up to a blazing 17.0 Hz, spawning rotten apple hazards and dynamic temporary energy barriers.
  - **Temporary Fatal Barriers:** Energy walls appear dynamically in Hard Mode after 3 apples. Each barrier flashes a warning reticle for 2.0 s before solidifying into a lethal hazard-striped obstacle for 4.0 s.
  - **Dynamic Backgrounds:** Dual-screen cyber grids accelerate drift and intensify color palettes (plasma cyan in Normal, hyper-crimson in Hard, radioactive violet when cursed) in tandem with game speed.
- **Persistent Game Over Screen:**
  - Collision state is preserved: snake, apples, and barriers remain visible on the playfield so players can review their final position.
  - Background smoothly decelerates and dims into a somber tone.
  - Dedicated top-screen summary presents final score, apples eaten, length, difficulty, and exact cause of defeat (Bite Collision, Energy Barrier Impact, or Rotten Apple Depletion).
- **Main Menu & Pause Screen:**
  - Integrated start menu to toggle Hard Mode and Music.
  - In-game pause menu with instant restarts and mode toggles.

---

## Controls

| Screen / Context | Button | Action |
|---|---|---|
| **Main Menu** | **D-Pad Up / Down** | Navigate menu options |
| **Main Menu** | **A** or **START** | Select option / Start game |
| **In-Game** | **D-Pad** | Steer snake (inverted while cursed) |
| **In-Game** | **START** | Pause / Resume |
| **In-Game** | **R Trigger** | Swap top and bottom screens (`lcdSwap`) |
| **In-Game** | **SELECT** | Toggle debug HUD (coordinates, ticks, raw keys) |
| **In-Game** | **START + L** | Exit game |
| **Paused** | **B** | Return to Main Menu |
| **Paused** | **X** | Toggle background music ON/OFF |
| **Paused** | **Y** | Toggle Normal / Hard mode and restart |
| **Game Over** | **A** or **START** | Restart game |
| **Game Over** | **B** | Return to Main Menu |
| **Game Over** | **R Trigger** | Swap top and bottom screens (`lcdSwap`) |

---

## Building from Source

### Prerequisites

Ensure you have the following installed:
1. **[devkitPro](https://devkitpro.org)** with the `nds-dev` payload:
   - `devkitARM` toolchain
   - `libnds`, `calico`, `maxmod9`
   - Utilities: `ndstool`, `grit`, `mmutil`, `bin2s`
2. **CMake** (>= 3.13)
3. **Ninja** build system
4. **[melonDS](https://melonds.kuribo64.net/)** (optional, for emulation and testing)

Ensure the `DEVKITPRO` environment variable is set:
```bash
export DEVKITPRO=/opt/devkitpro
```

### Build Instructions

```bash
# Clone the repository
git clone <repo-url> snakePlus
cd snakePlus

# Configure build with Ninja
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

# Compile the .nds ROM and .elf binary
cmake --build build
```

This generates:
- [`snakePlus.nds`](snakePlus.nds) — Ready to run on an emulator or flashcard.
- [`snakePlus.elf`](snakePlus.elf) — ELF binary for GDB debugging.

---

## Running & Emulation

### Using melonDS via CMake target

```bash
cmake --build build --target run
```

### Direct launch

```bash
melonDS snakePlus.nds
```

### Installing to Flashcard / SD Card

A convenience target is included in CMake to copy the `.nds` ROM to an SD card path:

```bash
cmake --build build --target install_sd
```
*(Configure `OUTPUT_DIRECTORY` in [`CMakeLists.txt`](CMakeLists.txt) as desired).*

---

## Development & Code Quality

- **VS Code Tasks:** Built-in tasks in [`.vscode/tasks.json`](.vscode/tasks.json) support one-key build, run in melonDS, and debug with GDB.
- **Clang-Tidy:** Run `run-clang-tidy` or launch the watch script:
  ```bash
  bash tools/clang_tidy_watch.sh
  ```
- **Language Standards:** C11 / C++14 targeting ARM9 (`armv5te`).

---

## Architecture & Developer Documentation

For an in-depth architectural breakdown, hardware register mapping, OAM details, and guidelines for AI agents or contributors, refer to [`AGENTS.md`](AGENTS.md).

---

## Credits & Author

- **Game Design & Code:** Phillip Kuehne
- **Music:** `0rigin.xm`
- **Sound Effects:** Freesound.org contributors (`treasuresounds`, `pacomav`, `crisstanza`, `timbre`, `benboncan`)
- **Platform Libraries:** `libnds`, `maxmod` by devkitPro team