diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index e688c3c0f..be55f76a1 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -14,17 +14,20 @@ on: - published jobs: - markdown-lint: + lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - run: docker run -v $PWD:/workdir ghcr.io/igorshubovych/markdownlint-cli:latest --disable MD013 MD033 MD046 -- "**/*.md" - mkdocs-build: + build: if: github.event_name == 'pull_request' runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 + with: + # the `git-revision-date-localized` plugin needs full history to find page creation date + fetch-depth: 0 - uses: actions/setup-python@v4 with: python-version: 3.x @@ -43,8 +46,8 @@ jobs: pages-status-check: if: github.event_name == 'pull_request' needs: - - markdown-lint - - mkdocs-build + - lint + - build runs-on: ubuntu-latest steps: - uses: re-actors/alls-green@release/v1 diff --git a/.markdownlintignore b/.markdownlintignore new file mode 100644 index 000000000..17f96f2ae --- /dev/null +++ b/.markdownlintignore @@ -0,0 +1 @@ +docs/license.md diff --git a/docs/alternatives.md b/docs/alternatives.md index 078b79f8d..be0064843 100644 --- a/docs/alternatives.md +++ b/docs/alternatives.md @@ -2,30 +2,42 @@ There are a few different popular ROM managers that have similar features: -| Feature | [igir](index.md) | [clrmamepro](https://mamedev.emulab.it/clrmamepro/) | [RomVault](https://www.romvault.com/) | [Romcenter](http://www.romcenter.com/) | [Romulus](https://romulus.cc/) | -|-----------------------------------------|---------------------------------------------------------------|---------------------------------------------------------------|-------------------------------------------------------------|--------------------------------------------|--------------------------------| -| Code: still in development | ✅ | ✅ | ✅ | ❓ | ❓ | -| Code: open source | ✅ GPL | ❌ | ❌ | ❌ | ❓ | -| App: OS compatibility | ✅ anything [Node.js supports](https://nodejs.org/en/download) | ⚠️ Windows, macOS & Linux via [Wine](https://www.winehq.org/) | ⚠️ Windows, Linux via [Mono](https://www.mono-project.com/) | ❌ Windows only | ❓ | -| App: UI or CLI | CLI only by design | UI only | Separate UI & CLI versions | UI only | ❓ | -| App: required setup steps | ✅ no setup required | ❌ requires "profile" setup per DAT | ⚠️ if specifying DAT & ROM dirs | ❌ requires per-DAT DB setup | ❓ | -| DATs: supported formats | ✅ Logiqx XML, CMPro, HTGD SMDB | ✅ Logiqx XML, CMPro | ✅ Logiqx XML, CMPro | ✅ Logiqx XML, CMPro | ❓ | -| DATs: built-in download manager | ❌ | ❌ | ⚠️ via [DatVault](https://www.datvault.com/) | ❌ | ❓ | -| DATs: supports DAT URLs | ✅ | ❌ | ❌ | ❌ | ❓ | -| DATs: process multiple at once | ✅ | ⚠️ via the batcher | ✅ | ❌ | ❓ | -| DATs: create from files | ❌ | ✅ | ✅ | ❌ | ❓ | -| DATs: combine multiple | ❌ | ❌ | ✅ | ❌ | ❓ | -| Archives: extraction formats | ✅ many formats ([archive docs](archives.md)) | ✅ `.zip`, `.7z`, `.rar` | ⚠️ `.zip`, `.7z` | ⚠️ `.zip`, `.7z` | ❓ | -| Archives: creation formats | ❌ `.zip` only by design | ✅ `.zip`, `.7z`, `.rar` | ⚠️ `.zip`, `.7z` | ⚠️ `.zip`, `.7z` | ❓ | -| ROMs: CHD scanning | ❌ | ⚠️ via chdman | ⚠️ v1-5 natively, chdman for v5 | ⚠️ v1-4 natively | ❓ | -| ROMs: scan/checksum caching | ❌ by design | ❌ | ✅ | ✅ | ❓ | -| ROMs: header parsing | ✅ | ✅ | ✅ | ✅ via plugins | ❓ | -| ROMs: header removal | ✅ | ❌ | ❌ | ❌ | ❓ | -| ROMs: patching support | ✅ [patching docs](rom-patching.md) | ❌ | ⚠️ SNES SuperDAT | ❌ | ❓ | -| Filtering: region, language, type, etc. | ✅ many options | ❌ only 1G1R options | ❌ | ⚠️ only at DB setup | ❓ | -| Filtering: 1G1R support | ✅ many options | ⚠️ region & language only | ❌ | ⚠️ only at DB setup | ❓ | -| Reports: report-only mode | ✅ | ✅ | ✅ | ✅ | ❓ | -| Reports: easily parseable | ✅ CSV | ⚠️ newline-separated "have" & "miss" lists | ⚠️ newline-separated "full" & "fix" reports | ⚠️ newline-separated "have" & "miss" lists | ❓ | -| Output: separate input & output dirs | ✅ | ❌ | ⚠️ yes but files are always moved | ❌ | ❓ | -| Output: subdirectory customization | ✅ | ❌ | ✅ | ❌ | ❓ | -| Output: fixdat creation | ✅ [dats docs](dats.md) | ✅ | ✅ | ❌ | ❓ | +| Feature | [igir](index.md) | [clrmamepro](https://mamedev.emulab.it/clrmamepro/) | [RomVault](https://www.romvault.com/) | [Romcenter](http://www.romcenter.com/) | +|-----------------------------------------|---------------------------------------------------------------|---------------------------------------------------------------|-------------------------------------------------------------|--------------------------------------------| +| Code: still in development | ✅ | ✅ | ✅ | ❓ | +| Code: open source | ✅ GPL | ❌ | ❌ | ❌ | +| App: OS compatibility | ✅ anything [Node.js supports](https://nodejs.org/en/download) | ⚠️ Windows, macOS & Linux via [Wine](https://www.winehq.org/) | ⚠️ Windows, Linux via [Mono](https://www.mono-project.com/) | ❌ Windows only | +| App: UI or CLI | CLI only by design | UI only | Separate UI & CLI versions | UI only | +| App: required setup steps | ✅ no setup required | ❌ requires "profile" setup per DAT | ⚠️ if specifying DAT & ROM dirs | ❌ requires per-DAT DB setup | +| DATs: supported formats | ✅ Logiqx XML, CMPro, HTGD SMDB ([DATs docs](input/dats.md)) | ⚠️ Logiqx XML, CMPro | ✅ Logiqx XML, CMPro, HTGD SMDB | ✅ Logiqx XML, CMPro | +| DATs: process multiple at once | ✅ | ⚠️ via the batcher | ✅ | ❌ | +| DATs: built-in download manager | ❌ | ❌ | ⚠️ via [DatVault](https://www.datvault.com/) | ❌ | +| DATs: supports DAT URLs | ✅ | ❌ | ❌ | ❌ | +| DATs: create from files (dir2dat) | ❌ | ✅ | ✅ | ❌ | +| DATs: combine multiple | ❌ | ❌ | ✅ | ❌ | +| Archives: extraction formats | ✅ many formats ([archive docs](input/archives.md)) | ✅ `.zip`, `.7z`, `.rar` | ⚠️ `.zip`, `.7z` | ⚠️ `.zip`, `.7z` | +| Archives: creation formats | ❌ `.zip` only by design | ✅ `.zip`, `.7z`, `.rar` | ⚠️ `.zip`, `.7z` | ⚠️ `.zip`, `.7z` | +| ROMs: CHD scanning | ❌ | ⚠️ via chdman | ✅ v1-5 natively | ⚠️ v1-4 natively | +| ROMs: scan/checksum caching | ❌ by design | ❌ | ✅ | ✅ | +| ROMs: header parsing | ✅ | ✅ | ✅ | ✅ via plugins | +| ROMs: header removal | ✅ | ❌ | ❌ | ❌ | +| ROMs: patching support | ✅ [patching docs](rom-patching.md) | ❌ | ⚠️ SNES SuperDAT | ❌ | +| Filtering: region, language, type, etc. | ✅ many options | ❌ only 1G1R options | ❌ | ⚠️ only at DB setup | +| Filtering: 1G1R support | ✅ many options | ⚠️ region & language only | ❌ | ⚠️ only at DB setup | +| Reports: report-only mode | ✅ | ✅ | ✅ | ✅ | +| Reports: easily parseable | ✅ CSV | ⚠️ newline-separated "have" & "miss" lists | ⚠️ newline-separated "full" & "fix" reports | ⚠️ newline-separated "have" & "miss" lists | +| Output: separate input & output dirs | ✅ | ❌ | ⚠️ yes but files are always moved | ❌ | +| Output: subdirectory customization | ✅ | ❌ | ⚠️ depends on DAT organization | ❌ | +| Output: create single archive for DAT | ✅ | ❌ | ✅ | ❌ | +| Output: fixdat creation | ✅ [DATs docs](input/dats.md) | ✅ | ✅ | ❌ | + +!!! note + + Just like `igir`, other ROM managers that are in active development are likely to release new features often. The above table is not guaranteed to be perfectly up-to-date, it is just a best effort. + +Other alternative ROM managers can be found in a number of other wikis, such as: + +- [Emulation General Wiki](https://emulation.gametechwiki.com/index.php/ROM_managers) +- [Pleasuredome's "Retro Arcade Guides"](https://pleasuredome.miraheze.org/wiki/ROM_Manager) +- [Recalbox](https://wiki.recalbox.com/en/tutorials/utilities/rom-management) +- [RetroPie](https://retropie.org.uk/docs/Validating%2C-Rebuilding%2C-and-Filtering-ROM-Collections/) diff --git a/docs/commands.md b/docs/commands.md index 32430e2e9..342a2286f 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -18,9 +18,9 @@ Files in the input directories will be left alone, they will _not_ be modified o ### `move` -Move ROMs from an input directory to the output directory. The same directory can be specified for both input & output, resulting in ROMs being renamed as their names change in [DATs](dats.md). +Move ROMs from an input directory to the output directory. The same directory can be specified for both input & output, resulting in ROMs being renamed as their names change in [DATs](input/dats.md). -ROMs will be deleted from their input directory after _all_ ROMs for _every_ [DAT](dats.md) have been written. +ROMs will be deleted from their input directory after _all_ ROMs for _every_ [DAT](input/dats.md) have been written. ### `symlink` @@ -36,7 +36,7 @@ If no archive command is specified, files will be left as-is. If they are alread !!! note - See the [archives page](archives.md) for more information on supported archive types. + See the [archives page](input/archives.md) for more information on supported archive types. ### `extract` @@ -63,12 +63,12 @@ After performing one of the ROM writing commands, verify that the file was writt ### `clean` -Files in the output directory that do not match any ROM in any [DAT](dats.md) will be deleted. +Files in the output directory that do not match any ROM in any [DAT](input/dats.md) will be deleted. ## ROM reporting ### `report` -A report will be generated of what input files were matched by what DAT, and what games in what [DATs](dats.md) have missing ROMs. +A report will be generated of what input files were matched by what DAT, and what games in what [DATs](input/dats.md) have missing ROMs. See the [reporting page](output/reporting.md) for more information. diff --git a/docs/archives.md b/docs/input/archives.md similarity index 91% rename from docs/archives.md rename to docs/input/archives.md index 40985b7d7..9017fe1ca 100644 --- a/docs/archives.md +++ b/docs/input/archives.md @@ -6,7 +6,7 @@ `igir` only supports creating `.zip` archives, which is why the command is `igir zip`. -`.zip` archives store CRC32 information in the file table (see below) which helps drastically speed up file scanning, and they are easy to create without proprietary tools (e.g. Rar). +`.zip` archives store CRC32 information in their "file table" (see below) which helps drastically speed up `igir`'s file scanning, and they are easy to create without proprietary tools (e.g. Rar). ## Supported archive types for reading diff --git a/docs/dats.md b/docs/input/dats.md similarity index 99% rename from docs/dats.md rename to docs/input/dats.md index 1421a0dbd..4b7e26a7d 100644 --- a/docs/dats.md +++ b/docs/input/dats.md @@ -79,12 +79,6 @@ Being able to know that many releases are actually the same game gives `igir` th If you have the option to download "parent/clone" or "P/C" versions of DATs, you should always choose those. -## Aren't DATs primarily for MAME? - -That's where DATs started. The [Logiqx XML](http://www.logiqx.com/DatFAQs/) DAT format can include information in [clrmamepro](https://mamedev.emulab.it/clrmamepro/) or [Romcenter](http://www.romcenter.com/) formats on how to handle MAME-specific settings such as [merging](https://docs.mamedev.org/usingmame/aboutromsets.html#parents-clones-splitting-and-merging) (non-merged vs. merged vs. split) and packing (zip vs. not). `igir` doesn't use any of this information, but it helps paint a picture of why DATs are structured the way they are. - -These days, depending on what type of emulation you're interested in, non-MAME DATs such as No-Intro's may be more common than MAME DATs. See the [DAT groups](#dat-groups) section above for some of the popular DAT release groups. - ## Fixdats "Fixdats" are DATs that contain only ROMs that are missing from your collection. Fixdats are derived from some other DAT (see above for obtaining DATs), containing only a subset of the ROMs. Fixdats are specific to the state of each person's ROM collection, so they aren't necessarily meaningful to other people. @@ -113,3 +107,11 @@ ROMs-Sorted/ ├── Nintendo - Game Boy Advance (20230414-173400) fixdat.dat └── Nintendo - Game Boy Color (20230414-173400) fixdat.dat ``` + +## FAQ + +### Aren't DATs primarily for MAME? + +That's where DATs started. The [Logiqx XML](http://www.logiqx.com/DatFAQs/) DAT format can include information in [clrmamepro](https://mamedev.emulab.it/clrmamepro/) or [Romcenter](http://www.romcenter.com/) formats on how to handle MAME-specific settings such as [merging](https://docs.mamedev.org/usingmame/aboutromsets.html#parents-clones-splitting-and-merging) (non-merged vs. merged vs. split) and packing (zip vs. not). `igir` doesn't use any of this information, but it helps paint a picture of why DATs are structured the way they are. + +These days, depending on what type of emulation you're interested in, non-MAME DATs such as No-Intro's may be more common than MAME DATs. See the [DAT groups](#dat-groups) section above for some of the popular DAT release groups. diff --git a/docs/file-scanning.md b/docs/input/file-scanning.md similarity index 97% rename from docs/file-scanning.md rename to docs/input/file-scanning.md index 1e7c093de..8c3e97a61 100644 --- a/docs/file-scanning.md +++ b/docs/input/file-scanning.md @@ -4,7 +4,7 @@ - ROMs: `--input` (required), `--input-exclude` - [DATs](dats.md): `--dat`, `--dat-exclude` -- [ROM patches](rom-patching.md): `--patch`, `--patch-exclude` +- [ROM patches](../rom-patching.md): `--patch`, `--patch-exclude` ## Archive files diff --git a/docs/installation.md b/docs/installation.md index 28d6fe298..ef4abeb35 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,6 +1,8 @@ # Installation -A few different installation options are offered for `igir`. +`igir` is supported on :simple-windowsxp: Windows, :simple-apple: macOS, :simple-linux: Linux, and every other operating system that [Node.js](https://nodejs.org) supports. + +There are a few different installation options offered for `igir` with varying levels of technical complexity. Every option will require some baseline understanding of command-line interfaces (CLIs). ## Via Node.js @@ -49,6 +51,6 @@ docker run --interactive --tty \ !!! warning - Make sure to quote all of your [file globs](file-scanning.md)! + Make sure to quote all of your [file globs](input/file-scanning.md)! [![asciicast](https://asciinema.org/a/5OAVbSXXoosTr0WyBvjQGBqRp.svg)](https://asciinema.org/a/5OAVbSXXoosTr0WyBvjQGBqRp) diff --git a/docs/internals.md b/docs/internals.md index abc291d9d..239924dd3 100644 --- a/docs/internals.md +++ b/docs/internals.md @@ -6,15 +6,18 @@ Information about the inner workings of `igir`. `igir` runs these steps in the following order: -1. Scans each DAT input path for every file and parses them, if provided (`--dat`) -2. Scans each ROM input path for every file (`--input`) - - Then detects headers in those files, if applicable (see [header docs](rom-headers.md)) -3. Scans each patch input path for every file (`--patch`) (see [patching docs](rom-patching.md)) -4. ROMs are matched to the DATs, if provided - - Then ROMs are matched to any applicable patches, creating multiple versions from the same ROM - - Then filtering and sorting options are applied (see [filtering docs](rom-filtering.md)) - - Then ROMs are written to the output directory, if specified (`copy`, `move`) - - Then written ROMs are tested for accuracy, if specified (`test`) - - Then input ROMs are deleted, if specified (`move`) -5. Unknown files are recycled from the output directory, if specified (`clean`) -6. An output report is written to the output directory, if specified (`report`) +1. Scan each DAT input path for every file and parse them, if provided (`--dat`) +2. Scan each ROM input path for every file (`--input`) + - Detect headers in those files, if applicable (see [header docs](rom-headers.md)) +3. Scan each patch input path for every file (`--patch`) (see [patching docs](rom-patching.md)) +4. Then for each DAT: + - ROMs in the DAT are filtered to only those desired (see [filtering & preference docs](rom-filtering.md)) + - Input files are matched to ROMs in the DAT + - Patch files are matched to ROMs in the DAT + - ROM preferences are applied (`--single`, see [filtering & preference docs](rom-filtering.md)) + - ROMs are written to the output directory, if specified (`copy`, `move`, `symlink`) + - Written ROMs are tested for accuracy, if specified (`test`) + - A "fixdat" is created, if specified (`--fixdat`) +5. "Moved" input ROMs are deleted (`move`) +6. Unknown files are recycled from the output directory, if specified (`clean`) +7. An output report is written to the output directory, if specified (`report`) diff --git a/docs/license.md b/docs/license.md new file mode 120000 index 000000000..ea5b60640 --- /dev/null +++ b/docs/license.md @@ -0,0 +1 @@ +../LICENSE \ No newline at end of file diff --git a/docs/output/reporting.md b/docs/output/reporting.md index cb369aea4..0383f1e91 100644 --- a/docs/output/reporting.md +++ b/docs/output/reporting.md @@ -9,30 +9,32 @@ When using DATs (the `--dat` option), the `igir report` command can report on: - What input files didn't match to any ROM - What output files were cleaned (`igir clean` command) -At least one DAT is required for the `igir report` command to work, otherwise `igir` has no way to understand what input files are known ROMs and which aren't. See the [DAT docs](../dats.md) for more information about DATs. +At least one DAT is required for the `igir report` command to work, otherwise `igir` has no way to understand what input files are known ROMs and which aren't. See the [DAT docs](../input/dats.md) for more information about DATs. -The `igir report` can be specified on its own without any [writing command](../commands.md) in order to report on an existing collection, e.g.: +The `igir report` command can be specified on its own without any [writing command](../commands.md) (i.e. `igir copy`, `igir move`, etc.) in order to report on an existing collection. This causes `igir` to operate in a _read-only_ mode, no files will be copied, moved, or deleted. For example: ```shell $ igir report --dat *.dat --input ROMs/ -$ ls ROMs/*.csv -ROMs/igir_2023-03-29T18;26;00-04;00.csv +$ ls *.csv +igir_2023-03-29T18;26;00-04;00.csv ``` +See the `igir --help` message for the report's default location. + ## Format & filtering -The output report format is a standard CSV which can be opened in Microsoft Excel, Apple Numbers, Google Sheets, LibreOffice Calc, and similar spreadsheet applications. +The output report format is a standard CSV that can be opened in Microsoft Excel, Apple Numbers, Google Sheets, LibreOffice Calc, and other similar spreadsheet applications. -Unlike the report formats of other tools, CSVs allow you to filter rows by column values. For example, you can filter the "Status" column to only "MISSING" to understand what ROMs are missing from your collection, or to "UNMATCHED" to understand what input files aren't recognized as a known ROM. The ability to filter CSVs in spreadsheet applications means that `igir` should not need use-case-specific options to achieve your goal. +Unlike the report formats of [other ROM managers](../alternatives.md), CSVs allow you to filter rows by column values. For example, you can filter the "Status" column to only "MISSING" to understand what ROMs are missing from your collection, or to "UNMATCHED" to understand what input files aren't recognized as a known ROM. The ability to filter CSVs in spreadsheet applications means that `igir` should not need use-case-specific report options to achieve your goal. To perform this filtering, most spreadsheet applications have a button or menu item to "create a filter" or "auto filter." ## Output location -The `--report-output` options is provided to configure where the `igir report` report is written. See the `igir --help` message for the report's default location. +The `--report-output` options is provided to configure where the `igir report` CSV is written. See the `igir --help` message for the report's default location. -The report output filename supports a version of [Moment.js symbols](https://momentjs.com/docs/#/displaying/) for date and time. To make it clearer what is a replaceable symbol, `%` is prepended to symbols. This is _non-standard_ for Moment.js - but the `%` format should feel more familiar to more people as it resembles [Python's `date.strftime()`](https://docs.python.org/3/library/datetime.html#datetime.date.strftime), [PHP's `strftime()`](https://www.php.net/manual/en/function.strftime.php), [C++'s `strftime()`](https://cplusplus.com/reference/ctime/strftime/), and more. +The report output filename supports a version of [Moment.js symbols](https://momentjs.com/docs/#/displaying/) for date and time. To make it clearer what is a replaceable symbol, `%` is prepended to symbols. This is _non-standard_ for Moment.js, but the `%` format should feel more familiar to more people as it resembles [Python's `date.strftime()`](https://docs.python.org/3/library/datetime.html#datetime.date.strftime), [PHP's `strftime()`](https://www.php.net/manual/en/function.strftime.php), [C++'s `strftime()`](https://cplusplus.com/reference/ctime/strftime/), and more. !!! info diff --git a/docs/output/tokens.md b/docs/output/tokens.md index ed93d6253..51c013259 100644 --- a/docs/output/tokens.md +++ b/docs/output/tokens.md @@ -4,13 +4,13 @@ When specifying a ROM [writing command](../commands.md) you have to specify an ` For example, if you want to group all ROMs based on their region, you would specify: -=== "Windows" +=== ":simple-windowsxp: Windows" ```batch igir.exe copy extract --dat *.dat --input ROMs/ --output "ROMs-Sorted/{datReleaseRegion}/" ``` -=== "macOS" +=== ":simple-apple: macOS" ```shell igir copy extract --dat *.dat --input ROMs/ --output "ROMs-Sorted/{datReleaseRegion}/" @@ -39,13 +39,19 @@ ROMs-Sorted/ ## DAT information -When using [DATs](../dats.md), you can make use of console & game information contained in them: +When using [DATs](../input/dats.md), you can make use of console & game information contained in them: - `{datName}` the matching DAT's name, similar to how the `--dir-dat-name` option works - `{datDescription}` the matching DAT's description, similar to how the `--dir-dat-description` option works - `{datReleaseLanguage}` each of the ROM's language(s) (e.g. `EN`, `ES`, `JA`) - `{datReleaseRegion}` each of the ROM's region(s) (e.g. `USA`, `EUR`, `JPN`, `WORLD`) +## Game information + +You can use some information about each game: + +- `{gameType}` the game's "type," one of: `Aftermarket`, `Alpha`, `Bad`, `Beta`, `BIOS`, `Demo`, `Device`, `Fixed`, `Hacked`, `Homebrew`, `Overdump`, `Pending Dump`, `Pirated`, `Prototype`, `Retail` (most games will be this), `Sample`, `Test`, `Trained`, `Translated`, `Unlicensed` + ## File information You can use some information about the input and output file's name & location: diff --git a/docs/overview.md b/docs/overview.md index 9012bf616..26a41d951 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -19,9 +19,9 @@ ROM managers are applications that serve two main purposes: all additional features help serve these two purposes. -Most ROM managers can automatically read & write many different ROM types including those in [archives](archives.md) and those with [headers](rom-headers.md) so that you don't have to do much pre-work. +Most ROM managers can automatically read & write many different ROM types including those in [archives](input/archives.md) and those with [headers](rom-headers.md) so that you don't have to do much pre-work. -Most ROM managers rely on [DATs](dats.md), files that catalog every known ROM that exists per game system. DATs are published by release groups dedicated to keeping these catalogs accurate and up-to-date. DATs help ROM collectors name their ROMs in a consistent way as well as understand what ROMs may be missing from their collection. +Most ROM managers rely on [DATs](input/dats.md), files that catalog every known ROM that exists per game system. DATs are published by release groups dedicated to keeping these catalogs accurate and up-to-date. DATs help ROM collectors name their ROMs in a consistent way as well as understand what ROMs may be missing from their collection. ## What is `igir`? diff --git a/docs/rom-dumping.md b/docs/rom-dumping.md index 4beee5b5f..e73bd4b1c 100644 --- a/docs/rom-dumping.md +++ b/docs/rom-dumping.md @@ -6,6 +6,8 @@ Emulators are generally _legal_, as long as they don't include copyrighted software such as a console BIOS. Downloading ROM files that you do not own is piracy which is _illegal_ in many countries. +!!! info + [Dumping.Guide](https://dumping.guide/start) and [Emulation General Wiki](https://emulation.gametechwiki.com/index.php/Ripping_games) are some of the best resources for legally creating ROM files from games you own. Here is a condensed version that isn't guaranteed to be up-to-date. diff --git a/docs/rom-filtering.md b/docs/rom-filtering.md index abb13aebc..f488c1f0c 100644 --- a/docs/rom-filtering.md +++ b/docs/rom-filtering.md @@ -1,16 +1,12 @@ -# ROM Filtering +# ROM Filtering & Preference -`igir` offers many options for filtering as well as 1G1R priority (combined with `--single`). +`igir` offers many options for filtering as well as 1G1R preferences/priorities (when combined with the `--single` option). -They are processed in this order: - -1. Any [filters](#filters) (e.g. `--language-filter`, `--region-filter`) -2. Any priorities (e.g. `--prefer-good`, `--prefer-revision-newer`) -3. If `--single` is specified, only the highest priority game from a set of parent/clones (see [docs](dats.md#parentclone-pc)) is returned +ROM filters cut down the list of games desired for a set, and any games filtered out will not appear in [reports](output/reporting.md). ROM preferences decide what duplicates to eliminate (1G1R). ## Filters -`igir` supports the following filters: +Multiple filter options can be specified at once. ### Language filter @@ -18,7 +14,7 @@ They are processed in this order: --language-filter [languages..] ``` -Languages are two-letter codes, and you can specify multiple languages with commas between them. See the `--help` message for the full list of understood languages. +Languages are two-letter codes, and multiple languages can be specified with commas between them. See the `--help` message for the full list of understood languages. If a game does not have language information specified, it will be inferred from the region. @@ -285,7 +281,9 @@ GB-Wordyl (World) (Aftermarket) (Homebrew) --no-unverified, --only-unverified ``` -Filter out, or only include games that do _not_ contain `[!]` in their name, e.g.: +Only include, or filter out games that contain `[!]` in their name. + +For example, `--no-unverified` would filter out the following: ```text Getaway, The (U) @@ -294,6 +292,14 @@ Golf (W) [o1] Grand Theft Auto (E) (M5) [C][t1] ``` +and `--only-unverified` would filter out the following: + +```text +Kirby & The Amazing Mirror (U) [!] +Legend of Zelda, The - A Link To The Past with Four Swords (E) (M5) [!] +Mario & Luigi - Superstar Saga (U) [!] +``` + !!! warning This is a [GoodTools](https://emulation.gametechwiki.com/index.php/GoodTools#Good_codes) naming convention, other groups such as [No-Intro](https://no-intro.org/) never include `[!]` in their names! @@ -318,3 +324,117 @@ as well as games that contain `[c]` or `[x]` and are _not_ verified dumps (above Brian Lara Cricket 96 (E) [a1][x] Micro Machines Military - It's a Blast! (E) [x] ``` + +## Preferences (for 1G1R) + +The `--single` option is required for all `--prefer-*` options, otherwise there would be no effect. + +Multiple `--prefer-*` options can be specified at once, and they will be applied in the following order of importance (most to least). + +### Prefer verified + +```text +--prefer-verified +``` + +Prefer games that contain `[!]` in their name over those that don't. + +!!! warning + + This is a [GoodTools](https://emulation.gametechwiki.com/index.php/GoodTools#Good_codes) naming convention, other groups such as [No-Intro](https://no-intro.org/) never include `[!]` in their names! + +### Prefer good + +```text +--prefer-good +``` + +Prefer games that _don't_ contain `[b]` or `[b#]` in their name over those that do. + +See the [bad dumps](#bad-dumps) section for more information about "good" and "bad" ROMs. + +### Prefer language + +```text +--prefer-language +``` + +Prefer games of certain languages over those in other languages. Multiple languages can be specified, in priority order, with commas between them. See the `--help` message for the full list of understood languages. + +If a game does not have language information specified, it will be inferred from the region. + +For example, to prefer games in English and _then_ Japanese, the command would be: + +```text +--prefer-language En,Ja +``` + +### Prefer region + +```text +--prefer-region +``` + +Prefer games from certain regions over those from other regions. Multiple regions can be specified, in priority order, with commas between them. See the `--help` message for the full list of understood regions. + +For example, to prefer games from: USA (highest priority), "world," and then Europe, the command would be: + +```text +--prefer-region USA,WORLD,EUR +``` + +### Prefer revision + +```text +--prefer-revision-newer, --prefer-revision-older +``` + +Prefer newer or older revisions of a game. + +Revisions can be numeric: + +```text +Frogger (Europe) (En,Fr,De,Es,It,Nl) (GB Compatible) +Frogger (USA) (Rev 1) (GB Compatible) +Frogger (USA) (Rev 2) (GB Compatible) +``` + +or alphabetical: + +```text +MSR - Metropolis Street Racer (Europe) (En,Fr,De,Es) +MSR - Metropolis Street Racer (Europe) (En,Fr,De,Es) (Rev A) +MSR - Metropolis Street Racer (Europe) (En,Fr,De,Es) (Rev B) +``` + +### Prefer retail + +```text +--prefer-retail +``` + +Prefer games that are considered "retail" releases over those that aren't. + +See the [only retail](#only-retail) section for more information on what games are considered "retail." + +### Prefer NTSC, PAL + +```text +--prefer-ntsc, --prefer-pal +``` + +Prefer games that are explicitly labeled as NTSC or PAL, over those that aren't. + +!!! note + + Most DAT groups do not label games with this information, generally games are labeled by region instead. + +### Prefer parent + +```text +--prefer-parent +``` + +Prefer games that DATs consider the "parent" of other game clones, over the clones themselves. + +It is unlikely you will often use this option, it is more likely other preference options will accomplish what you want. diff --git a/docs/rom-headers.md b/docs/rom-headers.md index 6c0a640c5..058c140bf 100644 --- a/docs/rom-headers.md +++ b/docs/rom-headers.md @@ -16,13 +16,17 @@ Some of these headers are used to tell the emulator information about how to emu | Nintendo - Famicom Disk System | fsNES/FDS | `.fds` | | Nintendo - SNES | SMC | `.smc` | -Those file extensions above are the commonly accepted "correct" ones and `igir` will attempt to detect if a header is present in them automatically. If for some reason your files don't have the right extension (e.g. `.rom`) you can force header detection with the `--header` glob option: +Those file extensions above are the commonly accepted "correct" extensions and `igir` will attempt to detect if a header is present in those ROM files automatically. If for some reason your files don't have the right extension (e.g. `.rom`) you can force header detection with the `--header` glob option: ```shell igir [commands..] --dat --input --header "*.rom" ``` -`igir` will use this detected header information to compute both "headered" and "un-headered" checksums of ROMs and use both of those to match against DAT files. Many DAT groups expressly only include the size and checksum information for the un-headered file, even if the header should not be removed. +`igir` will use this detected header information to compute both "headered" and "un-headered" checksums of ROMs and use both of those to match against DAT files. + +!!! warning + + Many DAT groups expressly only include the size and checksum information for the un-headered file, even if the header should not be removed. ## Manual header removal @@ -50,6 +54,6 @@ igir [commands..] --dat --input --remove-headers ## Automatic header removal -Some DAT groups such as No-Intro publish "headered" and "headerless" DATs for the same console, such as NES. `igir` will treat these DATs differently, automatically removing headers (if present) for "headerless" DATs, and leaving the header intact for "headered" DATs (regardless of CLI parameters). +Some DAT groups such as No-Intro publish "headered" and "headerless" DATs for the same console, such as NES. `igir` will treat these DATs differently, it will automatically remove headers (if present) for "headerless" DATs, and leave the header intact for "headered" DATs (ignoring the `--remove-headers` option completely). As explained above, you almost always want the "headered" version. It's only in very specific circumstances that you might need the "headerless" version. diff --git a/docs/rom-patching.md b/docs/rom-patching.md index 6d76722b2..a19954280 100644 --- a/docs/rom-patching.md +++ b/docs/rom-patching.md @@ -6,7 +6,7 @@ Games and their ROMs are protected under copyrights, so patches are used in orde ## Specifying patch files -Patch files can be specified with the `--patch` option. See the [file scanning docs](file-scanning.md) for more information. +Patch files can be specified with the `--patch` option. See the [file scanning docs](input/file-scanning.md) for more information. ## Patch types diff --git a/docs/usage/collection-sorting.md b/docs/usage/collection-sorting.md index 63851d220..ade3ea079 100644 --- a/docs/usage/collection-sorting.md +++ b/docs/usage/collection-sorting.md @@ -8,11 +8,11 @@ A walkthrough of an example way to sort your ROM collection. ## First time collection sort -First, you need to download a set of [DATs](../dats.md). For these examples I'll assume you downloaded a No-Intro daily P/C XML `.zip`. +First, you need to download a set of [DATs](../input/dats.md). For these examples I'll assume you downloaded a No-Intro daily P/C XML `.zip`. Let's say that you have a directory named `ROMs/` that contains ROMs for many different systems, and it needs some organization. To make sure we're alright with the output, we'll have `igir` copy these files rather than move them. We'll also zip them to reduce disk space & speed up future scans. -=== "Windows" +=== ":simple-windowsxp: Windows" ```batch igir.exe copy zip test ^ @@ -22,7 +22,7 @@ Let's say that you have a directory named `ROMs/` that contains ROMs for many di --dir-dat-name ``` -=== "macOS" +=== ":simple-apple: macOS" ```shell igir copy zip test \ @@ -57,7 +57,7 @@ Let's say that we've done the above first time sort and were happy with the resu Now we have new ROMs that we want to merge into our collection, and we want to generate a [report](../output/reporting.md) of what ROMs are still missing. We also want to delete any unknown files that may have made their way into our collection. -=== "Windows" +=== ":simple-windowsxp: Windows" ```batch igir.exe move zip test clean report ^ @@ -68,7 +68,7 @@ Now we have new ROMs that we want to merge into our collection, and we want to g --dir-dat-name ``` -=== "macOS" +=== ":simple-apple: macOS" ```shell igir move zip test clean report \ @@ -106,7 +106,7 @@ Let's say we've done the above sorting we want to copy some ROMs from `ROMs-Sort We would prefer having only one copy of every game (1G1R), so there is less to scroll through to find what we want, and because we have a preferred language. Our flash cart can't read `.zip` files, so we'll need to extract our ROMs during copying. -=== "Windows" +=== ":simple-windowsxp: Windows" Replace the `E:\` drive letter with wherever your SD card is: @@ -122,7 +122,7 @@ We would prefer having only one copy of every game (1G1R), so there is less to s --prefer-region USA,WORLD,EUR,JPN ``` -=== "macOS" +=== ":simple-apple: macOS" Replace the `/Volumes/FlashCart` drive name with whatever your SD card is named: @@ -152,4 +152,4 @@ Your flash cart might then look something like this: !!! info - See the [ROM filtering](../rom-filtering.md) page for other ways that you can filter your collection. + See the [ROM filtering & preference](../rom-filtering.md) page for other ways that you can filter your collection. diff --git a/docs/usage/console/gamecube.md b/docs/usage/console/gamecube.md new file mode 100644 index 000000000..60f6f92e0 --- /dev/null +++ b/docs/usage/console/gamecube.md @@ -0,0 +1,37 @@ +# GameCube + +## Swiss + +[Swiss](https://github.com/emukidid/swiss-gc) is typically used to load game backups on the GameCube. See the [GC-Forever Wiki](https://www.gc-forever.com/wiki/index.php?title=Main_Page) for resources on installing & running Swiss. + +!!! warning + + Swiss is sensitive to files being fragmented on SD cards ([swiss-gc#763](https://github.com/emukidid/swiss-gc/issues/763), [swiss-gc#122](https://github.com/emukidid/swiss-gc/issues/122), etc.). This means that you should only write one ISO at a time! + +`igir` has a `--writer-threads` option to limit the number of files being written at once. You can use the option like this: + +=== ":simple-windowsxp: Windows" + + Replace the `E:\` drive letter with wherever your SD card is: + + ```batch + igir copy extract test clean ^ + --dat "Redump*.zip" ^ + --input "ISOs" ^ + --output "E:\ISOs" ^ + --dir-letter ^ + --writer-threads 1 + ``` + +=== ":simple-apple: macOS" + + Replace the `/Volumes/SD2SP2` drive name with whatever your SD card is named: + + ```shell + igir copy extract test clean \ + --dat "Redump*.zip" \ + --input "ISOs/" \ + --output "/Volumes/SD2SP2/ISOs/" \ + --dir-letter \ + --writer-threads 1 + ``` diff --git a/docs/usage/console/ps2.md b/docs/usage/console/ps2.md new file mode 100644 index 000000000..9ab87f993 --- /dev/null +++ b/docs/usage/console/ps2.md @@ -0,0 +1,37 @@ +# PlayStation 2 + +## Open PS2 Loader (OPL) + +[OPL](https://github.com/ps2homebrew/Open-PS2-Loader) is typically used to load game backups on the PS2. See the [PS2-HOME Forums](https://www.ps2-home.com/forum/viewforum.php?f=50) for resources on installing & running OPL. + +!!! warning + + OPL is sensitive to files being fragmented on USB drives and SD cards (MX4SIO/SIO2SD). This means that you should only write one ISO at a time! + +`igir` has a `--writer-threads` option to limit the number of files being written at once. You can use the option like this: + +=== ":simple-windowsxp: Windows" + + Replace the `E:\` drive letter with wherever your USB drive is: + + ```batch + igir copy extract test clean ^ + --dat "Redump*.zip" ^ + --input "ISOs" ^ + --output "E:\DVD" ^ + --dir-letter ^ + --writer-threads 1 + ``` + +=== ":simple-apple: macOS" + + Replace the `/Volumes/PS2` drive name with whatever your USB drive is named: + + ```shell + igir copy extract test clean \ + --dat "Redump*.zip" \ + --input "ISOs/" \ + --output "/Volumes/PS2/DVD/" \ + --dir-letter \ + --writer-threads 1 + ``` diff --git a/docs/usage/desktop/batocera.md b/docs/usage/desktop/batocera.md index 71da7c2d2..cad779fb7 100644 --- a/docs/usage/desktop/batocera.md +++ b/docs/usage/desktop/batocera.md @@ -1,7 +1,36 @@ # Batocera -[Batocera](https://batocera.org/) is a pre-configured Linux OS image for [EmulationStation](https://emulationstation.org/). +[Batocera](https://batocera.org/) is a pre-configured Linux distribution for [EmulationStation](https://emulationstation.org/) & [RetroArch](https://www.retroarch.com/). Batocera is primarily for single-board computers (SBCs) such as the [Raspberry Pi](https://www.raspberrypi.com/). ## BIOS +Because Batocera uses RetroArch under the hood, the instructions are generally the [same as RetroArch](retroarch.md). By default, the [Batocera BIOS directory](https://wiki.batocera.org/add_games_bios#adding_bios_files) is `/userdata/bios`: + +=== ":simple-linux: Batocera (Linux)" + + You can copy BIOS files from a USB drive named "USB-Drive" like this: + + ```shell + igir copy extract test clean \ + --dat "https://raw.githubusercontent.com/libretro/libretro-database/master/dat/System.dat" \ + --input /media/USB-Drive/BIOS/ \ + --output /userdata/bios/ + ``` + ## ROMs + +Batocera has a `roms` folder in the "userdata partition" at `/userdata/roms` that is used by default: + +=== ":simple-linux: Batocera (Linux)" + + You can copy ROMs from a USB drive named "USB-Drive" like this: + + ```shell + igir copy zip test clean \ + --dat "/media/USB-Drive/No-Intro*.zip" \ + --input "/media/USB-Drive/ROMs/" \ + --output "/userdata/roms/" \ + --dir-dat-name \ + --dir-letter \ + --no-bios + ``` diff --git a/docs/usage/desktop/lakka.md b/docs/usage/desktop/lakka.md index 6b35e832d..d94d86f0b 100644 --- a/docs/usage/desktop/lakka.md +++ b/docs/usage/desktop/lakka.md @@ -1 +1,36 @@ # Lakka + +[Lakka](https://www.lakka.tv/) is a pre-configured Linux distribution based on [LibreELEC](https://libreelec.tv/) that comes with [RetroArch](https://www.retroarch.com/) installed. Lakka is primarily for single-board computers (SBCs) such as the [Raspberry Pi](https://www.raspberrypi.com/). + +## BIOS + +Because Lakka uses RetroArch under the hood, the instructions are generally the [same as RetroArch](retroarch.md). By default, the [Lakka BIOS directory](https://www.lakka.tv/doc/Accessing-Lakka-filesystem/) is `/storage/system`: + +=== ":simple-linux: Lakka (Linux)" + + You can copy ROMs from a USB drive named "USB-Drive" like this: + + ```shell + igir copy extract test clean \ + --dat "https://raw.githubusercontent.com/libretro/libretro-database/master/dat/System.dat" \ + --input /media/USB-Drive/BIOS/ \ + --output /storage/system + ``` + +## ROMs + +Lakka has a `roms` folder at `/storage/roms` that is used by default: + +=== ":simple-linux: Lakka (Linux)" + + You can copy ROMs from a USB drive named "USB-Drive" like this: + + ```shell + igir copy zip test clean \ + --dat "/media/USB-Drive/No-Intro*.zip" \ + --input "/media/USB-Drive/ROMs/" \ + --output "/storage/roms/" \ + --dir-dat-name \ + --dir-letter \ + --no-bios + ``` diff --git a/docs/usage/desktop/recalbox.md b/docs/usage/desktop/recalbox.md index 686e354fd..e3858d48e 100644 --- a/docs/usage/desktop/recalbox.md +++ b/docs/usage/desktop/recalbox.md @@ -1 +1,36 @@ # Recalbox + +[Recalbox](https://www.recalbox.com/) is a pre-configured Linux distribution for [EmulationStation](https://emulationstation.org/) & [RetroArch](https://www.retroarch.com/). + +## BIOS + +Because Recalbox uses RetroArch under the hood, the instructions are generally the [same as RetroArch](retroarch.md). By default, the [Recalbox BIOS directory](https://wiki.recalbox.com/en/basic-usage/file-management#adding-bios) is `/recalbox/share/bios`: + +=== ":simple-linux: Recalbox (Linux)" + + You can copy ROMs from a USB drive named "USB-Drive" like this: + + ```shell + igir copy extract test clean \ + --dat "https://raw.githubusercontent.com/libretro/libretro-database/master/dat/System.dat" \ + --input /media/USB-Drive/BIOS/ \ + --output /recalbox/share/bios + ``` + +## ROMs + +Recalbox has a `roms` folder at `/recalbox/share/roms` that is used by default: + +=== ":simple-linux: Recalbox (Linux)" + + You can copy ROMs from a USB drive named "USB-Drive" like this: + + ```shell + igir copy zip test clean \ + --dat "/media/USB-Drive/No-Intro*.zip" \ + --input "/media/USB-Drive/ROMs/" \ + --output "/recalbox/share/roms/" \ + --dir-dat-name \ + --dir-letter \ + --no-bios + ``` diff --git a/docs/usage/desktop/retroarch.md b/docs/usage/desktop/retroarch.md index 6c71841fc..a25cabf46 100644 --- a/docs/usage/desktop/retroarch.md +++ b/docs/usage/desktop/retroarch.md @@ -10,9 +10,9 @@ First, RetroArch needs a number of [BIOS files](https://docs.libretro.com/library/bios/). Thankfully, the libretro team maintains a DAT of these "system" files, so we don't have to guess at the correct filenames. -With `igir`'s support for [DAT URLs](../../dats.md) we don't even have to download the DAT! Locate your "System/BIOS" directory as configured in the RetroArch UI and use it as your output directory: +With `igir`'s support for [DAT URLs](../../input/dats.md) we don't even have to download the DAT! Locate your "System/BIOS" directory as configured in the RetroArch UI and use it as your output directory: -=== "Windows (64-bit)" +=== ":simple-windowsxp: Windows (64-bit)" The root directory is based on where you installed RetroArch, but by default it is: @@ -23,7 +23,7 @@ With `igir`'s support for [DAT URLs](../../dats.md) we don't even have to downlo --output C:\RetroArch-Win64\system ``` -=== "Windows (32-bit)" +=== ":simple-windowsxp: Windows (32-bit)" The root directory is based on where you installed RetroArch, but by default it is: @@ -34,7 +34,7 @@ With `igir`'s support for [DAT URLs](../../dats.md) we don't even have to downlo --output C:\RetroArch-Win32\system ``` -=== "macOS" +=== ":simple-apple: macOS" ```shell igir copy extract test clean \ @@ -49,7 +49,7 @@ RetroArch is less opinionated about where your ROMs can live, you have to specif If you want to store your ROMs in the RetroArch folder, you could co-locate them near your BIOS files: -=== "Windows (64-bit)" +=== ":simple-windowsxp: Windows (64-bit)" The root directory is based on where you installed RetroArch, but by default it is: @@ -62,7 +62,7 @@ If you want to store your ROMs in the RetroArch folder, you could co-locate them --no-bios ``` -=== "Windows (32-bit)" +=== ":simple-windowsxp: Windows (32-bit)" The root directory is based on where you installed RetroArch, but by default it is: @@ -75,7 +75,7 @@ If you want to store your ROMs in the RetroArch folder, you could co-locate them --no-bios ``` -=== "macOS" +=== ":simple-apple: macOS" ```shell igir copy zip test \ diff --git a/docs/usage/desktop/retropie.md b/docs/usage/desktop/retropie.md index 127764b80..68931820b 100644 --- a/docs/usage/desktop/retropie.md +++ b/docs/usage/desktop/retropie.md @@ -1,12 +1,12 @@ # RetroPie -[RetroPie](https://retropie.org.uk/) is an installer for [EmulationStation](https://emulationstation.org/) & [RetroArch](https://www.retroarch.com/) on single-board computers (SBCs). +[RetroPie](https://retropie.org.uk/) is an installer for [EmulationStation](https://emulationstation.org/) & [RetroArch](https://www.retroarch.com/) on single-board computers (SBCs) such as the [Raspberry Pi](https://www.raspberrypi.com/). ## BIOS Because RetroPie uses RetroArch under the hood, the instructions are generally the [same as RetroArch](retroarch.md). By default, the RetroPie BIOS directory is `/home/pi/RetroPie/BIOS`: -=== "RetroPie (Linux)" +=== ":simple-linux: RetroPie (Linux)" ```shell igir copy extract test clean \ @@ -19,7 +19,7 @@ Because RetroPie uses RetroArch under the hood, the instructions are generally t The [RetroPie docs](https://retropie.org.uk/docs/Transferring-Roms/) recommend creating a `retropie/roms` directory at the root of a USB drive. You can then load up this USB drive with your ROMs from a different computer: -=== "Windows" +=== ":simple-windowsxp: Windows" Replace the `E:\` drive letter with wherever your SD card is: @@ -33,7 +33,7 @@ The [RetroPie docs](https://retropie.org.uk/docs/Transferring-Roms/) recommend c --no-bios ``` -=== "macOS" +=== ":simple-apple: macOS" Replace the `/Volumes/RETROPIE` drive name with whatever your SD card is named: diff --git a/docs/usage/handheld/onionos.md b/docs/usage/handheld/onionos.md index 5ab722996..7a6e60579 100644 --- a/docs/usage/handheld/onionos.md +++ b/docs/usage/handheld/onionos.md @@ -10,7 +10,7 @@ OnionOS has its BIOS folder at the root of the SD card at `/BIOS`, and it uses the [RetroArch filenames](https://github.com/OnionUI/Onion/wiki/Installation#step-3-copy-over-your-bios-and-rom-files): -=== "Windows" +=== ":simple-windowsxp: Windows" Replace the `E:\` drive letter with wherever your SD card is: @@ -21,7 +21,7 @@ OnionOS has its BIOS folder at the root of the SD card at `/BIOS`, and it uses t --output E:\BIOS ``` -=== "macOS" +=== ":simple-apple: macOS" Replace the `/Volumes/OnionOS` drive name with whatever your SD card is named: @@ -36,7 +36,7 @@ OnionOS has its BIOS folder at the root of the SD card at `/BIOS`, and it uses t OnionOS uses its own proprietary [ROM folder structure](https://github.com/OnionUI/Onion/wiki/Emulators#rom-folders---quick-reference), so `igir` has a replaceable `{onion}` token to sort ROMs into the right place. See the [replaceable tokens page](../../output/tokens.md) for more information. -=== "Windows" +=== ":simple-windowsxp: Windows" Replace the `E:\` drive letter with wherever your SD card is: @@ -49,7 +49,7 @@ OnionOS uses its own proprietary [ROM folder structure](https://github.com/Onion --no-bios ``` -=== "macOS" +=== ":simple-apple: macOS" Replace the `/Volumes/OnionOS` drive name with whatever your SD card is named: diff --git a/docs/usage/hardware/analogue-pocket.md b/docs/usage/hardware/analogue-pocket.md index 79329d1c6..e2db972d7 100644 --- a/docs/usage/hardware/analogue-pocket.md +++ b/docs/usage/hardware/analogue-pocket.md @@ -18,7 +18,7 @@ Most Pocket updater utilities will download BIOS files required for each core fo This token can be used to reference each core's specific directory in the SD card's `Assets` directory. ROMs go in the `Assets/{pocket}/common` directory. -=== "Windows" +=== ":simple-windowsxp: Windows" Replace the `E:\` drive letter with wherever your SD card is: @@ -32,7 +32,7 @@ This token can be used to reference each core's specific directory in the SD car --no-bios ``` -=== "macOS" +=== ":simple-apple: macOS" Replace the `/Volumes/POCKET` drive name with whatever your SD card is named: diff --git a/docs/usage/hardware/everdrive.md b/docs/usage/hardware/everdrive.md index 9f5c4fc97..ffa216aa6 100644 --- a/docs/usage/hardware/everdrive.md +++ b/docs/usage/hardware/everdrive.md @@ -2,9 +2,9 @@ ## ROMs -Because flash carts are specific to a specific console, you can provide specific input directories & [DATs](../../dats.md) when you run `igir`. For example: +Because flash carts are specific to a specific console, you can provide specific input directories & [DATs](../../input/dats.md) when you run `igir`. For example: -=== "Windows" +=== ":simple-windowsxp: Windows" Replace the `E:\` drive letter with wherever your SD card is: @@ -16,7 +16,7 @@ Because flash carts are specific to a specific console, you can provide specific --no-bios ``` -=== "macOS" +=== ":simple-apple: macOS" Replace the `/Volumes/EverDrive` drive name with whatever your SD card is named: @@ -30,9 +30,9 @@ Because flash carts are specific to a specific console, you can provide specific you can then add some other output options such as `--dir-letter`, if desired. -Alternatively, `igir` supports [Hardware Target Game Database SMDB files](https://github.com/frederic-mahe/Hardware-Target-Game-Database/tree/master/EverDrive%20Pack%20SMDBs) as [DATs](../../dats.md). Unlike typical DATs, Hardware Target Game Database SMDBs typically have an opinionated directory structure to help sort ROMs by language, category, genre, and more. Example usage: +Alternatively, `igir` supports [Hardware Target Game Database SMDB files](https://github.com/frederic-mahe/Hardware-Target-Game-Database/tree/master/EverDrive%20Pack%20SMDBs) as [DATs](../../input/dats.md). Unlike typical DATs, Hardware Target Game Database SMDBs typically have an opinionated directory structure to help sort ROMs by language, category, genre, and more. Example usage: -=== "Windows" +=== ":simple-windowsxp: Windows" Replace the `E:\` drive letter with wherever your SD card is: @@ -43,7 +43,7 @@ Alternatively, `igir` supports [Hardware Target Game Database SMDB files](https: --output E:\ ``` -=== "macOS" +=== ":simple-apple: macOS" Replace the `/Volumes/EverDrive` drive name with whatever your SD card is named: diff --git a/docs/usage/hardware/mister.md b/docs/usage/hardware/mister.md index 291285d79..30d57cf3a 100644 --- a/docs/usage/hardware/mister.md +++ b/docs/usage/hardware/mister.md @@ -12,7 +12,7 @@ The MiSTer [`update_all.sh`](https://github.com/theypsilon/Update_All_MiSTer) sc This token can be used to reference each core's specific directory in the MiSTer's `games` directory. -=== "Windows" +=== ":simple-windowsxp: Windows" Replace the `E:\` drive letter with wherever your SD card is: @@ -25,7 +25,7 @@ This token can be used to reference each core's specific directory in the MiSTer --no-bios ``` -=== "macOS" +=== ":simple-apple: macOS" Replace the `/Volumes/MISTER` drive name with whatever your SD card is named: diff --git a/docs/usage/personal.md b/docs/usage/personal.md index 52dcd1d26..933c5c036 100644 --- a/docs/usage/personal.md +++ b/docs/usage/personal.md @@ -38,7 +38,7 @@ The file tree in that hard drive looks like this: └── igir_library_sync.sh ``` -The root directory has a DAT zip and subdirectory for each [DAT](../dats.md) release group. This helps separate differing quality of DATs and different DAT group ROM naming schemes. I then have one subdirectory for each game console, using the `--dir-dat-name` option. +The root directory has a DAT zip and subdirectory for each [DAT](../input/dats.md) release group. This helps separate differing quality of DATs and different DAT group ROM naming schemes. I then have one subdirectory for each game console, using the `--dir-dat-name` option. The `igir_library_sync.sh` script helps me keep this collection organized and merge new ROMs into it. The complete source is: @@ -107,6 +107,10 @@ That lets me create an EN+USA preferred 1G1R set for my Pocket on the fly, makin ## GameCube +!!! note + + See the full [GameCube](console/gamecube.md) page for more detailed information. + I have this script `sd2sp2_pocket_sync.sh` at the root of my GameCube [SD2SP2](https://github.com/citrus3000psi/SD2SP2) SD card: ```bash @@ -126,7 +130,3 @@ npx --yes igir@latest copy extract test clean \ ``` It doesn't use DATs because I have the ISOs in a trimmed NKit format (see [Swiss](https://github.com/emukidid/swiss-gc)), so they won't match the checksums in DATs. I also exclude some games due to limited SD card size. - -!!! note - - This uses the `--writer-threads` debug option because Swiss is sensitive to files being fragmented on the SD card ([swiss-gc#763](https://github.com/emukidid/swiss-gc/issues/763), [swiss-gc#122](https://github.com/emukidid/swiss-gc/issues/122), etc.). From experience, if you write too many files to an SD card at once, you may get an ambiguous error message mentioning fragmentation when loading an ISO. diff --git a/mkdocs.yml b/mkdocs.yml index 9129f0364..5d0917342 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -39,7 +39,6 @@ theme: - navigation.tabs.sticky - navigation.indexes - navigation.sections - - navigation.expand - navigation.instant - navigation.footer - toc.follow @@ -58,7 +57,10 @@ nav: - Usage: - usage/collection-sorting.md - Desktop Frontends: + - usage/desktop/batocera.md - usage/desktop/emulationstation.md + - usage/desktop/lakka.md + - usage/desktop/recalbox.md - usage/desktop/retroarch.md - usage/desktop/retropie.md - Handheld Frontends: @@ -67,11 +69,14 @@ nav: - usage/hardware/analogue-pocket.md - usage/hardware/everdrive.md - usage/hardware/mister.md + - Specific Consoles: + - usage/console/gamecube.md + - usage/console/ps2.md - usage/personal.md - File Inputs: - - file-scanning.md - - dats.md - - archives.md + - input/file-scanning.md + - input/dats.md + - input/archives.md - ROM Processing: - rom-filtering.md - rom-headers.md @@ -83,6 +88,8 @@ nav: - internals.md - Misc: - rom-dumping.md + - Terms and Conditions: + - license.md # https://github.com/squidfunk/mkdocs-material/issues/889#issuecomment-582297142: how-to open nav links in new tabs - Download ↗: https://github.com/emmercm/igir/releases/latest" target="_blank - Issues ↗: https://github.com/emmercm/igir/issues?q=is%3Aopen+is%3Aissue+label%3Abug" target="_blank @@ -95,7 +102,10 @@ plugins: enable_creation_date: true - redirects: redirect_maps: + 'archives.md': 'input/archives.md' + 'dats.md': 'input/dats.md' 'examples.md': 'usage/collection-sorting.md' + 'file-scanning.md': 'input/file-scanning.md' 'reporting.md': 'output/reporting.md' #- htmlproofer: # raise_error_excludes: @@ -121,6 +131,11 @@ markdown_extensions: alternate_style: true # https://github.com/mkdocs/mkdocs/issues/545: allow two-space indented lists - mdx_truly_sane_lists + # https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/ + - attr_list + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg extra: analytics: