GBC C Starter Kit

A starter kit for developing Game Boy Color games in C, powered by gbdk-2020, CMake, and Ninja. Provides a clean project structure and build setup to jumpstart your homebrew development.

Description

This repository is a template project for Game Boy Color homebrew development. It includes a ready-to-use setup with gbdk-2020, CMake, and Ninja, providing developers with:

• A clean folder structure for source code and assets
• A complete build configuration for cross-platform compilation
• A minimal working example to start coding right away

Requirements

This project is primarily set up for Windows with Visual Studio Code, but it can be adapted to other platforms with minor changes.

Make sure the following tools are installed:

• gbdk-2020 – C compiler and libraries for Game Boy / Game Boy Color development
• CMake (version 3.16 or higher) – project configuration and build system generator
• Ninja – fast, portable build system
• A standard C compiler (e.g., GCC or Clang)
• Visual Studio Code with CMake Tools extension (recommended)
• bgbw64 – Game Boy / Game Boy Color emulator used to run the compiled ROMs

Features

• Preconfigured project structure for Game Boy Color homebrew in C
• Ready-to-use CMake setup for modern project management
• Support for Ninja as a fast and portable build system
• Compatible with Visual Studio Code on Windows (with CMake Tools extension)
• Integrated with bgbw64 emulator for testing the compiled ROMs directly from the project
• State-based game loop with smooth screen transitions
• Game State Management
  • Centralized game state tracking (lives, score, level)
  • Easy state initialization and reset
  • Extensible structure for future game mechanics
• Clean folder layout for source code, headers, and assets
• Easy to extend for larger projects

Graphics & Display

• Advanced Sprite Management

  • Efficient OAM handling with automatic tile reuse
  • Support for multi-tile sprites (up to 2x2)
  • Dynamic sprite allocation and deallocation
  • CGB palette support with DMG fallback

• Background System

  • Multiple background layer support (game, UI, etc.)
  • Smooth scrolling capabilities
  • CGB attribute map support
  • Dynamic palette management
  • Efficient VRAM usage

Technical Features

• DMG/CGB Compatibility

  • Auto-detection of hardware
  • Graceful degradation on DMG
  • Full CGB features when available

• Memory Management

  • Efficient VRAM usage
  • Optimized sprite and background updates
  • Safe memory access patterns

Getting Started

Follow these steps to build and run your first Game Boy Color ROM:

1. Clone the repository

git clone https://github.com/spinellifabio/gbc-c-starter-kit.git
cd gbc-c-starter-kit

2. Generate the build files with CMake

cmake -B build -G Ninja

3. Compile the project

ninja -C build

After compilation, the .gbc ROM file will be generated inside the rom/ directory.

4. Run the ROM with bgbw64

start bgbw64.exe rom/your-game.gbc

By default the prototype runs through splash, intro cutscene, title, gameplay test loop, then shows the credits scene (skippable with START/SELECT) before returning to the title screen.

Prototype controls

• Title: START to play, SELECT for options.
• Dialogue Yes/No: LEFT/RIGHT moves the cursor, A confirms current choice, B snaps to No and confirms.

Visual Studio Code (recommended)

If you are using Visual Studio Code with the CMake Tools extension:

• Open the folder gbc-c-starter-kit/ in VS Code
• Select the CMake preset for Ninja
• Build the project using the CMake Tools commands
• The compiled ROM will automatically launch in bgbw64 if configured in CMakeLists.txt

Configuration / Custom Paths

Some paths in this template are preconfigured for Windows and may need to be updated according to your system setup.

1. gbdk-2020 include path

In .vscode/settings.json, update the C_Cpp.default.includePath entry to match where you installed gbdk-2020:

"C_Cpp.default.includePath": [
    "C:/path/to/your/gbdk/include",
    "${workspaceFolder}/src"
]

2. BGB Emulator path

Both .vscode/tasks.json and .vscode/launch.json reference the path to bgbw64. Update these to point to your emulator location:

tasks.json

"command": "\"C:/path/to/bgbw64/bgb64.exe\" \"${workspaceFolder}/rom/${workspaceFolderBasename}.gb\""

launch.json

"program": "C:/path/to/bgbw64/bgb64.exe",
"args": [
    "${workspaceFolder}/rom/${workspaceFolderBasename}.gb"
]

3. CMake run target

In CMakeLists.txt, the path to the emulator is set in the BGB_EXE variable:

set(BGB_EXE "C:/path/to/bgbw64/bgb64.exe")

Adjust this path to match your system, so the run target can launch the ROM automatically after building.

Tip: If you move your emulator or gbdk installation in the future, make sure to update all relevant paths in these files to avoid build or launch errors. ⚠️

Project Structure

The repository is organized as follows:

gbc-c-starter-kit/
│── .vscode/                    # VS Code configuration (tasks, launch settings)
│   │── extensions.json         # VS Code extensions
│   │── launch.json             # Launch configuration
│   │── settings.json           # User settings
│   └── tasks.json              # CMake tasks
│── build/                      # Output directory (generated after compilation)
│── cmake/                      # CMake scripts
│   └── gbdk-toolchain.cmake    # Toolchain configuration
│── docs/                       # Project documentation
│── include/                    # Header files
│   │── sprite.h                # Sprite management system
│   │── game_settings.h         # Game settings and configuration
│   │── game_system.h           # Core game system functions
│   └── input.h                 # Input handling
│── res/                        # Resource files
│   ├── sprites/                # Sprite graphics
│   │   ├── Alex_idle_16x16.c   # Character sprite data
│   │   └── Alex_run_16x16.c    # Character run animation
│   └── tiles/                  # Tile graphics
│       └── tileset.c           # Game tileset data
│── rom/                        # Compiled ROMs
│── src/                        # C source code
│   │── credits.c               # Credits screen implementation
│   │── dialogue.c              # Dialogue system
│   │── game_settings.c         # Game settings implementation
│   │── game_system.c           # Core game system
│   │── gameplay.c              # Main game logic
│   │── input.c                 # Input handling
│   │── intro.c                 # Intro sequence
│   │── lang.c                  # Language support
│   │── main.c                  # Entry point
│   │── options_screen.c        # Options menu
│   │── sprite.c                # Sprite management
│   └── title_screen.c          # Title screen
│── .gitignore                  # Ignored files
│── AGENTS.md                   # AI agent configuration
│── CMakeLists.txt              # Main build configuration
│── CMakePresets.json           # CMake presets
└── README.md                   # Project documentation

This structure keeps source code, headers, and assets separated for clarity. The build/, CMakeFiles/, and rom/ directories are ignored by version control and only contain generated files.

Screens Flow

The following diagram shows the screen flow for the GBC prototype. Nodes styled in green are implemented; nodes in red are planned in the roadmap.

Goal

The goal of this starter kit is to provide a solid foundation for Game Boy Color homebrew development.

It is designed for developers who want to:

• Quickly start coding in C for the Game Boy Color
• Use a modern and maintainable build system with CMake and Ninja
• Test ROMs immediately using the integrated bgbw64 emulator
• Have a clean and organized project structure that can scale for larger projects

This template is meant to reduce setup time, allowing developers to focus on creating games rather than configuring the build environment.

See the Roadmap for planned features and updates.

Keywords

gameboy-color, gbc, gbdk-2020, cmake, ninja, c-programming, starter-kit, template, homebrew, romhacking, bgbw64

Resources / Documentation

• Game Boy History – A detailed history of the Game Boy
• GBDK-2020 Official Documentation – Reference for Game Boy / Game Boy Color development in C
• Game Boy Development Wiki – Guides and technical details about the hardware
• Ninja Build System – Documentation for the build tool
• CMake Documentation – Full reference for CMake commands and usage
• bgbw64 Emulator – Official emulator for testing Game Boy / Game Boy Color ROMs
• Free Game Boy / Game Boy Color Assets – Free game assets for Game Boy / Game Boy Color homebrew development
• PNG to GB Asset Converter – Tool for converting PNG files to Game Boy graphics
• RPG-Style Movement – Tutorial for RPG-style movement in Game Boy development
• Game Boy Graphics - Understanding the Game Boy's Graphics in Game Boy development
• Learn about retro game development! – A collection of tutorials for Game Boy development
• Drawing Advanced Dialogue Boxes - Tutorial for drawing advanced dialogue boxes in Game Boy development

Credits

 $$$$$$\  $$$$$$$\   $$$$$$\         $$$$$$\         $$$$$$\    $$\                          $$\                               $$\   $$\ $$\   $$\
$$  __$$\ $$  __$$\ $$  __$$\       $$  __$$\       $$  __$$\   $$ |                         $$ |                              $$ | $$  |\__|  $$ |
$$ /  \__|$$ |  $$ |$$ /  \__|      $$ /  \__|      $$ /  \__|$$$$$$\    $$$$$$\   $$$$$$\ $$$$$$\    $$$$$$\   $$$$$$\        $$ |$$  / $$\ $$$$$$\
$$ |$$$$\ $$$$$$$\ |$$ |            $$ |            \$$$$$$\  \_$$  _|   \____$$\ $$  __$$\\_$$  _|  $$  __$$\ $$  __$$\       $$$$$  /  $$ |\_$$  _|
$$ |\_$$ |$$  __$$\ $$ |            $$ |             \____$$\   $$ |     $$$$$$$ |$$ |  \__| $$ |    $$$$$$$$ |$$ |  \__|      $$  $$<   $$ |  $$ |
$$ |  $$ |$$ |  $$ |$$ |  $$\       $$ |  $$\       $$\   $$ |  $$ |$$\ $$  __$$ |$$ |       $$ |$$\ $$   ____|$$ |            $$ |\$$\  $$ |  $$ |$$\
\$$$$$$  |$$$$$$$  |\$$$$$$  |      \$$$$$$  |      \$$$$$$  |  \$$$$  |\$$$$$$$ |$$ |       \$$$$  |\$$$$$$$\ $$ |            $$ | \$$\ $$ |  \$$$$  |
 \______/ \_______/  \______/        \______/        \______/    \____/  \_______|\__|        \____/  \_______|\__|            \__|  \__|\__|   \____/

                                                                                                       v1.0.0 - Code assembled in spare time by Fabio