Docs / Getting Started

To get started with GBDK.js we’ve created a boilerplate example project that you can clone as a starting point for your own games.

> git clone
> cd gbdkjs-example-boilerplate
> npm install

You can now build this project as a GameBoy ROM file.

> make rom
> open open build/gb/

You should see the example application open in your GameBoy emulator.

> make web
> live-server --wait=2000 build/web

If you don’t have live-server you can install it with

> npm -g install live-server

or you can use something like python -m SimpleHTTPServer or any number of web server applications. Unfortunately you can’t just open the index.html directly as you’ll get a cross origin error.

The graphics assets

If you have ggbgfx installed you’ll be able to modify the graphics files and rebuild the game with your own assets.

Try editing the file assets/screen.png and running the script assets/

> cd assets
> sh
> cd ..
> make clean
> make web
> live-server --wait=2000 build/web

The code

The most important files in the boilerplate are the following

  • src/game.c The main game code file, contains all game logic and the run loop.

  • include/game.h The game headers and library includes.

  • Makefile The compile scripts for building your game, until you start adding more files or want to replace the Emscripten shell file you shouldn’t need to change this.

  • assets/ A build script for compiling PNG assets into the GameBoy graphics format.

  • include/assets.h An autogenerated file created by the assets build script containing your game’s graphics data. As your game’s graphics data increases you’ll want to move these into separate files and in probably into other banks.

Next: Example Projects