Skip to content

README.md

Latest commit

 

History

History
275 lines (206 loc) · 9.71 KB

README.md

File metadata and controls

275 lines (206 loc) · 9.71 KB
Raw

8bitworkshop

Build Status

8bitworkshop is a browser-based IDE for micro computers and consoles. It compiles or assembles your code as you type, then runs the result in a built-in emulator — all locally in your browser, with no server round-trip.

It bundles toolchains and emulators for dozens of platforms, including the Atari 2600/7800/8-bit, Commodore 64/VIC-20, NES, Game Boy, ColecoVision, MSX, ZX Spectrum, Amstrad CPC, PC Engine, Vectrex, Apple II, and a number of arcade boards. See Toolchains & Platforms for the complete list.

8bitworkshop IDE

Use Online

Latest release:

Bleeding edge (built from HEAD):

Features

  • In-browser compilers and assemblers (cc65, SDCC, Z80/6502/6809 assemblers, and more) — see Tools
  • Built-in emulators with keyboard and gamepad input
  • Debugger with breakpoints, stepping, memory browser, disassembly, call stack, memory probes, and time-travel replay
  • Hardware simulation with Verilog
  • Asset editor for bitmaps and palettes
  • Export ROMs, save screenshots/videos, share playable links, and sync projects to GitHub

Read the IDE documentation for a guided tour.

Install Locally

Requirements:

  • Node.js 24.x
  • npm
  • make and git
  • Python 3 (for the local dev server)

To clone just the main branch:

git clone -b master --single-branch git@github.com:sehugg/8bitworkshop.git

To build the 8bitworkshop IDE:

# On Windows, use the `UCRT64` shell from https://msys2.org/
# On Linux/macOS, just type:
make

make initializes git submodules, installs npm dependencies, builds the TypeScript and lezer grammars, and runs esbuild.

To use GitHub integration locally, download the Firebase config file, e.g. https://8bitworkshop.com/v[version]/config.js

Start Local Web Server

Start a web server on http://localhost:8000/ while TypeScript compiles in the background:

make tsweb

Run Tests

# To avoid "API rate limited exceeded" errors, set `TEST8BIT_GITHUB_TOKEN`,
# see: https://github.com > Settings > Developer settings > Personal access tokens
export TEST8BIT_GITHUB_TOKEN="<github_personal_access_token>"

npm test

Command-Line Tool

The 8bws CLI builds and runs projects headlessly, without a browser. It is useful for scripting, CI, and regression tests.

# Build a source file to a ROM
npm run cli -- build --platform c64 hello.c -o hello.prg --symbols

# Run a ROM for 200 frames and take a screenshot
npm run cli -- run --platform nes --frames 200 --png shot.png game.nes

# Run with a debugger script (symbolic addresses come from the build)
npm run cli -- run --platform gb hello.c -e "break _main; pc 4"

npm run cli -- list-platforms
npm run cli -- list-tools

Run scripts (-e or --script <file>) can run, break, step, trace, hist, key, mem, screen, pc, info, reset, and echo. Run npm run cli -- help for the full list.

Documentation

The IDE manual lives in src/docs/:

Contributing

Thank you for your contribution!

The 8bitworkshop IDE is intended for a diverse audience using a wide range of devices. It likes:

  • Running locally
  • Vanilla TypeScript against Web APIs
  • Stable/mature dependencies
  • Running decently on 10-year old Chromebooks
  • Working (or degrading gracefully) on 5-year old browsers
  • Not changing anything described in the 8bitworkshop books too much

The code samples in presets/ are intended to be studied by humans. LLM usage for generating code samples is discouraged, as they tend to hide subtle errors in code and in comments, and it diminishes the human achievement and human-to-human communication aspects of the project. Please thoroughly review and edit such code.

Adapting third party sample code with permissive licenses and giving credit to the original author(s) is encouraged.

Credits

8bitworkshop is created and maintained by Steven E. Hugg.

Major contributors:

  • Fred Sauer - CodeMirror 6 editor migration, Apple II enhancements, and general IDE work.
  • Mike DX - PC Engine / Game Boy / Williams 6809 enhancements, library code, and examples.
  • Micah Cowan - Apple II enhancements.

The emulators, compilers, assemblers, and libraries that this project builds on are credited in Dependencies and retain their own licenses (see License).

For the complete list of contributors, see the GitHub contributors graph.

License

The original source code in this repository is Copyright © 2016-2026 Steven E. Hugg and is licensed under the GPL-3.0.

This project also bundles and links against third-party components, including emulators, compilers, and libraries. These components are not covered by the GPL-3.0 license above; they remain under their own licenses, and you must comply with those terms when redistributing this project or a modified version of it. See the individual dependencies' own license files for details.

All included code samples located in the presets/ directory are licensed under CC0 unless a different license is explicitly stated within the specific code sample.

Dependencies

Emulators

Compilers

Assemblers/Linkers

Dev Kits / Libraries

Firmware

The emulator cores need system firmware to boot. Only freely distributable replacement images are included — see mame/roms/README.md for their provenance and licenses.

To use your own firmware, add it to the project as a binary file named <platform-id>.rom (for example c64.rom); the IDE loads it as the BIOS at startup. Only freely distributable firmware should be shared.

Related Projects

Tool Server (experimental)

This is an experimental feature that relies on a Docker container to provide compiler tools like llvm-mos. Right now, you have to run locally and build your own docker container.

docker build -t 8bitws-server-debian scripts/docker
docker run -p 3009:3009 8bitws-server-debian
echo '{"REMOTE_URL":"http://localhost:3009/build"}' > remote.json

Then add "&tool=llvm-mos" to your URL, like this. You can also rename your C files to have the suffix "-llvm.c". Right now only the platforms c64, atari8, nes (NROM), and pce are supported. Not very many of the current examples work with the new toolchain.