autumnagnificent / overlunky

An overlay for Spelunky 2 to help you with modding, exploring the depths of the game and practicing with tools like spawning arbitrary items, warping to levels and teleporting.

Overlunky

An overlay for Spelunky 2 to help you with modding, exploring the depths of the game and practicing with tools like spawning arbitrary items, warping to levels and teleporting made by the cool people from the Spelunky Community Discord.

Please read the before complaining about them in the discord.

is compatible with

(prerelease build) is compatible with

WHIP builds are whipped together automatically from the latest changes and are not tested or documented at all. They are mainly to keep up with the ever changing scripting api and usually contain bugfixes for that. Use at your own discretion, but if you want the latest scripts, get this.

Disclaimer

You are strongly discouraged from using any modding tools in your actual online Steam installation as to prevent unlocking achievements, ruining or corrupting your savefile and cheating while using online features. You should make a copy of your game somewhere else and install Mr. Goldbergs Steam Emulator in the game directory. (Just replace steam_api64.dll with the one in the zip and that copy of the game can't talk to Steam no more!) If you break anything using this tool you get to keep both pieces. Do not report modding related bugs to BlitWorks.

Installation and usage

YouTube tutorial for kids who can't read good and who wanna learn to do other stuff good too.

Download the latest release and extract to your game folder. Run the program, leave it running and then start your game, or the other way around! Check the keyboard shortcuts and troubleshooting before asking dumb questions. Overlunky doesn't do any permanent changes to your game, it only exists when you run it.

Overlunky does NOT work online! I thought the disclaimer was clear on this... Now I'm not going to stop you from trying, but you'll just find yourself in a world of desync and crashes.

Check the generated Spelunky 2/overlunky.ini after running to change shortcut keys and check Spelunky 2/entities.txt for a list of numerical entity IDs.

Features

Current features and their default keyboard shortcuts. Note: There's a LOT of useful keys that are not listed here because this list is getting pretty long, check your overlunky.ini for cool beans.

• F1: Search and spawn entities where you're standing
  • Ctrl+Enter: Spawn entity
  • Tab: Add selected itemid to list
  • Mouse left: Spawn entity at mouse cursor
  • Mouse right: Teleport to mouse cursor
  • Mouse middle: Select or drag entities around (not stuff like walls)
  • Ctrl+Mouse middle: Launch dragged entity with velocity
  • Shift+Mouse middle: Select or drag all entities around (even walls and background)
  • (Ctrl/Shift+)Mouse 4: Zap / Boom / Big Boom / Nuke!
  • Mouse 5: Destroy entity (not stuff like walls)
  • Ctrl+Mouse 5: Clone entity
  • Shift+Mouse 5: Destroy any entity (really unsafe :)
  • Shift+123...: Spawn saved kit number
  • You can also draw a velocity vector for spawn/teleport by holding the mouse button
  • Dragged entities have noclip on, so you can drag yourself through walls etc
  • Enter multiple numeric IDs like 526 560 570 to spawn them all at once. Useful for making a kit you can Save for later use with a single click.
• F2: Warp and make doors to many places
  • Shift+Enter: Spawn back layer door
  • Ctrl+Shift+Enter: Spawn warp door
  • Ctrl+Shift+W: Warp to set level
• F3: Camera controls
  • Ctrl+,: Zoom in
  • Ctrl+.: Zoom out
  • Ctrl+0: Auto fit level width to screen
  • Ctrl+2345: Zoom to X level width
• F4: Entity properties
  • See and change a lot of variables of the selected entity
• F5: Game state
  • See and change a lot of variables from the game state
  • Ctrl+Space: Toggle game engine pause
  • (Shift+)Space: Advance frame when engine is paused
• F6: Save editor
  • Edit your save data.
  • Note: Doesn't automatically save to file, you need to let the game trigger a save for that.
• F8: Scripts
  • You can load, edit and set options for Lua scripts here
  • Ctrl+F5: Reload enabled scripts
• F9: Options
  • Lots of options. Check the ini for hotkeys, I'm tired of updating this.
• F11: Hide overlay
• Ctrl+Shift+U: Change UI color
• Ctrl+Shift+I: ImGui internal metrics and settings
• Ctrl+Shift+S: Save options, hotkeys and UI colors
• Ctrl+Shift+L: Load options, hotkeys and UI colors
• Ctrl+Shift+D: Detach active tab in tabbed interface
• Enter: Run active tool
• Escape: Return focus to game from an input

Scripts

Lua scripting is buggy and unfinished and the API will change, so don't go around making and releasing huge things. They will break. There's some documentation and examples to get you started though. The examples should be considered Unlicensed, so please DO NOT credit the author when copying them. Scripts are loaded from Spelunky 2/Overlunky/Scripts by default, but you can change this in the ini. Optionally you can also load main.lua files from Mods/Packs.

Scripts don't work online either! While technically they can work, yours truly has no interest in making any online features. If you want an online rando, make and test it yourself. Or use Parsec.

Troubleshooting

• If your game crashes when launching Overlunky or it just closes and you don't see the overlay in game:
  • Make sure you are running the latest version of each. We don't support old game versions and sometimes not the too recent ones either. The latest somewhat tested version can be found at the top if this document.
  • Make sure your antivirus is not blocking it. This is very likely if you're using one. Overlunky is very hacky and acts like malware. It isn't, but you can audit the source code and build it yourself if you want.
  • Try the WHIP build, it might have already fixed the problem.
• If your game crashes when actually trying to use the tools:
  • See previous section.
  • Some entities just crash the game, try to avoid them next time.
  • Some scripts just crash the game too, the api is not very safe.
• If your game crashes and you're using Modlunky2 or Playlunky:
  • While we try to keep all the modding tools compatible, some things may break sometimes.
  • Check the open issues for known compatibility problems with other tools.
• If you're missing some overlay windows or tabs:
  • Try resetting window positions. (See hotkeys above.)
  • Delete Spelunky 2/imgui.ini to reset tool window positions that might be outside the screen region for whatever reason.
  • Maybe the overlay is just really tiny? You can resize it.
• If you mess up your keyboard shortcuts or UI:
  • Delete Spelunky 2/overlunky.ini.
• If keyboard input no longer works in game after using the tools:
  • This shouldn't be a problem anymore in 0.4.8+. File an issue if this still happens.
• If your UI is all black or you want to change the color
  • Change the color then. The keyboard shortcuts are right there.
• If stuff just don't work and you're running Windows 7 or a machine not designed to play games
  • You're on your own here. We don't test on or make this for ancient software/hardware.
• If you have problems with OBS
  • Use Game Capture and disable Allow Transparency if Overlunky looks weird/black.
  • If you have lag or crashes, check previous question.
• If you're running Linux
  • The game and OL should run fine with the latest Wine if you install DXVK.
  • Also works with Proton 5.13 if you first start the game on Steam and then run STEAM_COMPAT_DATA_PATH=~/.steam/steam/steamapps/compatdata/418530 WINEPREFIX=~/.steam/steam/steamapps/compatdata/418530/pfx ~/.steam/root/steamapps/common/Proton\ 5.13/proton run ~/.steam/steam/steamapps/common/Spelunky\ 2/Overlunky/Overlunky.exe adjusting the paths for your setup.
  • Put the Segoe UI ttf files to your wineprefixes Windows/Fonts to show the ui correctly.
  • You're still mostly on your own here, this is a Windows 10 program for a Windows 10 game.
• If you don't have scripts in the Scripts tab
  • You didn't put them in the right place. Follow the instructions.

Development

If you'd rather build it yourself or help with development, clone the repository, get some C++ build tools and run this to get started:

cd overlunky
git submodule update --init --recursive
mkdir build
cd build
cmake ..
cmake --build . --config Release --target ALL_BUILD

The binaries will be in build/bin/Release/. You can also try the scripts in .vscode with VSCode. Set OL_DEBUG=1 in the game environment to enable logging to console.