Differences

This shows you the differences between two versions of the page.

--- systems:scummvm [2022/04/26 07:37] – consistency and cleanup atari
+++ systems:scummvm [2025/05/17 03:33] (current) – typo tovarichtch
@@ Line 1: / Line 1: @@
 <WRAP group>
 <WRAP round box twothirds column>
-{{ https://raw.githubusercontent.com/fabricecaruso/es-theme-carbon/master/art/logos/scummvm.svg?nolink&300 }}
+{{ https://raw.githubusercontent.com/fabricecaruso/es-theme-carbon/master/art/logos/scummvm.svg?nolink&360 }}
 ====== ScummVM ======
-For those who prefer videos, check out [[https://youtu.be/Lsza3f_OzGA|Batocera Nation's excellent ScummVM guide]].
+ScummVM is a program that runs classic graphical point-and-click adventure and RPG games from the 80s and 90s. It supports over two-hundred games with many classics from LucasArts, Sierra On-Line, Cyan or Westwood Studios.
-ScummVM is an emulator that runs classic graphical point-and-click adventure and RPG games from the 80's and 90s. It supports 250+ games with many classics from LucasArts, Sierra On-Line, Cyan or Westwood Studios.
 Notable ResidualVM games (modern Lucas Arts games) include Escape from Monkey Island, Grim Fandango, Myst III: Exile and The Longest Journey. Notable Notable AGS titles include Heroine's Quest, Resonance, Gemini Rue, The Apprentice I and II.
-ScummVM emulates the engine, but requires the game's data files to function.
+ScummVM requires the game's data files to function.
 This system scrapes metadata for the "pc" group(s) and loads the ''scummvm'' set from the currently selected theme, if available.
@@ Line 23: / Line 21: @@
 ==== Quick reference ====
-  * **Accepted ROM formats:** ''.scummvm'', ''.squashfs''
+  * **Emulator:** [[#Core_differences|ScummVM]]; [[#Core_differences|libretro: ScummVM]]
   * **Folder:** ''/userdata/roms/scummvm''
+  * **Savegames:** ''/userdata/saves/scummvm''
-^ Emulators ^
+  * **Accepted ROM formats:** ''.scummvm'', ''.squashfs''
-| [[#scummvm|ScummVM]] |
-| [[#libretro:_scummvm|libretro: ScummVM]] |
 ===== BIOS =====
-No ScummVM emulator in Batocera needs a BIOS file to run.
+No ScummVM emulator in Batocera needs a BIOS file to run. For Roland MT-32 emulation indeed some files are needed. Please refer to [[#midi_roms_roland_mt-32_music|Roland MT-32]] section
 ===== Game files =====
-<WRAP center round important>
+A list of freeware games and where to buy commercial games can be found at [[https://wiki.scummvm.org/index.php/Where_to_get_the_games|ScummVM FAQ]] and specifically for [[https://store.steampowered.com/search/?sort_by=_ASC&term=scummvm|Steam games]] search the store.
-As each ScummVM game needs to be in its own folder, be careful with the option on how you display folders in **UI Settings**. It should be set to **HAVING MULTIPLE GAMES** or **NEVER**. If you set it to **ALWAYS**, well, you'll always see the ScummVM folders.
+<WRAP center round tip>
+Since ScummVM games require their own folder, setting the folder display setting in **USER INTERFACE SETTINGS** to **HAVING MULTIPLE GAMES** or **NONE** will prevent redundant menu navigation.
 </WRAP>
-A list of freeware games and where to buy commercial games can be found at https://wiki.scummvm.org/index.php/Where_to_get_the_games (and for Steam games specifically https://store.steampowered.com/search/?sort_by=_ASC&term=scummvm).
+==== Setup games ====
-Batocera Nation has kindly pre-configured some of the freeware games to allow for easy drag-and-drop installation: https://www.batoceranation.com/downloads/ (scroll down to "10 Freeware Games for ScummVM"). These can be used as examples to see how things are setup in case any of the following is confusing.
+Since **Batocera v42** it is easier than ever to setup the ScummVM. In the first example we explain the [[#General_Setup|general setup]] that will generally work in older versions and is a solid setup. Later the [[#Autodetection|autodetection]] and the specific setup by using the [[#GameID_or_EngineID|GameID or EngineID]] (for example language) is explained.
-==== For standalone ====
+As the ultimate setup, there is a [[https://raw.githubusercontent.com/crcerror/BATOCERA-Shares/refs/heads/master/ScummVM/scummvm-addgames-v2.sh|small script]] available. This will create the correct ''GameID'' within the auto created ''scummvm''-file. The script will not work if there is a ''scummvm''-file already in the game directory or if the ''GameID'' is already inside the ''scummvm.ini'' file - read more about installation and the usage [[#Use_Setup_Script|here]].
-Create a directory per game in ''/userdata/roms/scummvm/''. For example, let's imagine you own the data file from the Day of the Tentacle, in that case, just put all the files in a directrory ''/userdata/roms/scummvm/Day_of_the_Tentacle/''. Then, in this game data directory, you need to create a file with the **codename** of the game, like ''tentacle.scummvm''. This file can just be empty.
+Be aware that a kind of priorizing takes place. Highest priority is **file content**, after that the **filename**, then the **autodetection** takes place. If you enter a false GameID as file content this has highest priority - please take care about this.
-To find out the codename of the game, open up ''scummvm'' from the Applications menu (''[F1]'' on the system list) and load the game, the ID will be provided. For example, with the game The 11th Hour: The Sequel to The 7th Quest (DOS/English):
+=== General Setup ===
+Create a directory per game in ''/userdata/roms/scummvm/''. For this example, we will use the game files for **The Day of the Tentacle**. The game files will need to be put in the directory ''/userdata/roms/scummvm/Day_of_the_Tentacle/''. Then, in this game data directory, a blank file named ''<GameID>.scummvm'' needs  of the game, like ''tentacle.scummvm''. Now you can even pack this directory to ''squashfs''-file and run it from there.
+=== GameID or EngineID ===
+Please refer to [[#Detect_GameID|Detect GameID section]] to get instructions how to obtain the proper IDs from your ScummVM games.
+Create a directory per game in ''/userdata/roms/scummvm/''. For this example, we will use the game files for **The Day of the Tentacle**. The game files will need to be put in the directory ''/userdata/roms/scummvm/Day_of_the_Tentacle/''. Now create a game file like ''Day of the Tentacle.scummvm'' and inside the file put the content ''tentacle'' for it's GameID. This methods needs at least Batocera v42.
+=== Autodetection ===
+Create a directory per game in ''/userdata/roms/scummvm/''. For this example, we will use the game files for **The Day of the Tentacle**. The game files will need to be put in the directory ''/userdata/roms/scummvm/Day_of_the_Tentacle/''. Now create a game file like ''Day of the Tentacle.scummvm''. As there is no valid GameID detectable the autodetection is activated and ScummVM tries to autodetect the correct GameID. This is by far the most convinient way but at least needs Batocera v42. This feature also enables ''squashfs''-files that there is no need in containing any additional ''scummvm''-file inside the archive.
+**Attention:** Autodection displays a list of games from the current or specified directory and starts the **first game** in the list. This is usally the english version of a game.
+=== Use Setup Script ===
+You can use a [[https://raw.githubusercontent.com/crcerror/BATOCERA-Shares/refs/heads/master/ScummVM/scummvm-addgames-v2.sh|small script]] to setup everything for you. Be aware that the script will exit if there is a ''scummvm''-file already present in the specific game folder. If you already started the setup and the ''scummvm.ini'' contains already the GameID for your game then the script will refuse to create the start file. So best practise is to start from a clean setup. Means, you remove old ''scummvm''-files and delete the ''scummvm.ini''
+<code>
+Usage:
+./scummvm-addgames-v2.sh <gamefolder> {auto|standalone|libretro|random|ma-random}
+</code>
+  * ''auto/standalone'' use ''scummvm.ini'' location of the standalone core and write GameID there
+  * ''libretro'' use ''scummvm.ini'' location of the libretro core and write GameID there
+  * ''random'' use ''/tmp/scummvm_<RND#>.ini'' to write GameID within. It's basically a new file that can be copied over.
+  * ''ma-random'' use ''/tmp/scummvm_<RND#>.ini'' to write GameID within. As long as the file ''/tmp/scummvm.identifier'' is found all data is written into the same file. This is ideal if you use a script to mass add games to a new created ini-file.
+Download the script from [[https://raw.githubusercontent.com/crcerror/BATOCERA-Shares/refs/heads/master/ScummVM/scummvm-addgames-v2.sh|here]] and put it inside ''/userdata/roms/scummvm''. Make it executable with ''chmod +x scummvm-addgames-v2.sh'' or use interpreter ''bash scummvm-addgames-v2.sh''.
+You can wrap a small script around this to autocreate all files needed for your games. Thanks to knulli for the script, I made some small modifications around that.
+Here is a small example how to use the script to mass add games and to proper create scummvm-files. Please improve the scripts to make it work for you and share with the community. Me (crcerror aka cyperghost) has a real life ... so please see this as a scripting example.
+<code>
+    #!/bin/bash
+    # Error Codes:
+    # 0  - everything went okay
+    # 1  - general error (missing parameters, wrong parameter
+    # 11 - game folder does not exist
+    # 12 - game folder is empty
+    # 13 - scummvm file found in gamedir
+    # 15 - scummvm.ini already contains GameID
+    # So it's up to YOU to handle this, please delete /tmp/scummvm.identifier after you used ma-random parameter for mass adding
+    readarray -t array < <(find . -mindepth 1 -maxdepth 1 -name "*" -type d)
+    for i in "${array[@]}"; do
+        bash scummvm-addgames-v2.sh "$i" ma-random
+    done
+    rm /tmp/scummvm.identifier
+</code>
+==== Detect GameIDs ====
+GameIDs are needed to setup a game for a specific language or to use special features that are included inside the game. That means CD specials like //talkie versions//. The EngineID can be more descriped as the base game features without langue string. That means, englisch language is default for multi language games. For example EngineID is ''gob3'' only, whereas GameID is ''gob3-fr''
+<WRAP center round tip>
+The GameIDs need to be setted inside the ''scummvm.ini'' file. It is a bit unfortun, that the location of the ini file is different between the both cores. Read more about the [[#Core_differences|Differences in the cores]] in this wonderfull instruction. So if you want to setup both cores then copy the ready setted ''scummvm.ini'' from one core to to annother.
+</WRAP>
+To find out the GameID of the game, open up ''scummvm'' from the Applications menu (''[F1]'' on the system list) and load the game, the ID will be provided. For example, with the game The 11th Hour: The Sequel to The 7th Quest (DOS/English):
 {{:systems:scummvmgameid1.png?720|}}
@@ Line 54: / Line 107: @@
 {{:systems:scummvmgameid3.png?720|}}
-Here, the codename is ''11h''.
+Here, the EngineID is ''11h''.
 <WRAP center round tip>
-Mass add to add all the games at once!
+Use ''%%/usr/bin/scummvm --add --recursive --path=/userdata/roms/scummvm --config=~/configs/scummvm/scummvm.ini%%'' to mass add all the games at once to the ScummVM Launcher! This is important, otherwise ScummVM does not recognize how to start a game if you use a filename based setup like ''sword25-fr.scummvm'' for example.
 </WRAP>
-After the game been added on ScummVM it's possible to edit the codename. It's a good way to setup the launcher for [[#the_game_isn't_in_my_language/is_in_english|different languages]] for AGS games.
+After the game been added on ScummVM it's possible to edit the EngineID. It's a good way to setup the launcher for [[#the_game_isn't_in_my_language/is_in_english|different languages]] for AGS games.
 {{:systems:scummvmagslanguagelaunchersetup1.png?720|}}
@@ Line 71: / Line 124: @@
 </WRAP>
-==== For libretro: ScummVM ====
+Note: All settings are stored into scummvm.ini config file, if you want to backup, migrate or sync it to another device, just backup or restore this file.
+  * Path location:
+    * Batocera: /userdata/bios/scummvm.ini
+    * Windows: %APPDATA%\ScummVM\scummvm.ini
+      * For Windows 95/98/ME, the file is at C:\WINDOWS\scummvm.ini
+    * MacOS: ~/Library/Preferences/ScummVM Preferences/scummvm.ini
+      * If an earlier version of ScummVM was installed on your system, the configuration file remains in the previous default location of ~/.scummvmrc
+    * Linux: ~/.config/scummvm/scummvm.ini
+      * If ScummVM was installed using Snap, the configuration file is found at ~/snap/scummvm/current/.config/scummvm/scummvm.ini
+      * If ScummVM was installed using Flatpak, the configuration file is found at ... [update later]
+    * Other platforms normally at path to:ScummVM/scummvm.ini
+      * All paths here: [[https://docs.scummvm.org/_/downloads/en/latest/pdf/|ScummVM Documentation]]
+  * Find or Edit the config location path at:
+  * {{:systems:scummvm_config_path.png?nolink&720|}}
-Create a directory per game in ''/userdata/roms/scummvm/''. For example, let's imagine you own the data file from the Day of the Tentacle, in that case, just put all the files in a directrory ''/userdata/roms/scummvm/Day_of_the_Tentacle/''. Then, in this game data directory, you need to create a file with the **codename** of the game, like ''tentacle.scummvm''. This file can just be empty.
+==== Core Differences ====
-To find out the codename, [[:access_the_batocera_via_ssh|SSH]] into Batocera and run ''%%/usr/bin/scummvm --list-games | >> codename.txt%%'' and search for your game.
+Since Batocera v42 both cores work quite similarly. They share the same savegame location, both cores use autodetection if no ''GameID'' is setted from filename or file content. Let us now talk about the differences:
+  - Location of ''scummvm.ini''
+    - Standalone ScummVM: ''/userdata/system/config/scummvm/scummvm.ini''
+    - Libretro ScummVM: ''/userdata/bios/scummvm.ini''
+  - Handling of GameID as filename
+    - Standalone ScummVM: Handles a GameID from file content and filename
+    - Libretro ScummVM: Handles a GameID only from file content, EngineID from filename
+  - Different versions:
+    - Refer to core and its version info. Usually the version number differs not so much, so libretro and standalone cores are almost compatible
+  - Language Setup
+    - Standalone ScummVM: Use the GameID, setted from file content and filename or use EmulationStation Frontend to define the specific language
+    - Libretro ScummVM: Language can only be setted by proper GameID - there is no option in ES available
+I made best experience to setup one core completly and then copy the setupd ''scummvm.ini'' to the second core location. Also using symblink works.
 ==== None of that works for me! ====
-Game titles and their codenames are also provided on [[http://scummvm.org/compatibility/|the compatibility page from the main ScummVM website]] (AGS games specifically are [[https://wiki.scummvm.org/index.php?title=AGS/Games|on their wiki]], as well as [[ https://wiki.scummvm.org/index.php/Category:Fan_Games|fangames]]). If you //still// can't find the game ID for your game, then look up the ''detection_tables.h'' file for the specific group of games directly from the repository: https://github.com/scummvm/scummvm/tree/master/engines (for instance, AGS games are in the ''ags/detection_tables.h'' file).
+First be aware that priorizing takes place. Highest priority is **file content**, after that the **filename**, then the **autodetection** takes place. So if you made a mistake here, ScummVM will fail to launch - check first the logs in ''\userdata\system\logs'' for errors.
+Alternatively, [[:access_the_batocera_via_ssh|SSH]] into Batocera and run ''%%/usr/bin/scummvm --list-games >> /userdata/system/engineid.txt%%'' to list //all// the game titles and search for your game in the resulting ''/userdata/system/engineid.txt'' file.
+Game titles and their EngineIDs are also provided on [[http://scummvm.org/compatibility/|the compatibility page from the main ScummVM website]] (AGS games specifically are [[https://wiki.scummvm.org/index.php?title=AGS/Games|on their wiki]], as well as [[ https://wiki.scummvm.org/index.php/Category:Fan_Games|fangames]]). If you //still// can't find the game ID for your game, then look up the ''detection_tables.h'' file for the specific group of games directly from the repository: https://github.com/scummvm/scummvm/tree/master/engines (for instance, AGS games are in the ''ags/detection_tables.h'' file).
+==== MIDI ROMs / Roland MT-32 music ====
+Some of the engines provided by ScummVM support Roland MT-32 midi music. However, unlike other soundcard emulators like AdLib or CMS, Roland MT-32 music requires some additional files that need to be provided separately.
+If you want to use Roland MT-32 music in your ScummVM games, you will have to provide the required files yourself. Once you've sourced the files, put them in the bios folder of your userdata folder like this:
+<code>
+/bios
+  └─ scummvm/
+    └─ extra/
+        └─ MT32_CONTROL.ROM
+        └─ MT32_PCM.ROM
+</code>
+Once you have added the files:
+  * Launch any ScummVM game.
+  * Press ''Start'' then ''Return to Launcher'' to get to the ScummVM launcher.
+  * From there go to ''Global Options''.
+  * Go to the ''Audio'' tab.
+  * Set ''Preferred Device'' to ''MT-32 emulator''.
+  * Quit ScummVM and re-launch the game.
+  * Enjoy the music.
 ===== Emulators =====
@@ Line 107: / Line 214: @@
 Open up ''scummvm'' from the Applications menu (''[F1]'' on the system list) and load the game.
-Select the game's language in **GAME** => **LANGUAGE** or **ENGINE** => **GAME LANGUAGE**:
+Select the game's language in **GAME** -> **LANGUAGE** or **ENGINE** -> **GAME LANGUAGE**:
 {{:systems:scummvmlanguage.png?720|}}
@@ Line 114: / Line 221: @@
 ==== RetroArch ====
-[[https://docs.libretro.com/|RetroArch]] (formerly SSNES), is a ubiquitous frontend that can run multiple "cores", which are essentially the emulators themselves. The most common cores use the [[https://www.libretro.com/|libretro]] API, so that's why cores run in RetroArch in Batocera are referred to as "libretro: (core name)". RetroArch aims to unify the feature set of all libretro cores and offer a universal, familiar interface independent of platform.
+RetroArch has [[emulators:retroarch|its own page]].
-=== RetroArch configuration ===
-RetroArch offers a **Quick Menu** accessed by pressing ''[HOTKEY]'' + {{:wiki:south.png?nolink&20|South button (B SNES)}} which can be used to alter various things like [[:advanced_retroarch_settings|RetroArch and core options]], and [[:remapping_controls_per_emulator|controller mapping]]. Most RetroArch related settings can be altered from Batocera's EmulationStation.
-Standardized features available to all libretro cores: ''scummvm.videomode'', ''scummvm.ratio'', ''scummvm.smooth'', ''scummvm.shaders'', ''scummvm.pixel_perfect'', ''scummvm.decoration'', ''scummvm.game_translation''
-^ ES setting name ''batocera.conf_key'' ^ Description => ES option ''key_value'' ^
-^ Settings that apply to all cores of this emulator ||
-| **GRAPHICS BACKEND ''scummvm.gfxbackend''** | Choose your graphics rendering\\ => OpenGL ''opengl'', Vulkan ''vulkan''. |
-| **AUDIO LATENCY ''scummvm.audio_latency''** | Audio latency in milliseconds, turn it up if you hear crackles\\ => 256 ''256'', 192 ''192'', 128 ''128'', 64 ''64'', 32 ''32'', 16 ''16'', 8 ''8''. |
-| **THREADED VIDEO ''scummvm.video_threaded''** | Improves performance at the cost of latency and more video stuttering. Use only if full speed cannot be obtained otherwise.\\ => On ''true'', Off ''false''. |
 === libretro: ScummVM ===
@@ Line 149: / Line 244: @@
 Here are the default ScummVM's controls shown on a [[:configure_a_controller|Batocera Retropad]]:
-{{ https://raw.githubusercontent.com/batocera-linux/batocera-controller-overlays/master/solid-4k/scummvm.png }}
+{{https://raw.githubusercontent.com/batocera-linux/batocera-controller-overlays/master/solid-4k/scummvm.png}}
 ===== Troubleshooting =====
+First be sure you added your game to the ScummVM-Player list. Most commands introduced later down, like language setting per filename, will not work without this.
+==== My game isn't launching (standalone) ====
+On certain hardware configurations, ScummVM has difficulties with the **HEADS UP DISPLAY** option in **GAME SETTINGS**, try setting it to "NONE".
+Make sure you have at least one physical gamepad connected and configured, even if you aren't intending on using it for that game.
 ==== The game isn't in my language/is in English ====
@@ Line 175: / Line 278: @@
 - ''sword25-es.scummvm'' for Spanish
-==== I've put the codename in for my game but it's failing to launch ====
+==== I've put the EngineID in for my game but it's failing to launch ====
 It's the launch file that needs to be ''tentacle.scummvm'', **not the directory** that contains the game files.
@@ Line 181: / Line 284: @@
 If that's not it, some games could have different versions, you can specify it with (or a combination of):
-- ''<codename>.scummvm'' for Floppy or DOS
+- ''<EngineID>.scummvm'' for Floppy or DOS
-- ''<codename>-cd.scummvm'' or ''gameidcd.scummvm'' for CD
+- ''<EngineID>-cd.scummvm'' or ''gameidcd.scummvm'' for CD
-- ''<codename>-win.scummvm'' or ''gameidwin.scummvm'' for Windows
+- ''<EngineID>-win.scummvm'' or ''<EngineID>win.scummvm'' for Windows
-- ''<codename>-amiga.scummvm'' for Amiga
+- ''<EngineID>-amiga.scummvm'' for Amiga
-- ''<codename>-fm.scummvm'' for FM-Towns
+- ''<EngineID>-fm.scummvm'' for FM-Towns
-- ''<codename>-v2.scummvm'' for Version 2
+- ''<EngineID>-v2.scummvm'' for Version 2
-- ''<codename>vga.scummvm'' or ''gameid-vga.scummvm'' for VGA
+- ''<EngineID>-vga.scummvm'' or ''<EngineID>vga.scummvm'' for VGA
-- ''<codename>-ega.scummvm'' for EGA
+- ''<EngineID>-ega.scummvm'' for EGA
-- ''<codename>sci.scummvm'' for SCI
+- ''<EngineID>-sci.scummvm'' for SCI
-- ''<codename>agdi.scummvm'' for AGDI
+- ''<EngineID>-agdi.scummvm'' for AGDI
-- ''<codename>-demo.scummvm'' for DEMO
+- ''<EngineID>-demo.scummvm'' for DEMO
-- ''<codename>deluxe.scummvm'' for DELUXE
+- ''<EngineID>-deluxe.scummvm'' for DELUXE
-- ''<codename>-steam.scummvm'' for STEAM
+- ''<EngineID>-steam.scummvm'' for STEAM
-- ''<codename>-win-cd-us.scummvm'' for Windows, CD and US
+- ''<EngineID>-win-cd-us.scummvm'' for Windows, CD and US
 ==== Further troubleshooting ====
-[[https://wiki.scummvm.org/index.php?title=Main_Page|ScummVM's wiki]] contains a wealth more information. ScummVM's documentation is available on their [[docs.scummvm.org|docs website]], and further info on [[https://github.dev/scummvm/scummvm/tree/master/engines|their Github dev website]].
+[[https://wiki.scummvm.org/index.php?title=Main_Page|ScummVM's wiki]] contains a wealth more information. ScummVM's documentation is available on their [[https://docs.scummvm.org|docs website]], and further info on [[https://github.dev/scummvm/scummvm/tree/master/engines|their Github dev website]].
 For further troubleshooting, refer to the [[:support|generic support pages]].