6502 Retro Games Dev Assistant

Expert assistance for the sixtyfiveohtwo repository - a collection of classic Apple II games (Telengard, Sabotage, Proving Grounds, TPro BBS) ported to modern web technologies while preserving their retro charm.

What This Skill Does

This skill provides specialized knowledge for working with a monorepo containing four interconnected retro games:

1. **Telengard** - React dungeon crawler RPG with procedural generation

2. **Sabotage** - React arcade shooter with canvas rendering

3. **Proving Grounds** - Express-based BBS door game

4. **TPro BBS** - Full BBS system recreation

The assistant understands the architecture, build system, testing approach, and game-specific algorithms for all four games.

Instructions

Initial Assessment

When a user asks for help with this codebase:

1. **Identify the game or component** - Determine which part of the monorepo is relevant

2. **Check for game-specific context** - Each game has its own `CLAUDE.md` with detailed technical information

3. **Understand the task type** - Development, debugging, testing, or deployment

Architecture Knowledge

The monorepo structure:

```

server.js (Express router)

├── /telengard/ (React SPA - Vite build)

├── /sabotage/ (React SPA - Vite build)

├── /provinggrounds/ (Express SSR - Socket.IO)

└── /tprobbs/ (Express SSR - EJS templates)

```

**Key technical details:**

Common Commands Reference

Root-level commands:

```bash

npm install # Install deps and build all games

npm start # Production server on port 3000

npm run dev # Dev server with hot reload

npm run build # Build all games

```

Per-game development:

```bash

Telengard

cd telengard && npm run dev # Dev at http://localhost:5173

Sabotage

cd sabotage/sabotage-web && npm run dev # Dev at http://localhost:5174

Proving Grounds

cd provinggrounds && npm run db:init && npm run db:seed

TPro BBS

cd tprobbs && node src/db/ensure.js # Safe init (doesn't delete data)

```

Testing:

```bash

cd telengard && npm run lint && npm run build

cd sabotage/sabotage-web && npm run lint && npm run build

cd provinggrounds && npm test

npx playwright test tprobbs/tests/e2e.spec.js

```

Development Workflow

When modifying code:

1. **Read game-specific CLAUDE.md first** - Each game has detailed architecture docs

2. **Test per-game, not full suite** - Run tests only for the game being modified

3. **Respect retro authenticity** - These are ports of 6502 assembly; preserve original algorithms

4. **Check build before commit** - All games must build successfully

Code Modification Guidelines

**For React games (Telengard, Sabotage):**

**For Express apps (Proving Grounds, TPro BBS):**

**Critical algorithms to preserve:**

Environment Setup

Ensure `.env` file exists (copy from `.env.example`):

Deployment

Railway deployment via `railway.json`:

Troubleshooting

**Build failures:**

1. Check per-game build: `cd [game] && npm run build`

2. Verify dependencies: `npm install` in both root and game directories

3. Check TypeScript errors: `npm run lint`

**Database issues:**

**Server routing:**

Best Practices

1. **Preserve authenticity** - These are historical recreations; don't modernize UX without reason

2. **Test in isolation** - Run per-game tests, not full monorepo suite

3. **Read disassembly notes** - Sabotage has original 6502 code comments in `.dis65` file

4. **Respect game-specific docs** - Each `CLAUDE.md` contains formula derivations and algorithm explanations

5. **Check health endpoint** - `/health` route must respond for Railway deployments

Examples

**Example 1: Adding a feature to Telengard**

1. Read `telengard/CLAUDE.md` for dungeon generation details

2. Modify state in `src/state/gameState.ts` (Zustand)

3. Update renderer in `src/renderers/`

4. Test: `cd telengard && npm run lint && npm run build`

**Example 2: Debugging Sabotage physics**

1. Check `sabotage/Sabotage.dis65` for original 6502 logic

2. Compare with `src/engine/update.ts` (TypeScript port)

3. Verify constants in `src/constants/game.ts`

4. Test: `cd sabotage/sabotage-web && npm run dev`

**Example 3: Database schema change**

1. For Proving Grounds: Modify `provinggrounds/src/db/schema.sql`

2. Reset: `cd provinggrounds && npm run db:init && npm run db:seed`

3. Update routes in `src/routes/` to match schema

4. Test: `cd provinggrounds && npm test`

Important Notes