diff --git a/docs/concepts/game-folders.md b/docs/concepts/game-folders.md index 7ec005d5..03a8eac1 100644 --- a/docs/concepts/game-folders.md +++ b/docs/concepts/game-folders.md @@ -1,81 +1,93 @@ What is a game folder? ---------------------- -TODO +A game folder +is higan's way of grouping all +the information and resources required +to properly emulate a particular game. +Other emulators group resources related to a game +by requiring that every file has the base name +but different file extensions. + +For example, +if another emulator loaded the game `dkc3.sfc` +it might store the save data in `dkc3.srm`: + +```text ++- Super Famicom + | + +- dkc3.sfc + | + +- dkc3.srm +``` + +higan would create a game folder named `dkc3.sfc`, +and inside it store the game data as `program.rom` +and the save data as `save.ram`: + +```text ++- Super Famicom + | + +- dkc3.sfc + | + +- program.rom + | + +- save.ram +``` Why game folders? ----------------- -A game is more than just -the raw data originally encased in a game's ROM chip. -If a game allows you to save your progress, -that information needs to be stored somewhere. -If you use an emulator's [save states](#save-states), -those save states need to be stored somewhere. -If you use Game Genie or Pro Action Replay codes, -information about what codes exist, -what codes are enabled, -and what they do -needs to be stored somewhere. +The traditional files-with-different-extensions system +works well enough when a game only requires +a small number of files, +because a file extension doesn't offer +much room for description. +Also, +since file extensions traditionally describe +the format of the file in question, +it also means a game can't use +two or more files in the same format. -On the technical side, -a physical game cartridge contains a circuit board -that makes the game data available to the console, -and different games used circuit boards that work differently. -That circuit-layout information needs to be stored somewhere. -Some games included custom processors -to do calculations the base console could not do quickly enough -(like the SuperFX chip used in _StarFox_ for the Super Famicom) -and information about extra chips needs to be stored somewhere. -Some of those custom processors require extra data to work -that's not part of the main game data -(like the DSP chip used in Super Mario Kart for the Super Famicom) -and that data needs to be stored somewhere too. +Compared to other emulators, +higan tends to use a larger number of files per game. +For example, +higan's low-level emulation of Super Famicom co-processors +often requires [separate firmware files][firmware]. +higan's [MSU-1 support][msu1] +requires up to 99 audio tracks per game, +and higan supports up to 133 save-states per game. +Therefore, +higan suffers from the limitations of name-based-grouping +more than most. -higan keeps all this game-related information together -in a single place: -a game folder in the higan library. +higan's game folders allow all a game's resources +to be given unique, descriptive filenames, +and to use the file-extension +that's most appropriate for that file. +They also allow emulator-specific data +like save-states and the cheat database +to be kept separate from the game's actual data, +by putting it in a sub-folder. + +[msu1]: ../guides/import.md#msu-1-games +[firmware]: ../guides/import.md#games-with-co-processor-firmware For a more detailed motivation for game folders, -see [Game Paks on the higan website][gp] +see [Game Paks on the higan website][gp]. [gp]: https://byuu.org/emulation/higan/game-paks -What is a manifest? -------------------- - -TODO - -The most important file in a game folder is `manifest.bml`, -which describes how all the other files should be wired together -to create a runnable game cartridge. -However, -the manifest format has occasionally changed -as new emulation details were uncovered -that could not be represented in the old format. -Therefore, -icarus [defaults](#the-icarus-settings-dialog) -to not writing out manifests when it imports games, -and higan [defaults](#the-configuration-dialog) -to ignoring manifests that are present. -Instead, -when higan loads a game, -it will ask icarus to generate a temporary manifest in the latest format, -based on the files present in the game folder -and how they are likely to go together. -You can view this temporary manifest -in [the Manifest Viewer](#the-manifest-viewer). - What's in a game folder? ------------------------ -As mentioned [above](#why-game-folders), +As mentioned [above](#what-is-a-game-folder), a game folder collects all the information relevant to emulating a particular game. Not all of the following files are relevant to every emulated console, or to every game on a given console, -but they may be relevantunder particular circumstances. +but they may be present under particular circumstances. All the files directly in the game folder are expected to be useful @@ -97,7 +109,7 @@ to all emulators that support them: from the cartridge's ROM chips. - `ines.rom`: While other consoles typically include enough hints - in `program.rom` for icarus to generate a manifest, + in `program.rom` for icarus to guess a working manifest, the Famicom does not. Famicom games not stored in game folders typically include an "iNES header" to store that information, @@ -117,25 +129,20 @@ to all emulators that support them: Games that include a calendar or real-time clock will create this file. - `*.data.rom`, `*.program.rom`: - Files named like this are usually - [co-processor firmware](#importing-and-playing-games-with-co-processor-firmware). + Files named like this are usually [co-processor firmware][firmware]. - `msu1.rom`: - Holds streamable data for - [the MSU-1](#importing-and-playing-MSU-1-games). + Holds streamable data for [the MSU-1][msu1]. - `track-*.pcm`: - Holds streamable audio for - [the MSU-1](#importing-and-playing-MSU-1-games). + Holds streamable audio for [the MSU-1][msu1]. Files that are only useful to higan specifically are placed in a `higan` subdirectory: - `cheats.bml`: All information present in - [the Cheat Editor](#the-cheat-editor) + [the Cheat Editor](../interface/higan-tools.md#the-cheat-editor) is stored here. - `states/quick/slot-*.bst`: - All the save states made to - [Quick state slots](#quick-states). + All [Quick States](save-states.md#quick-states) are stored here. - `states/managed/slot-*.bst`: - All the save states made with - [the State Manager](#the-state-manager). + All [Manager States](save-states.md#manager-states) are stored here. diff --git a/docs/concepts/manifests.md b/docs/concepts/manifests.md new file mode 100644 index 00000000..30226e83 --- /dev/null +++ b/docs/concepts/manifests.md @@ -0,0 +1,128 @@ +What is a manifest? +------------------- + +If a [game folder](game-folders.md) is +the emulation equivalent of +a physical game cartridge, +a manifest is like +the circuit board inside the cartridge: +it controls how all the other parts of the cartridge +talk to one another and to the console itself. + +If you load a game into higan, +you can look at the game's manifest +by opening [the Tools menu](../interface/higan.md#the-tools-menu) +and choosing [Manifest Viewer](../interface/higan-tools.md#the-manifest-viewer). + +Why manifests? +-------------- + +Any given console might support +hundreds or thousands of different games, +but the vast majority of those games +use one of a few different circuit boards. +For most consoles, +the raw game data provides enough clues +to guess a circuit board configuration +that will get the game running, +but relying on heuristics often leads to problems: + + - Inventing heuristics + that correctly guess the configuration + for a particular game is very difficult. + - If you change the rules, + you really need to re-test + the console's entire game library + to check you haven't broken anything. + - Some games accidentally do the wrong thing. + - The Mega Drive game *Warrior of Rome II* + follows the rule for a European game running at 50fps, + when it's really an American game designed for 60fps. + - Some games deliberately do the wrong thing. + - The Game Boy Advance game *Top Gun - Combat Zones* + follows the rule for + (several kinds of) + save-game storage. + If it detects any save-game storage, + it assumes it's running in an emulator + and disables all the main menu options. + - Heuristics are difficult to reason about. + - If a homebrew developer + takes a game that almost does what they want + and changes it slightly, + it can result in the emulator + doing something completely different + because it now matches + some completely different game. + - Heuristics can make sensible configurations impossible. + - If a homebrew developer wants + a particular hardware configuration + that no official games happened to use, + it may not be possible + to trigger it heuristically. + - It's not hardware accurate. + - The original console did not use heuristics + to guess a hardware configuration, + it just used the actual configuration + of the actual hardware. + +Manifests provide a way to *tell* the emulator +what hardware configuration to use, +avoiding all these problems entirely. + +Where do manifests come from? +----------------------------- + +Ideally, +everybody who extracts the data from a game cartridge would +(at the same time) +record the board configuration in a manifest file. +Unfortunately, +manifests were invented long after cartridge extracting, +so there are a lot of previously extracted games +with no manifest attached. + +If a game doesn't come with a manifest, +it may be possible to look up the correct manifest. +The +[SNES Preservation Project](https://preservation.byuu.org/) +intends to re-dump every Super Famicom game +and record its board configuration at the same time. +Given a game's data, +you can take the SHA256 fingerprint +and look it up in the Project's database +to find the correct manifest to use. + +Unfortunately, +this doesn't help for any other console. +Even for the Super Famicom, +there will always be games +too rare to acquire for re-dumping, +and homebrew that was never on a cartridge to begin with. +For these games, +heuristics will always be needed as a fallback, +but at least if the heuristics are wrong +the can be overridden. + +Manifests can be found inside +[game folders](game-folders.md), +but usually aren't. +Occasionally, +a newly-dumped game will turn out to have +a configuration that can't be expressed +in the existing manifest file format, +and a new format must be designed. +If manifests were always written inside game folders, +games with old-format manifests +would break when played in emulators that supported the new format. + +Therefore, +icarus [defaults](#the-icarus-settings-dialog) +to not writing out manifests when it imports games, +and higan [defaults](#the-configuration-dialog) +to ignoring manifests that are present. +Instead, +when higan loads a game, +it will ask icarus to generate a temporary manifest in the latest format, +based on the files present in the game folder +and how they are likely to go together. diff --git a/mkdocs.yml b/mkdocs.yml index b857de2d..f44de09a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,7 +25,8 @@ pages: - Using video shaders: guides/shaders.md - Choosing drivers: guides/drivers.md - Concepts: - - Manifests and Game Folders: concepts/game-folders.md + - Game Folders: concepts/game-folders.md + - Game Manifests: concepts/manifests.md - The Game Library: concepts/game-library.md - Save States: concepts/save-states.md - Frequently Asked Questions: faq.md