This toolset provides a collection of useful tools for debugging and sourcemap generation in the Stingray game engine.
Before using this toolset, make sure you have the following prerequisites installed:
- Python (3.9 or higher): Official Python Website
- Supported Game with RawRay plugin installed: RawRay
- Lua Debug Extension for Visual Studio Code: Lua Debug
- Git: Download Link
To install the toolset, unpack Installation Files And install requirments in the unpacked directory by running:
pip install -r requirements.txt
Configure your game's path in config.json
specified in game_path
. The default is: C:/Program Files (x86)/Steam/steamapps/common/Warhammer Vermintide 2
Make sure that you use forward slashes
Generate game sourcemaps and download mod sources. The output would be to {workspace_path}/game
and {local_repos_path}
configured in config.json
:
python toolset.py sourcemap game
python toolset.py sourcemap mods
Add the sourcemap
folder to VSCode Workspace by drag&drop or via File->Add Folder To Workspace
Make sure the game is NOT running
Install debugger addon in RawRay:
python toolset.py debugger install
- Run the game in Modded Realm, You should see the game pause at a black screen waiting for the debugger.
- Open VSCode and go to Run and Debug,
Select
Stingray Attach (sourcemaps)
from theRUN AND DEBUG
drop down menu and attach (F5) or click the green play button - VSCode should attach to the game and pause
RR_debug_demo_log.mp4
RR_debug_demo_bp_step.mp4
The debugger option allows you to install/remove the addon and manipulate the luajit VM used in RawRay for debugging purposes.
The
install
command installs the debugger addon to RawRay.
- Usage:
python toolset.py debugger install
The
remove
command removes the debugger addon from RawRay.
- Usage:
python toolset.py debugger remove
The
inject
command replaces the luajit VM with the debugger's luajit VM. Not recommended if you want a stable game. This will make the game only playble in modded realm, useeject
to restore to original state.
- Usage:
python toolset.py debugger inject
The
eject
command restores the luajit VM to its original state.
- Usage:
python toolset.py debugger eject
The sourcemap option enables you to generate game sourcemaps from the bundle files and download mods specified in the config.
The
game
command generates game sourcemaps from the bundle files, needs to be done every game update or on first run.
- Usage:
python toolset.py sourcemap game
The
mods
command downloads mods specified in the config and modifies thelaunch.json
to include the sourcemaps, needs to be done on mod updates and first run.
- Usage:
python toolset.py sourcemap mods
- Warhammer: Vermintide 2 (Modded Realm only)
- Official Realm will not work if
toolset.py debugger inject
was run, usetoolset.py debugger eject
to restore state - LJD decompilation isn't perfect. breakpoints might not trigger perfectly or at all if the line info doesn't perfectly match on the function
- Some asserts and other rare cases can cause the game to pause execution, can be temporarly solved by reattaching the debugger using
Ctrl+Shift+F5
- Exception catching currenlty disabled in compatibility mode(when not running
inject
) due to some bug that causes to stop execution when they are disabled in VSCode
- Game doesn't pause, check
rawray/rawray.log
at game's path for debugger addon initialization, make suredebugger.enable = true
atrawray/config.lua
- The team at lua-debug, especially @fesily for adding support for luajit and working closely with me to address issues
- @Manny from Fatshark studios for being an awesome game dev that's active in the community, also for his PoC Line Number Adjustment
- Vermintide Modders Discord Community for all the awesome mods and tools they made over the years
This project is licensed under the MIT License. See the LICENSE file for details.