Sandopolis

A portable multi-system Sega emulator

---

Download the latest desktop version of Sandopolis from here or try Sandopolis in your web browser.

Footage of Sandopolis running a few games:

Sonic & Knuckles	The Revenge of Shinobi
Golden Axe II	Streets of Rage

Key Features

• Accurate Sega Genesis/Mega Drive, Sega CD, Master System, Game Gear, and SG-1000 emulation
• Very portable; can be built and run on any platform that Zig supports
• Very configurable, including gameplay input, frontend hotkeys, and rendering settings
• Has a permissive license that allows commercial use

See ROADMAP.md for the list of implemented and planned features.

Important

This project is still in early development, so compatibility is not perfect. Bugs and breaking changes are also expected. Please use the issues page to report bugs or request features.

---

Quickstart

Download the Latest Release

A. Desktop

You can download the latest pre-built binaries from the project's release page.

B. Web

You can download and use the latest pre-built Docker image for the web version of Sandopolis from the GHCR:

docker run -d -p 8085:80 --rm ghcr.io/pixel-clover/sandopolis-web:latest

Then open http://localhost:8085 in your browser.

Build Sandopolis from Source

Alternatively, you can build the emulator from source by following the steps below.

1. Clone the repository

git clone --depth=1 https://github.com/pixel-clover/sandopolis.git
cd sandopolis

Note

If you want to run the tests and develop Sandopolis further, you may want to clone the repository with git clone --recursive https://github.com/pixel-clover/sandopolis.git. Note that you also need to have git-lfs installed to download some of the files like test ROMs.

2. Build the Sandopolis Binary

# This can take some time
zig build -Doptimize=fast

If the build is successful, you can find the built binary at zig-out/bin/.

Note

To build from source, you mainly need to have Zig and Git installed. The current version of the emulator is developed and tested using Zig 0.17.0.

Run the Emulator

Run the sandopolis binary to start the emulator GUI:

sandopolis

Run sandopolis --help to see the list of available command-line options.

Example output:

A portable multi-system Sega emulator for Genesis, Sega CD, Master System, Game Gear, and SG-1000

Usage:
  sandopolis [flags] [rom_file]

Arguments:
  rom_file  Path to a ROM file (.bin, .md, .smd, .gen, .sms, .gg, .sg), a .zip archive containing one, or a Sega CD disc image (.cue, .iso) (optional)

Flags:
  -h, --help            Shows help information for this command [Bool] (default: false)
      --audio-mode      Audio render mode: normal, ym-only, psg-only, unfiltered-mix [String] (default: "")
      --audio-queue-ms  Audio queue budget in milliseconds (40-150) before backlog recovery [String] (default: "")
      --renderer        SDL render driver override (e.g. software, opengl) [String] (default: "")
      --config          Path to the unified config file (default: SANDOPOLIS_CONFIG, platform app data, or ./sandopolis.cfg) [String] (default: "")
      --pal             Force PAL/50Hz timing and version bits [Bool] (default: false)
      --ntsc            Force NTSC/60Hz timing and version bits [Bool] (default: false)
      --version         Print version information and exit [Bool] (default: false)

---

Important

Sandopolis boots Sega CD games either from a pair of .cue and .bin files, or a single .iso file. Note that Sega CD needs a few BIOS files (normally segacd.bios_us/segacd.bios_eu/segacd.bios_jp, or bios_CD_U.bin/bios_CD_E.bin/ bios_CD_J.bin files) that are not included in this project. Place the BIOS files per build in the locations mentioned below:

• For the desktop build, put the files in the bios directory beside the config file (sandopolis.cfg).
• For the Libretro build, place the files in the frontend's system directory.
• For Sandopolis web, upload the bios files through Settings menu. You need to do it only one time normally, and the files will be kept in the browser you're using.

---

Contributing

See CONTRIBUTING.md for details on how to make a contribution.

License

This project is licensed under the MIT License (see LICENSE).

Acknowledgements

• The logo is from SVG Repo with some modifications.
• This project uses material from the following projects and resources:
  • Minish framework for property-based testing
  • Chilli framework for CLI parsing and handling
  • Rocket 68 for the main CPU (Motorola 68000) emulation
  • jgz80 for the Z80 chip emulation
  • SDL3 for the emulator frontend (rendering and input; via zsdl and SDL)
  • stb for the TrueType font rendering
  • JetBrains Mono for the monospace font used in the frontend
  • Test ROMs for testing
  • Libretro overlays for the frontend overlays

Reference Implementations

Sandopolis implementation logic was checked with the following implementations for finding errors and verifying correctness:

• Genesis-Plus-GX
• Nuked-OPN2
• clownmdemu-core
• kiwi
• jgenesis