Devices and templates system

[XargonWan]

From the old RetroMan project, I wish to introduce the concept of device/template association to give more flexibility to the library and the third party devices.

The idea is that the library is a device: there can be more than one library as there are many device, a library example can be found here: #294.
So the "device" is a term to call a library OR a physical device such as the Miyoo Mini as they have the same logic underneath.

Read the device file, find its template by checking if the file templates/<id>.yaml is present and virtually merge them in a dictionary.

Example, RomM is calling the device named My Miyoo Mini so it looks for a folder named My Miyoo Mini in the devices folder.
The folder is found so the file "My Miyoo Mini.yml" is searched.

The file is found, it contains:
"My Miyoo Mini.yml"

id: miyoominiv3-onion
friendly_name: Miyoo Mini (OnionOS)
device_root: /home/public-folder/gits/RetroMan/test/My MIyoo Mini
force_decompression: true

This device is calling for the id miyoominiv3-onion, so RetroMan searches for a miyoominiv3-onion.yml, and finds:

# Miyoo Mini v3 - OnionOS
miyoominiv3-onion:
  name: Miyoo Mini
  template_version: 0.1
  brand: Ingenic
  gamelist_file: miyoogamelist.xml
  saves: Saves/CurrentProfile/saves
  states: Saves/CurrentProfile/states
  roms_path: ROMs
  systems:
    - gb:
        - status: "supported" # This is the default status, can be omitted
        - emulators:
          - gambatte:
              default: true
              saves: _savesdir_/Gambatte
              states: _statesdir_/Gambatte
    - gbc
    - nes
    - snes
    - megadrive
    - dreamcast:
        - status: "available"

This is put into a dictionary.

At this point it scans for all the systems and searches for their missing information inside the library.yml, and it finds for example of megadrive:

    - megadrive:
        name: Megadrive
        manifacturer: Sega
        name_us: Genesis
        release_jp: 29-10-1988
        release_eu: 01-11-1990
        release_us: 14-07-1989
        release_uk: 14-08-1990
        release_br: 01-12-1990
        system_folders:
          - megadrive
          - genesis
        extensions:
          - 68k
          - mdx
          - md
          - sgd
          - smd
          - gen
          - bin
          - zip
          - 7z

In this case the dictionary is updated as the following:

# Miyoo Mini v3 - OnionOS
miyoominiv3-onion:
  name: Miyoo Mini
  template_version: 0.1
  brand: Ingenic
  gamelist_file: miyoogamelist.xml
  saves: Saves/CurrentProfile/saves
  states: Saves/CurrentProfile/states
  roms_path: ROMs
  systems:
    - gb:
        - status: "supported" # This is the default status, can be omitted
        - emulators:
          - gambatte:
              default: true
              saves: _savesdir_/Gambatte
              states: _statesdir_/Gambatte
    - gbc
    - nes
    - snes
    - megadrive:
        name: Megadrive
        manifacturer: Sega
        name_us: Genesis
        release_jp: 29-10-1988
        release_eu: 01-11-1990
        release_us: 14-07-1989
        release_uk: 14-08-1990
        release_br: 01-12-1990
        system_folders:
          - megadrive
          - genesis
        extensions:
          - 68k
          - mdx
          - md
          - sgd
          - smd
          - gen
          - bin
          - zip
          - 7z
    - dreamcast:
        - status: "available"

And so on for all the other systems.

NOTE: in case of conflicts the library.yml is weaker than the template file miyoominiv3-onion.yml that wins over the library.

NOTE2: the entry emulator and folder are mandatory in every device template and they're not inherited by library.
Otherwise when a game is copied onto the device, the engine will not know in which folder to put it.

[XargonWan]

For reference here is how a device template can be, I call this "Master Template".
This is a resume of all the possible option, it's basically a guide on how creating templates.

# Master template file, use it just for reference
# the set option is the default one, the bracked options are allowed values
# value: default (value1, value2, null, integer, string)
# where null is not specified means the value is mandatory unless a default value is set

master-template:
  name: string
  template_version: string
  brand: null, string
  roms_path: ./roms ( string )
  gamelist: {{ $roms_path }}/filename ( string )    # usually gamelist.xml, filename of the gamelist file, null= no gameslist file
  saves: ./saves ( string )                         # in case saves are in the same rom directory {{ $roms_path }} can be put
  states: ./states ( string )                       # in case saves are in the same rom directory {{ $roms_path }} can be put
  media:
    - screenshot:                                   # if image/video is not set it's false by default and no scraped media is moved
        path: {{$resources}}/screenshot
        height: null, number                        # in px
        width:  null, number                        # in px
        formats: list[string]                       # extensions, this might be needed when the older devices don't support specific formats
    - video:
        path: {{$resources}}/video
        height: null, number
        width:  null, number
        formats: list[string]
    - manuals:
        path: {{$resources}}/manuals ( null, string )   # {{$system.system_folders}}/manuals
    - support:
        path: {{$resources}}/support ( null, string )   # Where the cartdrige or disk image is saved
        height: null, number
        width:  null, number
        formats: list[string]
    - wheel:
        path: {{$resources}}/wheel
        height: null, number
        width:  null, number
        formats: list[string]
    - logo:
        path: {{$resources}}/logo
        height: null, number
        width:  null, number
        formats: list[string]
    - title:
        path: {{$resources}}/title
        height: null, number
        width:  null, number
        formats: list[string]
  systems:
    - {{ $system_id }}:                             # if nothing except this is delcared, it will be inherited from library
          name: string                              # main name
          name_alt: map{(string,string)}            # additional names, example: {("us","Genesis"),("jp","メガドライブ")}
          manufacturer: null, string
          release: map{(string,string)}             # release dates, example: {("us","01-01-1988"),("jp","01-04-1987")}, date format is dd-mm-yyyy 
          status: supported ( available )           # supported = the system is playable, avaliable = system is not performing good
          bios: map{(string,string)}                # needed bios files, example:{(bios1,hash1),(bios2,hash2)}
          opt_bios: map{(string,string)}            # optional bios files, example:{(bios1,hash1),(bios2,hash2)}
          system_folders: list ( string )           # possible system folders name to search into, in case of device template only one must be specified
          dlc: false ( bool )                       # this system officially supports DLC
          patches: false ( bool )                   # this system officially supports patches
          merged: list(string)                      # Merges two or more systems in one, some handhelds are merging systems like wonderswan and wonderswan color in a single sytem
          emulators:
            - {{ $emulator1 }}:
                default: true ( bool )
                saves: {{ $system.saves }} ( string )                       # possibility to override saves location for a single emulator
                states: {{ $system.states }} ( string )                     # possibility to override states location for a single emulator
                system_folders: {{ $system.system_folders }} list[string]   # possibility to override the roms folder for a single emulator
                extensions: {{ $system.extensions }} list[string]           # possibility to specify supported extensions for a single emulator
                bios: {{ $system.bios }} map{(string,string)}               # additional bioses that the emulator may need. Those are merged with the sytem bioses
                opt_bios: {{ $systems.opt_bios }} map{(string,string)}      # additional bioses that the emulator may optionaly have. Those are merged with the sytem bioses
            - {{ $emulator2 }}:
                default: false ( bool )

[XargonWan]

RomM will have a list of created (managed) devices that is available when the device is disconnected.
In this case I can add/remove roms/collection and this changes will be applied when the device is reconnected.

If at the reconnection, the device state is not as expected by RomM, the user will get a prompt asking on what to do, such as:

• Restore to the previous state
• Resolve the conflicts
• Force the new state

[XargonWan]

A thought: we may simplify this by removing the extensions check and just check all the files in a folder with some filters such as .DS_STORE, .xml and so on.

[XargonWan]

I did this edit but the emulator must have the extension field as an optional value as not all the emulators of the same system are supporting the same roms extensions.

[gantoine]

Rolling this into #2199