PacArcadeComp

An arcade-accurate Windows player for a classic 1980 maze game, with modern extras you can switch off.

PacArcadeComp contains a software copy of the arcade machine's board (the memory map, the video and sound chips) and the game itself written as native C++ that reproduces the original program exactly (from your own pacman.zip it reads only the data tables: maze, text, levels, graphics and sound data). It does not contain a Z80 processor: every frame of the game, including its exact timing, was proved identical to the real program running on a Z80 (millions of frames, see docs/evidence/N48 and N49a), so the game behaves like the arcade board: same ghost behaviour, same speeds, same bugs (including the famous level 256). Around that machine sits a modern front end: menus, save states, rewind, game-pad support, screen effects and more.

This repository does not contain the game. No ROM, no artwork, no sound and nothing made from them is included. You supply your own copy of the ROM set (a file named pacman.zip). The name "PacArcadeComp" is a working title. The project is not affiliated with, authorised by or endorsed by the owners of the original game or its trademarks.

---

Contents

1. Download and run (Windows)
2. Features
3. Controls
4. Reset to defaults and achievements
5. Troubleshooting and FAQ
6. For people who want to look inside or change the game
7. How the project was made
8. Legal

---

Download and run (Windows)

You need: a Windows 10 or 11 PC (64-bit) and your own pacman.zip ROM set (the file you may legally use; the program checks that it is the right one and never changes, copies or uploads it).

1. Open the Releases page of this repository and download PacArcadeComp-2.0.0-win64.zip (under "Assets").
2. Right-click the downloaded zip, choose Extract All... and extract it somewhere (your Desktop is fine). Do not run the program from inside the zip.
3. Copy your pacman.zip into the extracted PacArcadeComp folder, next to PacArcadeComp.exe.
4. Double-click PacArcadeComp.exe.
   • Windows may show a blue "Windows protected your PC" window, because the program is new and not signed with a paid certificate. Click More info, then Run anyway.
   • If the program cannot find the ROM it says so and offers Choose file: pick your pacman.zip once; the choice is remembered.
5. Press 5 to insert a coin, 1 to start. Press Esc for the menu.

The release folder also contains REPORT-A-PROBLEM.bat: start the game with it instead of the exe if something goes wrong; it writes a problem_report.txt you can attach to an issue.

Features

Accuracy

• Plays exactly like the original program: every rule, speed table and quirk was proved identical, frame by frame, against the real code running on a Z80 (that Z80 emulator is kept only in tests/oracle for the tests, not in the game).
• Frame-exact timing (60.6 Hz like the arcade board), the original sound chip (three-voice wave generator) and the original video layout.
• Checked by an automated test suite against reference values and a second, independent prototype; many tests replay recorded play and compare the whole machine state frame by frame (tests/).
• High levels, including level 256, are tested against the arcade program (docs/evidence/S30A_level256_full.txt).

Play (Esc menu)

• Resume, Save state (F2) and Load state (F4), eight save slots with a picker, Rewind (Backspace).
• Game options: lives (1, 2, 3 or 5), bonus life (10000, 15000, 20000 or none), difficulty (normal/hard) and ghost names (normal/alternate): the arcade's own DIP-switch settings.
• Restart game, quit game, saved high score.

Display (Esc > DISPLAY)

• Window or full screen (F11), integer or fill scaling (F8), optional window frame (F7), ultrawide screens.
• Screen effects: scanlines (F5), CRT shadow mask, glow, curved screen with vignette, and four ready-made CRT presets.
• Surround: plain black, an original arcade-cabinet look, or an "ambient" glow; or your own picture (surround.png next to the exe).
• Frame rate (new in 2.1.0): 30, 60, 75, 100, 120, 144 or unlocked. The game itself always runs at the arcade's own speed; a higher frame rate only makes the sprites move more smoothly on your screen, like a modern game. 60 is the classic setting. Details: docs/notes/frame_rate.md.
• Smooth pacing at 180 Hz (F6; only at frame rate 60), help panel with every key, run summary after a game.

Controls (Esc > CONTROLS)

• Remap every key; use Xbox, PlayStation 4 and PlayStation 5 pads with matching button pictures; vibration; lightbar colours on PlayStation pads (yellow while playing, red near a ghost, blue when ghosts are blue).
• Pad buttons for menu, pause, save, load and rewind; the program shows keyboard or pad hints depending on what you used last.
• Mouse works in all menus. Pause when the window loses focus.

Modding

• Esc > GAME OPTIONS > RULES: ORIGINAL (the arcade program's own routines, the standard) or READABLE (the same rules written as C++, proved frame-for-frame identical).
• A text file rules.cfg changes the game's numbers without programming: speeds, scatter/chase and blue-ghost times, Cruise Elroy and ghost-house limits, points, the extra-life score. Three ready-made example mods in mods/. Modded games are marked MODDED and never count for records; the Reset to defaults button on the GAME OPTIONS page puts RULES back to ORIGINAL. See MODDING.md.

Statistics and records

• Per-run statistics, achievements (taken from the public RetroAchievements list for this game, none invented by us), recorder for replays used by the tests.

(The screenshots show only this program's own menus; the game's own artwork is not part of this repository.)

Controls

Key	Action	Key	Action
5	Insert coin	Esc	Menu
1 / 2	Start 1 / 2 players	F1	Pause
Arrows or W A S D	Move	F2 / F4	Save / load state
Backspace	Rewind	F5	Scanlines
F6	Smooth pacing	F7	Window frame
F8	Scaling	F9 / F10	Keys page / pad page
F11	Full screen	F12	Reset controls to standard

Everything can be changed in Esc > CONTROLS. The complete list of settings and where to find them is in docs/notes/settings_table.md.

Settings, controls, records and your high score are stored in %APPDATA%\PacmanPort (Windows key + R, type %APPDATA%\PacmanPort, Enter). Delete that folder to start fresh.

Reset to defaults and achievements

There is no Purist item in the menu. Instead two buttons called RESET TO DEFAULTS exist (press Enter twice: the first press only asks). On the DISPLAY page it puts the look back to the standard (frame rate, scanlines, scaling, window frame, key panel, CRT effects, surround) at once, without touching the game. On the GAME OPTIONS page it puts lives, bonus life, difficulty, ghost names and RULES back to the standard and restarts the game so they take effect. Neither touches your key and pad bindings, the saved high score, records, achievements or save slots. Lives, bonus life, difficulty and ghost names are put into the running game at the attract screen; otherwise they apply from the next game. Achievements can unlock only while every game setting is at its standard value; display settings and save states have no effect on them. The test suite proves that the standard state is identical to the plain emulator, frame for frame (docs/evidence/S34_purist.txt, docs/evidence/S34D_reset_to_defaults.txt, docs/evidence/S34E_two_resets.txt).

Cheats. The first menu page has its own CHEATS page (it is not part of GAME OPTIONS). It holds INVINCIBLE: ghosts that are not blue cannot catch Pac-Man; after a power pellet the blue ghosts are eaten as usual. While a game is played with it on, that game does not count for records, statistics or achievements (nothing unlocks, even if you switch it off again later in the same game; a new game counts again). It is never saved: every start of the program begins with it off, and RESET TO DEFAULTS does not switch it on or off.

Troubleshooting and FAQ

"Windows protected your PC". Click More info > Run anyway. The program is not code-signed (a certificate costs money). You can instead build it yourself (BUILDING.md).

The program says it cannot find the ROM. Put pacman.zip next to PacArcadeComp.exe or use "Choose file". The zip must be the Midway "pacman" set (the same 10 files MAME uses); the message names what is wrong if it is a different set.

Where do I get the ROM? This project cannot provide it or point you to it. You must own the game and have the right to use the file.

There is no sound. Check the Windows output device and volume, then restart the game.

The picture is blurry / has black bars. Esc > DISPLAY > SCALING (F8) switches between sharp integer scaling and fill. Black bars are normal at non-matching window shapes.

My pad is not recognised. Plug it in before starting, then press a button once; the program shows "NO PAD CONNECTED" otherwise. Xbox, PlayStation 4 and PlayStation 5 pads are supported and tested; other pads may work but are untested.

Does it work on Linux or Mac? The source builds and is tested on Linux (BUILDING.md). The release download is Windows only.

The game crashed or looks wrong. Start with REPORT-A-PROBLEM.bat, reproduce it, close the game with Esc > QUIT GAME, and open an issue with the problem_report.txt and the questions in docs/BUG_REPORT_TEMPLATE.md.

Is it really exactly the arcade game? The game logic is native C++ that was proved identical to the original program (running on a Z80 emulator in the tests) frame by frame, including the exact cycle count of every frame, over millions of frames (docs/evidence/, summary in ARCHITECTURE.md). The honest limits are listed in PROJECT_STATUS.md ("Known limitations").

For people who want to look inside or change the game

• BUILDING.md: build the program yourself (Windows and Linux) and run the tests.
• MODDING.md: change the game's numbers with a text file (rules.cfg, three example mods in mods/), change the readable rules in C++ (with a worked example), change the menus and the look, and the honest list of what is still original arcade code.
• ARCHITECTURE.md: a map of every folder and file, how the native game, video, audio and app fit together, how it was proved, and what the ROM is still needed for.
• CONTRIBUTING.md: how to report a problem or send a change.
• CHANGELOG.md: what changed in each version.
• MACHINE_NOTES.md: everything we learned about how the arcade machine works (memory map, video, sound, timing, inputs, routines).
• src/logic/README.md: the game's rules rewritten as readable C++, each piece proved identical to the original routine (and used by the game with RULES READABLE).

How the project was made

The project was built step by step by a non-programmer working with an AI assistant (Claude), under a strict rule: no step is accepted without evidence. Each step has a step file (docs/steps/), a test, and an evidence note (docs/evidence/); PROJECT_STATUS.md lists all 100+ steps and their status, and docs/PLAN.md is the plan. In short:

1. Study (S01 to S13): identify the ROM, study how the machine works from public sources, disassemble and label the game program, map its memory, and cross-check the numbers against the published Pac-Man Dossier (everything matched). Written up in MACHINE_NOTES.md.
2. Emulator (S14 to S24): bring in a Z80 core, then build the board, video and input, proving each against a Python reference prototype until the first playable build.
3. Sound, replay and behaviour tests (S25 to S30A): sound chip, recorded replays that prove the machine is deterministic, timing/speed/ghost/scoring behaviour tests, level 256.
4. Front end (S31 to S34, X-steps): display options, controls and pads, save states, rewind, the two Reset to defaults buttons, mouse, lightbar, statistics, achievements, CRT effects, cabinet look, ultrawide.
5. Release (S35 to S37): package the Windows exe, release testing, this repository.
6. Readable rules (T01a to T02k): the game's rules as readable C++, proved identical to the ROM routines, and switchable in the game (RULES READABLE, modding).
7. Native game (N01 to N53): the original program rewritten as C++ routine by routine, each step proved identical frame by frame against the original on a Z80 reference; the Z80 emulator was then removed from the program and kept only as a test tool (tests/oracle/), and the game state was given names (src/game/state.h, src/game/output.h). The ROM's instructions are no longer used; only its data tables are read. See ARCHITECTURE.md.

Legal

• No game ROM, artwork, sound or code of the original game is in this repository or in the release download. The player supplies their own ROM file; the program only reads it.
• Not affiliated with, authorised by or endorsed by the owners of the original game or its trademarks. "PacArcadeComp" is our own project name; it is not an official name of the original game.
• The code and documents written for this project are under the MIT licence. Third-party components (SDL2, miniz, the z80 emulator core) have their own licences: THIRD-PARTY-LICENSES.txt.