beep8-sdk

BEEP-8 Logo

BEEP-8 SDK

English 日本語 繁體中文（廣東話）

BEEP-8 is a virtual retro game console designed for developing C/C++ applications. It runs on an emulated ARM v4 CPU at a fixed 4 MHz and is optimized for vertical smartphone displays. The SDK adopts a two-layer architecture: at the low level, developers can directly access hardware (H/W) through minimal APIs. At the high level, developers are free to choose their own structure, frameworks, or libraries to build applications. A PICO‑8–like C/C++ library is provided as one such option for rapid and familiar development, but it is entirely optional.

While the CPU is a 32-bit processor, the VDP (video display processor) and APU (audio processing unit) are modeled after simpler 8-bit–era virtual devices, striking a balance between modern programmability and nostalgic hardware constraints.

BEEP-8 runs smoothly at a guaranteed 60 fps on PC, smartphones (iPhone, Android), and tablet devices such as iPad, thanks to its browser-based design and rendering optimizations using WebGL and GPU shaders.

Even on iPhones, you can freely upload and share your self-made BEEP-8 apps with users around the world without going through Apple’s App Store review process, since the platform is entirely web-based.
All apps can be shared instantly via the official portal at https://beep8.org, making global distribution as simple as uploading a file.

It also allows developers to create 8-bit-style touch-enabled games, offering a retro experience combined with modern touch interaction—ideal for casual and mobile-friendly gameplay.

BEEP-8 System Block Diagram

BEEP-8 Block Diagram

Quick Start

Supported Platforms

The BEEP-8 SDK is cross-platform and supports the following environments:

On most platforms, no external toolchain installation is required—the SDK includes prebuilt compilers for all supported platforms.

Download

You can get started with the SDK in one of the following ways:

We strongly recommend using Option 1 (Git) unless you have a specific reason to avoid Git.

Directory Structure

The SDK repository is organized as follows:

├── README.md             # This file
├── doc/                  # Documentation
├── gnuarm/               # Prebuilt GNU ARM GCC toolchains for each supported platform
│   ├── Windows_NT/
│   ├── linux/
│   └── osx/
├── sdk/                  # Main SDK components
│   ├── app/              # Sample BEEP-8 applications and build targets
│   ├── b8helper/         # Optional utility libraries to assist BEEP-8 app development
│   └── b8lib/            # Core BEEP-8 SDK implementation
├── setenv.bat            # Windows script to add make to the system PATH
└── tool/                 # Development tools
    ├── busybox/          # BusyBox for UNIX-like command support on Windows
    ├── ccache/           # Compiler cache to speed up rebuilds
    ├── genb8rom/         # Tool for generating BEEP-8 ROM filesystem images
    ├── geninstcard/      # Tool for generating thumbnail images for BEEP-8 ROMs
    ├── make/             # Windows-compatible make.exe, path set via setenv.bat
    ├── png2c/            # Optional PNG-to-C array converter for asset embedding
    ├── relb8rom/         # Tool for packaging final release ROMs (required for distribution)
    └── scripts/          # Helper scripts for automating app development tasks

Build a Sample Application

sdk/                   # Main SDK components
└─ app/                # Sample BEEP-8 applications and build targets
   ├── hello/          # Hello world sample in BEEP-8
   ├── pico8_example/  # PICO-8–style library sample
   ├── bgprint/        # Prints text to the background layer
   ├── helper_nesctrl/ # NES-like controller sample displayed on-screen
   ├── ppu_example/    # Direct PPU control sample
   ├── touch/          # Touch panel status retrieval sample
   ├── Makefile        # Makefile for users who prefer make
   ├── build_all.sh    # Script to build all samples under this directory
   ├── makefile.app    # Shared Makefile include for make users
   ├── run_common.sh   # Build shell script for macOS/Linux users
   └── run_common.bat  # Build BAT for Windows/DOS prompt users

Each sample can be built, ROM-generated, and launched with a single script. No make is required unless you prefer it.

macOS / Linux (Bash)

  1. Change into your sample’s directory (example: pico8_example): 
    cd sdk/app/pico8_example
  2. Run the build-and-launch script: 
    ./run.sh

    This will:

    • Compile all source files and graphics data
    • Generate the .b8 ROM file
    • Open the application in your default web browser

run

run on iPhone

Windows (Command Prompt)

  1. Open Command Prompt, then change into your sample’s directory: 
    cd sdk\app\pico8_example
  2. Run the build-and-launch script: 
    run.bat

    This will:

    • Compile all source files and graphics data
    • Generate the .b8 ROM file
    • Launch the application in your default web browser

Advanced users (Make/CI): see MAKEFILE.md for full Make-based instructions.

Sample Application Directory Structure

pico8_example
├── run.sh                     # Build and upload script
├── data
│   ├── export
│   │   ├── sprite0.png.cpp   # Converted from sprite0.png to C++ source
│   │   └── sprite1.png.cpp   # Converted from sprite1.png to C++ source
│   └── import
│       ├── sprite0.png       # 128×128 sprite (4bpp), Bank #0
│       └── sprite1.png       # 128×128 sprite (4bpp), Bank #1
├── main.cpp                   # Application source code
└── romfs
    └── instcard.jpg           # Title image for distribution

API Documentation

For complete API details, please refer to the header files in the sdk/b8lib/include/ directory. Key headers include:

API Reference BEEP-8 SDK
BEEP-8 SDK is the core system library required for developing BEEP-8 applications.
It provides direct access to the virtual hardware such as CPU, PPU, APU, timers, and the RTOS (b8OS).
All essential functions for bare-metal style development are defined here.

API Reference BEEP-8 HELPER LIB
BEEP-8 HELPER is an optional utility library that provides helpful modules to accelerate application development.
It includes utilities such as graphics helpers, math functions, and simple input managers that abstract away some of the hardware-level complexity.

API Reference PICO-8 LIKE LIB
This is a PICO-8–style compatibility library written in C/C++.
It mimics the original PICO-8 API as closely as possible while adapting it to C/C++ semantics.
The goal is to make the development experience familiar for PICO-8 users, while still leveraging the performance and flexibility of native code.
You can build full games using this library with minimal knowledge of the underlying hardware.

How to Release a BEEP-8 App

RELEASE.md

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contact

Happy coding with BEEP-8!

This site is open source. Improve this page.