nes-php-glfw AGENTS.md

Codex Development Guidelines for NES Emulator

This document provides guidelines for AI-assisted development of this NES (Nintendo Entertainment System) emulator written in PHP.

Agent Document Source of Truth

• AGENTS.md is the master agentic development document for this repository.
• If another agentic development document disagrees with AGENTS.md, follow AGENTS.md.
• Keep all other agentic development documents in sync with AGENTS.md, including .cursorrules, CLAUDE.md, .github/copilot-instructions.md, and .junie/guidelines.md.
• When changing agent guidance, update AGENTS.md first, then update the corresponding Cursor, Claude, Copilot, Junie, and contributor-facing documentation in the same change.

Project Overview

This is a cycle-accurate NES emulator implementation in PHP 8.5+ using:

• Graphics: PHP-GLFW (OpenGL) via the VISU framework
• Architecture: 6502 CPU emulation, PPU (Picture Processing Unit), APU (Audio Processing Unit - planned)
• Testing: PHPUnit with comprehensive unit and integration tests
• Quality: PHPStan for static analysis, Laravel Pint for code formatting

Code Style & Standards

Documentation

Properties and Methods:

• All properties must have docblocks describing their purpose
• All methods must have docblocks describing what they do
• Only include @param or @return when generics need to be declared (e.g., list<int>, array<int, string>)
• Use @throws, @see, or @inheritDoc when appropriate
• Do NOT add class-level docblocks

Example:

/**
 * The current PPU cycle within a scanline.
 */
private int $cycle = 0;

/**
 * Executes a single CPU instruction and returns the number of cycles consumed.
 *
 * @throws \RuntimeException
 */
public function run(): int
{
    // ...
}

Comments

General Rules:

• Remove superfluous comments that merely restate the code
• All comments must end with a period (.)
• Multi-line comments use C-style /* */ syntax
• Single-line comments use // syntax
• Keep comments that explain complex logic or non-obvious behavior