CHL debugger for Black & White: Creature Isle

[Daniels118]

Hi all!
I have released the first beta version of my debugger for B&W CI!

First demo video:

Main features

• update the CHL scripts while the game is running
• patch individual ASM instructions without stopping the scripts
• breakpoints (normal, conditional, hit count), with optional commands to be executed when hit
• watches (break at any point in the code when the value of an expression changes)
• exceptions (break when an "until" condition is meet)
• execute the code (both ASM instructions or source lines) step by step (including step in/over/out of scripts)
• display the instructions as they are executed (both ASM or high level instructions)
• define a list of display commands to be run at each step
• list the code around the current executing instruction
• jump at arbitrary instruction (allows to skip or re-execute part of the code)
• inspect the stack or change its size
• display active "threads"
• display or change the value of both global and local variables
• evaluate expressions
• compile and execute arbitrary code
• define custom commands
• write complex macros (with IF-ELSE and WHILE instructions)
• execute commands from a file
• execute existing scripts
• launch OS commands, so one can recompile the CHL without leaving the debugger window
• arrange the windows in a convenient way (for example, forcing the game window to be always on top of other windows)

Requirements
Custom CHL compiler: https://github.com/Daniels118/blackandwhite_ci
Mods loader DLL: https://github.com/Daniels118/BW_mods_loader
Debugger DLL: https://github.com/Daniels118/BWCI_debugger

How to use
First you have to download the file "ddraw.dll" from the mods loader project and put it in the installation folder. Then in the same folder create a directory named mods, and put there the file debugger.dll.

In order to use all the features, you have to compile the game scripts using my custom CHL compiler with the -dbg switch to add debug information to the CHL file.
If you want to compile the original game, you can find the source files here: https://forum.bwgame.net/threads/source-files-for-creature-isle-challenges.8543/

Put the source scripts under "Black and White\CreatureIsle\Scripts\CreatureIsles\decompiled" or something similar. If you use a different path, be sure to update it in the following scripts.

In the same folder create a batch script named "make.cmd", it will make it easier to update the CHL while the game is running (be sure to update the path of the compiler):

@echo off

set OLDPATH=%PATH%
set PATH=%PATH%;C:\Users\Daniele\git\blackandwhite_ci\chlasm_ci\build\chlasm_ci

set BWPATH=E:\Games\Black and White\CreatureIsle

call chlasm_ci -compile -path "%BWPATH%" -scriptpath "Scripts\CreatureIsles\decompiled" -inputfile _challenges.txt ..\challenge.chl -jst -ext -dbg
set rc=%ERRORLEVEL%

set PATH=%OLDPATH%
exit /B %rc%

Make a backup copy of the original Challenge.chl file and run the above script. If you have an autosave be sure to delete it, otherwise the game won't reload the new CHL file; the autosave is always the folder "CreatureIsle\Profiles\PROFILENAME\Saved Games\20".

Create a batch script named "debug.cmd" or similar in the installation directory, with the following content (be sure to update the path of your installation):

@echo off
set PATH=E:\Games\Black and White\CreatureIsle\Scripts\CreatureIsles\decompiled;%PATH%
start CreatureIsle.exe /console /gdb

Now start the game from this script. Once the game loads, the console will wait for your commands!

P.S. the debugger will also work for saved games, but if you load a game that was started using a CHL file that wasn't compiled from the correct source files, then the source line numbers will be wrong, and source line display won't be useful.

Happy modding!