Waveforge

Waveforge is the game I'm developing for GitHub Game Off 2025.

The concept

Waveforge is a 2D platformer where the player needs to manipulate water waves (and other physical phenomena) to somehow move a rubber duck to the checkpoint in a pixel emulated world with physics simulation (of it's own style, not always realistic though).

For more details about the game physics system, please refer to Physics System Documentation.

Current status

The game is finished to a playable state with 18 levels, published as version 0.4 on Itch.io. Try it out and let me know what you think!

Build instructions

The project consists of a C++ core logic with all the game mechanics and a scripting system for defining game UI written in TypeScript. This makes the build process two-fold and may require some setup.

C++ Part

You need to have CMake and a C++23 compatible compiler installed (e.g. GCC 14, Clang 20, MSVC 19.44.35219.0). Then run the following commands in the project root directory:

# Make sure to enter MSVC environment when on Windows
cmake -B build -DCMAKE_BUILD_TYPE=Release .
cmake --build build --config Release

Changing Release to Debug will build the debug version for development.

The direct dependencies will be automatically downloaded and built. Find the executable in build directory. The built program can be found at build/waveforge (or build/waveforge.exe on Windows).

For Linux systems, SFML might requires some additional system libraries. The simplest way is to install SFML via your package manager, so that all those internal dependencies are automatically handled. For example:

# Debian/Ubuntu
sudo apt install libsfml-dev

# Arch Linux and dirivatives
sudo pacman -S sfml

You can also install those dependencies manually if you prefer not to install SFML system-wide. Please refer to SFML's official documentation for more details.

TypeScript Part

Scripted scenes are written in TypeScript and compiled to JavaScript bundles that are loaded by the QuickJS runtime at runtime.

Prerequisites: pnpm and Node.js.

pnpm install
pnpm build

Bundles are output to assets/bundled-js/.

AI benchmark interface

The optional Waveforge MCP server runs the unmodified game in a private Xvfb display and exposes mouse, single-key, screenshot, and batch tools over HTTP. It supports realtime and externally paused turn-based play with native 1x screenshots and isolated temporary saves.

The Pi + Firecracker harness runs the agent inside a microVM while the game stays on the host, and records screenshots, memory files, Pi sessions, compaction and evaluation budgets.

Team Members

• Code: fang_erj
• Music & SFX: stevvven
• Pixel Art: ZTL-UwU

Acknowledgements

We would like to thank zurry for thier inspiring thoughts on game play, mechanics and level design. We would also like to thank RitaRossweisse301 for early testing and feedback.

We would also like to thank the following open source projects for making this game possible:

• microsoft/proxy: A C++ library for "Next Generation Polymorphism"

• SFML: Simple and Fast Multimedia Library for graphics and audio.

• cpptrace: A simple & self-contained C++ stack trace library.

• Aseprite: A pixel art tool used for creating pixel art assets.

Additionally, we would like to acknowledge GitHub and Lee Reilly for organizing the GitHub Game Off 2025 game jam, which provided the inspiration and motivation for this project.