How ScummVM Detects Games, Variants, and Unknown Releases

ScummVM does not decide that a directory contains a supported game from one executable name. Each engine plugin implements detection logic that combines expected files with fingerprints, sizes, platform, language, and variant metadata. The result selects an engine and creates a configured target that can later carry user settings and saved games.

This distinction matters when an uncommon CD pressing, translation, demo, or fan-maintained release appears as an “unknown variant.” Detection failed to identify an exact table entry; it did not necessarily prove the files are corrupt, unsupported, or interchangeable with the closest title in a menu.

Engines own their detection data

ScummVM’s plugin architecture lets each engine describe the families of data it understands. Many engines use the shared advanced detector framework. Detection tables list a game ID and one or more file descriptions, then attach language, platform, variant text, flags, GUI options, and engine-specific metadata.

The required file set distinguishes games that share generic names such as resource.000 or data.dat. A fingerprint, often an MD5 over a defined portion of a file, separates releases whose directory layouts look identical. File size provides another useful discriminator and catches many truncated or altered copies.

The exact hashing rule is detector-specific. Do not calculate an arbitrary whole-file checksum and conclude it should match a table that fingerprints only an initial segment, nor assume every engine uses the same byte limit. Read the relevant engine’s detector code and the unknown-variant report emitted by the running ScummVM build.

A game ID is not a configured target ID

The game ID names a supported game family inside an engine. A target is the user’s configured instance, with a unique domain in the ScummVM configuration file. Two targets can point to different language releases of the same game and keep separate options or save paths.

Changing a target ID to make a launch command look familiar does not change the detected data. Likewise, selecting a nearby game ID manually cannot transform one engine’s assets into another variant. Preserve the detected engine, platform, language, and extra description as evidence of what was selected.

When adding a directory from the launcher or command line, verify the path contains the complete data set required by the ScummVM documentation. Installers sometimes leave files across several discs or nested directories. Copy the documented game data from a legitimately owned source into a clean directory without mixing patches from another edition.

Directory scans are intentionally bounded

Detection can inspect subdirectories according to engine declarations, directory globs, and scan-depth limits. Bounded scanning avoids crawling an entire drive and prevents unrelated files from becoming accidental candidates. It also means pointing ScummVM at a collection root may miss a deeply nested game that is detected immediately when its real data directory is selected.

Keep one release per directory during diagnosis. A folder containing multiple editions can satisfy several partial signatures, produce ambiguous results, or select files from the wrong set. Case sensitivity also varies by host filesystem, while historical media and detector rules may expect particular names.

Do not rename files solely to satisfy an expected list. Names are only one part of detection, and a forced name can hide the fact that content belongs to a different patch level or platform.

Fallback detection reads format structure

Not every valid release has an exact static table entry. Some engines implement fallback detection based on signatures or structural properties inside the data. That can identify a game family while leaving the precise edition unknown.

Fallback is engine code, not a license to guess. The detector should make the weakest conclusion supported by the bytes it parsed. A user interface may show a warning or extra text indicating that a variant is unrecognized even though the engine can attempt to run it.

Support status is also separate. An exact detector match can point to a game whose engine remains incomplete, while a structurally detected variant may run well. Check the compatibility information for the ScummVM release being used and reproduce issues on the latest official build before filing a report.

Unknown variants are valuable preservation evidence

An unknown legitimate release can fill a gap in the project’s tables. Preserve the original media, note its label and catalog information, and follow ScummVM’s reporting instructions. The detector often prints the file names, sizes, hashes, and an engine-specific entry maintainers need.

Submit generated metadata, platform, language, edition, and whether the files came from original media or an official digital release. Do not upload copyrighted game data to an issue unless the rights and project instructions explicitly permit it. In most cases the fingerprint and provenance are enough for maintainers to determine whether a new entry is justified.

Before reporting, remove unofficial translations, no-CD modifications, fan patches, resource replacements, and files copied from another edition. Re-run detection on a clean extraction. A fingerprint for a modified executable documents the modification, not a previously unknown retail release.

Detection tables evolve with ScummVM

A result belongs to a particular ScummVM build. New releases add detector entries, refine file lists, and sometimes split variants that older versions grouped together. Record the exact version and build revision with every reproduction.

When a working target changes after an upgrade, keep the old configuration and save data untouched, scan a copy of the game directory with both versions, and compare detection output. Do not overwrite saves until the new engine has loaded a duplicate successfully. Detection selects an engine, but save compatibility follows engine-specific rules.

Downstream distributions may ship a different plugin set from the official build. A missing engine plugin can make a known game appear unsupported even when upstream has a detector. Confirm which engines are compiled and available before modifying the data files.

Audit a collection without altering it

For each game, record a read-only inventory of paths, sizes, and cryptographic hashes of the full files for your own preservation manifest. Then run ScummVM detection and store its separate engine-specific result. These two records answer different questions: the manifest proves whether your copy changed, while detector output shows how a given ScummVM version classified it.

Test that the configured target launches, reaches an interactive scene, sees expected speech or subtitles, and creates a save in a controlled location. Preserve logs for warnings about unknown variants or missing files. A launcher entry alone is not a complete acceptance test.

Good detection practice never alters bytes to obtain a prettier label. It preserves provenance, gives the engine an unmixed data directory, distinguishes a target from a game ID, and reports unknown releases with reproducible metadata. That approach improves both personal collections and ScummVM’s long-term knowledge of software history.

Related:

Sources: