madcow/scummvm-cursorfix
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Leon Krieg
2026-02-02 04:50:13 +01:00
commit 5b11698731
22592 changed files with 7677434 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
doc/docportal/use_scummvm/LAN.rst Normal file
View File

@@ -0,0 +1,47 @@
==================================
Using the local web server
==================================
ScummVM can run a local web server (LAN), to simplify the transfer of game files, saved games and configuration files between devices on the same network. This is a good option if you do not want to use the Cloud, or if ScummVM for your platform does not have cloud functionality.
.. note::
LAN functionality is not supported on all platforms.
This guide explains how to set up and run a local web server.
From the Launcher, select **Options**, click the **>** scroll arrow until the LAN tab is visible, and then select the **LAN** tab.
Click **Run server** to start the server.
.. figure:: ../images/cloud_and_lan/LAN_server_running.png
The LAN tab, with the server running.
To access the server, type the URL shown into the address bar of any web browser:
.. figure:: ../images/cloud_and_lan/LAN_server.png
The server's browser interface.
To download a file, click on the file to open the system download dialog.
To create a new directory, click **Create Directory**.
.. figure:: ../images/cloud_and_lan/LAN_server_new.png
Create a new directory
To upload files, click **Upload Files** and select files from the system file browser.
.. figure:: ../images/cloud_and_lan/LAN_server_upload.png
Upload files
To change which files are accessible on the web server, set the **/root/ Path** to the directory containing the files you wish to access. You can access anything inside that directory, but you cannot access its parent directory. On some platforms ScummVM automatically sets the **/root/ Path**, but on some other platforms you need to configure this manually before running the web server for the first time.
To stop the web server, click **Stop server** to stop the server, or click **Ok** to close the settings dialog.

89
doc/docportal/use_scummvm/add_play_games.rst Normal file
View File

@@ -0,0 +1,89 @@
=================================
Adding and playing a game
=================================
Where to get the games
=============================
One of the most frequently asked questions is, "Where do I get the games?!?". If you still have your old floppy discs or CDs lying around, and have a way to read them, then you can use the game files from those original discs.
If you haven't had a floppy disc or even a CD in your possession for a while, there is a ScummVM `wiki page <https://wiki.scummvm.org/index.php?title=Where_to_get_the_games>`_ dedicated to helping you find some games to play.
.. tip::
ScummVM has an affiliate referrer programme with ZOOM-Platform.com, so if you are going to buy a game, please use this `ZOOM-Platform.com <https://www.zoom-platform.com/?affiliate=c049516c-9c4c-42d6-8649-92ed870e8b53>`_ link to help the project!
Make sure to check out the `compatibility list <https://www.scummvm.org/compatibility/>`_ on the ScummVM website, and the `Supported Games page <https://wiki.scummvm.org/index.php?title=Category:Supported_Games>`_ and `Platform Overview page <https://wiki.scummvm.org/index.php/Platforms/Overview>`_ on the ScummVM wiki before you buy a game, to ensure it can run with ScummVM.
.. _add and play games:
Adding games to the Launcher
==============================
The following steps explain how to add a game to ScummVM, and assume you have access to the data files for each game. If you're not sure how to access the game data files, see the :doc:`game_files` page.
1. Run ScummVM to open :doc:`the Launcher <../use_scummvm/the_launcher>`.
2. In the Launcher window, click **Add Game**. This opens a file browser; either the system file browser or the ScummVM file browser.
.. image:: ../images/Launcher/add_game.png
To add multiple games at once, click the expander arrow next to **Add Game**, and select **Mass Add**.
.. image:: ../images/Launcher/mass_add.png
3. Use the file browser to locate the folder containing the game data files. For the ScummVM file browser: Double click on a folder to open it, and use **Go up** to go back up one level. Highlight the folder by clicking on it, and then click **Choose**
.. image:: ../images/Launcher/choose_game_directory.png
:class: with-shadow
.. note::
The **Use Native file browser** option in the :doc:`Misc <../settings/misc>` tab of the global settings controls whether ScummVM uses the system file browser, or its own file browser.
If you are using **Mass Add**, select **Yes** to run the mass game detector. A dialog opens to advise which games were added to the games list.
.. image:: ../images/Launcher/mass_add_confirm.png
.. image:: ../images/Launcher/mass_add_success.png
Sometimes, ScummVM detects multiple versions of a single game. In this case, highlight the correct version and click **Choose** to continue.
.. figure:: ../images/Launcher/choose_version.png
.. caution::
If you are using **Mass Add**, ScummVM adds all versions of a game.
If you are adding an unknown version of a game, ScummVM is not able to add the game to the games list. An error message appears to warn you that the game has not been added.
4. The **Game Options** window opens to allow configuration of various settings for the game. These can be reconfigured at any time, but for now everything should be OK at the default settings. Any settings changed here override the global settings. Click **Ok**.
.. image:: ../images/Launcher/game_settings.png
:class: with-shadow
.. note::
The **Game Options** window does not open when **Mass Add** is used.
5. Games are now ready to play! To play, either double-click on the game in the games list, or highlight the game by clicking on it, and then click **Start**. In grid view, either double-click on a game to start it, or select the game and click the play icon in the pop-up window.
.. image:: ../images/Launcher/start_game.png
:class: with-shadow
Games can also be launched directly from the command line. For more information, see the `Command line options <../advanced_topics/command_line>`_ page.
A note about copyright
==============================
ScummVM has a strict anti-piracy stance and the team will not tolerate discussions around pirated games in any part of the project, including on the Forum or on Discord.
Copy protection screen
************************
There are cases where the game companies themselves bundled 'cracked' executables with their games. In these cases the data files still contain the copy protection scripts, but the interpreter bypasses them; similar to what an illegally cracked version might do, only that here the producer of the game did it. There is no way for ScummVM to tell the difference between legitimate and pirated data files, so for the games where a cracked version of the original interpreter was sold at some point, ScummVM has to bypass the copy protection.
In some cases ScummVM still shows the copy protection screen. Enter any answer; chances are that it will work.

99
doc/docportal/use_scummvm/connect_cloud.rst Normal file
View File

@@ -0,0 +1,99 @@
===============================
Connecting a cloud service
===============================
Connecting ScummVM to a cloud storage service provides an easy way of sharing game files and saved games between multiple devices. ScummVM currently supports Dropbox, OneDrive, Google Drive and Box, although only one service can be connected at any one time.
.. note::
Cloud functionality is not supported on all platforms.
This guide explains how to connect a cloud service to ScummVM.
From the Launcher, select **Options** and then select the **Cloud** tab.
Select your preferred cloud storage service from the **Active storage** dropdown.
.. figure:: ../images/cloud_and_lan/cloud_storage.png
Click **Connect**.
The cloud connection wizard
------------------------------
The cloud connection wizard offers two ways to connect the cloud service: Quick mode and Manual mode.
Quick mode
****************
1. Select **Quick mode**
.. figure:: ../images/cloud_and_lan/cloud_wizard_quick.png
2. Select **Run server**. This starts a :doc:`Local Webserver <../use_scummvm/LAN>`. Select **Next**.
.. figure:: ../images/cloud_and_lan/cloud_wizard_quick_1.png
3. Click on the link.
.. figure:: ../images/cloud_and_lan/cloud_wizard_quick_2.png
4. In the browser window that opens, select the cloud service to connect. Untick the **ScummVM version 2.7.1 or newer** tickbox if you're using an older version.
.. figure:: ../images/cloud_and_lan/cloud_wizard_browser.png
5. Sign in to the chosen cloud service. Once completed, return to ScummVM. On the success screen, select **Finish** to exit.
.. figure:: ../images/cloud_and_lan/cloud_wizard_success.png
6. Back on the main Cloud tab, check the username for the connected service is correct, then select **Enable storage**.
.. figure:: ../images/cloud_and_lan/cloud_enable.png
Manual mode
**************
If the Local Webserver is not working, use manual mode to connect the cloud service.
1. Select **Manual mode**.
.. figure:: ../images/cloud_and_lan/cloud_wizard_manual.png
2. Click on the link.
.. figure:: ../images/cloud_and_lan/cloud_wizard_manual_1.png
3. In the browser window that opens, select the cloud service to connect. Untick the **ScummVM version 2.7.1 or newer** tickbox if you're using an older version.
.. figure:: ../images/cloud_and_lan/cloud_wizard_browser.png
4. Sign in to the chosen cloud service.
5. When the error screen appears, copy the JSON code found in the text box.
.. figure:: ../images/cloud_and_lan/cloud_wizard_manual_2.png
.. figure:: ../images/cloud_and_lan/cloud_wizard_manual_3.png
6. Return to ScummVM, select **Paste** and then **Next**.
.. figure:: ../images/cloud_and_lan/cloud_wizard_manual_4.png
7. On the success screen, select **Finish** to exit.
.. figure:: ../images/cloud_and_lan/cloud_wizard_success.png
8. Back on the main Cloud tab, check the username for the connected service is correct, then select **Enable storage**.
.. figure:: ../images/cloud_and_lan/cloud_enable.png
Using the cloud with ScummVM
------------------------------
Saved games sync automatically on launch, when a game is saved, and when a saved game is loaded. Select **Sync now** to manually sync.
To download game files from your cloud ScummVM folder, click **Download game files**.
.. note::
The game file download functionality is not available with Google Drive. To use this feature, choose another provider.
To change to a different cloud account, or to disconnect your cloud account from ScummVM, click **Disconnect**.

69
doc/docportal/use_scummvm/game_files.rst Normal file
View File

@@ -0,0 +1,69 @@
===========================
Handling game files
===========================
ScummVM needs access to the data files for each game. A list of required data files for each game is found on the `wiki entry <https://wiki.scummvm.org/index.php?title=Category:Supported_Games>`__ for that game. ScummVM can run the game data files from any directory it has access to, including external media.
.. note::
For ease of use, you can create a dedicated games folder into which folder containing game files can be copied. The resulting directory structure will look somewhat like this::
ScummVM Games
|-- Day of the Tentacle
| |-- MONSTER.SOU
| |-- TENTACLE.000
| `-- TENTACLE.001
`-- Flight of the Amazon Queen
|-- QUEEN.1
`-- queen.tbl
For games on floppies or CDs, if the data files are accessible, the external media can be accessed directly by ScummVM. Alternatively, copy the game files to a folder as described above. If the data files are not accessible, run the installer on the platform the game was designed for, to extract the game files.
For games downloaded from digital distributors or from various `freeware sources <https://wiki.scummvm.org/index.php?title=Where_to_get_the_games#Freeware_Games>`__ run the installer to extract the data files, or if the data files are supplied as a zip file, extract the files.
For macOS or Linux users without access to a Windows machine, you can get the data files from games that only have Windows installers. Use `Wine <https://www.winehq.org/>`_ to run the Windows installer. Alternatively, for GOG.com games, use `innoextract <https://constexpr.org/innoextract/>`_ to unpack game files from the installer without actually running it.
.. tip::
Use ScummVM's Cloud functionality to share game files and automatically back up and sync your saved game states. For detailed instructions see the :doc:`../use_scummvm/connect_cloud` guide. For devices on the same local network, ScummVM can also run a web server to allow hassle-free transfer of files. For detailed instructions, see the :doc:`../use_scummvm/LAN` guide. This is a good option if you do not wish to connect a Cloud service.
Multi-disc games
===================
ScummVM needs access to all the data files, so it will not be able to run directly from a CD if the game has multiple discs. To add a multi-CD game, copy the required data files from the CD to a folder on your hard drive. For a list of required files, see the `wiki entry <https://wiki.scummvm.org/index.php?title=Category:Supported_Games>`__ for the game you're playing.
As a general guideline, where there are duplicate, identical files (same name, same file size) on more than one disc, only one copy of the file is required. Where there are files that have the same name but are different on each disc, rename them. For example, where there is a ``music.clu`` on two discs, rename the file on the first disc to ``music1.clu`` and the file on the second disc to ``music2.clu``.
.. _cdaudio:
CD audio
============
In most cases, ScummVM can use CD audio directly from the game CD. If you don't always want to insert the game CD to use the CD audio, you can extract the audio tracks from the CD and save them locally:
1. Extract the CD audio tracks in WAV or AIFF format.
2. Convert the tracks to either MP3, FLAC, M4A or OGG file formats.
3. Place the converted audio files in the same folder that contains the other game datafiles.
4. You can name them in several ways:
1. track01.ogg - track12.ogg
2. track1.ogg - track12.ogg
3. track_01.ogg - track_12.ogg
4. track_1.ogg - track_12.ogg
.. tip::
`fre:ac <https://www.freac.org/>`_ is a multi-platform, open-source software, with the ability to both rip CDs and convert audio between MP3, OGG, FLAC and WAV file formats.
.. _macgames:
Macintosh games
==================
Many of the supported games also exist in versions for the Macintosh, however it can be tricky to extract the correct files from a Macintosh floppy or CD, especially if you are using Windows or Linux. See :doc:`../use_scummvm/mac_game_files` for an in-depth how-to guide.

25
doc/docportal/use_scummvm/how_to_settings.rst Normal file
View File

@@ -0,0 +1,25 @@
=======================
Changing settings
=======================
From the Launcher
==================
The settings are arranged by subject, on different tabs:
:doc:`Game tab <../settings/game>` | :doc:`Graphics tab <../settings/graphics>` | :doc:`Control tab <../settings/control>` | :doc:`Keymaps tab <../settings/keymaps>` | :doc:`Audio tab <../settings/audio>` | :doc:`Volume tab <../settings/audio>` | :doc:`Midi tab <../settings/audio>` | :doc:`MT-32 tab <../settings/audio>` | :doc:`Paths tab <../settings/paths>` | :doc:`GUI tab <../settings/gui>` | :doc:`Misc tab <../settings/misc>` | :doc:`Cloud tab <../settings/cloud>` | :doc:`LAN tab <../settings/lan>` | :doc:`Accessibility tab <../settings/accessibility>`
To change a setting globally, so that it affects all games, select the **Global Options** button to open the menu, and then select the tab containing the setting you would like to change.
To change a setting for just one game, highlight the game in the games list, then select the **Game Options** button and select the tab containing the setting you would like to change. If the Launcher is in grid view, select the game and then select the gear icon in the pop-up window. To make the game use the settings in the Game Options tab instead of the Global Options tab, tick **Override global settings**.
Not all settings are available for all games; for example, where there is no MIDI soundtrack for a game, there will be no MIDI or MT-32 tabs.
In the configuration file
==========================
See the :doc:`configuration file <../advanced_topics/configuration_file>` page for more information on how to do this. Configuration keys are listed in the Settings pages, after the description of each setting, in italics.
From the command line
======================
Some settings can be specified in the command line (the complete list can be found at :doc:`command line <../advanced_topics/command_line>`). These are valid for the duration of the program and don't get saved to the configuration file unless modified. They are also marked by a special color in the launcher tabs mentioned above.

113
doc/docportal/use_scummvm/install_computer.rst Normal file
View File

@@ -0,0 +1,113 @@
=====================================
Installing ScummVM
=====================================
This page explains how to install ScummVM on a computer. For all other platforms, see the relevant :ref:`platform guide <platformspecific>`.
.. tab-set::
.. tab-item:: Windows
There are two ways to install ScummVM on Windows: use the installer, or install manually.
.. dropdown:: Installing ScummVM using the installer
:open:
Download the Windows installer for your operating system from the `ScummVM downloads page <https://www.scummvm.org/downloads/>`_, and double click the downloaded file. The installer guides you through the install process, and adds a shortcut to the Start Menu. There is also an option to add a shortcut to the desktop.
To run ScummVM, either navigate to desktop and double click the ScummVM shortcut, or go to **Start > All Apps > ScummVM**. For Windows XP, go to **Start > All Apps > ScummVM**.
.. dropdown:: Installing ScummVM manually
Download the Windows zip file for your operating system (32bit or 64bit). To extract the files, right-click the folder and select **Extract All**.
To run ScummVM from the extracted folder, find the ``scummvm.exe`` file and double click it.
.. dropdown:: Running ScummVM in portable mode
Starting with ScummVM 2.6.0, ScummVM offers a portable mode. Instead of storing saved games, icons and screenshots in your user's directory, they are stored in the same folder as the ScummVM executable.
To run ScummVM in portable mode, create an empty file called ``scummvm.ini`` in the folder where you extracted the ScummVM zipfile.
.. tab-item:: macOS
.. dropdown:: Installing ScummVM using the disk image
:open:
Download the recommended disk image file from the `ScummVM downloads page <https://www.scummvm.org/downloads/>`_. After the download has completed, double click the file to mount the disk image file. A window containing the ScummVM icon opens. Drag this icon into your Applications folder to install ScummVM.
To run ScummVM, click on the icon in the Applications folder.
.. note::
macOS includes technology called Gatekeeper, which checks to ensure only trusted software is run on your Mac. ScummVM is not available from the App Store, so follow the steps on this `Apple support page <https://support.apple.com/en-us/HT202491>`_ to allow ScummVM to run.
.. tab-item:: Linux
There are multiple ways to install ScummVM on Linux: use the Snap Store, Flathub or the software repository, or manually install the release binary.
.. dropdown:: Installing ScummVM using the Snap Store
:open:
A Snap is an app that is bundled with its dependencies, which makes the install on any Linux operating system very easy. Snap comes pre-installed on Debian and Ubuntu-based distributions, but can be installed on any Linux distribution by following the instructions on the `Snapcraft website <https://snapcraft.io/>`_.
The ScummVM Snap comes with a selection of freeware games and demos pre-loaded.
Enter the following on the command line to install the ScummVM Snap:
.. code:: bash
sudo snap install scummvm
To run ScummVM, enter ``scummvm`` on the command line, or launch ScummVM through the desktop interface by clicking **Menu > Games > ScummVM**.
.. dropdown:: Installing ScummVM using Flathub
Flathub is another way to install apps for Linux, by using Flatpak. Flatpak comes standard with Fedora-based distributions, but can be installed on any Linux operating system. The `Flathub website <https://flatpak.org/setup/>`_ has excellent install instructions.
When Flatpak is installed, enter the following on the command line to install ScummVM:
.. code:: bash
flatpak install flathub org.scummvm.ScummVM
Some distributions have the option to install Flatpaks through the graphical desktop interface. Navigate to the `ScummVM Flatpak page <https://flathub.org/apps/details/org.scummvm.ScummVM>`_ , click the **INSTALL** button and then follow the install process.
To run ScummVM, enter the following on the command line:
.. code:: bash
flatpak run org.scummvm.ScummVM
To pass :doc:`Command line arguments <../advanced_topics/command_line>`, add them after the Flatpak ``run`` command.
.. note::
The Flatpak version of ScummVM is sandboxed, meaning that any games need to be copied into the Documents folder to be accessible by ScummVM.
.. dropdown:: Installing ScummVM using the software repository
ScummVM is found in the software repositories of many Linux distributions.
.. caution::
The repositories might not contain the most up-to-date version of ScummVM.
To run ScummVM, enter ``scummvm`` on the command line, or launch ScummVM through the desktop interface by clicking **Menu > Games > ScummVM**.
.. dropdown:: Installing ScummVM using the release binaries
Binary packages are only released for Debian and Ubuntu. On the `ScummVM downloads page <https://www.scummvm.org/downloads/>`_, find and download the ScummVM package that corresponds to your operating system and architecture. To install a DEB package, either double click on the downloaded DEB file to use the graphical installer, or, if that's not available, use the command line.
.. code:: bash
sudo apt install /path/to/downloaded/file.deb
Replace ``/path/to/downloaded/file.deb`` with the actual path to the downloaded DEB package. The APT software manager handles the installation.
To run ScummVM, enter ``scummvm`` on the command line, or launch ScummVM through the desktop interface by clicking **Menu > Games > ScummVM**.

32
doc/docportal/use_scummvm/keyboard_shortcuts.rst Normal file
View File

@@ -0,0 +1,32 @@
===================
Keyboard shortcuts
===================
ScummVM supports various in-game keyboard and mouse shortcuts, and since version 2.2.0 these can be manually configured in the :doc:`Keymaps tab <../settings/keymaps>`, or in the :doc:`configuration file <../advanced_topics/configuration_file>`.
For game-specific controls, see the `wiki entry <https://wiki.scummvm.org/index.php?title=Category:Supported_Games>`_ for the game you are playing.
Default shortcuts are shown in the table.
.. csv-table::
:widths: 30 70
:header-rows: 1
Shortcut, Description
:kbd:`Ctrl+F5` ,Displays the Global Main Menu
:kbd:`Cmd+q` ,Quit (macOS)
:kbd:`Ctrl+q` ,Quit (Linux/Unix)
:kbd:`Alt+F4`,Quit (Windows)
:kbd:`Ctrl+z`,Quit (other platforms)
:kbd:`Ctrl+u` ,Mutes all sounds
:kbd:`Ctrl+m` ,Toggles mouse capture
:kbd:`Ctrl+Alt` and :kbd:`9` or :kbd:`0`,Cycles forwards/backwards between graphics filters
:kbd:`Ctrl+Alt` and :kbd:`+` or :kbd:`-`,Increases/decreases the scale factor
:kbd:`Ctrl+Alt+a` ,Toggles aspect ratio correction on/off
:kbd:`Ctrl+Alt+f` ,Toggles between nearest neighbor and bilinear interpolation (graphics filtering on/off)
:kbd:`Ctrl+Alt+s` ,Cycles through stretch modes
:kbd:`Alt+Enter` ,Toggles full screen/windowed mode
:kbd:`Alt+s` ,Takes a :ref:`screenshot <screenshotpath>`
:kbd:`Ctrl+F7`,"Opens virtual keyboard (if enabled). This can also be opened with a long press of the middle mouse button or wheel."
:kbd:`Ctrl+Alt+d`,"Opens the ScummVM debugger"

320
doc/docportal/use_scummvm/mac_game_files.rst Normal file
View File

@@ -0,0 +1,320 @@
=======================================
Handling Macintosh game files
=======================================
This section explains how to access game data files from Macintosh media. For general information on how ScummVM handles game data files, including which files are required to play a game, see :doc:`../use_scummvm/game_files`.
Background
==============
There are three main aspects of Macintosh floppy or CD media that can make it difficult to extract the game data: the file system, forks, and file name encoding.
**HFS and HFS+ file system**
The Macintosh uses a different file system to other operating systems; HFS for older media, and HFS+ for more recent ones.
HFS (`Hierarchical File System <https://en.wikipedia.org/wiki/Hierarchical_File_System>`_), also known as Mac OS Standard, was used on Macintosh hard disk, floppy disks, and CDs until the late 90s. It was superseded by `HFS+ <https://en.wikipedia.org/wiki/HFS_Plus>`_, or Mac OS Extended, with the release of Mac OS 8.1 in 1998. Most game CDs released before the mid-2000 still use HFS. Modern macOS computers can still access HFS+ media, but support for reading HFS media was dropped in macOS 10.15 (Catalina).
To view and copy the files from HFS and HFS+ floppy disks and CDs on a Windows or Linux system, you need to install additional software.
Most, if not all, Macintosh games supported by ScummVM were released on an HFS medium, but if you do have a HFS+ CD then check out the :ref:`macfileaccessother` section for ways to access these files. ScummVM's :ref:`Python-based dumper <python_dumper>` also supports the HFS+ format if you are using it on macOS.
**Forks**
Macintosh HFS and HFS+ media have a concept called forks. For those familiar with NTFS, it's the same principle as NTFS streams. A file can consist of two forks, a data fork and a `resource fork <https://en.wikipedia.org/wiki/Resource_fork>`_. Both are important for games to work correctly. Systems other than macOS do not support resource forks, and a regular file copy from a HFS or HFS+ media on such a system will only copy the data fork. To properly preserve the resource fork during the copy, those files need to be converted to a MacBinary file.
**File name encoding**
Filenames in Japanese games are encoded in a way that is unique to Apple. The result is that a Mac copy of a game will not always show the correct filenames.
Macintosh also allowed special characters to be used that are disallowed in filenames on other platforms.
ScummVM runs on a wide variety of platforms and not all those platforms can store Japanese filenames or other special characters, such as non-ascii characters. ScummVM uses `punycode <https://en.wikipedia.org/wiki/Punycode>`_ to handle file names that would otherwise not be supported. Punycode converts all non-ascii characters to a special format. If the original file name had special characters, the new file name will start with ``xn--``,for example, ``xn--Icon-ja6e``.
Files that contain prohibited characters are always puny-encoded.
.. note::
Windows, macOS and Linux can store these files and do not need punycode enabled.
For more information, see the `Windows naming conventions <https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions>`_ for a list of prohibited characters.
.. _macfiledumper:
How to extract Macintosh game files
======================================
The simplest way to extract the correct game files is to use the dumper companion created and supplied by ScummVM. The dumper can extract files from an HFS medium, encode files to the MacBinary format, and rename files with Punycode if needed.
There are two versions of the dumper: a disk/ISO image version that runs in a browser, and a full-fledged version which uses Python. The browser-based version is the preferred method since this will work in the majority of cases, and it is less hassle because there is nothing to install.
The first step is to create an ISO image of your floppy or CD medium.
Creating the ISO image
------------------------
.. note::
If you are accessing HFS+ media in macOS, or HFS media on a macOS 10.14 Mojave system or older, this step is not required when using the Python dumper in MAC mode.
.. tab-set::
.. tab-item:: Windows
Use an application such as `IsoBuster <https://www.isobuster.com>`_ to create an ISO image of the CD.
.. tab-item:: macOS
Use the following commands in the Terminal to find the identifier of the media, and then create an ISO image of that media.
List disks to get the identifier for the CD or floppy disk partition:
.. code-block::
diskutil list
Alternatively, find this information using the Disk Utility application. Select the CD partition and look at the name under the *device* section.
Unmount the disk if needed:
- By default disks are mounted when they are inserted, and they need to be unmounted so that you can create the ISO file.
- HFS is no longer supported on macOS 10.15 and above, therefore those disk cannot be mounted and do not need to be unmounted.
.. code-block::
sudo umount /dev/diskID
Create the iso image:
.. code-block::
sudo dd if=/dev/diskID of=/path/name.iso
Eject the CD:
.. code-block::
drutil tray eject
.. dropdown:: Example
In the example below the CD is the last disk listed as ``CD_partition_scheme``, and the identifier for the HFS partition is ``disk5s1s2``.
.. code-block::
iMac:~ ego$ diskutil list
/dev/disk0 (internal, physical):
#: TYPE NAME SIZE IDENTIFIER
0: GUID_partition_scheme *121.3 GB disk0
1: EFI EFI 209.7 MB disk0s1
2: Apple_APFS Container disk4 121.1 GB disk0s2
/dev/disk1 (internal, physical):
#: TYPE NAME SIZE IDENTIFIER
0: GUID_partition_scheme *3.0 TB disk1
1: EFI EFI 209.7 MB disk1s1
2: Apple_APFS Container disk4 3.0 TB disk1s2
/dev/disk2 (synthesized):
#: TYPE NAME SIZE IDENTIFIER
0: APFS Container Scheme - +3.1 TB disk2
Physical Stores disk0s2, disk1s2
1: APFS Volume Macintosh HD 1.8 TB disk2s1
2: APFS Volume Preboot 42.2 MB disk2s2
3: APFS Volume Recovery 510.6 MB disk2s3
4: APFS Volume VM 20.5 KB disk2s4
/dev/disk3 (external, physical):
#: TYPE NAME SIZE IDENTIFIER
0: CD_partition_scheme *783.5 MB disk3
1: Apple_partition_scheme 682.2 MB disk3s1
2: Apple_partition_map 1.0 KB disk3s1s1
3: Apple_HFS disque 1 681.6 MB disk5s1s2
iMac:~ ego$ sudo umount /dev/disk3s1s2
Password:
iMac:~ ego$ sudo dd if=/dev/disk3s1s2 of=/Users/ego/BS1-fr.iso
1331200+0 records in
1331200+0 records out
681574400 bytes transferred in 396.380454 secs (1719495 bytes/sec)
iMac:~ ego$ drutil tray eject
.. tab-item:: Linux
Use the following commands to create an ISO image from an inserted HFS or HFS+ medium.
.. code-block::
sudo dd if=/dev/cdrom of=/path/name.iso
Usually the device will be ``/dev/cdrom``, ``/dev/dvd``, or ``/dev/floppy``. Alternatively, use ``sudo blkid`` to list the mounted and unmounted devices with their ID.
.. dropdown:: Example
.. code-block::
~$ sudo blkid
/dev/sr0: PTTYPE="mac"
~$ sudo dd if=/dev/sr0 of=/home/ego/BS1-fr.iso
1332420+0 records in
1332420+0 records out
682199040 bytes (682 MB, 651 MiB) copied, 421.918 s, 1.6 MB/s
Using the browser dumper companion - preferred method
-------------------------------------------------------
The `browser based dumper companion <https://www.scummvm.org/dumper-companion>`_ supports reading HFS media as ISO and disk images. It generates a ZIP file that can be extracted and then imported in ScummVM.
#. Upload the disk/ISO image file
#. Select the options:
- Choose Japanese when dumping Japanese disks
- Deselect unicode if the platform does not support it
3. Click the dump button
4. Download the ZIP file
5. Extract the ZIP file
6. Add the extracted directory to scummvm
.. figure:: ../images/dumper/browser_dumper.png
The browser based dumper companion.
.. note::
This web dumper-companion works entirely in your web browser and does not transfer the data to any servers.
.. _python_dumper:
Using the Python dumper companion
----------------------------------
The Python dumper companion supports HFS disks, unless you are running it on a Mac, in which case MAC mode also supports HFS+.
Prerequisites
*************
- Python3 with pip installed. Information on how to install Python can be found `here <https://wiki.python.org/moin/BeginnersGuide/Download>`_.
- The dumper file `downloaded <https://github.com/scummvm/scummvm/blob/master/devtools/dumper-companion.py>`_ from the repository.
Installation
*************
Install machfs, and xattr if using macOS:
.. tab-set::
.. tab-item:: macOS
.. code-block::
pip3 install machfs xattr
.. tab-item:: Others
.. code-block::
pip3 install machfs
Use
****
The dumper companion supports three modes: ISO, DIR and MAC. The MAC mode is specific to macOS. There's also a STR mode that is used to test drive the punyencode parts. For more info see its help section.
.. note::
The dumper companion also has help text:
.. code-block::
./dumper-companion.py --help
**ISO mode**
This mode will dump an HFS ISO file to the OUTPUT directory. This directory can then be added to scummvm.
.. code-block::
dumper-companion.py iso [-h] [--punycode] [--japanese] INPUT OUTPUT
Options:
* ``--punycode``: encodes all filename characters as punycode. Select this when your platform doesn't support UTF-8 filenames
* ``--japanese``: Use this when dumping Japanese disks.
**DIR mode**
This mode will puny-encode all files and directories in the current directory.
.. code-block::
dumper-companion.py dir [-h] directory
**MAC mode**
This mode is specific to macOS. It will traverse a directory, find all the resource forks and combine them in a MacBinary file. It is useful for when you already have all game files on your harddrive and want to import them into ScummVM.
.. code-block::
dumper-companion.py mac [-h] [--punycode] directory
Options:
* ``--punyencode``: encodes all filename characters as punycode, select this when your platform doesn't support UTF-8 filenames
.. note::
On macOS ScummVM directly accesses data and resource forks, however converting to MacBinary can be useful if you plan to transfer those files to a different system.
.. _macfileaccessother:
Other methods
--------------
There are other ways to access HFS and HFS+ media on Windows, macOS, and Linux. These methods require you to copy the files manually.
.. tab-set::
.. tab-item:: Windows
For Windows, `HFS Explorer <http://www.catacombae.org/hfsexplorer/>`_ is a basic and free option, which gives you read-only access to both HFS and HFS+ drives. Use the installer rather than the zip file, to ensure it is installed correctly. For files with a resource fork you will need to use the option to extract as MacBinary. Extract files that only have a data fork as a "raw copy, data fork".
Alternatively, `HFVExplorer <https://www.emaculation.com/doku.php/hfvexplorer>`_ can also be used for HFS drives. There is no option to extract as MacBinary, but you can extract files with a resource fork as AppleDouble using the "extract data and resource fork(s)" option.
.. tab-item:: macOS
On macOS you can read HFS+ volumes, and in some cases HFS volumes, and copy the files in the usual way in the Finder. Some discs shipped with hidden files that need to be copied. To view hidden files in macOS, press :kbd:`Cmd+Shift+.` in a Finder window.
There is also no need to convert files with a resource fork into MacBinary files, but if you want to do it, for example to later transfer the files onto a different system, you can use the ``macbinary`` command line tool.
.. code-block::
macbinary encode -o <outfile> <infile>
However the :ref:`dumper companion <macfiledumper>` is recommended in some cases:
* If you have a newer operating system. HFS media can only be read on macOS 10.14 (Mojave) and older. Support for reading HFS volumes was removed in macOS 10.15 (Catalina).
* If files contain invalid characters.
* If you plan to transfer those files to a different system.
.. tab-item:: Linux
Access HFS+ drives using ``hfsplus``. To use hfsplus, use the command line:
1. Install hfsplus using the software manager. On Debian-based distributions, use ``sudo apt install hfsplus``.
2. Find the game disc by running ``sudo fdisk -l`` and finding the one with type ``Apple HFS/HFS+``. In this example, this is ``/dev/fd0``.
3. Create a mount point, for example: ``sudo mkdir /media/macgamedrive``
4. Mount the device to that mount point: ``sudo mount -t hfsplus /dev/fd0 /media/macgamedrive``
5. Access the device at ``/media/macgamedrive``. To copy files you can use ``hpcopy``. It takes options to indicate if the files should be converted to macbinary (``-m``) or copied as a raw file (``-r``).
Access HFS drives using ``hfsutils``. To use hfsutils, use the command line:
1. Install hfsutils using the software manager. On Debian-based distributions, use ``sudo apt install hfsutils``.
2. Find the game disc by running ``sudo fdisk -l`` and finding the one with type ``Apple HFS/HFS+``. In this example, this is ``/dev/fd0``.
3. Mount the HFS volume by running ``hmount /dev/fd0``
4. List the files and directories on the HFS media using ``hls``, change the working directory on the HFS media using ``hcd`` and copy files using ``hcopy``. The ``hcopy`` commands take options to indicate if the files should be converted to macbinary (``-m``) or copied as a raw file (``-r``). For example ``hcopy -m "PP Disk 1:PP Data:JMP PP Resources" "pegasus/JMP PP Resources"``.
5. Unmount the HFS media with ``humount /dev/fd0``

98
doc/docportal/use_scummvm/save_load_games.rst Normal file
View File

@@ -0,0 +1,98 @@
===============================
Saving and loading a game
===============================
This page explains how to save and load a game from the Global Main Menu, or load a game directly from the Launcher.
.. note::
Some games use their own load or save entry points within the game, or use their own menu instead of the GMM.
Saving a game
==============
When you're playing a game and you're ready to save, press :kbd:`Ctrl+F5` (:kbd:`Ctrl+fn+F5` on a Mac) to access the Global Main Menu. Select **Save**.
.. figure:: ../images/Launcher/gmm_save.png
The Global Main Menu (GMM).
There are two views: list view and grid view. Click the list and grid icons at the bottom left of the window to toggle between the two.
In tile view, click on the **New Save** tile. Enter a description for the game, then click **OK**.
.. figure:: ../images/Launcher/save_game_grid.png
Saving a game, grid view.
.. figure:: ../images/Launcher/save_game_grid_desc.png
Save game description, grid view.
In list view, click on a slot to save the game to that slot. Enter a description for the game, then click **Save**.
.. figure:: ../images/Launcher/save_game_list.png
Saving a game, list view.
Autosave
------------
ScummVM automatically saves your game every 5 minutes. The :ref:`autosave period <autosave>` can be changed in the Misc settings tab, or in the :doc:`configuration file <../advanced_topics/configuration_file>`.
Location of saved game files
===============================
The save directory can be changed with the savepath setting in the :doc:`Paths tab <../settings/paths>`. It can also be changed in the :doc:`configuration file <../advanced_topics/configuration_file>`.
.. _savelocation:
Default saved game paths are shown below.
.. tab-set::
.. tab-item:: Windows
``%APPDATA%\ScummVM\Saved games``
.. tab-item:: macOS
``~/Library/Application Support/ScummVM/Savegames/`` (with versions of ScummVM prior to 2.9 it was in ``~/Documents/ScummVM Savegames/``).
.. tab-item:: Linux/Unix
ScummVM follows the XDG Base Directory Specification, so by default the saved games can be found at ``~/.local/share/scummvm/saves/``, but this location might vary depending on the value of the ``XDG_DATA_HOME`` environment variable.
``.local`` is a hidden directory. To view it use ``ls -a`` on the command line.
If ScummVM was installed using Snap, the saves can be found at ``~/snap/scummvm/current/.local/share/scummvm/saves/``
Loading a game
===============
If you want to load your saved game without having to start the game first, select the **Load** button directly from the Launcher. To load a saved game while you're playing a game, press :kbd:`Ctrl+F5` (:kbd:`Ctrl+fn+F5` on a Mac) to access the Global Main Menu, then select **Load**.
There are two views: list view and tile view. Click the list and tile icons at the bottom left of the window to toggle between the two.
In list view, the pane on the left shows a list of your saved games. Click on a saved game to highlight it. In the pane on the right you can see timestamps, screenshots and playtime for that saved game.
Once you have highlighted the game you want to play, click **Load**.
To delete a saved game, highlight the saved game and click **Delete**.
.. figure:: ../images/Launcher/load_game_list.png
Loading a game, list view.
In grid view, each tile shows a screenshot of the saved state, as well as a description and a save slot number. Click on the tile to load that saved game.
.. figure:: ../images/Launcher/load_game_grid.png
Loading a game, grid view.

45
doc/docportal/use_scummvm/taskbar_integration.rst Normal file
View File

@@ -0,0 +1,45 @@
===========================
Taskbar integration
===========================
The taskbar integration has several features:
- Adds an overlay icon in the taskbar/dock when running a game (Windows and macOS)
- Updates a list of recently played games that can be started from the taskbar/dock (Windows and macOS).
- Shows a progress bar when doing a mass add of games, and shows the number of games found at the end (Windows, macOS and Linux).
- Shows an error state in the taskbar if an error occurs when running a game (Windows only).
Setting up the icon overlay
================================
Currently the taskbar cannot yet use the icon .dat files that can be downloaded from the **Global Options**. This means the icons need to be downloaded manually from our `GitHub repository <https://github.com/scummvm/scummvm-icons>`. Either place these in the default :ref:`Icon Path <iconspath>` or change the Icon Path to point to the folder containing the icons.
The icon files must be ICO files for Windows, or PNG files for macOS. They must follow one of these naming conventions, where xxx is the file extension:
- :ref:`ID <id>`.xxx
- gameid.xxx
- engineid.xxx
- engineid-gameid.xxx
To find the gameid and the engineid, open the :doc:`configuration file <../advanced_topics/configuration_file>`. The game entry will be similar to this:
.. code::
[lure]
description=Lure of the Temptress (VGA/DOS/English)
iconspath=/Users/user/games/icons
path=/Users/user/games/lure
gameid=lure
engineid=lure
.. figure:: ../images/taskbar/game_icon.png
macOS dock with a custom icon overlay for Beneath a Steel Sky.
Launching recently played games
=======================================
To start a recently played game, right click on the ScummVM icon in the taskbar or dock, and select the game you want to play.

160
doc/docportal/use_scummvm/the_launcher.rst Normal file
View File

@@ -0,0 +1,160 @@
===================================
Understanding the interface
===================================
The Launcher
===============
The main ScummVM window is called the Launcher. The Launcher opens whenever you start ScummVM, unless you launch a game directly from the command line. Use the buttons on the bottom left of the screen to toggle between list and grid view.
.. figure:: ../images/Launcher/launcher_list.png
The Launcher in list view.
.. figure:: ../images/Launcher/launcher_grid.png
The Launcher in grid view.
The games list
********************
The pane on the left, when the Launcher is in list view, shows the games list, which shows all the games that have been added to ScummVM. The games list usually offers some additional information about each game, such as original platform and language. To highlight any game on the list, type the first letter(s) of its title, or click on it.
In grid view, all game icons are in the pane below the buttons, and show the game artwork. See :ref:`Update Icons <updateicons>` for information on how to update these. Use the **Icons per row** slider at the bottom of the page to change the size of the icons. Click on a game to select it. Click on the play icon in the pop-up menu to start the game, the gear icon to open the Game Options menu, or the export icon to load a saved game.
.. figure:: ../images/Launcher/launcher_popup.png
Game pop-up menu in grid view
.. _search_box:
The search box
********************
The search box lets you filter the games list. It is located at the top of the page next to the magnifying glass icon. The filter is applied as you type, and is not case sensitive. To clear the filter, click **X**.
There are many ways to filter games. For example, you can type "Monkey Island" to locate all "Monkey Island" games on the list, or you can type "lang:de" to find German games. For a comprehensive look at how to use the search box, check out our :doc:`../advanced_topics/understand_search_box` guide.
The grouping menu
******************
.. _group:
To the right of the search box is the grouping menu. Use this menu to group games in alphabetical order, or by engine, series, publisher, language or platform. Hide or show groups of games by clicking on the black arrow to the left of each group heading.
.. figure:: ../images/Launcher/launcher_list_group.png
The grouping menu, with the Launcher in list view
The buttons
************************
To the right of the games list in list view, or above the games list in grid view, there are a number of buttons. Their functions are as follows:
Start (list view only)
^^^^^^^^^^^^^^^^^^^^^^^
Launches the highlighted game.
Load (list view only)
^^^^^^^^^^^^^^^^^^^^^
Opens the load game window, from which you can go to a saved game without having to start the game first.
See the :doc:`save_load_games` page.
Add Game
^^^^^^^^^^
Opens a file browser. To add a game, select a folder containing game files.
See the :doc:`add_play_games` page.
Game Options (list view only)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Opens the game settings window. This window also opens whenever a game is added to the games list in the Launcher.
Use this window to configure settings specific to a game. These settings override the global settings. For more information, see the :doc:`../use_scummvm/how_to_settings` page.
Remove Game
^^^^^^^^^^^^^
Removes the highlighted game from the list. This does not remove any saved games, so if you add a game to the games list again, you are able to resume where you left off.
Global Options
^^^^^^^^^^^^^^^^^^^^
Opens the global settings window. Use this window to define global game settings, as well as change a number of the ScummVM Launcher settings. For more information, see the :doc:`../use_scummvm/how_to_settings` page.
About
^^^^^^^^^^
Shows credits and miscellaneous information about ScummVM.
Quit
^^^^^^^
Closes the Launcher and quits the ScummVM application.
The Global Main Menu
=====================
You can access the ScummVM Global Main Menu, also known as the GMM, while you are playing a game. To open the GMM, press :kbd:`Ctrl+F5` (:kbd:`Ctrl+fn+F5` on a Mac).
.. figure:: ../images/Launcher/gmm.png
The Global Main Menu, or GMM.
The buttons
*****************
In the Global Main Menu there are a number of buttons. Their functions are as follows:
Resume
^^^^^^^^^^
Closes the GMM and resumes the game.
Load
^^^^^^
Opens the load game window. From here, you can load a saved game.
Save
^^^^^^
Opens the save game window. From here, you can save a game.
Options
^^^^^^^^
Opens a dialog which provides some gameplay options, such as sound volume, subtitle and keymap settings.
About
^^^^^^^^^^^
Displays the ScummVM **About** dialog. This is also available from the Launcher.
Help
^^^^^^
Displays a list of keyboard shortcuts for the game. Note that this is not available for all games; refer to the :doc:`../settings/keymaps` tab for keyboard shortcuts.
Return to Launcher
^^^^^^^^^^^^^^^^^^^^^
Quits the game and returns to the Launcher.
.. note::
This is not available for all games.
Quit
^^^^^^^
Quits the game and ScummVM, and returns to the operating system. Any unsaved game progress is lost.