
SCARE contains a game debugger that offers a few features that might help with
debugging Adrift games, though its primary purpose is to help debugging SCARE
itself.

To access the game debugger in Linux, set the environment variable
SC_DEBUGGER_ENABLED prior to running SCARE.  Any value will do.  Other SCARE
platform interfaces may use different ways to enable the debugger.  When
debugging, it may also be useful to set SC_STABLE_RANDOM_ENABLED.  This makes
sure that SCARE generates predictable random number sequences.

When the debugger is enabled, SCARE offers the following prompt directly after
loading the game:

    --- SCARE 1.3.10 Game Debugger
    --- Type 'help' for a list of commands.

    [SCARE debug]>

The way the debugger appears may vary, depending on how the interface to SCARE
is written; the default where an interface does nothing special with debugging
input and output is that this prompt appears in the main game display window.

You interact with the debugger in much the same way as interacting with the
game itself, by entering debugging commands at the prompt.  The debugger lets
you examine the state of the game, and also set 'watchpoints' -- monitors on
changes in the games objects, NPCs, tasks, or other attributes that the
debugger will catch when they happen.

The following debugging commands examine game state:

    game              -- Print general game information, and class counts
    player            -- Show the player location and position
    rooms [Range]     -- Print information on game rooms
    objects [Range]   -- Print information on objects in the game
    npcs [Range]      -- Print information on game NPCs
    events [Range]    -- Print information on the game's events
    tasks [Range]     -- Print information on the game's tasks
    variables [Range] -- Show variables defined by the game

For example:

    [SCARE debug]>player
    Player "Professor Pettibone"
        In Room 0 "In the basket of a balloon"
        Standing

    [SCARE debug]>room
    Room 0 "In the basket of a balloon"
        Visited
        Player "Professor Pettibone"
        Dynamic 0 "the" "overcoat"
        Static 1 "the" "gas valve rope"
        [...]
        Static 55 "the" "sky"
        NPC 0 "Mister" "Hubert Booby"

Most commands take range inputs.  This can be a single number, to apply the
command to just that item, a range such as '0 to 10' (or '0 - 10', '0 .. 10',
or simply '0 10') to apply to that range of items, or '*' to apply the
command to all items of the class.

If you omit the range, the debugger applies the command only to the items of
the class 'relevant' to the current game state.  For Rooms, this is the
current player room; for Objects and NPCs, it's the objects and NPCs in the
current player room; for Events, this is all running events; and for Tasks,
it's all runnable tasks.  For variables, omitting the range is the same as
'*', all variables.

The 'player', 'objects', 'npcs', 'events', 'tasks', and 'variables' commands
may be prefixed with 'old', in which case the values printed will be those
for the previous game turn, rather than the current values.

These debugging commands manage watchpoints:

You can prefix the 'player', 'objects', 'npcs', 'events', 'tasks', and
'variables' commands with 'watch', to set watchpoints.  Use Watchpoints to
automatically enter the debugger when the item changes state during a game
turn.  For example 'watchobject 10' monitors object 10 for changes, and
'watchnpc *' monitors all NPCs.  A 'watch' command with no range prints out
all watchpoints set for that class.

When the game hits one or more of the watchpoints, SCARE prints a message
telling you which ones triggered, and on which Object, NPC, and so on, then
immediately enters the debugger, something like:

    --- Object watchpoint triggered { 10 }.
    --- NPC watchpoint triggered { 0 1 2 }.

    [SCARE debug]>

You can then examine the current game state, and use the 'old' prefix to see
what change triggered the watchpoint.

Prefix commands with 'clear' to clear watchpoints, for example 'clearnpcs *'.
Use 'watchall' to obtain a complete list of every watchpoint set, and
'clearall' to clear all watchpoints in one go.  A 'clear' command with no
range behaves the same as a 'watch' command with no range.

These debugging commands print details of game output and control the
debugger and interpreter:

    buffer            -- Show the current buffered game text
    resources         -- Show current and requested game resources
    random [Seed]     -- Control the random number generator
    step              -- Run one game turn, then re-enter the debugger
    continue          -- Leave the debugger and resume the game
    quit              -- Exit the interpreter main loop
    help [Command]    -- Print help specific to Command

You may abbreviate debugging commands to their shortest unambiguous form.
You can use 'quit' as a fast exit from the interpreter, equivalent to a
confirmed 'quit' within the game itself.

When the game is running, you can use the 'debug' or '#debug' command, typed
at the usual game prompt, to return to the debugger at more or less any time.
The exception is if a game catches all input with one of its tasks, in which
case it will "swallow" your 'debug' command; this is one reason why the debug
prompt appears on starting the game, giving you a chance to set watchpoints
for any of the game's initialization tasks or events.

The debugger triggers watchpoints by comparing the new game state with a copy
taken for undo purposes just before the game turn is run by SCARE.  The more
watchpoints you set, the more work the debugger has to do on each game turn,
but the overhead of this isn't really noticeable.

SCARE's debugger is disabled by default because it offers major game spoilers.
Time spent in the debugger does not count as time spent in the game; as far as
games that measure playing time are concerned, time stops while the debugger
is active.

