2013-05-25 05:48:03 +00:00
|
|
|
==================
|
|
|
|
Writing installers
|
|
|
|
==================
|
|
|
|
|
2013-06-09 22:00:52 +00:00
|
|
|
Fetching required files
|
|
|
|
=======================
|
|
|
|
|
2013-06-17 22:05:32 +00:00
|
|
|
The ``files`` section of the installer references every file needed for
|
2014-01-24 12:05:24 +00:00
|
|
|
installing the game. This section's keys are unique identifier used later in
|
|
|
|
the ``installer`` section. The value can either be a string containing a URI
|
|
|
|
pointing at the required file or a dictionary containing the ``filename`` and
|
2015-04-30 21:37:12 +00:00
|
|
|
``url`` keys. The ``url`` key is equivalent to passing only a string to the
|
2014-01-24 12:05:24 +00:00
|
|
|
installer and the ``filename`` key will be used to give the local copy another
|
2014-03-15 21:02:17 +00:00
|
|
|
name. [TODO: example]
|
2013-06-09 22:00:52 +00:00
|
|
|
|
2013-06-17 22:05:32 +00:00
|
|
|
If the game contains copyrighted files that cannot be redistributed, the value
|
2013-07-11 16:15:32 +00:00
|
|
|
should begin with ``N/A``. When the installer encounter this value, it will
|
|
|
|
prompt the user for the location of the file. To indicate to the user what file
|
2014-02-09 13:39:39 +00:00
|
|
|
to select, append a message to ``N/A`` like this:
|
|
|
|
``N/A:Please select the installer for this game``
|
2013-07-11 16:15:32 +00:00
|
|
|
|
2014-03-15 21:02:17 +00:00
|
|
|
Examples:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
files:
|
|
|
|
- file1: http://site.com/gamesetup.exe
|
|
|
|
- file2: "N/A:Select the game's setup file"
|
|
|
|
|
2013-06-09 22:00:52 +00:00
|
|
|
|
2013-06-17 22:05:32 +00:00
|
|
|
If the game makes use of (Windows) Steam data, the value should be
|
2014-02-09 13:39:39 +00:00
|
|
|
``$WINESTEAM:appid:path/to/data``. This will check that the data is available
|
2013-06-09 22:00:52 +00:00
|
|
|
or install it otherwise.
|
|
|
|
|
2014-01-24 12:05:24 +00:00
|
|
|
|
2013-06-18 00:13:03 +00:00
|
|
|
Installer meta data
|
|
|
|
===================
|
|
|
|
|
2014-01-24 12:05:24 +00:00
|
|
|
Referencing the main file
|
|
|
|
---------------------------
|
|
|
|
|
|
|
|
For Linux and Wine games, specify the executable file with the ``exe``
|
2014-03-15 22:26:22 +00:00
|
|
|
directive. The given path is relative to the game directory.
|
|
|
|
Example: ``exe: game.sh``
|
2014-01-24 12:05:24 +00:00
|
|
|
|
|
|
|
For emulator games, in case you don't ask the user to select the rom
|
|
|
|
directly but make the installer extract it from an archive or something, you
|
2014-03-15 21:02:17 +00:00
|
|
|
can reference the rom with the ``main_file`` parameter.
|
2014-03-15 22:26:22 +00:00
|
|
|
Example: ``main_file: game.rom``
|
2014-01-24 12:05:24 +00:00
|
|
|
|
2014-03-15 21:02:17 +00:00
|
|
|
For browser games, specify the game's URL with ``main_file``.
|
2014-03-15 22:26:22 +00:00
|
|
|
Example: ``main_file: http://www...``
|
2014-03-15 21:02:17 +00:00
|
|
|
|
|
|
|
Presetting game parameters
|
|
|
|
--------------------------
|
|
|
|
|
|
|
|
The ``game`` directive lets you preset game parameters and options. Available
|
|
|
|
parameters depend on the runner:
|
|
|
|
|
2014-09-18 16:20:43 +00:00
|
|
|
* linux: ``args`` (optional command arguments), ``working_dir``
|
|
|
|
(optional working directory, defaults to the exe's dir).
|
2014-03-15 21:02:17 +00:00
|
|
|
|
2014-09-18 16:20:43 +00:00
|
|
|
* wine: ``args``, ``prefix`` (optional Wine prefix), ``working_dir`` (optional
|
|
|
|
working directory, defaults to the exe's dir).
|
2014-03-15 21:02:17 +00:00
|
|
|
|
2014-09-18 16:20:43 +00:00
|
|
|
* winesteam: ``args``, ``prefix`` (optional Wine prefix).
|
2014-08-21 18:05:12 +00:00
|
|
|
|
|
|
|
[TODO: reference all options] Meanwhile, you can check the configuration window
|
|
|
|
of any game using the runner you're writing for to get a list of the available
|
|
|
|
options.
|
2014-03-15 21:02:17 +00:00
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
game:
|
|
|
|
exe: drive_c/Game/game.exe
|
|
|
|
prefix: $GAMEDIR
|
|
|
|
args: -arg
|
2013-06-18 00:13:03 +00:00
|
|
|
|
2014-03-15 21:02:17 +00:00
|
|
|
Mods and add-ons
|
|
|
|
----------------
|
|
|
|
|
|
|
|
Mods and add-ons require that a base game is already installed on the system.
|
2014-01-24 12:05:24 +00:00
|
|
|
You can let the installer know that you want to install an add-on by specifying
|
2013-06-28 10:15:37 +00:00
|
|
|
the ``requires`` directive. The value of ``requires`` must be the canonical
|
2014-03-15 21:02:17 +00:00
|
|
|
slug name of the base game, not one of its aliases. For example, to install the
|
|
|
|
add-on "The reckoning" for Quake 2, you should add:
|
2013-06-18 00:13:03 +00:00
|
|
|
|
|
|
|
``requires: quake-2``
|
|
|
|
|
2014-01-24 12:05:24 +00:00
|
|
|
|
2013-06-17 22:05:32 +00:00
|
|
|
Writing the installation script
|
|
|
|
===============================
|
|
|
|
|
2014-01-24 12:05:24 +00:00
|
|
|
After every file needed by the game has been aquired, the actual installation
|
2013-06-17 22:05:32 +00:00
|
|
|
can take place. A series of directives will tell the installer how to set up
|
2014-03-15 21:02:17 +00:00
|
|
|
the game correctly. Start the installer section with ``installer:`` then stack
|
|
|
|
the directives by order of execution (top to bottom).
|
2013-05-25 05:48:03 +00:00
|
|
|
|
2013-05-25 11:08:39 +00:00
|
|
|
Displaying an 'Insert disc' dialog
|
|
|
|
----------------------------------
|
|
|
|
|
2013-05-26 16:43:42 +00:00
|
|
|
The ``insert-disc`` command will display a message box to the user requesting
|
2014-03-15 21:02:17 +00:00
|
|
|
him to insert the game's disc into the optical drive.
|
|
|
|
|
|
|
|
Ensure a correct disc detection by specifying a file or folder present on the
|
|
|
|
disc with the ``requires`` parameter.
|
|
|
|
|
2014-10-25 13:56:22 +00:00
|
|
|
The $DISC variable will contain the drive's path for use in subsequent
|
|
|
|
installer tasks.
|
|
|
|
|
2014-03-15 22:26:22 +00:00
|
|
|
A link to CDEmu's homepage and PPA will also be displayed if the program isn't
|
2014-03-15 21:02:17 +00:00
|
|
|
detected on the machine, otherwise it will be replaced with a button to open
|
|
|
|
gCDEmu. You can override this default text with the ``message`` parameter.
|
|
|
|
|
|
|
|
Example:
|
2013-05-25 11:08:39 +00:00
|
|
|
|
2014-03-15 21:02:17 +00:00
|
|
|
::
|
|
|
|
|
|
|
|
- insert-disc:
|
|
|
|
requires: diablosetup.exe
|
2013-05-25 11:08:39 +00:00
|
|
|
|
2013-06-17 22:05:32 +00:00
|
|
|
Moving files and directories
|
|
|
|
----------------------------
|
2013-05-25 05:48:03 +00:00
|
|
|
|
2014-11-24 15:44:00 +00:00
|
|
|
Move files or directories by using the ``move`` command. ``move`` requires
|
|
|
|
two parameters: ``src`` (the source file or folder) and ``dst`` (the
|
|
|
|
destination folder).
|
2013-05-25 05:48:03 +00:00
|
|
|
|
2014-11-24 15:44:00 +00:00
|
|
|
The ``src`` parameter can either be a ``file ID`` or a path relative to game
|
2014-02-09 11:29:27 +00:00
|
|
|
dir. If the parameter value is not found in the list of file ids,
|
2014-01-24 12:05:24 +00:00
|
|
|
then it must be prefixed by either ``$CACHE`` or ``$GAMEDIR`` to move a file or
|
|
|
|
directory from the download cache or the game's install dir, respectively.
|
2013-05-25 05:48:03 +00:00
|
|
|
|
2013-05-26 16:43:42 +00:00
|
|
|
The ``dst`` parameter should be prefixed by either ``$GAMEDIR`` or ``$HOME``
|
|
|
|
to move files to path relative to the game dir or the current user's home
|
2014-11-24 15:44:00 +00:00
|
|
|
|
|
|
|
If the source is a ``file ID``, it will be updated with the new destination
|
|
|
|
path. It can then be used in following commands to access the moved file.
|
2013-05-25 05:48:03 +00:00
|
|
|
|
|
|
|
The ``move`` command cannot overwrite files.
|
2013-05-26 16:43:42 +00:00
|
|
|
|
2013-06-28 10:15:37 +00:00
|
|
|
Example:
|
|
|
|
|
|
|
|
::
|
2013-07-11 16:15:32 +00:00
|
|
|
|
2014-03-15 21:02:17 +00:00
|
|
|
- move:
|
2015-04-29 22:07:16 +00:00
|
|
|
src: $game-file-id
|
2014-03-15 21:02:17 +00:00
|
|
|
dst: $GAMEDIR/location
|
2013-07-11 16:15:32 +00:00
|
|
|
|
2013-06-17 22:05:32 +00:00
|
|
|
Copying and merging directories
|
|
|
|
-------------------------------
|
|
|
|
|
2013-06-28 10:15:37 +00:00
|
|
|
Both merging and copying actions are done with the ``merge`` directive.
|
2014-01-24 12:05:24 +00:00
|
|
|
Whether the action does a merge or copy depends on the existence of the
|
2013-06-28 10:15:37 +00:00
|
|
|
destination directory. When merging into an existing directory, original files
|
2014-01-24 12:05:24 +00:00
|
|
|
with the same name as the ones present in the merged directory will be
|
|
|
|
overwritten. Take this into account when writing your script and order your
|
|
|
|
actions accordingly.
|
2013-06-17 22:05:32 +00:00
|
|
|
|
2014-11-24 15:44:00 +00:00
|
|
|
If the source is a ``file ID``, it will be updated with the new destination
|
|
|
|
path. It can then be used in following commands to access the copied file.
|
|
|
|
|
2013-06-28 10:15:37 +00:00
|
|
|
Example:
|
|
|
|
|
|
|
|
::
|
2013-07-11 16:15:32 +00:00
|
|
|
|
2014-03-15 21:02:17 +00:00
|
|
|
- merge:
|
2015-04-29 22:07:16 +00:00
|
|
|
src: $game-file-id
|
2014-03-15 21:02:17 +00:00
|
|
|
dst: $GAMEDIR/location
|
2013-06-28 10:15:37 +00:00
|
|
|
|
2013-06-17 22:05:32 +00:00
|
|
|
Extracting archives
|
|
|
|
-------------------
|
2013-05-26 16:43:42 +00:00
|
|
|
|
2013-06-28 10:15:37 +00:00
|
|
|
Extracting archives is done with the ``extract`` directive, the ``file``
|
2015-04-29 22:03:46 +00:00
|
|
|
argument is a ``file id`` or a file path. If the archive should be extracted
|
|
|
|
in some other location than the ``$GAMEDIR``, you can specify a ``dst``
|
|
|
|
argument.
|
2013-06-28 10:15:37 +00:00
|
|
|
|
2014-03-15 22:26:22 +00:00
|
|
|
You can optionally specify the archive's type with the ``format`` option.
|
2014-02-09 11:29:27 +00:00
|
|
|
This is useful if the archive's file extension does not match what it should
|
|
|
|
be. Accepted values for ``format`` are: zip, tgz, gzip and bz2.
|
|
|
|
|
2013-07-11 16:15:32 +00:00
|
|
|
Example:
|
2013-06-28 10:15:37 +00:00
|
|
|
|
|
|
|
::
|
|
|
|
|
2014-03-15 21:02:17 +00:00
|
|
|
- extract:
|
2015-04-29 22:07:16 +00:00
|
|
|
file: $game-archive
|
2014-03-15 21:02:17 +00:00
|
|
|
dst: $GAMEDIR/datadir/
|
2013-06-28 10:15:37 +00:00
|
|
|
|
|
|
|
Making a file executable
|
|
|
|
------------------------
|
|
|
|
|
|
|
|
Marking the file as executable is done with the ``chmodx`` command. It is often
|
2014-03-15 21:02:17 +00:00
|
|
|
needed for games that ship in a zip file, which does not retain file
|
|
|
|
permissions.
|
2013-06-28 10:15:37 +00:00
|
|
|
|
2014-03-15 21:02:17 +00:00
|
|
|
Example: ``- chmodx: $GAMEDIR/game_binary``
|
2013-06-28 10:15:37 +00:00
|
|
|
|
2014-01-24 12:05:24 +00:00
|
|
|
Executing a file
|
|
|
|
----------------
|
|
|
|
|
2015-05-04 21:58:47 +00:00
|
|
|
Execute files with the ``execute`` directive. Use the ``file`` parameter to
|
|
|
|
reference a ``file id`` or a path, ``args`` to add command arguments,
|
|
|
|
``terminal`` (set to "true") to execute in a new terminal window.
|
|
|
|
The command is executed within the Lutris Runtime (resolving most shared
|
|
|
|
library dependencies).
|
2014-01-24 12:05:24 +00:00
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
2014-03-15 21:02:17 +00:00
|
|
|
- execute:
|
2014-09-18 16:20:43 +00:00
|
|
|
args: --argh
|
2015-04-29 22:07:16 +00:00
|
|
|
file: $great-id
|
2015-05-04 21:58:47 +00:00
|
|
|
terminal: true
|
2014-01-24 12:05:24 +00:00
|
|
|
|
2014-10-19 00:11:34 +00:00
|
|
|
Writing into an INI type config file
|
|
|
|
------------------------------------
|
|
|
|
|
2014-11-11 18:26:47 +00:00
|
|
|
Modify or create a config file with the ``write_config`` directive. A config file
|
2014-10-19 00:11:34 +00:00
|
|
|
is a text file composed of key=value (or key: value) lines grouped under
|
|
|
|
[sections]. Use the ``file`` (an absolute path or a ``file id``), ``section``,
|
|
|
|
``key`` and ``value`` parameters. Not that the file is entirely rewritten and
|
|
|
|
comments are left out; Make sure to compare the initial and resulting file
|
|
|
|
to spot any potential parsing issues.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
2015-03-19 10:27:53 +00:00
|
|
|
- write_config:
|
2014-10-19 00:11:34 +00:00
|
|
|
file: $GAMEDIR/game.ini
|
|
|
|
section: Engine
|
|
|
|
key: Renderer
|
|
|
|
value: OpenGL
|
|
|
|
|
|
|
|
|
2013-07-11 16:15:32 +00:00
|
|
|
Running a task provided by a runner
|
|
|
|
-----------------------------------
|
|
|
|
|
2014-02-09 11:29:27 +00:00
|
|
|
Some actions are specific to some runners, you can call them with the ``task``
|
2013-07-11 16:15:32 +00:00
|
|
|
command. You must at least provide the ``name`` parameter which is the function
|
2014-10-19 12:39:33 +00:00
|
|
|
that will be called. Other parameters depend on the task being called. It is
|
|
|
|
possible to call functions from other runners by prefixing the task name with
|
|
|
|
the runner's name (e.g., from a dosbox installer you can use the wineexec task
|
|
|
|
with ``wine.wineexec`` as the task's ``name``)
|
2013-07-11 16:15:32 +00:00
|
|
|
|
|
|
|
Currently, the following tasks are implemented:
|
|
|
|
|
2015-03-19 10:27:53 +00:00
|
|
|
* wine / winesteam: ``create_prefix`` Creates an empty Wine prefix at the
|
|
|
|
specified path. The other wine/winesteam directives below include the
|
|
|
|
creation of the prefix, so in most cases you won't need to use the
|
|
|
|
create_prefix command. Parameters are ``prefix`` (the path), ``arch``
|
|
|
|
(optional architecture of the prefix, default: win32).
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
- task:
|
|
|
|
name: create_prefix
|
|
|
|
prefix: $GAMEDIR
|
|
|
|
arch: win64
|
|
|
|
|
2014-09-18 16:20:43 +00:00
|
|
|
* wine / winesteam: ``wineexec`` Runs a windows executable. Parameters are
|
2015-03-19 10:27:53 +00:00
|
|
|
``executable`` (``file ID`` or path), ``args`` (optional arguments passed
|
|
|
|
to the executable), ``prefix`` (optional WINEPREFIX),
|
|
|
|
``working_dir`` (optional working directory).
|
2014-03-15 21:02:17 +00:00
|
|
|
|
2014-09-18 16:20:43 +00:00
|
|
|
Example:
|
2014-03-15 21:02:17 +00:00
|
|
|
|
2014-09-18 16:20:43 +00:00
|
|
|
::
|
2014-03-15 21:02:17 +00:00
|
|
|
|
2014-09-18 16:20:43 +00:00
|
|
|
- task:
|
|
|
|
name: wineexec
|
|
|
|
prefix: $GAMEDIR
|
|
|
|
executable: drive_c/Program Files/Game/Game.exe
|
|
|
|
args: --windowed
|
2014-03-15 22:26:22 +00:00
|
|
|
|
2014-09-18 16:20:43 +00:00
|
|
|
* wine / winesteam: ``winetricks`` Runs winetricks with the ``app`` argument.
|
|
|
|
``prefix`` is an optional WINEPREFIX path.
|
2014-03-15 21:02:17 +00:00
|
|
|
|
2014-09-18 16:20:43 +00:00
|
|
|
Example:
|
2014-03-15 21:02:17 +00:00
|
|
|
|
2014-09-18 16:20:43 +00:00
|
|
|
::
|
2014-03-15 21:02:17 +00:00
|
|
|
|
2014-09-18 16:20:43 +00:00
|
|
|
- task:
|
|
|
|
name: winetricks
|
|
|
|
prefix: $GAMEDIR
|
|
|
|
app: nt40
|
2014-03-15 21:02:17 +00:00
|
|
|
|
2014-09-18 16:20:43 +00:00
|
|
|
* wine / winesteam: ``set_regedit`` Modifies the Windows registry. Parameters
|
2014-10-09 14:14:15 +00:00
|
|
|
are ``path`` (the registry path, use backslashes), ``key``, ``value``,
|
|
|
|
``type`` (optional value type, default is REG_SZ (string)), ``prefix``
|
|
|
|
(optional WINEPREFIX).
|
2014-03-15 21:02:17 +00:00
|
|
|
|
2014-09-18 16:20:43 +00:00
|
|
|
Example:
|
2014-03-15 21:02:17 +00:00
|
|
|
|
2014-09-18 16:20:43 +00:00
|
|
|
::
|
2013-07-11 16:15:32 +00:00
|
|
|
|
2014-09-18 16:20:43 +00:00
|
|
|
- task:
|
|
|
|
name: set_regedit
|
|
|
|
prefix: $GAMEDIR
|
2014-10-09 14:14:15 +00:00
|
|
|
path: HKEY_CURRENT_USER\Software\Valve\Steam
|
|
|
|
key: SuppressAutoRun
|
|
|
|
value: 00000000
|
|
|
|
type: REG_DWORD
|
2013-07-11 16:15:32 +00:00
|
|
|
|
2015-02-05 23:48:45 +00:00
|
|
|
* wine / winesteam: ``set_regedit_file`` Apply a regedit file to the
|
|
|
|
registry
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
- task:
|
|
|
|
name: set_regedit_file
|
|
|
|
prefix: $GAMEDIR
|
|
|
|
filename: myregfile
|
2013-05-26 16:43:42 +00:00
|
|
|
|
2015-03-21 11:12:01 +00:00
|
|
|
* dosbox: ``dosexec`` Runs dosbox. Parameters are ``executable`` (optional
|
|
|
|
``file ID`` or path to executable), ``config_file``
|
|
|
|
(optional ``file ID`` or path to .conf file), ``args`` (optional command
|
|
|
|
arguments), ``working_dir`` (optional working directory, defaults to the
|
|
|
|
``executable``'s dir or the ``config_file``'s dir), ``exit`` (set to
|
|
|
|
``false`` to prevent DOSBox to exit when the ``executable`` is terminated).
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
- task:
|
|
|
|
name: dosexec
|
2015-04-29 22:07:16 +00:00
|
|
|
executable: $file_id
|
2015-03-21 11:12:01 +00:00
|
|
|
config: $GAMEDIR/game_install.conf
|
|
|
|
args: -scaler normal3x -conf more_conf.conf
|
|
|
|
|
2015-02-07 18:36:30 +00:00
|
|
|
Displaying a drop-down menu with options
|
|
|
|
----------------------------------------
|
|
|
|
|
|
|
|
Request input from the user by displaying a menu filled with options to choose
|
|
|
|
from with the ``input_menu`` directive.
|
|
|
|
The ``description`` parameter holds the message to the user, ``options`` is an
|
|
|
|
indented list of ``value: label`` lines where "value" is the text that will be
|
2015-02-07 23:09:50 +00:00
|
|
|
stored and "label" is the text displayed, and the optional ``preselect``
|
2015-02-07 18:36:30 +00:00
|
|
|
parameter is the value to preselect for the user.
|
|
|
|
|
|
|
|
The result of the last input directive is available with the ``$INPUT`` alias.
|
|
|
|
If need be, you can add an ``id`` parameter to the directive which will make the
|
|
|
|
selected value available with ``$INPUT_<id>`` with "<id>" obviously being the
|
|
|
|
id you specified. The id must contain only numbers, letters and underscores.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
- input_menu:
|
|
|
|
description: Choose the game's language:
|
|
|
|
id: LANG
|
|
|
|
options:
|
|
|
|
- en: English
|
|
|
|
- bf: Brainfuck
|
|
|
|
- "value and": "label can be anything, surround them with quotes to avoid issues"
|
2015-08-29 08:57:04 +00:00
|
|
|
preselect: bf
|
2015-02-07 18:36:30 +00:00
|
|
|
|
|
|
|
In this example, English would be preselected. If the option eventually
|
|
|
|
selected is Brainfuck, the "$INPUT_LANG" alias would be available in
|
|
|
|
following directives and would correspond to "bf". "$INPUT" would work as well,
|
|
|
|
up until the next input directive.
|
|
|
|
|
|
|
|
|
2014-01-24 12:05:24 +00:00
|
|
|
Trying the installer locally
|
|
|
|
============================
|
|
|
|
|
|
|
|
If needed (i.e. you didn't download the installer first from the website), add
|
|
|
|
the ``runner`` and ``name`` directives. The value for ``runner`` must be the
|
|
|
|
slug name for the runner. (E.g. winesteam for Steam Windows.)
|
|
|
|
Save your script in a file and use the following command in a terminal:
|
|
|
|
``lutris -i /path/to/file``
|
|
|
|
|
|
|
|
|
|
|
|
Calling the online installer
|
|
|
|
============================
|
2013-05-26 16:43:42 +00:00
|
|
|
|
2014-01-24 12:05:24 +00:00
|
|
|
The installer can be called with the ``lutris:<game-slug>`` url scheme.
|