GDPP: a Geometry Dash course inside a Garry's Mod sandbox

GD x People Playground, a Melty mashup. Garry's Mod is the host game. You build a physical sandbox scene, pick a real Geometry Dash level read from your own installed copy, press Start Run and play that level as the GD cube while your props stay physical and interact with the course. Die and the attempt restarts instantly with everything you built still standing.

Status: v0.1.0, first playable version. The GD cube simulation, the level reader, the course physics and the run loop are implemented and tested outside the game; the Garry's Mod side has not yet been run inside Garry's Mod (see docs/TESTING.md for exactly what has been tested and what has not).

The loop

1. Press Play in Melty. It installs the addon and reads your Geometry Dash levels (once).
2. Garry's Mod opens in sandbox on gm_flatgrass.
3. F4 opens the menu: pick a level from your own install, or open the sandbox palette.
4. Build your scene: ragdolls, crates, barrels, a jeep, weapons. Physgun moves them, the toolgun removes them.
5. Press Start on a level. The course appears next to your sandbox; the cube starts running.
6. Space or left click jumps (hold to keep jumping). R restarts the attempt. E gives up.
7. Touch a spike, a wall, a prop or a moving vehicle and the attempt restarts immediately. Finish and you drop back into your sandbox with everything as you left it.

Controls

| Where | Key | What it does | | --- | --- | --- | | Sandbox | F4 | Level list and sandbox palette | | Sandbox | any sandbox tools | Physgun, toolgun, spawnmenu, duplicator — as usual | | Run | Space / left click | Jump (hold to keep jumping on each landing) | | Run | R | Restart the attempt from the first block | | Run | E | Leave the run and return to the sandbox | | Run | F4 | Same menu (also restarts and leaves) |

What is in v0.1.0

• Real Geometry Dash levels. Read from your own Geometry Dash\Resources\LevelData.plist; the level strings are decoded in game. Nothing from Geometry Dash is included in the download or uploaded anywhere.
• Cube simulation at GD's own tick rate, 240 Hz, with GD's constants: 1x speed 311.58 units/s, gravity 0.876 A, jump 1.9522 V, terminal speed 2.6 V. Gravity portals, speed portals, jump pads, jump orbs (yellow, pink, red, black, green, blue), spikes, saws, pits, blocks and the ground.
• Cube rules: run automatically, one button, hold to jump again on landing, orbs need a fresh press and beat a surface jump, head hits kill, landing on a block side past 10.5 units deep kills, flipped gravity has a kill ceiling.
• Sandbox that survives: the course is built as frozen props; your props, ragdolls and vehicles are never removed by a run, and death restarts without touching them.
• Physical interaction: props and ragdolls in the cube's lane kill it on contact, so a crate placed on the course is a real obstacle.

What is deliberately not in v0.1.0

• Game modes other than the cube (ship, ball, UFO, wave, robot, spider, swing portals are skipped with a warning), mini size portals, dual mode and teleport portals.
• People Playground's own models, textures, audio and machines. v0.1.0 uses Garry's Mod's stock content for the sandbox. Reading People Playground's real assets is the next milestone, not a claim made here.
• Multiplayer, cosmetics, save files, level editing, GD's soundtrack (the level's music is not played yet).

Install

Through Melty (one click), or by hand:

1. Copy addons/gdpp into GarrysMod\garrysmod\addons\.
2. Run stage\gdpp-stage.cmd "C:\...\steamapps\common\GarrysMod" (or just double-click it after editing the path in the command), or set GDPP_GMOD_DIR and run wscript.exe gdpp-stage.js.
3. Start Garry's Mod, press F4.

The staging wrapper only reads your Geometry Dash LevelData.plist and writes the level strings into garrysmod\data\gdpp\. It needs no installs: it is Windows Script Host, which every Windows ships.

Checking a real install before opening the game

The staging step can be verified without Garry's Mod:

python tools/inspect_levels.py "<GarrysMod>\garrysmod\data\gdpp"

It lists every level it found with its block count, hazards, pads, orbs and portals, warns about features v0.1.0 does not simulate, flags levels too long for the world, and walks the cube through each level with no input to show where an idle run stops. Exit code 0 means every level decoded, parsed and fits.

Repository layout

melty.json                  Melty manifest (games, mappings, setup, launch)
addons/gdpp/                the Garry's Mod addon
  lua/gdpp/shared/          pure simulation: constants, objects, lzip, level, physics, catalog
  lua/gdpp/server/          course physics, run controller, sandbox palette
  lua/gdpp/client/          course rendering, camera, HUD, menus
  tools/windows/            the staging helper (JScript)
stage/gdpp-stage.cmd        Windows wrapper Melty runs in setup
tools/package.py            builds the release zip
tests/                      LuaJIT, Node and Python test suites
docs/                       physics, packaging, testing and architecture notes

Credits and licences

Geometry Dash is RobTop Games'. Garry's Mod is Facepunch Studios'. People Playground is studio-minus'. This is a fan project and is not affiliated with or endorsed by any of them. No game files are redistributed; see THIRD-PARTY-NOTICES.md for the sources behind the physics constants.