Megabonk Level Editor

An unofficial Megabonk mod for creating and playtesting custom levels: an in-game editor, a console, and a development harness with MCP tools.

Showcase · Player guide · Build setup

Note

This codebase extensively uses AI-assisted tooling (e.g., Claude Code, OpenCode, vLLM, etc.)

If that bothers you, please feel free to bounce off the repo. I wish you the best in your endeavors!

For those who stick around, I assure you that there's a lot of care and attention with (at the time of writing) over 2780 C#, 1280 python, and dozens of less important regression tests. This is a highly methodical, spec-driven repo that is older than its git history.

Develop

Use your own Steam copy of the Windows game build, natively on Windows or through Proton/Linux or Wine/macOS. Install BepInEx 6 IL2CPP and launch once to generate local interop assemblies. Native Linux mod support is unverified. Install the toolchain in modding setup and development, then:

Requirements: mise (verified with 2026.10.15) installs the toolchain pinned in .tool-versions, including uv 0.11.32, Python 3.13, Task, .NET 10 and Go; run mise install once. uv 0.11.32 is the minimum: the package builds with uv_build>=0.11.32,<0.12, which needs a matching uv.

mise install                         # pinned toolchain from .tool-versions
cp .env.example .env                 # configure your local game paths
uv sync
task mod:build                       # builds and deploys into your game install
task game:run

On macOS with r2modmac, install BepInExPack IL2CPP and Apply the profile, then quit Megabonk and run this before the first modded launch:

task wine:bepinex:repair -- --download --dry-run   # preview missing runtime files
task wine:bepinex:repair -- --download             # repair and safely park MelonLoader
task game:run                                      # use this, not r2modmac's Play button

The repair uses your configured game paths, preserves plugins and user data, and logs details to .tools/logs/bepinex-repair.log. See the r2modmac repair guide for local ZIPs, safety checks and rollback.

Press F8 to edit/play; backtick/tilde opens the console (help, Tab completion, Ctrl-R history). Enable MEGABONK_DEV=true in your local .env for debug commands and automated starts. After rebuilding, restart to load the new DLL:

uv run scripts/run.py relaunch levels/bramblecrown-hill.mblevel.json

Command	Purpose
task check	Build, installer tests, .NET/Python tests and lint
task scripts:test	Python tests without a running game
task mod:test	Unity-free .NET tests
uv run megabonk-mcp	Development MCP server from this clone; clients register it with uvx (setup)
task package:thunderstore	Runtime-only BepInEx package; no levels or packs

Explore

• src/ / tests/: C# plugin, pure logic and regression tests.
• scripts/: launch, harness, MCP, level generators and packaging.
• levels/: Bramblecrown Hill, Warehouse placement data and Forest example.
• unity/: optional local asset-pack authoring.
• pkg/ / go/: package metadata and legacy standalone installer.
• site/: the showcase website.

See level format, development and console commands, asset packs, and Thunderstore packaging.

Content and licensing

Bring your own legally obtained games and assets. Game binaries, interop assemblies, ROMs, extracted meshes/textures and soundtrack files are not included in this source tree. The optional Warehouse workflow extracts from your own PS1 THPS1 USA disc image, not a Steam release; its input checksum and local-only workflow are documented in Warehouse sources. Owning a copy does not grant redistribution rights for its content or generated packs. Retained screenshots depict gameplay; third-party rights remain with their owners.

Original project code is Unlicense; third-party components retain their own licenses. This project is not affiliated with or endorsed by Megabonk's creators, Activision, or the Tony Hawk's Pro Skater rights holders.