docs: add AGENTS.md and README.md documentation files
This commit is contained in:
phillip committed
1 parent
5048796b7d
commit
db9013c9c5
3 files changed
+440
-88
No files matched your search
@@ -0,0 +1,135 @@
|
||||
# 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!
|
||||
- **Cursed Apples:** Invert steering controls (Up ↔ Down, Left ↔ Right) for 40 ticks, requiring quick reflexes and adapted steering.
|
||||
- **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:**
|
||||
- **Normal Mode:** Relaxed tick rate (`TIMER_FREQ_1024(5)`), starting length 4.
|
||||
- **Hard Mode:** High-speed tick rate (`TIMER_FREQ_1024(9)`), starting length 2, and periodic rotten apple hazards.
|
||||
- **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** | **START** | Restart game |
|
||||
| **Game Over** | **B** | Return to Main Menu |
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
Reference in new issue
Block a user