SCI/FreeSCI/Debugger/Debugger commands

The FreeSCI built-in debugger provides the following commands:

accobj

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.

bplist

Lists all active breakpoints.

bpx (method)

Adds a breakpoint to the specified method.

bt

Backtrace: Shows the execution stack, bundled with call parameters and selector names where appropriate.

classtable

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.

clear_screen

Clears the screen background from all dynviews, i.e. only picviews, dropped dynviews and the background pic resource are displayed.

clonetable

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.

die

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.

dm_*

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.

dumpwords

Lists all parser words

gfx_current_port

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.

gfx_free_widgets

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.

gfx_print_dynviews

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.

gfx_print_visual

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 behaviour).

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.

gnf

Lists the rules of the GNF grammar used internally in FreeSCI to parse input.

go

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.

heapdump_all

Prints all heap segments, including information whether they are allocated or not.

heapfree

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")

list_sentence_fragments

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: A list dumper, which lists all list elements, keys, and heap positions.

man (command)

Shows a short descriptive message to the command.

meminfo

Prints information about heap and hunk memory allocation.

obj

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.

objs

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.

quit

Exits the interpreter gracefully, by shutting down all resources manually.

redraw_screen

This function retrieves the background picture, puts it on the foreground, and redraws everything. It's not inherently useful, though.

registers

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.

sci_version

Prints the SCI interpreter version currently being emulated.

scripttable

Lists all scripts that have been loaded, their positions in memory, and the position of their local variables and exports.

se

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.

set_parse_nodes

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

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.

so

"Steps over" one instruction, i.e. continues executing until that instruction has been completed (useful for send, call, and related functions).

sret

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.

version

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.

vmvarlist

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.