geometry-dash-rl

Teacher-student RL prototype for Geometry Dash with a mock training pipeline and a Geode shared-memory bridge.

Project status

Implemented:

• Gym-compatible privileged env (GDPrivilegedEnv) with mock IPC fallback
• Teacher PPO training entrypoint (SB3)
• Dataset collector writing compressed NPZ shards
• Student distillation trainer with weighted mode sampling
• Geode shared-memory adapter on the Python side
• Geode mod skeleton that writes core telemetry (obs[0..7]) + level-complete flag

Not finished yet:

• Real screen-frame capture in the collector
• Input injection from action_in into live gameplay
• Full production training/inference loop against real game frames

Repository layout

Path	Purpose
src/gdrl/env/privileged_env.py	Gym env, reward logic, mock IPC adapter
src/gdrl/teacher/train_ppo.py	Teacher PPO training (saves SB3 model)
src/gdrl/data/collector_cli.py	Rollout collection + NPZ export
src/gdrl/student/train_distill_dataset.py	Student distillation from NPZ
src/gdrl/student/train_distill.py	Sanity-only random train step
src/gdrl/env/geode_ipc.py	Python shared-memory adapter (gdrl_ipc)
src/gdrl/env/geode_ipc_test.py	Fake writer/reader IPC smoke test
src/gdrl/env/live_monitor.py	Live telemetry monitor for Geode segment
geode_mod/GDRLBridge/src/main.cpp	Geode mod hook implementation
docs/	IPC protocol + implementation planning docs

Requirements

• Python >=3.10
• Virtualenv recommended
• Python deps from requirements.txt (torch, stable-baselines3, gymnasium, etc.)
• Optional Geode path requires Geometry Dash 2.2081 and Geode SDK (as required by geode_mod/GDRLBridge/CMakeLists.txt)

Setup

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt
pip install -e .
mkdir -p artifacts

Or:

make setup

Quick start (mock-only, no Geode needed)

1. Train teacher:

python -m gdrl.teacher.train_ppo

Expected output model:

• artifacts/teacher_mock.zip

2. Collect dataset shard from teacher rollouts:

python -m gdrl.data.collector_cli \
  --teacher-path artifacts/teacher_mock.zip \
  --episodes 3 \
  --out artifacts/datasets/mock_shard_000.npz

3. Train student from NPZ:

python -m gdrl.student.train_distill_dataset \
  --data artifacts/datasets/mock_shard_000.npz \
  --epochs 2 \
  --out artifacts/student_mock.pt

4. Optional quick sanity step (no dataset required):

python -m gdrl.student.train_distill

5. Optional env smoke run:

python -m gdrl.env.run_env_smoke --mode mock --steps 10

Dataset format (NPZ shards)

src/gdrl/data/collector.py writes:

• frames: uint8, shape [N, 84, 84]
• teacher_probs: float32, shape [N, 2]
• modes: int32, shape [N]
• level_ids: int32, shape [N]
• frame_idxs: int64, shape [N]

Notes:

• Distillation stacks 4 consecutive frames.
• You need at least 5 frames in a shard or train_distill_dataset raises: Dataset too small for stack_size=4.

Geode IPC protocol summary

Shared memory segment:

• name: gdrl_ipc (Python side)
• size: 444 bytes

Field	Type	Notes
version	uint32	Protocol version
tick	uint32	Incremented every update
obs	float32[108]	Privileged observation vector
action_in	uint8	Action byte written by Python
reserved	uint8[3]	reserved[0] is level-complete flag

Action semantics:

• 0: release/no-click
• 1: press/hold

Reference: docs/GEODE_IPC_PROTOCOL.md.

IPC smoke test without the game

Terminal A:

python -m gdrl.env.geode_ipc_test writer

Terminal B:

python -m gdrl.env.geode_ipc_test reader

Or run env smoke against shared memory:

python -m gdrl.env.run_env_smoke --mode geode --steps 10

Running with live Geode telemetry

1. Build the Geode mod (example CMake flow):

export GEODE_SDK=/path/to/geode-sdk
cmake -S geode_mod/GDRLBridge -B geode_mod/GDRLBridge/build
cmake --build geode_mod/GDRLBridge/build -j

2. Install/load the built mod in Geometry Dash via Geode.

3. Start a level, then verify the segment appears:

python -m gdrl.env.geode_wait

4. Monitor live values:

python -m gdrl.env.live_monitor --print-every 25

5. Drive the Gym env from shared memory:

python -m gdrl.env.run_env_smoke --mode geode --steps 20

6. If a stale segment remains after crashes:

python -m gdrl.env.geode_shm_cleanup --shm-name gdrl_ipc

Geode mod behavior right now

Current implementation in geode_mod/GDRLBridge/src/main.cpp:

• Opens/creates POSIX shared memory /gdrl_ipc
• Writes version, increments tick every PlayLayer::postUpdate
• Fills core telemetry: obs[0]=x, obs[1]=y, obs[2]=y_vel, obs[3]=x_delta, obs[4]=on_ground, obs[5]=is_dead, obs[6]=speed(placeholder), obs[7]=mode
• Sets reserved[0]=1 on levelComplete

Pending:

• Applying action_in to actual jump/hold input (currently read only)

Troubleshooting

• FileNotFoundError or timeout waiting for segment: make sure a level is running and the Geode mod is loaded.
• Version mismatch in Python adapter: compare EXPECTED_VERSION in src/gdrl/env/geode_ipc.py with IPC_VERSION in geode_mod/GDRLBridge/src/main.cpp.
• Dataset trainer says shard is too small: collect more frames by increasing --episodes.
• Stale shared-memory segment: run python -m gdrl.env.geode_shm_cleanup --shm-name gdrl_ipc.

Additional docs

• docs/IMPLEMENTATION_PLAN.md
• docs/GEODE_IPC_PROTOCOL.md
• docs/GEODE_HOOK_PLAN.md