Dreamcast Homebrew

My original Sega Dreamcast games, network apps and technical demos.

Download the latest builds. Every project ships as a self-booting CDI and a plain ELF. The CDI is the easiest way to play: open it in an emulator, or load it on a real console with GDEMU or similar. If you are burning a physical CD-R, you may want to try the CD-R download instead. Each project directory has its own README.

Games

Preview	Project	Latest download	Try in browser
<img src="docs/screenshots/dreamkarts.png" alt="DreamKarts" width="360">	DreamKarts<br>A Mario Kart-style kart racer with hop-into-drift handling and mini-turbos, eight courses, CPU rivals, two-player split screen and online races.	CDI<br>CD-R	Play
<img src="docs/screenshots/drift-los-angeles.png" alt="Drift Los Angeles" width="360">	Drift Los Angeles<br>An open-city arcade street-drifting game with a C7-inspired coupe, four Los Angeles-style districts, traffic, drift chains, dense tire smoke, and recorded V8 audio.	CDI<br>ELF<br>CD-R	Play
<img src="docs/screenshots/gravity-wave.png" alt="Gravity Wave" width="360">	Gravity Wave<br>An infinite 3D arcade flight game featuring four biomes, procedural terrain, enemy formations, guardians, upgrades, and a synthesized soundtrack.	CDI<br>ELF<br>CD-R	Play
<img src="docs/screenshots/demon-bazooka.png" alt="Demon Bazooka" width="360">	Demon Bazooka<br>A compact 3D arena shooter with rockets, dashes, screen-clearing barrages, escalating demon waves, and runtime-generated visuals and audio.	CDI<br>ELF<br>CD-R	Play
<img src="docs/screenshots/totally-bazaar.png" alt="Totally Bazaar" width="360">	Totally Bazaar<br>A traditional market trading card game for 2-4 players: hot-seat play with hidden hands, CPU merchants, 3D-rendered goods, animated cards and tokens, and a synthesized bazaar soundtrack.	CDI<br>ELF<br>CD-R	Play
<img src="docs/screenshots/island-explorer.png" alt="Island Explorer on the resort beach" width="360">	Island Explorer (experimental)<br>A coastal exploration prototype with walking, swimming and dolphins, built on locally extracted Sonic Adventure assets.	Source only	-

dcvmu.com

Cloud saves for the Dreamcast. The console client backs up VMU saves to dcvmu.com and restores them, from the Dreamcast itself.

Preview	Project	Latest download	Guide
<img src="projects/dcvmu.com/service/static/dcvmu-client.png" alt="DCVMU browsing VMU saves with game icons and Power Stone selected" width="360">	DCVMU<br>Browse, upload and download VMU saves on the console. The web service lives here too.	CDI<br>ELF<br>CD-R	Getting started

Apps and demos

Preview	Project	Latest download	Try in browser
<img src="docs/screenshots/archicast.png" alt="Archicast RISC OS desktop with the Apps folder open" width="360">	Archicast (separate repo)<br>RISC OS 3.11 running natively on the Dreamcast, recompiled ahead of time to SH-4, with an ARM interpreter for 261 bundled Archimedes titles.	Source only (needs your own RISC OS ROM)	-
<img src="docs/screenshots/chroma-circuit.png" alt="Chroma Circuit Hyperfold scene" width="360">	Chroma Circuit<br>A nine-act, 60 Hz Dreamcast demo built entirely in SH-4 assembly, with raw PowerVR2 graphics and AICA music.	CDI<br>ELF<br>CD-R	Play
<img src="docs/screenshots/dream-tos.jpg" alt="Dream TOS desktop with the D: drive window open" width="360">	Dream TOS (separate repo)<br>A native port of EmuTOS, the open-source Atari TOS desktop, with bundled apps, games and utilities.	CDI<br>ELF	-
<img src="docs/screenshots/dreamcast-basic.png" alt="Dreamcast BASIC editor" width="360">	Dreamcast BASIC<br>A BASIC interpreter and full-screen editor for the Dreamcast keyboard, with QBasic-style graphics, PLAY music, one VMU save per program, and classic games such as Super Star Trek bundled as examples.	CDI<br>ELF<br>CD-R	Play
<img src="docs/screenshots/dreamcast-browser.png" alt="Dreamcast Browser" width="360">	Dreamcast Browser<br>A deliberately limited HTTPS browser supporting basic text, links, raster images, and Dreamcast keyboard, mouse, and controller input. JavaScript is not executed.	CDI<br>ELF<br>CD-R	Play
<img src="docs/screenshots/dreamcast-irc.png" alt="Dreamcast IRC" width="360">	Dreamcast IRC<br>An IRC client for Broadband Adapter or modem/DreamPi, with server and channel pages, fixed-size scrollback, keyboard input, and controller navigation.	CDI<br>ELF<br>CD-R	Play
<img src="docs/screenshots/kos-test.png" alt="KOS_Test's Run All Tests results page" width="360">	KOS_Test<br>A service-menu style test and benchmark suite that checks KallistiOS and the hardware and records CPU, memory and GPU numbers for each KOS build.	CDI<br>ELF<br>CD-R	-
<img src="docs/screenshots/lemonplay.png" alt="LemonPlay browsing a DLNA server" width="360">	LemonPlay<br>A DLNA media player that streams video and music from a PC running ZeroConfigDLNA in Dreamcast mode over the Broadband Adapter.	CDI<br>ELF<br>CD-R	-
<img src="docs/screenshots/pico8-dreamcast.jpg" alt="PICO-8 Player cartridge picker with five bundled games" width="360">	PICO-8 Player<br>A native FAKE-08 port with a cartridge picker, sound, controller support, HTTPS downloads over BBA or modem, and five MIT/GPL-licensed sample games.	CDI<br>ELF<br>CD-R	Play
<img src="docs/screenshots/ping-cube.png" alt="Ping Cube" width="360">	Ping Cube<br>A networking and PowerVR demo that continuously pings 8.8.8.8, visualizes latency through the cube's color, and displays live replies, loss, and timing statistics.	CDI<br>ELF<br>CD-R	Play

Building and running

Every project builds with KallistiOS (KOS), the open-source Dreamcast SDK, and runs in the Flycast emulator. I build on macOS; CI builds the same projects on Linux. Known-working baseline: KOS 2.3.0 master d81aa3f, kos-ports f4faacc, GCC 15.2.0, and Flycast master 628bd3d with these patches.

One-time setup

The launchers look for everything under ~/.local/share/dreamcast, so installing there needs no extra config. If you already have KOS somewhere else (its own default is /opt/toolchains/dc), export KOS_ENV=/path/to/kos/environ.sh and the launchers use that instead.

1. Clone this repo, then KOS and kos-ports side by side at the tested commits:

   git clone https://github.com/richstokes/dreamcast-homebrew.git
   DC="$HOME/.local/share/dreamcast"
   git clone https://github.com/KallistiOS/KallistiOS.git "$DC/kos"
   git -C "$DC/kos" checkout d81aa3f
   git clone https://github.com/KallistiOS/kos-ports.git "$DC/kos-ports"
   git -C "$DC/kos-ports" checkout f4faacc
   

2. Build the SH-4 cross compiler with kos-chain, KOS's toolchain builder. Install the host packages from its platform notes first (on macOS that's the Xcode command-line tools and one brew install). This is the slow step:

   cd "$DC/kos/utils/kos-chain"
   cp Makefile.dreamcast.cfg Makefile.cfg
   sed -i.bak "s|/opt/toolchains/dc|$DC|" Makefile.cfg
   make
   

3. Create environ.sh. This is KOS's environment script: it sets KOS_BASE, the compiler paths and flags, and puts kos-cc on your PATH. Every build starts by sourcing it. KOS ships a sample to copy:

   cd "$DC/kos"
   cp doc/environ.sh.sample environ.sh
   sed -i.bak "s|/opt/toolchains/dc|$DC|" environ.sh
   source environ.sh
   

4. Back in your clone of this repo, apply its KOS patches and build KOS. Every project expects them (network, dial-up, VMU and controller fixes):

   tools/kos/apply-patches.sh
   make -C "$KOS_BASE"
   

5. Dreamcast Browser, DCVMU and PICO-8 Player also link some kos-ports libraries, which need cmake to build:

   for port in zlib mbedtls curl stb_image; do make -C "$KOS_PORTS/$port" install; done
   

6. Flycast. On macOS, tools/flycast/build-macos.sh builds the patched Flycast the launchers try first. Stock Flycast 2.7 in /Applications runs most projects, but networking and keyboard input need the patches (details). Anywhere else, export FLYCAST_BIN=/path/to/flycast. DreamKarts also needs mkdcdisc (tools/mkdcdisc/build-macos.sh, or one on your PATH).

CI runs steps 1 and 3-5 from .github/scripts, with the compiler from the pcercuei/dreamcast-toolchain Docker image in place of step 2.

Build and run a project

Source the environment in each new shell (or add the line to your shell profile), then build and launch from the repo root:

source "$HOME/.local/share/dreamcast/kos/environ.sh"
make -C projects/games/drift-los-angeles
projects/games/drift-los-angeles/run-flycast.sh   # builds first; --skip-build reuses the ELF

Each project README has its own make targets and launcher options.

• Drift Los Angeles, DreamKarts, Island Explorer, PICO-8 Player and Totally Bazaar depend on SH4ZAM, pinned to a tested commit (v0.10.0) in tools/update-sh4zam.sh. Each build checks out an ignored third_party/sh4zam clone at the pin; a weekly canary flags new upstream gainz so they get benchmarked on the console before we bump
• Chroma Circuit is pure assembly: it needs the step 2 compiler but not KOS (make -C projects/apps/chroma-circuit verify)
• Asset generators and QA scripts run through uv. Generated assets are checked in, so a plain build doesn't need it

Real hardware

The make hw, hwbench, hwsoak and auto targets run on a real console through tools/dc-hw.sh, which expects:

• A Broadband Adapter, with the console booting into dcload-ip (mine goes GDEMU, openMenu, dcload-ip)
• dc-tool-ip on your PATH (or DC_TOOL=/path/to/dc-tool-ip)
• Optionally, the console's power on a Shelly smart plug, so the script can power-cycle a hung console and switch it off after a test. It never touches a plug until you name it: run tools/dc-hw.sh --use-shelly IP once and it is remembered (a bare --use-shelly takes the only plug on the network). Without one, switch the console on into dcload-ip before each run

Without a Broadband Adapter and dcload-ip, build with make and load the ELF however you normally do. For example dc-tool-ip -t <console-ip> -x game.elf with dcload-ip, dcload-serial with a coder's cable, or a CDI on GDEMU or a CD-R (tools/flycast/elf-to-cdi.sh game.elf game.cdi, or grab one from the releases). The Makefiles call the script through DC_HW, so make hw DC_HW=/path/to/your-script swaps in your own; it gets run, dc-hw.sh's options and the ELF.

Layout and releases

• projects/games/: games
• projects/apps/: apps and demos
• projects/dcvmu.com/: DCVMU client and web service
• projects/common/: code shared between projects
• tools/: Flycast build, KOS patches, real-hardware runner, SH4ZAM pin

Every push to main runs the tests, builds each project in the release manifest against pinned SDK commits, and republishes the rolling release with CDI and ELF files.

License and attribution

The original project code in this repository is available under the MIT License.

These projects are powered by KallistiOS, the independent Dreamcast SDK. KallistiOS is distributed separately under its BSD-like KOS license and requires attribution.

Drift Los Angeles, DreamKarts, Island Explorer, PICO-8 Player and Totally Bazaar use SH4ZAM, the SH-4 math library by Falco Girgis and contributors, available under the MIT License. It is fetched at build time and not included in this repository.

Support

If you enjoy these projects and want to support my work, you can buy me a coffee. Totally optional, but much appreciated!

<a href="https://buymeacoffee.com/richstokes"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="50"></a>