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) 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 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 (optional, for emulation and testing)

Ensure the DEVKITPRO environment variable is set:

export DEVKITPRO=/opt/devkitpro

Build Instructions

# 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 — Ready to run on an emulator or flashcard.
• snakePlus.elf — ELF binary for GDB debugging.

---

Running & Emulation

Using melonDS via CMake target

cmake --build build --target run

Direct launch

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:

cmake --build build --target install_sd

(Configure OUTPUT_DIRECTORY in CMakeLists.txt as desired).

---

Development & Code Quality

• VS Code Tasks: Built-in tasks in .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 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.

---

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