The built-in debugger takes advantage of a built-in command interpreter (which is not to be confused with the SCI command interpreter). It's appearance is going to vary in between versions (at the time of this writing, it runs on the terminal FreeSCI was started on, in text mode; later versions will likely integrate the debugger to the graphics screen), but all versions of FreeSCI will come with a working debugger[1]. Consult the documentation of your specific release for details on how to invoke it, if it is not activated automatically.
If activated, the debugger is called in between operation fetching and operation execution. It will show the command that is to be executed next, predicting the action done by send, super, and self calls where possible, and displaying any parameters to calling operations. It will also display the current register values and the number of operations that have been executed. It then waits for user input.
In order to simply execute the next operation, execute the "s" command. This will do one step of execution. If you want to execute more than one command, invoke "s [number-of-steps]". Other ways to step forward are "snk" (Step until the Next Kernel function is invoked) and "function/sret/" (Step until the interpreter RETurns from this function).
Speaking of functions, the FreeSCI interpreter also keeps a list of the call stack. This is similar to what the Sierra SCI interpreter provides as the "send stack", but it also includes call, calle and callb commands. Please note that callk commands are not included (some kernel functions actually call functions in user space). To display this list, invoke "bt". This function will list all calls on the stack, the parameters they carried, from where they were invoked, and the called object[2] and selector (where applicable).
Selectors are not only used for functions, of course, they are also used as variables. To inspect the selectors of the current object, use the "obj" operation. Sometimes you might want to inspect how a send operation influenced an object; do so by calling "accobj", which will show the selectors of the object indexed by the accumulator register (as used in sends).
For a complete listing of debugging commands, refer to the next chapter.
The FreeSCI built-in debugger provides the following commands:
The send operation requires a target object, which needs to be stored in the accumulator. This operation makes it possible to check if there is an object at the location indexed by acc, and, if it is, dump the type of object (Class, Object, or Clone), the object's name, and some other interesting stuff (selector names and values, funcselector names and addresses).
Deletes a breakpoint from the specified index of the list of active breakpoints.
Add a breakpoint terminating when the specified exported function of a script is called
Lists all active breakpoints.
Adds a breakpoint to the specified method.
Backtrace: Shows the execution stack, bundled with call parameters and selector names where appropriate.
One of the nice things about FreeSCI is that it doesn't hide its class table as Sierra SCI appears to do. With this command, you have the power to unravel the mysteries of classes and superclasses at your fingertips.
Clears the screen background from all dynviews, i.e. only picviews, dropped dynviews and the background pic resource are displayed.
FreeSCI doesn't take Clone()ing lightly. It carefully notes which clone was created and tracks its current position. This function allows you to find them all, and in the darkness bind them.
FreeSCI keeps an internal list of flags for specific areas of the game that should be watched more closely. The 'debuglog' command activates or deactivates debug output for each of those areas. Each area is described by a letter; to activate debugging for that area, use "debuglog +x", where x is the area you want to debug. "debuglog -x" deactivates debugging for that area. To activate or deactivate multiple areas, concatenate their single-letter descriptions. Run "debuglog" without parameters to get a listing of all active modes. The modes and describing letters are listed below.
| a: The audio subsystem |
| b: The Bresenham line algorithm functions |
| c: Character and string handling |
| d: System graphics display and management |
| f: Function calls |
| F: File IO |
| g: Graphics |
| l: List and node handling |
| m: Memory management |
| M: Menu system |
| p: The command parser |
| s: Base setter: Draws the bases of each actor as colored rectangles |
| S: Said specs |
| t: Time functions |
| u: Unimplemented functionality |
| *: Everything at once. Use with care. |
Exits the interpreter ungracefully.
The debugger is able to disassemble code parts on the fly. Just give it an address to dissassemble (and a number of commands to dump, if you're feeling bold enough to look at more than one of them simultaneously). Unfortunately, it can only do send prediction and parameter resolution if it is disassembling the PC.
Dumps a script resource (with the specified number) and examines it. Lists classes, static objects, relocation tables, and all the other stuff contained in scripts.
These are dmalloc utility functions. They are described in the dmalloc section below.
This operation draws the boundaries of the cel described by the indicated SCI object to the screen. The nsRect is drawn in green, the brRect in dark blue, and the position is marked by a small cross in the cel's priority, within a black box.
Displays a hex dump of the specified resource.
Lists up to index nodes of the parse tree.
Lists all parser words
Prints the port ID of the current port.
Toggles debug flags for the graphics driver. Using "+x", the flag 'x' can be enabled, "-x" disables it. Multiple flags can be set at once, e.g. "+abc" or "-abc". With no parameters, all flags currently enabled are displayed. Note that, depending on the graphics driver in use, some flags might not be used. The list of supported flags follows.
| b: Basic driver features |
| p: Pointing device management |
| u: Screen updates |
| x: Pixmap operations |
Draws a single cel to the center of the screen (augmented by the cel's delta-x and -y values). Depending on your graphics driver, you may have to refresh the screen for this to become visible.
Draws a single rectangle to the screen. The color parameter describes an EGA color (0-15) which will be the rectagle's color'
Renders a pic resource. The palette value specifies the pic's palette to use; if not specified, 0 will be assumed. flags set any of the pic drawing flags used in the operational layer (see the Section called The operational layer>).
Fills the entire screen (visual back and front buffer) with an EGA color.
This will free the main visual widget and all widgets it contains. Since it essentially invalidates the structured representation of the screen content, this will make the interpreter run into segfaults if you resume. It is intended for memory profiling and heap testing.
Prints the current dynview list. This list is generated by the Animate() kernel call and represents the visual state of all dynamical images on the screen. Documentation regarding the meaning of the widget descriptions can be found in the Section called Printing widgets.
Dumps the contents of the port specified (or, if omitted, the current port) to the output stream. Documentation regarding the meaning of the widget descriptions can be found in the Section called Printing widgets.
Prints the visual widget, and, recursively, its contents; this widget is the root widget, therefore, the structured representation of all graphical information will be print. Documentation regarding the meaning of the widget descriptions can be found in the Section called Printing widgets.
(This function is only available if the interpreter was compiled with widget debugging enabled)
If the parameter is not specified, this will print a list of all used widget debug slots (each widget goes into exactly one slot); if the parameter is specified, it is used as an index in the widget debug slot list, causing the corresponding widget to be print. Documentation regarding the meaning of the widget descriptions can be found in the Section called Printing widgets.
If no parameter is supplied, the start and end values of the priority line list will be print. Otherwise, this function prints the first line of the specified priority region.
Propagates a rectangular zone from the back buffer (0) or static buffer (1) to the next higher buffer.
Draws one of the screen maps to the visual back buffer and updates the front buffer. The maps are numbered as follows:
| 0: Visual buffer |
| 1: Priority buffer (z buffer) |
| 2: Control buffer |
Propagates a rectangle from the back buffer to the front buffer; the rectangle's origin and dimensions are passed as parameters.
Lists the rules of the GNF grammar used internally in FreeSCI to parse input.
Deactivates debug mode and runs the game. Debug mode can be re-activated in the usual ways.
Invoking this function will spit out number bytes, starting at address.
Prints all heap segments, including information whether they are allocated or not.
Dumps a list of the free heap space (free, not gratis).
This is the same as accobj, but it can interpret any object on the heap. Note that the "home" address of objects (as used here) are 8 bytes into the object structure (which starts with the magic number 0x34 0x12), and points to the first (zeroeth?) selector.
Searches for a list of hexadecimal numbers inside a single resource (if specified like "script.042"), or in a set of resources (if specified like "pic").
If called without parameters, it lists all things it can list. Among these are:
| vars: Global interpreter variables |
| cmds: All available commands |
| restypes: All resource types |
| selectors: All selectors |
| syscalls: All kernel functions |
| [resource]: All resources of that type (ex: "list view") |
Lists all parser rules in their normal almost-CNF representation.
So FreeSCI doesn't have an interactive list debugger as in Sierra SCI. But it has something better[3]: A list dumper, which lists all list elements, keys, and heap positions.
Shows a short descriptive message to the command.
Prints information about heap and hunk memory allocation.
This is, in essence, the same function as accobj, but it checks the current base object as opposed to the object indexed by the accumulator.
Lists all objects, classes, and clones that are currently on the stack. They are identified by their properties, and prefixed with an asterisk ('*') if they are clones, or a percent sign ('%') if they are classes.
Attempts to parse a single string, and displays the word groups, word classes and the resulting parse tree, if successful.
Prints the contents of one global interpreter variable.
Exits the interpreter gracefully, by shutting down all resources manually.
This function retrieves the background picture, puts it on the foreground, and redraws everything. It's not inherently useful, though.
This function will show the current values of the program counter, the accumulator, the frame pointer, the stack pointer, the prev register, and the &rest modifier. It will also print the addresses of the current base object, of the global variables, and of the stack.
FreeSCI packs resource type and number into the usual resource id combination. Use this little helper function to unpack it.
Forces a restart of the current game. The string parameter is meaningless now.
Tries to restore a game state from the specified directory. See the Section called Savegames for details about this.
This function will execute number steps, or one if number was not specified.
Saves the current game state to a directory with the specified name. The directory is created automatically; everything inside is deleted, and the game data is stored. See the Section called Savegames for details about this.
Prints the SCI interpreter version currently being emulated
Lists all scripts that have been loaded, their positions in memory, and the position of their local variables and exports.
Steps forward until an SCI keyboard event is received.
Sets the specified variable to a new value.
Frobbing the accumulator is not recommended, but it may be fun at times. Use this command to set your favourite register to an arbitrary value and watch things blow up.
Sets the nodes of the parse tree, and shows the result in list representation. Useful to display information gathered from a certain hacked version of Sierra's SCI interpreter in a more readable fashion.
Sets the visual display map. Mapnr can be any of the following:
| 0: Visual map |
| 1: Priority map |
| 2: Control map |
| 4: Auxiliary map [4] |
Simulates a keypress of a key with the specified key number. Modifiers are not applied.
Displays the total byte size of one single resource.
This executes a sound command. Due to the nature of pipelining between the sound server and the interpreter, it is possible that the result messages of those operations will not be print immediately, so you may have to issue a second command in order for the results of the first command to be displayed.
Also, please note that after entering the debug console, the sound server is, by default, suspended, so you will have to issue an explicit snd resume to do anything useful.
Suspends the sound server. This is the opposite of 'snd resume'.
Resumes the sound server after it has been suspended.
Instructs the sound server to play the indicated song with a handle of 42.
Mutes the indicated MIDI channel; events sent to this channel will be discarded before they reach the sound hardware.
Undoes a previous 'mute_channel' command, or part of a previous 'snd mute'
Mutes all channels (as per 'snd mute_channel')
Unmutes all channels (as per 'snd unmute_channel')
Mutes all but one channel
Lists all channels, and the instruments currently playing on them
Prints the instrument names and all General MIDI mappings for the song currently playing. This operation will only work correctly if MT-32 to General MIDI translation is being performed.
Retreives the numerical ID of the song currently playing from the sound server. Songs started with 'snd play' have a song ID of 42.
Executes MT32 to GM sound mapping commands.
Mutes the specified instrument
Maps the specified instrument to a GM percussion instrument
Maps the instrument to a normal GM instrument
Sets the shift value for the instrument
Fine-tunes the instrument, as via the MIDI command
Chooses a bender range for the instrument
Sets a relative instrument volume, ranging from 0 to 128.
Another step command: Step until the interpreter hits a callk command. If you're hunting for a very specific kernel call, just add its number as a parameter. Syscall hunting has never been so easy.
"Steps over" one instruction, i.e. continues executing until that instruction has been completed (useful for send, call, and related functions)
Step until RETurning. If you're bored of the function you're debugging, just invoke this command. It will step forward until the current function returns.
Can't remember what you pushed on that stack, and in which order? This command will display as many stack elements as you want, starting at the TOS.
Displays the interpreter and SCI game versions
Examines the specified view resource and displays the number of loops it has, the number of cels for each loop, and the size for each cel.
Lists the heap positions of the current global, local, parameter, and temporary variables.
Reads or sets a global, local, temporary, or parameter value. Type must be any of 'g', 'l', 'p', 't', to select global, local, parameter or temporary variables (respectively), while index represents the variable index. If value is not provided, that variable will be displayed; otherwise, it will be set to value.
The FreeSCI console proivdes an interface to the dmalloc memory debugger/profiler, if the interpreter was compiled with dmalloc support enabled. The following commands are provided:
Prints the current heap state into the dmalloc log file
Prints memory usage statistics to the output file
Lists unfreed pointers in the dmalloc output file
Verifies a pointer and prints the result to the dmalloc output file. Specifying 0 instead of a pointer will verify all pointers currently known to dmalloc.
Sets the dmalloc debug flags (please refer to the dmalloc documentation for a description)
Gets a mark describing the current heap situation (see also 'dm_chmark')
Compares a mark retreived by 'dm_mark' with the current heap situation, and prints the results to the dmalloc output file.
Prints arbitrary output to the dmalloc output file
| [1] | That's what I hope, anyway. |
| [2] | This is note quite correct: The object listed is, in fact, the object which is used as the base object for execution. This only makes a difference if the super operation is executed, but it may be confusing. Consider it a bug. |
| [3] | Well, this is debatable. |
| [4] | Not really meaningful; only used while pic resources are drawn. |