OpenGGF User Guide

OpenGGF is an open-source, Java-based engine that reimplements classic Mega Drive / Genesis Sonic the Hedgehog games. It is not an emulator: it reads data from original ROM images and runs its own implementation of the game logic, physics, rendering, and audio. No copyrighted assets are included. You must supply your own legally obtained ROM files.

The engine currently supports Sonic the Hedgehog (S1), Sonic the Hedgehog 2 (S2), and Sonic 3 & Knuckles (S3K) at varying levels of completeness.

Choose Your Path

I want to play

You have ROM files and want to get the engine running.

• Getting Started — From zero to playing in five minutes
• Configuration — Common setup questions answered
• Controls — Full keyboard reference
• Game Status — What works, what’s incomplete, what to expect
• Troubleshooting — Fixing common problems

I want to cross-reference the engine against the disassembly

You know s1disasm, s2disasm, or skdisasm and want to understand how the engine represents the same concepts — or you want to check the engine’s accuracy.

• How the Engine Reads ROMs — The data pipeline from ROM bytes to rendered screen
• 68000 Primer — Just enough assembly to read object routines
• Mapping Exercises — Learn to trace any feature between disassembly and engine
• Architecture Overview — Where things live in the codebase
• Tooling — RomOffsetFinder and other built-in tools
• Per-Game Notes — S1, S2, and S3K specific quirks

I want to contribute

You want to add objects, bosses, zones, or engine improvements.

• Dev Setup — Environment, build, and test setup
• Architecture Deep Dive — Providers, services, and runtime
• Documentation and Branch Policy — Commit trailers, changelog/discrepancy updates, and PR documentation checks
• Tutorial: Implement an Object — Worked example from disassembly to running code
• Adding Bosses — Boss-specific patterns
• Adding Zones — Bringing up a new zone
• Audio System — SMPS driver, FM synthesis, PSG
• Rewind System — Using, validating, and extending frame rewind
• Testing — Writing and running tests
• Trace Replay Testing — BizHawk recordings, replay tests, and divergence analysis

Related Documents

These documents live at the repository root and complement this guide:

• README — Project overview and FAQ
• CHANGELOG — Detailed release history
• ROADMAP — Development priorities
• CONFIGURATION — Full configuration reference (all keys)
• CREDITS — Community resources this project builds on
• OBJECT_CHECKLIST — Sonic 2 object implementation status
• S1_OBJECT_CHECKLIST — Sonic 1 object implementation status
• S3K_OBJECT_CHECKLIST — Sonic 3&K object implementation status