Edits included. Any other comments? If not, please link to the web page.
I changed the bug in the example to #357 since it's a little more obvious.
I'll have the next tutorial done next week sometime. BTW, "kiss death
angel" doesn't work in either version of PQ2.
Problem: In some games, ego can't walk to certain areas, other actors get
stuck, walk-over effects don't happen, you're always too far away from
an object to do something with it, or actors move through solid objects.
Sometimes, FreeSCI doesn't draw lines or fill boxes on the control map
properly or fully emulate Sierra SCI's , which sometimes results in these
kinds of bugs. The first thing
to do is to compare the control map as FreeSCI renders it, and the way Sierra SCI
renders it for the room where you are observing the problem. This requires
a DOS/Windows machine (or emulator) to run the original game on, a hex
editor, and a copy of FreeSCI. Having the game is helpful, also. In this
example, we'll use bug #357 as the basis for our investigation. Bug #357
affected Police Quest 2 version 1.002.011 in room 25.
First, get farmiliar with activating the debugger in Sierra SCI (SSCI) and
FreeSCI (FSCI). After starting the game, we press both Shift keys and the
minus ("-") key on the keypad at the same time. The game should pause, and
a dialog box with a title of "Debug" should appear in the upper right-hand corner.
In FreeSCI, pressing the Control key and the tilde ("~" or "`") key
activates the debugger. In FreeSCI, the game should halt and the text
window give some information about where the game has stopped. To see a
list of debugger commands in SSCI, type shift+? while in the debugger. To
see a list of debugger commands in FSCI, type "list cmds" at the debugger
prompt. To get more information on an FSCI debugger command, type "man
cmd"; where cmd is the command you want more information on. You can also
check the documentation on the FreeSCI web page for more information.
To repeat commands in the FSCI debugger, use the up and down arrow keys to
cycle through recently entered commands.
>From here, we "teleport" to the room where the problem is. In SSCI,
we break into the debugger, then press "g" key. (For a list of SSCI
debugger commands, press shift+? while the debugger is active.)
When prompted for which global variable you wish to edit, enter "13" and
press enter. Global variable 13 stores the current room number, changing
it and breaking out of the debugger will "teleport" ego to that room.
Note that this isn't a very good way to cheat, since some game flags won't
be set -- it serves our purpose of just seeing the room, though.
In the case of bug #357, we want to teleport to room 25. After choosing
global variable 13, we see a new window in SSCI that displays the current
value of the variable we are editing. Use backspace to erase the current
value, type "25", and press enter.
If you don't know what the room number is, restore your savegame where the problem
occurs. Break into debug modein SSCI, edit the global variable 13, and
note the current value.
In FSCI, break into the debugger. At the debugger prompt in the text
window, type "vmvars g 13 25" to change global variable 13 to the value of
25. To see what room you are currently
in, type "vmvars g 13" and the debugger will output the value in decimal
(base 10) and hex (base 16) of the Virtual Machine's global variable 13.
After changing the value of the global variable 13, resume the game. In
SSCI, press both Shift keys and "D" together to resume executing the game.
In FSCI, type "go" at the debugger prompt. The game should now resume, but
magically in room 25 (in PQ2 this is the Snuggler's Inn). Note that
entering a room that doesn't exist can cause the virtual machine to crash.
Now that we know how to get the room in both interpreters easily. We'll
need to compare the control maps in both interpreters. FSCI's debugger has
a built in command to do this, but SSCI will require some hex editing on
the SCIV.EXE/SIERRA.EXE binary. We'll start with the FSCI debugger first.
Once in the room with the bug in FSCI, break into the debugger. Make sure
the window that is diaplying game graphics is fully visible, as you won't
be able to move the window while broken in the debugger. If the
graphics from another window interfere or the window is blank, use the
"redraw_screen" command in the debugger to redraw the graphics in the
FreeSCI window. In the debugger, type "gfx_show_map 2". Map 1 is the
priority map, map 2 is the control map. The priority map says which
images go in front of which other images, giving the game a sort of 3D
effect. The control map is used by scripts to determine behaviour and to
limit the movement of actors in the room. For instance, standing in a box
on the control map would tell a script that the actor is close enough to
push a button. If the box on the control map is drawn incorrectly, the
script might think the actor is never close enough to push the button.
This is the case with bug #357. To make the display normal, type
"gfx_show_map 0" in the debugger and press enter.
To display the control map in SSCI is a bit more complicated. The SSCI
debugger doesn't have the functionality to change which map is being
displayed, so hex editing of the interpreter's executable is necessary.
On Windows, I like "Hex Workshop" for this step. Make a backup of the
original executable. Load the SCIV.EXE or
SIERRA.EXE into the hex editor and search for "01 00 00 00 01 00" in hex.
When it is found, edit the second 01 to be 04 and save the executable.
When you run the interpreter now, only the control map will be displayed.
(When done, change the 04 back to 01 to regain normal functionality.)
Enter the debugger and teleport to the room as you normally would.
Now that you can see the control map in both interpreters, note any
obvious differences like shapes missing entirely, shapes that are not
filled with the same color, etc. Note that FSCI's control map does not
always draw some of the white rectables you might see in SSCI's control
map because FSCI handles collisions between some props and actors
differently than SSCI. Ultimately, if the behaviour is different between
FSCI and SSCI, then you have a bug. If the control map is just missing
some white boxes, it may not be a bug. Ask on the mailing list or IRC
channel to be sure. Note that not all bugs with the behaviours mentioned
at the beginning of this document are control map bugs, sometimes dynviews
of pic views are given a wrong "bounding area" due to miscalculation on
FSCI's part. Inspecting objects to find this "bouding area" will be in a
future tutorial.
To get assistance from other FSCI
developers and testers, it is usually a good idea to get a screenshot of
the control map in SSCI if possible. To do this in Windows, run the
interpreter in a DOS shell. When at the point where you want to take a
screen shot, press Alt+Enter. With the DOS window selected, press
Shift+Print Screen. (Print Screen is usually next to the Scroll Lock key.)
Click Start->Run, then type mspaint. In mspaint, press Shift+Insert
(Control+V also works) and answer Yes to resize the bitmap. The image from
the DOS window should appear in MSPaint, select File->Save As to save the
bitmap to a file (16 colors preferred).
When reporting the bug, mention the room and the obsreved differences in
the control map (if any). Giving a URL to the screenshot or privately
mailing it to one of the developers is also a good idea. Please note the
version of the game you are reporting against! In the example of bug #357
(any many other bugs), the bug is only in one version of the game and not
the other.
Next tutorial: Getting behind things -- debugging priority map problems.
--
http://www.clock.org/~matt
