RetroToolbox Development Guide

Expert guidance for working with RetroToolbox - a React-based retro arcade game collection featuring Snake++, Neon Pong, Brick Breaker, Tetris Remix, Space Defense, and Pac-Man.

Critical Configuration

**STATIC PORT REQUIREMENT**: RetroToolbox MUST use port 3004 exclusively:

Architecture Overview

The application uses a fully modular React architecture:

Development Workflow

Step 1: Essential Commands

```bash

Start development server (REQUIRED for testing)

npm run dev

Build production bundle

npm run build

Run linting

npm run lint

npm run lint:fix

TypeScript type checking

npm run typecheck

Install dependencies (after package.json changes)

npm install

```

Step 2: Testing with Playwright MCP

**CRITICAL**: After EVERY code change, test using the local Playwright MCP server.

#### Setup Playwright MCP (if not installed):

```bash

Install as dev dependency

npm install @playwright/mcp@latest --save-dev

Add local MCP server

claude mcp add playwright-headless -s local -- npx @playwright/mcp@latest --headless

Verify installation

claude mcp get playwright-headless

```

#### Testing Protocol:

1. **Navigate to the application**:

```typescript

mcp__playwright-headless__browser_navigate({ url: "http://localhost:3004" })

```

2. **Take screenshots before/after changes**:

```typescript

mcp__playwright-headless__browser_take_screenshot({ filename: "before-change.png" })

// Make code changes

mcp__playwright-headless__browser_take_screenshot({ filename: "after-change.png" })

```

3. **Test user interactions**:

```typescript

// Get page snapshot to find element refs

mcp__playwright-headless__browser_snapshot()

// Click on game

mcp__playwright-headless__browser_click({ element: "game button", ref: "element_ref" })

// Test keyboard input

mcp__playwright-headless__browser_press_key({ key: "ArrowRight" })

// Check console for errors

mcp__playwright-headless__browser_console_messages()

```

4. **Verify game states**:

- Game starts when arrow key pressed

- Score updates correctly

- Game over triggers appropriately

- Touch controls work on mobile view

Step 3: Testing Checklist

Before considering any change complete:

Step 4: Git Workflow

**CRITICAL**: After completing any major upgrade or bug fix, commit and push to GitHub.

```bash

Check status and review changes

git status

git diff

Stage changes

git add .

Commit with descriptive message

git commit -m "fix: resolve issue description

🤖 Generated with Claude Code

Co-Authored-By: Claude <[email protected]>"

Push to GitHub

git push

```

#### Commit Message Format:

Advanced Debugging

Parallel Task Investigation Framework

For complex runtime errors (undefined property access, persistent bugs):

**5-Track Parallel Investigation:**

1. **Track A: Property Access Patterns**

```bash

search: \.x[\s\)\]\;\,]

search: \.position\.x

search: \.velocity\.x

```

2. **Track B: Array Operations**

```bash

search: \.splice\(

search: \.push\(.*x:

search: \.shift\(

```

3. **Track C: Event Coordinates**

```bash

search: clientX

search: e\.touches.*\.x

```

4. **Track D: Object Creation**

```bash

search: = \{.*x:

search: create.*\(

```

5. **Track E: Unprotected Loops**

```bash

search: forEach\(.*=>

search: for.*of.*

```

**Methodology:**

1. Launch 5 concurrent Task agents with specific search patterns

2. Each reports HIGH/MEDIUM/LOW risk findings

3. Apply fixes in priority order

4. Test with Playwright after each batch

5. Use pattern-based searches, not line numbers

**Example Fix:**

```typescript

// Before (HIGH RISK):

particle.velocity.x += particle.acceleration.x * deltaTime;

// After (SAFE):

if (!particle || !particle.velocity || !particle.acceleration) continue;

particle.velocity.x += particle.acceleration.x * deltaTime;

```

Adding New Games

1. Create new component in `src/components/games/`

2. Follow patterns from existing games

3. Import and add to `gameComponents` in `src/App.tsx`

4. Add metadata to `games` array

5. Integrate with core systems (Sound, Particles, Input)

6. Test thoroughly on desktop and mobile

Core Systems Reference

SoundManager (`src/core/SoundManager.ts`)

Web Audio API sound engine with methods:

InputManager (`src/core/InputManager.ts`)

Unified input handling for keyboard, mouse, touch, gamepad

ParticleSystem (`src/core/ParticleSystem.ts`)

High-performance visual effects system

Performance Considerations

State Management

Important Notes

1. Always run `npm run dev` before testing

2. Refresh page after changes

3. Check console messages for errors

4. Take screenshots to document issues

5. Test on different screen sizes

6. Verify all game states (ready, playing, paused, game over)

7. Use pattern-based debugging over line numbers

8. Commit frequently with clear messages

9. Test before committing

10. Never commit broken code