SCI/FreeSCI/Debugger/Debugger commands

From ScummVM :: Wiki
< SCI‎ | FreeSCI‎ | Debugger
Jump to navigation Jump to search

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).
bpdel (index)
Deletes a breakpoint from the specified index of the list of active breakpoints.
bpe (script, index)
Add a breakpoint terminating when the specified exported function of a script is called.
Lists all active breakpoints.
bpx (method)
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.
debuglog [mode]
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.
disasm (address) [number]
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.
dissectscript (script))
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.
draw_viewobj (object)
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.
dump (restype, resnr)
Displays a hex dump of the specified resource.
dumpnodes (index)
Lists up to index nodes of the parse tree.
Lists all parser words
Prints the port ID of the current port.
gfx_debuglog [mode]
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
gfx_draw_cel (view) (loop) (cel)
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.
gfx_draw_rect (x) (y) (width) (height) (color)
Draws a single rectangle to the screen. The color parameter describes an EGA color (0-15) which will be the rectagle's color'.
gfx_drawpic (pic) [palette] [flags]
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 operational layer section).
gfx_fill_screen (color)
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 Printing widgets section.
gfx_print_port [port]
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

Printing widgets section.

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 Printing widgets section.
gfx_widget [widget]
(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 Printing widgets section.
gfx_priority [priority]
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.
gfx_propagate_rect (x) (y) (width) (height) (buffer)
Propagates a rectangular zone from the back buffer (0) or static buffer (1) to the next higher buffer.
gfx_show_map [nr]
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
Buffers 1 and 2 will be rendered in EGA colors, with color values representing the associated priority/control values (this is identical to Sierra SCI behavior).
gfx_update_zone (x) (y) (width) (height)
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.
heapdump (address) (number) : 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).
heapobj (address)
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.
hexgrep (resource, hex 2-tuples+)
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").
list (string+)
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 (e.g.: "list view")
Lists all parser rules in their normal almost-CNF representation.
listinfo (address)
So FreeSCI doesn't have an interactive list debugger as in Sierra SCI. But it has something better[1]: A list dumper, which lists all list elements, keys, and heap positions.
man (command)
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.
parse (string)
Attempts to parse a single string, and displays the word groups, word classes and the resulting parse tree, if successful.
print (variable)
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.
resource_id (number)
FreeSCI packs resource type and number into the usual resource id combination. Use this little helper function to unpack it.
restart [string]]
Forces a restart of the current game. The string parameter is meaningless now.
restore_game (name)
Tries to restore a game state from the specified directory. See Savegames section for details about this.
s [number]
This function will execute number steps, or one if number was not specified.
save_game (name)
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 Savegames section 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.
set (variable, int)
Sets the specified variable to a new value.
set_acc (number)
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.
set_vismap (mapnr)
Sets the visual display map. Mapnr can be any of the following:
  • 0 Visual map
  • 1 Priority map
  • 2 Control map
  • 4: Auxiliary map[2]
This function is a no-op since FreeSCI 0.3.1
simkey (keynr)
Simulates a keypress of a key with the specified key number. Modifiers are not applied.
size (restype, resnr)
Displays the total byte size of one single resource.
snd ...
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.
snd stop
Suspends the sound server. This is the opposite of 'snd resume'.
snd resume
Resumes the sound server after it has been suspended.
snd play (song)
Instructs the sound server to play the indicated song with a handle of 42.
snd mute_channel (channel)
Mutes the indicated MIDI channel; events sent to this channel will be discarded before they reach the sound hardware.
snd unmute_channel (channel)
Undoes a previous 'mute_channel' command, or part of a previous 'snd mute'.
snd mute
Mutes all channels (as per 'snd mute_channel').
snd unmute
Unmutes all channels (as per 'snd unmute_channel').
snd solo (channel)
Mutes all but one channel.
snd printchannels
Lists all channels, and the instruments currently playing on them.
snd printmaps
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.
snd songid
Retreives the numerical ID of the song currently playing from the sound server. Songs started with 'snd play' have a song ID of 42.
sndmap ...
Executes MT32 to GM sound mapping commands.
sndmap mute (instr)
Mutes the specified instrument.
sndmap percussion (instr) (gm-percussion)
Maps the specified instrument to a GM percussion instrument.
sndmap instrument (instr) (gm-instrument)
Maps the instrument to a normal GM instrument.
sndmap shift (instr) (shift-value)
Sets the shift value for the instrument.
sndmap finetune (instr) (val)
Fine-tunes the instrument, as via the MIDI command.
sndmap bender (instr) (bender)
Chooses a bender range for the instrument.
sndmap volume (instr) (vol)
Sets a relative instrument volume, ranging from 0 to 128.
snk [number]
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.
stack (number)
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.
viewinfo (number)
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.
vmvars (type) (index) [value])
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.


  1. Well, this is debatable.
  2. Not really meaningful; only used while pic resources are drawn.