Onerom

Script to achieve the perfect 1g1r library.

🚧 Under heavy development 🚧

Why

There are plenty of 1g1r applications out there, why one more?

Onerom started years ago as a simple tool I used to filter my massive rom collection, down to a playable set with retroachievements enabled. Years later I learned about Igir and started using it, but it lacked what was my main interest: retroachievements. I also needed to prioritise some rom features over others, which Igir couldn't do, or I couldn't find how.

I decided to improve my tool, rename it and ultimately, why not, share it with the community.

Features

• Prioritize rom characteristics
• Retroachievements-aware
• Leverage DAT files
• Compression format changes (WIP)
• Config file instead of cli parameters

How does it work

Onerom is yet another 1g1r (One Game One Rom) application, aiming to extract the best roms among the huge romsets that populate Internet. But the concept of best differs from one person to another, so you can use this tool to define your perfect roms and copy them from your hoarding directories to your retrogaming library.

Inspired by other 1g1r programs like Igir or Retool, Onerom grabs the best from them and adds its own features, being the main ones:

• Assign different priority to each characteristic
• Retroachievements is one of those characteristics
• Unopinionated. You decide what is important and what not

Installation

Prerequisites:

• NodeJS 24 or higher.

To install Onerom you can do as follows:

npm install -g onerom

Or just don't install it and run it with npx:

npx onerom <command>

Usage

It you didn't install it globally, you can run Onerom:

npx onerom <command> (--parameters)*

If you installed it globally, you can use it as any other command in your PATH:

onerom <command>

Naming convention

At the moment, the roms need to follow a No-Intro naming convention. The TOSEC naming convention is on the works.

How does it work

Onerom will run through all your available roms first gathering as much information as it can from the file names and from the DAT file if it exists. It will group the roms by clones. A group of clones is a set of roms of the same game, but with different characteristics: different region, language, revision, retroachievements-enabled, and so on. In the config file, you'll have to specify which of these characteristics are the most important to you.

Then, it will, for each clone group, get the one rom that best fulfill your needs. It could even not pick any if all of them contain unwanted characteristics.

Configure

Onerom uses a JSON config file to define your preferences.

Example:

{
  "preferences": [
    {
      "type": "hasCheevos",
      "order": [
        true,
        false
      ]
    },
    {
      "type": "regions",
      "order": [
        "France",
        "Europe",
        "World",
        "USA",
        "Japan"
      ]
    },
    {
      "type": "pirate",
      "order": [
        false
      ]
    },
    {
      "type": "badDump",
      "order": [
        false
      ]
    }
  ],
  "retroachievements": {
    "username": "ra_username",
    "webApiKey": "123456abcdef"
  }
}

The heart of the config is the preferences array. It's an array because the order matters. Here you specify what characteristic of the roms are important to you and in which order. Onerom will run through this array and, for each item, it will see which roms fulfill the requirements.

In the above example, it will first check if there's any rom in a group of clones that has cheevos (retroachievements). If there's any, it will discard all the roms without cheevos. Then it will move to the next item in the array. If none of the roms has retroachievements, then it will keep all of them (as we specified false as an acceptable value).

Then it will move on to the next item which is of the type regions.

It will again go through the roms that were not discarded and check again. Is there a rom with the France region? If yes, discard the rest and move on to the pirate item. Otherwise, is there any with the Europe region? If yes, discard the rest and move on. Otherwise, go on with all the regions until at least one rom has a desired region.

Then it will move on to the pirate item.

The pirate item only has one acceptable value. It means that we only want non-pirate roms.

The same happens with the badDump preference: We don't want bad dumps.

All these definitions of acceptable values could lead to a situation where no rom in a clone group is acceptable.

Config spec

{
  "preferences": [
    {
      "type": "<preference type>",
      "order": [<list of acceptable values in order of priority>]
    },
  ],
  "retroachievements": {
    "username": "<ra username>",
    "webApiKey": "<ra webapikey>"
  }
}

Available types:

• regions: A list of acceptable regions. The name is not abbreviated, just like the No-Intro naming convention requires them
• languages: A list of acceptable languages. The name follows the ISO 639-1 standard, again just like the No-Intro naming convention.
• hasCheevos: A list of true/false, each value representing respectively that the rom has cheevos or it doesn't.
• verified: A list of true/false, verified or not verified.
• pirate: A list of true/false, pirate or not pirate.
• hack: A list of true/false, hack or not hack.
• demo: A list of true/false, demo or not demo.
• beta: A list of true/false, beta version or not beta version.
• badDump: A list of true/false, bad dump or good dump.
• pirate: A list of true/false, pirate or not pirate.
• aftermarket: A list of true/false, aftermarket or not aftermarket.

For now, there's no way to get the latest revision. WIP.

Commands

help

Without a command, it shows general help about Onerom. If you specify a command, it'll print the description and options of the command.

Usage

onerom help [command]

Parameters

• command (Optional): The command to get help of.

copy

Copy the best roms from one directory to another following the preferences in the config file.

Usage

onerom copy \
  --roms <rom_dir> \
  --dest <dest_dir> \
  --config <config_file> \
  [--dat <dat_file>] \
  [--dry-run]`

Parameters

• --roms <rom_dir>: The directory where all your unfiltered roms live.
• --dest <dest_dir>: The directory to which you want to copy your filtered roms.
• --config <config_file>: The JSON file that contains your preferences.
• --dat <dat_file> (Optional): A DAT file that contains extra information about the roms. This file is highly recommended, as its the best way to group rom clones. Without it, the only way to tell which rom is a clone is by the name, which is highly inaccurate.
• --dry-run (Optional): A dry run means that no real changes will be made in the file system. All the copying will be simulated, but you'll get the same output as if you did a real run. Useful to debug your config.

dat

Creates a DAT file with all the information that can be gathered from the available sources. If you specify a source DAT file, the new one will contain the same information plus all the added data.

Usage

onerom dat \
  --roms <rom_dir> \
  --dest <dest_dir> \
  --config <config_file> \
  [--dat <dat_file>] \
  [--retroachievements --system <system>] \
  [--ra-username <username> --ra-webapikey <key>] \
  [--dry-run]`

Parameters

• --roms <rom_dir>: The directory where all your unfiltered roms live.
• --dest <new_dat_file>: The new dat file you want to create.
• --config <config_file>: The JSON file that contains your preferences. The config file can contain the Retroachievements configuration: username and web api key, so that you don't need to type them on every command.
• --dat <dat_file> (Optional): A DAT file that contains extra information about the roms. This file is highly recommended, as its the best way to group rom clones. Without it, the only way to tell which rom is a clone is by the name, which is highly inaccurate.
• --retroachievements (Optional): Include Retroachievements information in the new DAT. If you specify this command, the execution will be slower as Onerom needs to obtain each rom's hash and check whether they have cheevos or not. You'll need to specify also your Retroachievements credentials, either on the config file or with the parameters --ra-username and --ra-webapikey. You'll also need to pass the --system parameters.
• --system: Mandatory if you passed the --retroachievements parameter. The code of the platform of the romset. The code can be either the Retroachievements id or Batocera's short name.
• --ra-username: Your Retroachievements username. If you pass the --retroachievements parameter, you'll need either this parameter or the corresponding key in the config file.
• --ra-webapikey: Your Retroachievements Web API Key (get it here). If you pass the --retroachievements parameter, you'll need either this parameter or the corresponding key in the config file.
• --dry-run (Optional): A dry run means that no file will be created. The creation will be simulated, but you'll get the same output as if you did a real run.