# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**Starclear NES** is a Galaga-style scrolling space shooter game for the Nintendo Entertainment System, written in 6502 assembly language. The game includes player lives, enemy waves, collision detection, bullet systems, random star field background, and basic game state management. This is a learning-focused NES homebrew development project with modern tooling and testing infrastructure.

## Development Philosophy & Goals

**Starclear NES** is an experiment in modern NES development - applying contemporary software engineering practices to retro hardware constraints. This is primarily a learning project designed to explore the intersection of modern development methodologies and vintage computing platforms.

### Project Goals
- **Learning-Focused**: Primary goal is education in NES development, 6502 assembly, and modern testing practices
- **Complete Game**: Despite simplicity, will include all core features of a finished Galaga-style game
- **Educational Codebase**: MIT-licensed source code designed to be instructional for other NES developers
- **Real Hardware Compatible**: Game plays correctly on real NES hardware loaded via FPGA cartridge

### Technical Philosophy
- **Modern Testing on Retro Platform**: Extensive Python unit testing with 6502 CPU emulation validates assembly logic
- **Performance First**: Target 60 FPS gameplay with zero dropped or delayed frames
- **Simplicity Over Features**: Deliberately minimal feature set focused on core gameplay mechanics
- **Mapper Enhancement Friendly**: Open to using advanced mappers while maintaining real hardware compatibility
- **Test-Driven Assembly**: Use Python reference implementations to verify complex 6502 algorithms

### Development Approach
- **Solo Project**: No external contributions sought, but codebase designed for educational value
- **Modern Release Process**: Git-based semantic versioning, automated builds/testing, and web distribution
- **Reproducible Builds**: All dependencies embedded in source tree for long-term buildability

### Project Management

- `project/` - contains project management related files.
- `project/TODO.md` - contains tasks backlog, in progress, and completed.

## Development Commands

### Build System
- `make` or `make build-pass` - Full build with testing
- `make test` - Run Python unit tests for game logic
- `make run` - Build and launch in FCEUX NES emulator
- `make clean` - Remove build artifacts
- `make package` - Create versioned distribution in dist/
- `make deploy` - Deploy built ROM to web server via rsync

### Release Management
- `make release-major` - Bump major version and create Git tag
- `make release-minor` - Bump minor version and create Git tag  
- `make release-patch` - Bump patch version and create Git tag
- All releases require corresponding CHANGELOG.md entries
- Automated versioning uses Git tags (semantic versioning)
- Deployment to `mddhosting:public_html/starclear-nes.git/dist/`

### Development Workflow
- Primary development happens in `src/*.6502.asm` assembly files
- Tests are in Python in the `test/` directory using py65 CPU emulation
- Graphics assets converted via `gif2chr.py` from `tileset.gif`
- All releases must pass automated testing
- Version management through Git tags with semantic versioning
- Deployment pipeline via `make deploy` for web distribution

## Development Environment

### Native Development
Install dependencies directly on Ubuntu/Debian-based systems using the `install-packages-ubuntu.sh` script.

## Architecture

### Core Technologies
- **Target Platform**: Nintendo Entertainment System (NES)
- **Assembly Language**: 6502 with ASL (Macro Assembler AS)
- **Build System**: GNU Make with embedded toolchain
- **Testing**: Python 3 with py65 CPU emulator and pytest framework
- **Graphics Pipeline**: PIL (Python Imaging Library) for GIF to CHR conversion
- **Deployment**: rsync for automated web distribution

### Source Organization
- `src/starclear.6502.asm` - Main ROM entry point and module includes
- `src/nesheader.6502.asm` - iNES ROM header definition
- `src/variables.6502.asm` - Zero-page variable allocation system using macros
- `src/constants.6502.asm` - Centralized magic numbers and game constants
- `src/start.6502.asm` - System initialization and NES setup
- `src/nmihandler.6502.asm` - VBlank interrupt handler (main game loop)
- `src/irqhandler.6502.asm` - IRQ interrupt handler
- `src/player.6502.asm` - Player entity logic and movement
- `src/player_bullet.6502.asm` - Player bullet system (separated from player logic)
- `src/enemy.6502.asm` - Enemy entity logic and AI
- `src/enemy_bullet.6502.asm` - Enemy bullet system (separated from enemy logic)
- `src/controller.6502.asm` - NES controller input handling
- `src/ppu.6502.asm` - Picture Processing Unit utilities and macros
- `src/print.6502.asm` - Text rendering and on-screen text display
- `src/math.6502.asm`, `src/random.6502.asm` - Mathematical and RNG utilities

### Memory Management
Uses a macro-based system for zero-page variable allocation:
- `newvar VARNAME` - Allocate single byte variable
- `newarr ARRAYNAME, SIZE` - Allocate array
- Variables auto-assigned to zero-page addresses for 6502 efficiency

### Testing Infrastructure
- Python unit tests in `test/` validate assembly implementations
- `py65` library provides 6502 CPU emulation for testing
- `pytest` framework for test organization and execution
- Tests compare assembly code results against Python reference implementations
- Symbol resolution via ASL map file parsing (`aslmap.py`)
- Current test coverage is limited but expanding (performance testing implemented)
- Performance testing measures NMI handler CPU cycle counts
- All builds must pass testing before deployment

### Asset Pipeline
- `gif2chr.py` converts 4-color GIF tiles to NES CHR-ROM format
- `tileset.gif` → `chr.rom` conversion integrated into build
- Uses PIL for image processing

### Dependencies

#### Build Dependencies (Ubuntu/Debian)
- `build-essential`, `texlive`, `texlive-lang-german` - ASL assembler compilation
- `python3`, `python3-pil` - Graphics asset pipeline
- `cmake`, `qtbase5-dev`, `pkg-config`, `zlib1g-dev`, `libminizip-dev` - FCEUX emulator
- `libsdl2-dev`, `liblua5.1-dev`, `qttools5-dev` - FCEUX runtime dependencies
- `libx264-dev`, `libx265-dev`, `libavcodec-dev`, `libavformat-dev` - Video encoding
- `libavutil-dev`, `libswscale-dev`, `libswresample-dev`, `cppcheck` - Development tools

#### Python Dependencies (requirements.txt)
- `pillow==11.2.1` - Image processing for CHR conversion
- `pytest==8.4.1` - Testing framework
- `pygments==2.19.2` - Syntax highlighting
- `iniconfig`, `packaging`, `pluggy` - Testing infrastructure

#### Embedded Dependencies
Complete source trees included for reproducible builds:
- `vendor/asl/` - ASL macro assembler source
- `vendor/fceux/` - FCEUX NES emulator source
- `vendor/py65/` - py65 6502 emulator library

### NES-Specific Constraints
- 6502 CPU @ 1.79MHz, 2KB RAM, 32KB PRG-ROM, 8KB CHR-ROM
- PPU renders 8x8 tiles, 256x240 resolution
- VBlank timing critical for graphics updates
- Zero-page memory ($00-$FF) used for frequently accessed variables

## Key Development Patterns

1. **Modular Assembly**: Each `.6502.asm` file handles specific game subsystem
2. **Macro-Heavy**: Extensive use of ASL macros for code reuse and memory management
3. **Test-Driven**: Critical game logic validated via Python unit tests with CPU emulation
4. **Modern Release Management**: Git-based versioning, automated builds/testing, and web deployment despite retro target platform
