hector/NekoBoy
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

1st commit, added some fundational documenetation.

Browse source
This commit is contained in:
Hector T 2026-05-27 01:39:48 -06:00
parent 55723a72f8
commit 618f37dba2
3 changed files with 302 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

75
docs/01-VISION-AND-PHILOSOPHY.md Normal file
View file

@ -0,0 +1,75 @@
# Vision and Philosophy
**Project Name**: NekoBoy
**Tagline**: *Pocket-sized passion. Meaningful play. Music that stays with you.*
## Core Vision
NekoBoy is a pocketable, open-source handheld gaming console designed to recapture the emotional impact and creative joy of classic 2D gaming while offering modern tools and developer accessibility.
We believe games and music should feel personal. We want developers (from complete beginners to experienced creators) to be able to make experiences that feel meaningful — games that players remember not just for the mechanics, but for how they made them feel.
## Core Philosophy
### 1. Emotion Over Realism
Modern games often prioritize graphical fidelity. NekoBoy prioritizes **feeling**. We focus on beautiful movement, expressive music, and simple-but-deep gameplay that can create strong emotional responses.
### 2. Purposeful Gaming
Physical cartridges encourage intentional play. Instead of endlessly scrolling through digital libraries, players choose a cartridge and engage with it more deliberately.
### 3. Developer Empowerment
The project is built to be approachable. A strong **Core Abstraction Layer**, a capable PC **Emulator**, and clear tooling (including `neko-asset`) allow developers to create content on their computer and move it to real hardware with minimal friction.
### 4. Music as a First-Class Citizen
Music is central to the NekoBoy experience. The platform includes a powerful FM + PCM audio system and **NekoTracker** — a dedicated music creation tool that can run both on PC and directly on the hardware.
### 5. Open Source & Community
Everything — hardware, firmware, software, and tools — is open source. We want the community to understand, modify, and improve the system.
## Target Experience
- **Form Factor**: Pocketable (GBA-like size or slightly larger)
- **Controls**: SNES-style layout with 4 shoulder buttons
- **Display**: 4.3" 800×480 IPS
- **Battery Life**: 10–12+ hours of gameplay
- **Development**: Create on PC using the emulator → Run on real hardware with minimal changes
- **Music Creation**: Use NekoTracker on PC or directly on the console via cartridge
## Benchmarks
NekoBoy should comfortably run games in the style of:
- **Vampire Survivors / Holocure** style games (many on-screen sprites, simple AI)
- Scaled versions of **DOOM** and **Minecraft**
- Rich 2D platformers and action games with layered graphics and expressive music
## Key Design Principles
| Principle | Meaning |
|-----------------------------|-------------------------------------------------------------------------|
| **Unified Development** | Write once, run on emulator and hardware with minimal changes |
| **Hardware/Software Balance** | Offload graphics and audio to FPGA so the CPU can focus on game logic |
| **Developer Accessibility** | Modern tools + clear documentation + helpful abstractions |
| **Musical Depth** | Rich FM synthesis + PCM with character (including optional lo-fi) |
| **Emotional Focus** | Prioritize feeling and memorability over technical spectacle |
| **Open & Hackable** | Easy to understand, modify, and extend |
## What NekoBoy Is Not
- It is **not** trying to compete with modern high-fidelity 3D games.
- It is **not** a high-powered emulation machine.
- It is **not** overly complex or bloated.
Instead, it aims to be a focused, coherent platform where creativity and emotion can flourish within well-defined (but expressive) boundaries.
## Success Criteria (v1)
- Developers can create games and music primarily on their computer.
- Games and music created on PC can run on real hardware with minimal modification.
- The audio system can convincingly recreate (and expand upon) the emotional range of classic FM soundtracks.
- The graphics system supports rich 2D visuals while remaining efficient.
- New developers can understand the system and start creating with reasonable effort.
---
*This document defines the "why" behind NekoBoy. All technical decisions should ultimately serve this vision.*

165
docs/02-SYSTEM-ARCHITECTURE.md Normal file
View file

@ -0,0 +1,165 @@
# System Architecture
**Last Updated**: 2026-05-27
**Status**: Draft
## 1. High-Level Overview
NekoBoy is built around a clear division of responsibilities between a microcontroller (CPU) and an FPGA. This hybrid architecture allows us to combine the flexibility of software with the deterministic, high-performance capabilities of custom hardware.
The system is designed so that the same high-level game code can run on both a PC emulator and the real hardware with minimal changes. This is achieved through a **Core Abstraction Layer**.
### Core Components
| Component | Role | Technology |
|---------------------------|---------------------------------------------------|---------------------|
| **STM32U575VIT6** | Main CPU – Game logic, AI, physics, high-level control | Microcontroller |
| **XC7S50-2CSGA324I** | PPU (Graphics) + APU (Audio) | FPGA |
| **Core Abstraction Layer**| Unified interface for PPU and APU | C library |
| **Emulator** | Software Reference PPU + APU (for development) | PC software |
| **NekoTracker** | Music creation tool | Runs on PC and Hardware |
## 2. Component Responsibilities
### STM32U575VIT6 (Main CPU)
The microcontroller handles everything that benefits from flexible software logic:
- Game logic, AI, and physics
- High-level game state management
- Asset streaming and coordination
- Communication with the FPGA via FMC
- Power management and system control
- Cartridge interface and flashing
- I2C communication with power, audio codec, and sensors
**Design Principle**: The CPU should stay focused on *what* should happen, while the FPGA handles *how* it is rendered and played.
### XC7S50 FPGA (PPU + APU)
The FPGA is responsible for all real-time, performance-critical tasks:
- **PPU (Pixel Processing Unit)**: Tile layers, sprites, palettes, priority, effects, and display output
- **APU (Audio Processing Unit)**: FM synthesis, PCM playback, mixing, and lo-fi post-processing
- Direct RGB output to the display
- I2S audio output to the codec
The FPGA provides deterministic timing and high parallelism, which is ideal for graphics and audio.
### Core Abstraction Layer
This is the most important software component in the project.
It defines a clean, consistent interface that games and tools use to interact with graphics and sound. The same interface is implemented in two ways:
- **Software Reference** → Used by the Emulator on PC
- **Hardware Driver** → Used on the real NekoBoy console
Because of this layer, most game code does not need to know whether it is running on an emulator or real hardware.
## 3. Data Flow
```
Game Code / NekoTracker
│
▼
Core Abstraction Layer (PPU + APU commands)
│
├──────────────────────┐
▼ ▼
Emulator (PC) STM32U575 (Hardware)
│ │
▼ ▼
Software Reference PPU/APU FPGA (Real PPU + APU)
```
### Typical Flow Example (Rendering a Sprite)
1. Game calls `ppu_draw_sprite(...)` through the abstraction layer.
2. On PC → The call goes to the Software Reference PPU.
3. On Hardware → The call is translated into FMC commands sent to the FPGA.
4. The FPGA renders the sprite using its hardware PPU logic.
The same pattern applies to audio playback.
## 4. Memory Architecture
NekoBoy uses a **split memory design** to avoid contention and maximize performance:
| Memory | Connected To | Purpose | Size |
|-------------------------|------------------|---------------------------------------------------|---------|
| **HyperRAM (CPU)** | STM32U575 | Game state, decompressed assets, buffers | 32 MB |
| **HyperRAM (FPGA)** | XC7S50 | Framebuffers, tilemaps, sprite data, audio | 32 MB |
| **Fast SRAM** | XC7S50 | High-speed texture/sprite cache | 2 MB |
This separation ensures that the FPGA has fast, dedicated access to the memory it needs for rendering and audio without competing with the CPU.
## 5. Communication Interfaces
### CPU ↔ FPGA Communication
- **Primary Interface**: FMC (Flexible Memory Controller)
- High-bandwidth parallel bus
- Low latency for commands and data transfer
- Used for PPU commands, sprite data, tilemap updates, etc.
- **Secondary**: GPIO / IRQ lines for synchronization (e.g., VBlank interrupts)
### Other Important Interfaces
| Interface | Connected Devices | Purpose |
|---------------|--------------------------------------------|--------------------------------------|
| **I2C** | Power ICs, Audio Codec, Sensors | Configuration and control |
| **QSPI** | Cartridge NOR Flash | Game ROM and assets |
| **SPI** | FRAM (saves) | Non-volatile save data |
| **I2S** | Audio Codec (from FPGA) | Digital audio output |
| **RGB TTL** | Display (from FPGA) | Direct video output |
## 6. Development vs Hardware Execution
One of the core goals of NekoBoy is to make development as smooth as possible.
| Environment | PPU Implementation | APU Implementation | How Code Runs |
|-------------------|-----------------------------|-----------------------------|----------------------------------------|
| **Desktop** | Software Reference PPU | Software Reference APU | Directly against abstraction layer |
| **Emulator** | Software Reference PPU | Software Reference APU | Same as desktop |
| **Real Hardware** | FPGA PPU | FPGA APU | Same abstraction calls via driver |
Because both the emulator and hardware use the same **Core Abstraction Layer**, developers can write and test most of their code on PC before moving to real hardware.
## 7. Block Diagram
```mermaid
graph TD
A[Game Code / NekoTracker] --> B[Core Abstraction Layer]
B --> C[Emulator on PC]
B --> D[STM32U575VIT6]
C --> E[Software Reference PPU]
C --> F[Software Reference APU]
D --> G[XC7S50 FPGA]
G --> H[Hardware PPU]
G --> I[Hardware APU]
D --> J[HyperRAM - CPU]
G --> K[HyperRAM + SRAM - FPGA]
G --> L[Display - RGB TTL]
G --> M[Audio Codec - I2S]
```
## 8. Key Design Decisions & Rationale
| Decision | Rationale |
|------------------------------------|-----------|
| **FPGA handles PPU + APU** | Provides deterministic timing and high performance for graphics and audio |
| **CPU handles game logic** | Offers flexibility and easier development for AI, physics, and game systems |
| **Split HyperRAM architecture** | Avoids memory contention and gives each processor fast access to the memory it needs most |
| **Core Abstraction Layer** | Enables "write once, run anywhere" (emulator ↔ hardware) development |
| **FMC as main CPU-FPGA bus** | High bandwidth and low latency for transferring graphics commands and data |
---
This architecture is designed to be **coherent**, **developer-friendly**, and **balanced** between performance and ease of use. All major components work together through well-defined interfaces, with the Core Abstraction Layer serving as the central contract.

62
docs/GLOSSARY.md Normal file
View file

@ -0,0 +1,62 @@
# Glossary
This glossary defines the key terms used throughout the NekoBoy project. It exists to ensure consistency and to help newcomers (and AI assistants) quickly understand the terminology.
## Core Project Terms
**NekoBoy**
The full name of the handheld gaming console. It is a pocketable, open-source, cartridge-based 2D system focused on emotional experiences, beautiful music, and developer accessibility.
**NekoTracker**
The music creation tool for the platform. It exists in two main forms:
- **Desktop version**: Runs on PC with full features.
- **Hardware version**: Runs on the NekoBoy console (as a cartridge or loaded software) using the real PPU.
## Hardware Components
**PPU (Pixel Processing Unit)**
The graphics engine implemented in the FPGA. Responsible for rendering tiles, sprites, layers, palettes, and visual effects. Inspired by classic systems (Neo Geo / SNES) but enhanced for modern 2D development.
**APU (Audio Processing Unit)**
The sound engine implemented in the FPGA. Handles FM synthesis, PCM playback, mixing, and light post-processing effects (including lo-fi character).
**Core Abstraction Layer**
The shared software interface (written in C) that defines how games and tools communicate with the PPU and APU. This layer is the key to running the same code on both the emulator and real hardware with minimal changes.
**HyperRAM**
High-speed pseudo-static RAM used by both the CPU and FPGA. Provides large amounts of fast memory for game state, assets, framebuffers, and audio buffers.
**FMC (Flexible Memory Controller)**
The high-speed parallel bus on the STM32U575 used to communicate with the FPGA. Used for sending commands, sprites, and tile data from the CPU to the PPU.
**neko-asset**
The asset conversion tool for the project. It converts modern image files (PNG) created in tools like Pixelorama or Aseprite into formats usable by the Neko PPU.
## Software & Development Terms
**Emulator / Development Environment**
The PC software that simulates the NekoBoy hardware. It allows developers to create and test games (and run NekoTracker) on their computer before running on real hardware. It uses the Software Reference implementations of the PPU and APU.
**Software Reference PPU / APU**
The desktop implementations of the graphics and audio engines. They match the behavior of the hardware versions as closely as possible so that code written against the Core Abstraction Layer behaves consistently on both PC and hardware.
**M8-style Tracking**
The sequencer model used by NekoTracker: 8 tracks that are monophonic at the pattern level (one note per track at a time), while the instruments themselves can be internally polyphonic.
**Cartridge**
Physical game media for NekoBoy. Contains game code, assets, and save data. Uses QSPI NOR flash for ROM and FRAM for non-volatile saves.
## Other Important Terms
**STM32U575VIT6**
The main microcontroller (CPU) used in NekoBoy. Handles game logic, AI, physics, high-level control, and communication with the FPGA.
**XC7S50-2CSGA324I**
The FPGA used in NekoBoy. Implements both the PPU (graphics) and APU (audio).
**Lo-fi Features**
Optional post-processing effects in the APU (random pitch flutter, gentle bit-depth reduction, and vinyl-style crackle) to give music a warm, nostalgic character.
---
*This glossary should be updated whenever new important terms are introduced.*