Reinforcement Learning for Geometry Dash

A DQN framework for playing Geometry Dash. Our project contains two parts:

1. A suite of DQN agents, models, and a custom gymnasium environment. /ai-model
2. A C++ mod to control the game. /gd-rl-mod

Paper | Demo

Update (9/30/25): Initial support for MLLMs and DinoV3 backbone, with GRPO training!

Demo

https://youtu.be/PKDMGPf-PEA

Standard DQN Agent:

Mixture-of-Experts DQN Agent:

demo.mp4

Setup

Since the mod only works on Mac, this is the only supported platform. See a side note about Windows below.

AI Model

# Install uv
pip install uv

# Install
cd ai-model
uv sync

# Train (change resume=False or True near end of script)
uv run train.py

# Play
# Ensure model checkpoints is in /checkpoints/latest.pt
uv run play.py

C++ Mod

1. Setup Geode. More details: https://docs.geode-sdk.org/getting-started/geode-cli#macos

# Install Geode (tested on v4.4.0)
brew install geode-sdk/geode/geode-cli

# Setup profile
geode config setup

# Install SDK
geode sdk install
geode sdk install-binaries

2. Build the mod

geode build

Windows

The socket and OpenGL libraries are different for Mac vs. Windows, and we've only got it to work for Mac. Some progress is made in the windows branch, here are some clues.

• Platform specific imports: platform.hpp
• Error about socket library redefinition if we include "Windows.h", otherwise it's library not found server.cpp