ZEsarUX debugger for DAAD
Para español click aquí.
ZEsarUX is a ZX Spectrum and Amstrad CPC emulator with many features, but we will talk today about one very intersting for DAAD Adventure Writer developers/authros: the DAAD debugger.
Those who use DAAD for creating 8 and 16 bit adventure games face simple challenges, but sometimes we want to impleement some complicated code which doesn’t seem to work fine when we test it. For those cases using a debugger, which allow us run condacts one by one and see what happens is very helpful.
To use ZEsarUX debugger, you just have to create your DAAD game using ZX Spectrum (any)or Amstrad CPC (tape) format, and load it into ZEsarUX.
What can we do with the debugger?
Well, as I said, you can execute your game step by step, that is, condact by condact. If you load a DAAD game and then you type, in this order, the following keys, you will get to the DAAD debugger: F5, E, D,8 (F5=Menu, E=dEbug, Debug CPU, view 8).
The picture below is the debugger. The message about being “Not in condacts” let us know we are not executing any condact at the moment (if you look at the game below, you see it’s actually waiting for player to press a key). Right you can see the watches, and below the options we have in this view (inverse video marks the key launching each one).
Watches allow the authors to see the content of flags, or the location of some objects. By default they will show the value of flags 0, 1, 33, 34, 35, 38 and 51.
Then, if the code we want to check depends a lot in a flag, i.e. flag 100, we can change the watches so flag 100 is shown in place of some of the default ones. To do that we press W (watch) wich will make the emulator ask us which line to change (if you look closely, you’ll se the watches are numbered 1 to 7)
Then we will be asked if we want to set that watch to watch an object location or a flag value.
And finally we will be asked for the flag number, or object number. once we enter flag 100 we will se the value of flag 100 in our screen.
In the image below we have changed watches so line 2 contains flag 100 value, and line 1 location of object 1.
The debugger does also allow us to change a flag value or change an object location. The option for that is the one name “wrIte”, which we will start pressing “i” key . Just like when we change the watches, the debugger will ask first if we want to change a flag or objetc location, then which flag (or object) and then the value we want to set.
If we update flag 100 and set value to 128 we will be able to see that in the watches.
Step by step execution
To run game step by stet, we have to press enter each time. That key, if we are out of the condacts zone is name as “runTO Condact”, and if the execution is in condacts zone is name “Step condacts”, but in the end it will lead as tu next condact (unless a player command has to be requested first). In the end we will get to some scrren like this:
In this case you can see EX BOSQU (the entry, you got to after player typing EX SELVA, being SELVA and BOSQU synonyms), and you can see also the condacts in that entry. Sorry for the spanish examples, basically , EX BOSQUE = EX FOREST and EX SELVA = EX JUNGLE.
Next condact to be executed is a EQ condition, that if succesful will lead us to PLUS 32 1, but if fails will probably lead us to another entry (exactly to the PLUS 31 1 you see below, which is in another EX BOSQUE entry).
After executing that PLUS, we go to another entry , which would lead us to process 5 (response table):
There are more EX BOSQUE entries inside process 5, the debugger will get to them all as DAAD excutes the process until a DONE or similar is run.
This is the one that finally is completed:
In this case, each time we press intro we will se how the execution goes further, first the ATGT, then the ATLT y and when we get to MESSAGE 3 a new option appears in menu (condMessage):
That option allow us to see which message is that, and will only appear if next condact is MESSAGE, MES, SYSMES or DESC. In the picture below you can see ho the text “Arboles y mas ….” is shown (it’s a description of the forest).
Run to parse
Run to parse, the option you get to pressing P, let’s the debugger know “ok, I’ve seen enough, run all condacts without stepping until a player command is requested. That let us check the part of the code we want to check, but then run fast until next input.
This option lets the debugger know he has tu run all condacts until a DEBUG condact is found. But there is no condact named DEBUG. Well, with the DAAD Reborn Compiler, aka DRC (https://github.com/Utodev/DRC) you can add that fake condact to you code, then you also add #debug at the start of your source file, and ZEsarUX will stop where you put that condact.
This is done to save you from having to run step by step lots of code until you reach the part you are interested in. Just put a DEBUG fake condact in the right place, activate the DAAD Breakpoint, and ZEsarUX will enter step mode where you want.
Please don’t forget to remove the DEBUG fake condacts from your source file, or at least remove the #debug directive at the beginning of source file (which will make the compiler skip all the DEBUG fake condacts as if they were not there).
It is possible to use this feature using original DC compiler, but it’s a little more complicated. Instead of DEBUG enter “#DEFB 240”. Don’t forget to remove them later!
The debugger does also allow us to see all message tables in the game. Just press E from the debugger and you will have a list of tables to view.
Choose the one you prefer and you will see it:
Pleas notice the many ? signs in the previous screenshots are there cause saome control codes (\n, #n, #k o \k, #b o \b, etc.) and some of the spanish special characters are not supported, so a ? character is drawn instead. If your game has accented vowels or “ñ” you will see them without the tilde, and “n” instead.
This feature is avaliable from ZEsarUX 7.3, you can download it here for Windows, Linux andMacOS:
ZEsarUX - ZX Second-Emulator And Released for UniX - chernandezba/zesarux
Please notice the DAAD debugger will only work in 48k mode, what’s not a problem as DAAD works with 48k only.
That’s all for today, ZEsarUX debugger is what you need to get your DAAD code to the infinity and beyond :-)
You can follow me in twitter at @uto_dev, for more information about DAAD, PAW and some other retrogaming stuff.