ScummVM Engine Debuggers: Observe a Failure Without Changing the Evidence

ScummVM’s interactive console is an engine debugger, not a universal command prompt for every supported game. That distinction matters when a character stops walking, a script fails to advance, a room renders incorrectly, or an audio transition disappears. The framework supplies common inspection tools, while individual engines register their own commands and variables. A command copied from a SCUMM investigation may be meaningless in another engine, and some commands deliberately alter the state being investigated.

This article describes an observation-first workflow. Its examples follow the current upstream debugger implementation reviewed on October 11, 2026. They are not a claim that every released build, backend, or engine exposes exactly the same console. Treat the installed version’s help output and the matching source revision as the authority for that session.

Establish a reproducible starting point

Before enabling logging, write down the game edition, language, platform variant, ScummVM version, configured target, and the actions that trigger the failure. The target is the launcher entry, not necessarily the engine’s game identifier. Two entries for the same title can have different paths or options, so recording only the commercial game name leaves important ambiguity.

Use an ordinary saved game made before the failure when the engine supports it. Quit ScummVM, copy the save to a separate backup, and retain that copy unchanged. A debugger experiment should not be the only surviving continuation point. If a bug occurs only when starting from the beginning, preserve the exact input sequence instead of assuming that loading a later save reproduces the same state.

Begin with the smallest sequence that still fails. For example, an investigation record might say: load a specified slot, enter one room, select one dialogue branch, wait for the speech to finish, and click an exit. This is an illustrative record, not a known bug. Removing unrelated actions makes the boundary between a script defect and accumulated session state easier to examine.

Enter the console and discover its actual interface

ScummVM’s debugging wiki documents Ctrl+Alt+D as the default interactive-debugger binding and notes that the keymapper can change it. On devices without that keyboard combination, inspect the configured input mapping rather than assuming the debugger was removed. Backend input handling and a missing engine console are different failures.

Start with these commands where the installed console lists them:

help
debugflag_list
exit

The common debugger registers help, channel-listing commands, and exit. In the implementation reviewed here, exit detaches the console. The same handler is also registered for quit; that name should not be interpreted as proof that it terminates the whole application. This is a useful example of why command names alone are insufficient evidence.

Save the output of help with the reproduction record. It provides a concrete inventory for the engine and build actually running. If an upstream source file lists a command absent from that output, first check the engine, version, and conditional build features. Do not try spelling variations until a state-changing command happens to run.

Separate observation from intervention

The SCUMM engine’s debugger registers commands including actors, objects, scripts, room, actor, script, restart, loadgame, and savegame. It also exposes variables such as the current room and SCUMM variables. Registration establishes that a name exists; the handler determines whether a particular argument form prints information or changes execution.

Classify a proposed command before using it. Reading a list of active scripts is different from manipulating one script. Jumping to another room can omit initialization normally performed by the game’s transition logic. Changing a variable can bypass the condition that caused a hang while leaving other state inconsistent. An apparently successful workaround therefore does not prove that the original failure is repaired.

A practical investigation has two runs. The first records the failure using inspection and limited logging. The second, on a fresh copy of the same starting save, may test a hypothesis by changing one thing. Label the second run as an intervention and retain the unmodified reproduction. This preserves the ability to distinguish evidence from an experimental alteration.

Choose channels instead of indiscriminate verbosity

The common console supports named debug channels and commands to enable or disable them. Engine-specific names come from the registered channel list; there is no universal audio or scripts channel guaranteed across all engines. The implementation also handles the special all argument, but enabling everything can produce a large, noisy log.

An illustrative console sequence is:

debugflag_list
debugflag_enable CHANNEL_FROM_THE_LIST
exit

Replace the placeholder with a name returned by the running engine. Reproduce the failure once, then reopen the console and disable that same channel. Capture a baseline first so the extra output can be evaluated rather than treated as normal behavior.

Logging changes the host workload. If a failure disappears while verbose output is enabled, record that result as timing-sensitive evidence. It does not show that the underlying engine state became correct. Conversely, new audio stutter during a high-volume trace may be a measurement artifact. Compare a short targeted trace with an uninstrumented run before attributing it to emulation or hardware performance.

Find and preserve the log

The official bug-report guide documents platform-specific log locations: %APPDATA%\ScummVM\Logs\scummvm.log on Windows, ~/Library/Logs/scummvm.log on macOS, and an XDG cache-based location on Linux. On Linux, XDG_CACHE_HOME can change the default. Sandboxed packages or device ports may have additional storage boundaries; use the documentation for the actual distribution.

After quitting the reproduction session, copy its log to a uniquely named case file. Record the approximate beginning and end of the failing action sequence. Preserve the complete log, then create a smaller excerpt for communication if needed. Removing earlier warnings from the only copy can erase evidence of a missing resource or fallback selected before the visible failure.

The following manifest is a suggested diagnostic format, not ScummVM-generated output:

Case: dialogue-to-room transition
ScummVM build: exact installed version or commit
Target: launcher entry identifier
Game edition: language, media variant, original platform
Starting save: filename and hash
Steps: numbered user actions
Channels enabled: exact names
Observed result: what stopped or changed
Baseline result: same test without additional logging

Do not publish local usernames, unrelated filesystem paths, cloud credentials, or copyrighted game assets merely because they appeared near useful diagnostics. A save or log may be sufficient for a report without distributing the game data itself.

Escalate at the right boundary

An engine console is useful for game-state problems, but backend crashes, graphics-device failures, or platform-specific memory faults may require a native debugger and a build with symbols. A readable engine trace and a native stack trace answer different questions. Record the exact executable associated with a stack trace; symbols from another build can produce misleading names or line numbers.

ScummVM’s report guide asks for a reproducible issue, the version, edition and language, platform information, and a saved game where possible. It also asks reporters to check current compatibility information and test whether the problem persists in a current daily build. Run that comparison against copied saves and record both builds; testing a daily build should not silently replace the trusted baseline.

The finished investigation should let another person repeat the failure without guessing which settings or debugger edits were used. A successful diagnostic outcome is not merely a console command that makes the game continue. It is an unchanged reproduction, a bounded trace, a clear distinction between observation and intervention, and enough version information to connect the evidence to the code responsible.

Related:

Sources: