{"id":50909939,"url":"https://github.com/a2v10/pdp11-emulator","last_synced_at":"2026-06-16T09:02:40.626Z","repository":{"id":364047288,"uuid":"1266139694","full_name":"a2v10/pdp11-emulator","owner":"a2v10","description":"A PDP-11 emulator, a MACRO-11 assembler and Arkanoid written in PDP-11 assembly — built in a single Claude Code session, guided by an engineer who remembers the real thing.","archived":false,"fork":false,"pushed_at":"2026-06-11T11:58:52.000Z","size":123,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-11T13:16:50.744Z","etag":null,"topics":["ai-assisted-coding","ai-pair-programming","anthro","claude","claude-code"],"latest_commit_sha":null,"homepage":"https://pdp11-arkanoid.azurewebsites.net","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/a2v10.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-11T11:00:02.000Z","updated_at":"2026-06-11T11:58:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/a2v10/pdp11-emulator","commit_stats":null,"previous_names":["a2v10/pdp11-emulator"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/a2v10/pdp11-emulator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a2v10%2Fpdp11-emulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a2v10%2Fpdp11-emulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a2v10%2Fpdp11-emulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a2v10%2Fpdp11-emulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/a2v10","download_url":"https://codeload.github.com/a2v10/pdp11-emulator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a2v10%2Fpdp11-emulator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34398408,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assisted-coding","ai-pair-programming","anthro","claude","claude-code"],"created_at":"2026-06-16T09:02:39.813Z","updated_at":"2026-06-16T09:02:40.621Z","avatar_url":"https://github.com/a2v10.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PDP-11 / Arkanoid\n\nA PDP-11 emulator in TypeScript: a dependency-free core, an assembler\n(MACRO-11 subset), a React shell for the browser — and two games written\nin PDP-11 assembly: Arkanoid and Tetris. Switch between them with the\ntabs above the screen.\n\n\n![Arkanoid running on the emulator](docs/Screenshot.png)\n\n\n**Live: https://pdp11-arkanoid.azurewebsites.net/**\n\nControls — Arkanoid: ← → move the paddle, Space (or ↑) launches the ball.\nTetris: ← → move, ↑ / Space rotate, ↓ soft-drop. On a phone an on-screen\njoystick appears. Pause the emulator to inspect the CPU registers mid-game.\n\nTetris on a PDP-11 is no accident: the original was written by Alexey\nPajitnov in 1984 on an Elektronika-60, a Soviet PDP-11 clone — so this\nruns it on (an emulation of) the machine it was born on.\n\n## The experiment\n\nThis project is an experiment in AI-assisted development: the entire thing —\nthe emulator core, the assembler, the React shell, the Arkanoid game in\nPDP-11 assembly, the tests and the deployment pipeline — was written in a\nsingle conversation with [Claude Code](https://claude.com/claude-code),\nguided by an engineer with 40+ years of experience who remembers the real\nPDP-11 era. The human set the architecture straight more than once (no 64K\ndecode lookup table in 1975 — the decoder is a switch cascade mirroring the\ncombinational logic of the real machine); the AI typed fast and kept the\ntest suite green. Total time from \"let's sketch the modules\" to the deployed\npublic site: one day.\n\n## Memory map (addresses in octal)\n\n| Range           | Size   | Purpose                                          |\n|-----------------|--------|--------------------------------------------------|\n| 000000–000377   | 256 B  | Interrupt and trap vectors                       |\n| 000400–057777   | ~24 KB | Code, data, stack                                |\n| 060000–157777   | 32 KB  | Framebuffer 512×512, 1 bpp, 64 bytes per row     |\n| 160000–177777   | 8 KB   | I/O page                                         |\n\nPixel (x, y): byte `060000 + (y \u003c\u003c 6) + (x \u003e\u003e 3)`, bit `x \u0026 7`.\n\n### Device registers\n\n| Address | Device | Description |\n|---------|--------|-------------|\n| 177544  | Speaker | bit 0 is the cone position, Sinclair Spectrum style. There is no tone generator: the program toggles the bit and the toggle rate *is* the pitch. Music costs CPU cycles, like it did in 1982. |\n| 177546  | KW11 line clock | bit 6 — interrupt enable, bit 7 — tick flag. Ticks at 60 Hz, interrupts through vector 100 at priority 6. This is the game's \"vsync\". |\n| 177570  | Joystick | read-only: bit 0 — left, bit 1 — right, bit 2 — fire, bit 3 — down. A mask of the *currently held* buttons. |\n\nThe game uses the speaker for bounce/brick effects and plays Korobeiniki\nwhile the ball waits on the paddle — the tune Tetris made famous, and\nTetris was written on an Elektronika-60, a Soviet PDP-11 clone.\n\n## Modules\n\n- `src/core/` — the emulator core, pure TS, knows nothing about the browser:\n  - `memory.ts` — 64 KB, one `ArrayBuffer` with byte and word views;\n  - `bus.ts` — address routing, I/O page dispatch, an `onAccess` hook;\n  - `cpu.ts` — registers R0–R7, PSW, all 8 addressing modes, step(), traps\n    and interrupts;\n  - `instructions.ts` — two cooperating forms of the instruction set:\n    `decode()` — **a cascade of nested switches over the octal fields of the\n    instruction word**, the software analog of the combinational decode\n    network in the real processor (the structure mirrors the opcode map in\n    the PDP-11 Processor Handbook); and `DEFS` — the \"programmer's reference\n    card\": data that feeds the assembler, the disassembler and the UI.\n    A test cross-checks the two on all 65536 opcode words;\n  - `machine.ts` — the assembled machine + state snapshots (rewind/replay);\n  - `devices/` — KW11, joystick, one-bit speaker.\n- `src/asm/` — a two-pass assembler, MACRO-11 subset: labels, `SYM = expr`,\n  `. = addr`, `.WORD/.BYTE/.ASCII/.ASCIZ/.BLKW/.BLKB/.EVEN/.END`, expressions\n  (octal by default, `64.` for decimal, `'A` for a character, left-to-right\n  evaluation with no operator precedence — just like the real MACRO-11), all\n  addressing modes. Output: an image + a symbol table + an address ↔ source\n  line map for the debugger.\n- `src/web/` — the React shell: a canvas screen (framebuffer → ImageData once\n  per frame), keyboard → joystick, Run/Pause/Step/Frame, a register panel,\n  an assembly editor. `npm run dev` → http://localhost:5173.\n- `programs/arkanoid.s` — Arkanoid: a 6×15 brick field, a 4×4 ball with\n  per-pixel movement (bit mask tables), bounce angle controlled by where the\n  ball hits the paddle, a score rendered in a 5×7 digit font, lives.\n  `programs/tetris.s` — Tetris: a 10×20 well of 24×24 cells, seven pieces ×\n  four rotations packed as 4×4-box cell tables, the board as 20 row bitmasks,\n  full-line clears with BCD scoring, levels that speed up gravity, an LFSR\n  piece bag, delayed auto-shift, and one-bit sound. No multiply or divide —\n  the whole layout is powers of two, so addressing stays additive.\n  `programs/demo.s` — a simple bouncing-ball demo.\n\n## Slots for the future \"learning mode\"\n\nDesigned in and covered by tests; a UI can plug in without touching the core:\n\n- `cpu.tracer` — an event per executed instruction (PC, opcode, name, PSW);\n- `bus.onAccess` — observes every memory/device access;\n- `Machine.snapshot()/restore()` — the full machine state; the core is\n  deterministic, so \"initial state + per-frame inputs\" gives exact replay\n  and rewind;\n- `InstrDef.units` — which functional units an instruction engages (for a\n  future animated CPU schematic);\n- `cpu.cycles` — an approximate cycle counter.\n\n## Authenticity and simplifications\n\nThe base instruction set is implemented (no EIS, FPU or MMU — with a\n512-pixel row all address arithmetic reduces to shifts). Faithfully done:\nbyte order, autoincrement by 1/2, MOVB sign-extension into registers, the\nodd-address trap (vector 4), bus timeout on unmapped I/O addresses,\ninterrupt priorities, WAIT, RTI/RTT, EMT/TRAP, double-fault handling.\n\n## Commands\n\n```\nnpm run dev        # Vite dev server\nnpm run build      # production build\nnpm test           # vitest, core/asm/game tests\nnpm run typecheck  # tsc --noEmit\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa2v10%2Fpdp11-emulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fa2v10%2Fpdp11-emulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa2v10%2Fpdp11-emulator/lists"}