Menu
Use this skill for LLM-driven NES game development in 6502 assembly with iterative planning, coding, testing, and debugging.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | Claude NES Agentic Development |
| description | Use this skill for LLM-driven NES game development in 6502 assembly with iterative planning, coding, testing, and debugging. |
Guide LLM agents (such as Claude) to build, refactor, test, and debug NES games in 6502 assembly and C. This skill integrates curated wiki projects, tooling references, core memory maps, architectural guardrails, and modular prompt templates to enable reliable, iterative development under strict NES hardware constraints.
Based on the official NESdev Wiki lists, use the following tools depending on the project's language stack, complexity, and assets:
.cfg) allowing full custom memory mapping, powerful macro system, excellent integration of assembly with C..ftm files..tmx JSON/XML formats into compressed RLE or raw tile indexes for assembly inclusion.Refer to these established templates from the NESdev Projects wiki to bypass boilerplate system setup:
https://github.com/rainwarrior/ca65-nes-templatehttps://github.com/igwgames/nes-starter-kitcc65 and neslib. Includes tile manipulation, metasprite systems, sound drivers, scrolling, and map engines. This is the recommended template for agents to get started fast and prototype game logic rapidly.Always enforce the following physical limitations in plans and edits to prevent memory corruption and hardware lockups:
JSR/RTS), and interrupt contexts. Do not store general variables here.$4014.If a game expands beyond 32KB PRG-ROM (code) or 8KB CHR-ROM (graphics), select and implement mapper configs:
Developing visual assets for the NES requires translating modern raster images and map formats into the specific byte configurations expected by the Picture Processing Unit (PPU).
$23C0–$23FF).To design background levels, configure Tiled as follows:
Modern LLMs can be utilized to generate raw tile bytes, sprite assembly tables, or custom conversion scripts.
.db assembly directives, or Python conversion code.You are an NES CHR graphics generator. I need the raw 16-byte hex format representing an 8x8 pixel tile for a simple "Coin" icon.
Constraints:
- 2 bits-per-pixel (planar format: Plane 1 is first 8 bytes, Plane 2 is second 8 bytes).
- Color 0: Transparent
- Color 1: Inner yellow (index %01)
- Color 2: Outer gold outline (index %10)
- Color 3: Highlights (index %11)
Design the coin as a circular shape with highlights. Provide the 16 bytes in ca65 .byte format and explain which pixel index each bit represents.
Write a robust Python 3 script that takes a 128x128 PNG image containing a tileset of 8x8 NES tiles and outputs a raw .chr binary.
The script must:
1. Verify that the image width and height are multiples of 8.
2. Read the image and map the pixels to a 4-color palette (0, 1, 2, 3) based on brightness or direct color values.
3. Convert each 8x8 block into the NES PPU format:
- First 8 bytes define Bit 0 of the color index for each of the 8 rows.
- Next 8 bytes define Bit 1 of the color index for each of the 8 rows.
4. Output a clean binary file (.chr). Include error handling for invalid sizes.
The Audio Processing Unit (APU) generates sound using five dedicated hardware channels. Managing music and sound effects requires a balance of timing, register mapping, and driver selection.
To create complete soundtracks using a traditional MIDI workflow:
.mid files.music_data.s) along with sound effect definitions (sfx.s).Sound effects can be triggered in two ways: through a driver API or by writing directly to hardware registers.
For quick, driver-less sound effects, write directly to the APU registers during gameplay cycles.
LDA #$3F ; Envelopes: Constant volume, volume level 15 (max)
STA $400C
LDA #$1C ; Frequency: Periodic noise mode, shift frequency
STA $400E
LDA #$18 ; Length Counter load
STA $400F
LDA #$87 ; Duty cycle 50%, constant volume, decay speed
STA $4000
LDA #$93 ; Enable sweep, shift count 3, sweep downwards
STA $4001
LDA #$C0 ; Low byte of frequency timer
STA $4002
LDA #$08 ; High byte of frequency timer + start length counter
STA $4003
If using a standard audio driver, include the exported assembly assembly sound assets and call the engine's play macro:
; Trigger inside gameplay logic when an event occurs
LDA #SFX_EXPLOSION ; SFX index in your exported .sfx file
LDX #$00 ; Play on Channel 0 (Pulse 1 Priority)
JSR FamiToneSfxPlay ; Let the driver handle frame-by-step register updates
A commercial-grade NES game is structured around a central Game State Machine. Transitions between screens (Title, Gameplay, Pause, Game Over) must be handled gracefully to prevent PPU artifacting and code lockups.
┌──────────────┐
│ Cold Reset │
└──────┬───────┘
▼
┌──────────────┐ Start Press
│ Title Screen ├──────────────┐
└──────▲───────┘ │
│ ▼
│ ┌──────────────┐
Game │ │ Gameplay │
Over │ │ Main Loop │
│ └──────┬───────┘
│ ▲ │
│ Start Press │ │ Player
│ (Toggle) │ │ Dies /
┌──────┴───────┐ ┌─┴────▼──────┐ Wins
│ Game Over │ │ Pause Screen│
│ (Win/Lose) │ └─────────────┘
└──────────────┘
Instead of nesting complex branch instructions (BEQ/BNE), implement a jump table based on a state variable gameState:
; Zero page allocations
.zeropage
gameState: .res 1 ; 0=Title, 1=Gameplay, 2=Pause, 3=GameOver, 4=Victory
.code
UpdateGame:
LDA gameState
ASL A ; Multiply state by 2 to get word index
TAX
LDA StateJumpTable, x
STA tmp_ptr
LDA StateJumpTable+1, x
STA tmp_ptr+1
JMP (tmp_ptr) ; Indirect jump to the active state function
StateJumpTable:
.addr UpdateTitleScreen
.addr UpdateGameplay
.addr UpdatePauseScreen
.addr UpdateGameOver
.addr UpdateVictoryScreen
LDA #0, STA $2001).$2000+).LDA #%00011110, STA $2001) during the next VBlank.UpdateTitleScreen):
gameState to 1 (Gameplay).UpdateGameplay):
ppu_draw_queue).gameState to 3 (Game Over). If level completion conditions are met, switch to 4 (Victory).LDA #$02, STA $4014) to render players and enemies.ppu_draw_queue. If entries exist, write those tiles to PPU $2006/$2007.$2005 to prevent visual sliding.gameState to 2.UpdatePauseScreen):
jsr FamiToneUpdate) and NMI sync loops so the background track continues playing and the screen does not crash or flicker.gameState to 1 (Gameplay).Follow this cycle for every development ticket:
┌──────────────────────────────────────────────────────────┐
│ 1. Environment Audit & Memory Budgeting │
│ - Read config files (.cfg), variable tables, zero page │
└───────────────────────────┬──────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────┐
│ 2. Feature Slicing & Planning │
│ - Define precise memory addresses and registers to use│
└───────────────────────────┬──────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────┐
│ 3. Surgical Assembly/C Implementation │
│ - Use local labels, correct addressing modes, comments│
└───────────────────────────┬──────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────┐
│ 4. Build & Emulator Verification │
│ - Run Makefile/compilation, inspect compiler errors │
│ - Boot emulator, verify memory map changes, log outcomes│
└───────────────────────────┬──────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────┐
│ 5. CodeQL Analysis & Small Atomic Commit │
│ - Run codeql_checker, commit safely, push to PR │
└──────────────────────────────────────────────────────────┘
Keep this checklist at hand during implementation to avoid common retro-programming traps:
CLC (Clear Carry) immediately before ADC (Add with Carry). Always execute SEC (Set Carry) immediately before SBC (Subtract with Carry). Failing to do so introduces off-by-one arithmetic errors.BCC, BCS, BEQ, BNE, BPL, BMI, BVC, BVS) are limited to a signed 8-bit offset (-128 to +127 bytes). For larger jumps, invert the branch condition and use JMP (Jump, which supports a 16-bit absolute address).PHA) and index registers (TXA, PHA, TYA, PHA) to the stack, and restore them in exact reverse order (PLA, TAY, etc.) before calling RTI (Return from Interrupt).$2006/$2007) during VBlank (inside the NMI) or when rendering is disabled ($2001 is zero). Writing outside this window corrupts background graphics and halts rendering.$2006 is a 16-bit latch written via two consecutive 8-bit writes (High byte, then Low byte). Always read $2002 (PPU Status) before writing to $2006 to reset the PPU flip-flop latch state and prevent high/low byte misalignment.$2006 modifies internal scroll registers, so executing any $2006 write after $2005 will scramble the screen scroll. Always reset scroll via $2005 writes (X scroll, then Y scroll) right before finishing the PPU update.LDA #$02, STA $4014) at the beginning of the VBlank/NMI sequence to ensure it finishes within the short VBlank timing window.$FFFC–$FFFD) completely clears internal CPU RAM ($0000–$07FF), waits for the PPU to stabilize (by reading $2002 and waiting for vblank twice), and sets up stack pointer (LDX #$FF, TXS).Copy and use these templates to optimize Agent context and performance.
You are an expert NES (6502) assembly development agent.
You are tasked with implementing the following feature: [INSERT FEATURE DESCRIPTION HERE]
Before writing code, construct a detailed implementation plan. You must output:
1. Memory Map Impact:
- What Zero Page ($00-$FF) variables are needed? Provide exact address allocations.
- What CPU SRAM ($0300+) variables are needed?
2. PPU/VRAM Impact:
- Does this need nametable updates?
- What palettes or CHR sprites are utilized?
3. NMI vs Main Loop Split:
- What logic runs in the NMI (PPU/VRAM writes, audio updates)?
- What logic runs in the Main Loop (input polling, physics, state changes)?
4. Step-by-Step Code Slices:
- Outline at least 3 incremental, testable slices to implement this feature.
Wait for my approval of the plan before generating assembly code.
The game currently suffers from the following bug: [INSERT BUG SYMPTOMS - e.g., "Background scroll is scrambled after drawing sprites"]
Analyze the code under the lens of the expert NES Assembly Developer:
1. Examine PPU Latch ($2006) writes. Are they properly paired with an initial read of $2002 to reset the latch flip-flop?
2. Verify scroll registers ($2005). Are scroll values written AFTER all $2006 PPU writes are finished?
3. Check status flags and registers. Are index registers corrupted by intermediate subroutines?
4. Look at VBlank timing. Is the Sprite DMA ($4014) triggered first, and are VRAM writes fitting within the safe VBlank period?
Provide the smallest, safest, surgical correction to fix the root cause.
Examine the existing game variables and RAM configuration.
Build and update a consolidated Markdown table mapping current memory usage:
| Address Range | Size (Bytes) | Scope (ZP/RAM/OAM) | Variable Name | Purpose / Use Case |
|---|---|---|---|---|
| $0000–$000F | 16 | ZP | System Registers | Temp math, loop counters |
| [ADDRESS] | [SIZE] | [ZP/RAM/OAM] | [NAME] | [PURPOSE] |
Highlight any overlaps, potential stack collisions, or variable safety issues in our current code path.
make or ca65) immediately after any code edit to catch syntax errors, label redefinitions, or branch range overflows.PPU_CTRL = $2000, PPU_MASK = $2001, etc.) as clear constants. Do not use raw values inside subroutines.