A JavaFX UI (2D + 3D) for Pac-Man and Ms. Pac-Man

ℹ️ Online version available

An older release of Pac-Man and Ms. Pac-Man (2D) can be played online:

This has been made possible thanks to the WebFX transpiler technology (👏 to Bruno Salmon).

About this project

This is an implementation of the classic Arcade games Pac-Man and Ms. Pac-Man in a JavaFX user interface. The game implementation is completely decoupled from the user interface such that also different user interfaces (e.g. a Swing UI) can be implemented without any change to the game code. (When developing the game, I originally maintained a Swing and a JavaFX UI in parallel to validate the UI abstraction, however the Swing UI got outdated and has been abandonded.)

There is a 2D-only user interface version and an extended version where the play scene can be switched between 2D and 3D, even during the gameplay (key combination Alt+3). The game implementation tries to mimic the original Arcade version as good as possible, however there are some differences, e.g. in the "attract mode" behaviour, or the bonus behaviour in the Ms. Pac-Man game.

The game also contains a 3rd game variant (working title "Pac-Man XXL") with 8 maps (shamelessly stolen from the one and only Shaun Williams 👏, https://github.com/masonicGIT/pacman). To integrate these maps, I implemented a map editor that can either be used as a standalone application or called from within the XXL version of the game). The nice thing is that all these maps and all your custom maps are playable in 2D and in 3D! You can also create maps of different size than the original Pac-Man maps, however this is still work in progress. Also the game can hang if the maps have dead-ends. So you have to be aware of that. The map editor has been used to create all the 8 new maps and you don't have to specify any graphics assets when adding a new map. Colors can be specified using map properties inside the editor.

How to use custom maps (in progress)

Use the map editor to create your custom map and store the .world file inside folder $user_home/.pacmanfx/maps. Select the "Pac-Man XXL" game variant, start it and open the dashboard (F1 or Alt+B). In the "Custom Maps" info box, select "CUSTOM_MAPS_FIRST". This will select all your custom maps (in alphabetic order) first, then the standard maps and after the last standard map, select any maps randomly.

How to run

In each release you find attached 3 installers.

On Windows, a MSI installer is created.
The Linux (.deb) installer has only been tested on Ubuntu inside a VM, it worked after installing the FFMPeg library (see linux-issues.md).
The Mac-OS (.dmg) version has not been tested at all, any help is appreciated.

How to build

Prerequisites: You need to have JDK 21 and Git installed on your computer.

git clone https://github.com/armin-reichert/pacman-javafx.git
cd pacman-javafx
./gradlew jpackage or just make (Windows) or ./make.sh (Linux)

This will create

an installer (.msi/.deb/.dmg depending on your platform) for the 2D-only game (subdirectory pacman-ui-2d/build/jpackage)
an installer for the full game (subdirectory pacman-ui-3d/build/jpackage)
an installer for the map editor (subdirectory pacman-mapeditor/build/jpackage)

Running the application(s) using Gradle

Pac-Man 2D: ./gradlew pacman-ui-2d:run
Pac-Man 3D: ./gradlew pacman-ui-3d:run

To be able to create the Windows executables, you need to have the following tools installed:

as described in the JavaPackager guide (👏 to Francisco Vargas Ruiz).

I also had to add the paths "C:\Program Files (x86)\WiX Toolset v3.11\bin" and "C:\Program Files (x86)\Inno Setup 6" to my PATH variable.

How to use the application

Start screen:

V, LEFT Select next game variant
RIGHT Select previous game variant
ENTER or SPACE Start game

Intro screen:

5 Add credit ("insert coin")
1 Start the game
H Show/hide context-sensitive help

The keys 5 and 1 have been chosen because the MAME emulator uses them too.

Pac-Man steering:

Pac-Man is steered using the cursor keys. When the dashboard is open, the cursor keys might also change slider values etc. To avoid this, you can also steer using CTRL+cursor key.

General shortcuts: