An advanced NES space shooter written in pure 6502 assembly, showcasing mastery-level programming techniques and demonstrating that LLMs can write sophisticated, optimized assembly code.
Stellar Assault is a vertical scrolling space shooter that pushes the limits of the NES hardware while maintaining clean, readable, and well-documented code. The game demonstrates advanced programming techniques including object pooling, optimized collision detection, and efficient sprite management.
- Smooth 8-directional player movement with responsive controls
- Rapid-fire bullet system supporting up to 8 concurrent player bullets
- Dynamic enemy spawning with up to 16 simultaneous enemies
- Wave-pattern enemy AI with sine-wave movement algorithms
- Pixel-perfect collision detection using optimized AABB checks
- Sound effects using custom APU sound engine
- Zero-page optimization - Critical variables placed in fast zero-page memory
- Object pooling - Efficient memory management for bullets and enemies
- Structure-of-arrays - Cache-friendly data layout for game objects
- Unrolled loops - Performance optimization in critical paths
- Frame-synchronized gameplay - NMI-driven game loop at 60 FPS
- OAM DMA - Fast sprite uploads during VBlank
- PPU register manipulation - Proper use of PPUCTRL, PPUMASK, PPUSCROLL
- APU sound programming - Pulse and noise channels for sound effects
- CHR-ROM management - Custom sprite graphics generation
- Proper timing - VBlank synchronization and cycle-accurate operations
- Clean separation of concerns - Modular code organization
- Comprehensive comments - Every system thoroughly documented
- Consistent naming conventions - Clear, readable code structure
- No spaghetti code - Well-structured control flow
- Educational value - Code serves as learning resource for NES development
| System | Implementation | Details |
|---|---|---|
| Player | update_player | 8-direction movement, shooting, invincibility frames |
| Bullets | spawn_bullet, update_bullets | Object pool of 8 bullets, velocity-based movement |
| Enemies | spawn_enemies, update_enemies | Wave patterns, 16-object pool, AI behaviors |
| Collision | check_collisions | AABB algorithm, O(n×m) with early exit optimization |
| Rendering | render_sprites | Dynamic OAM generation, sprite multiplexing ready |
| Sound | update_sound | APU register programming, shoot/hit effects |
| Input | read_controller | Controller strobing with proper timing |
- GCC (for compiling asm6f)
- Python 3 (for CHR-ROM generation)
- Make
# Clone the repository
git clone https://github.com/web3dev1337/stellar-assault.git
cd stellar-assault
# Build the ROM
make
# The ROM will be at: build/stellar-assault.nes# 1. Build asm6f assembler
wget https://raw.githubusercontent.com/freem/asm6f/master/asm6f.c -O tools/asm6f.c
gcc -o tools/asm6f tools/asm6f.c
# 2. Generate CHR-ROM graphics
python3 tools/generate_chr.py
# 3. Assemble ROM
./tools/asm6f src/main.asm build/stellar-assault.nesLoad build/stellar-assault.nes in any NES emulator:
- D-Pad: Move player ship
- A Button: Shoot
- Start: Pause (future)
| Metric | Value |
|---|---|
| ROM Size | ~24 KB |
| PRG-ROM | 32 KB (2 × 16 KB banks) |
| CHR-ROM | 8 KB (sprite graphics) |
| Mapper | 0 (NROM) |
| Mirroring | Vertical |
| Lines of Code | ~750 (assembly) |
| Zero-page usage | 17 bytes |
| RAM usage | ~80 bytes |
| Sprites | Up to 64 (player, bullets, enemies) |
| Frame rate | 60 FPS (NTSC) |
The codebase is organized into logical modules:
src/
├── main.asm # Core game loop and NMI handler
├── constants.inc # Hardware registers and game constants
└── macros.inc # Reusable assembly macros
Game Systems:
├── Reset Handler # Initialization sequence
├── Main Loop # Frame-based update loop
├── NMI Handler # VBlank processing (OAM DMA, scroll)
├── Player System # Movement, shooting, state
├── Bullet System # Spawning, updating, pooling
├── Enemy System # AI, spawning, movement patterns
├── Collision System # AABB detection
├── Rendering System # Sprite OAM generation
└── Sound System # APU programming
This project serves as an educational resource for:
- 6502 Assembly Programming - Real-world examples of optimization techniques
- NES Development - Proper use of PPU, APU, and controller hardware
- Game Programming - Object pooling, collision detection, game loops
- Retro Computing - Understanding hardware constraints and optimization
See CLAUDE.md for complete 6502 and NES development documentation.
This entire project was generated by Claude (Anthropic's AI assistant) using claude.com/code to demonstrate that:
- LLMs can write complex, low-level assembly code
- AI-generated code can be optimized, readable, and well-documented
- Automated development workflows are possible even for retro platforms
All code was written without human intervention, including:
- Complete 6502 assembly implementation
- CHR-ROM graphics generation
- Build system and CI/CD pipeline
- Comprehensive documentation
stellar-assault/
├── src/ # Assembly source code
├── assets/ # Graphics data (CHR-ROM)
├── tools/ # Build tools (asm6f, CHR generator)
├── build/ # Build outputs
├── .github/ # CI/CD workflows
├── Makefile # Build system
├── CLAUDE.md # Complete 6502/NES development guide
└── README.md # This file
The project includes automated GitHub Actions workflows that:
- ✅ Build the ROM on every push
- ✅ Validate iNES header format
- ✅ Check ROM size constraints
- ✅ Upload build artifacts
- ✅ Generate build reports
Potential additions to showcase more advanced techniques:
- Sprite multiplexing (>8 sprites per scanline)
- Parallax scrolling backgrounds
- Music engine with multi-channel compositions
- Boss battles with multi-phase patterns
- Power-up system (weapon upgrades, shields)
- Particle effects for explosions
- Score and high-score system
- Title screen and game states
- CHR-RAM banking for dynamic graphics
- asm6f - Excellent NES assembler by freem
- NESdev Community - Invaluable documentation and resources
- Mesen2 - Outstanding emulator for development and testing
MIT License - see LICENSE file for details.
Built with 6502 assembly • Powered by Claude Code • Targeting NES/Famicom hardware