Getting Started

This page gets you from zero to playing in under five minutes.

What You Need

• For downloaded releases: no separate Java install is required; release packages include a native OpenGGF executable for your platform.
• For source builds: Java 21 or later. Download from Adoptium or your preferred distribution. Run java -version to check.
• A GPU that supports OpenGL 4.1. Any discrete GPU from the last decade will work. Integrated graphics (Intel HD 4000+, Apple Silicon) are fine.
• ROM files for the games you want to play. The engine does not include any game data. You must supply your own legally obtained copies.

Expected ROM Files

The engine is verified against these specific ROM revisions. Other revisions may produce incorrect results.

Game	Expected Filename	Revision
Sonic 1	Sonic The Hedgehog (W) (REV01) [!].gen	World, Revision 01
Sonic 2	Sonic The Hedgehog 2 (W) (REV01) [!].gen	World, Revision 01
Sonic 3&K	Sonic and Knuckles & Sonic 3 (W) [!].gen	World (lock-on combined ROM)

ROM filenames can be changed in config.yaml if yours differ. See Configuration for details.

Install and Run

Option A: Download a Release

1. Download the latest release package for your platform from the Releases page:
   • Windows: OpenGGF-windows.zip
   • macOS: OpenGGF-macos.zip
   • Linux: OpenGGF-linux.tar.gz
2. Extract it to a folder.
3. Place your ROM files next to the editable config.yaml included in the package.
4. Start OpenGGF:
   • Windows: double-click OpenGGF.exe, or run it from a terminal.
   • macOS: open OpenGGF.app.
   • Linux: run ./OpenGGF from the extracted OpenGGF directory.
5. If your ROM filenames differ from the defaults, edit config.yaml in the extracted package.

Windows terminal example:

.\OpenGGF.exe

Linux terminal example:

cd OpenGGF
./OpenGGF

Option B: Build from Source

1. Clone the repository:

   git clone https://github.com/jamesj999/sonic-engine.git
   cd sonic-engine

2. Build with Maven:

   mvn package

3. Place your ROM files in the project root directory (next to pom.xml).
4. Run:

   java -jar target/OpenGGF-0.6.prerelease-jar-with-dependencies.jar

First Launch

When the engine starts, you will see:

1. Master title screen — An engine-wide title screen with animated clouds and a game selection menu. Use the arrow keys to highlight a game and press Space to select it.
2. Game title screen — The selected game’s original title screen (e.g., the Sonic 2 “PRESS START BUTTON” screen).
3. Gameplay — The first zone of the selected game.

If a ROM file is missing for the game you selected, the engine will show an error.

Quick Configuration

The engine reads settings from config.yaml in the working directory. If the file does not exist, defaults are used. A few settings you might want to change immediately:

Setting	What it does	Default
roms.default	Which game boots first ("s1", "s2", or "s3k")	"s3k"
startup.masterTitleScreen	Show game picker on launch	true
display.windowAutosize	Derive the window size from the aspect preset	true
audio.enabled	Enable or disable sound	true
characters.sidekick	Add Tails as a CPU sidekick ("tails" or "")	"tails"
debug.flags.editor	Allow Shift+Tab to open the experimental editor overlay	false

Key bindings can be written as names like "SPACE" and "F9" instead of raw numeric key codes.

For the full list, see Configuration or the Configuration Reference.

What Next?

• Controls — Learn the keyboard layout
• Game Status — See what works in each game
• Troubleshooting — If something went wrong