======================= WEM TUTORIAL PAGE ONE =======================
Welcome to the WEM tutorial! A seven page guide to get you
acquainted with the WEM workflow and its capabilities.
The goal is to show the general workflow, how one can get started.
The following text assumes you've got an installable game that's
known to work, as well as "wem" itself installed somewhere on your
system $PATH. You should also have wine and winetricks installed,
preferably from your system package manager.
The example game we're working with is The Elder Scrolls III:
Morrowind. You can purchase a copy of that at the below URL:
https://www.gog.com/game/the_elder_scrolls_iii_morrowind_goty_edition
When you run commands, WEM will print various bits of information to
the log. Try to pay attention to this as it helps you follow along.
You may Ctrl-c at any time to quit.
Press q to continue...
======================= WEM TUTORIAL PAGE TWO =======================
Step One: init
You can "init" your env like this, with no specific configurations:
wem init tes3
Or like this, providing specific configurations:
wem init tes3 \
--gog-silent-install \
--install-exe "{{.InstallWorkDir}}/setup_tes_morrowind_goty_2.0.0.7.exe" \
--install-expected "{{.RunExe}}" \
--install-post "{{.WinetricksPath}} d3dcompiler_43 d3dcompiler_47 vcrun2010 d3dx9" \
--install-workdir $HOME/games \
--kron4ek-type staging-tkg-ntsync-amd64-wow64 \
--kron4ek-version 10.10 \
--quiet-run \
--run-exe "{{.RunWorkDir}}/Morrowind.exe" \
--run-workdir "{{.WinePrefix}}/drive_c/game" \
--virtualdesktop 1920x1080
When options are given to init like this, they are processed and
saved along with the configuration that's generated. The file
"$HOME/.config/wem/tes3.cfg" is created with the following configured
within:
* Pass the gog installer special arguments to make it quiet
* Set the executable to use for installation
* Values can be used inside of other values (e.g. {{.WinePrefix}})
* Environment variables will be expanded as well (e.g. $HOME)
* Nested variables work! See how --install-expected is used above.
* In the above example, "$HOME" works fine because your shell expands
it when you run WEM; it's not written to the config that way
* The file we expect to exist after the installation
* A command to run after installation (use winetricks to install
extra things so that MGE-XE and MWSE, engine extender and
modding/scripting tools, can work)
* The directory to be in when running the installer
* Install a specific package type for Kron4ek Wine
* Install a specific version of Kron4ek Wine
* Setting a type and version for Kron4ek will use that as the env's wine
executable
* If you don't enable a Kron4ek build, WEM will try to find a wine executable
in $PATH
* Stop wine from printing to stdout
* The exe to run the env with (argument to wine)
* The directory to be in when running the env executable
* Run the env with a "virtual desktop"
If no wine runner is selected, the wine executable is selected from $PATH. If
you don't have wine available, nothing will be set and you'll have to configure
something.
The wine prefix is automatically selected based on the global WEM configuration
value "WineEnvDir", which is located at "$HOME/.local/share/wem/envs" by
default.
Press q to continue...
====================== WEM TUTORIAL PAGE THREE ======================
Step Two: cfg
This step is optional, but you may configure your env after init like
this:
wem cfg tes3 --dxvk-version "2.0" --no-render --save
The "--no-render" argument is important if you're using template
variables, it prevents variables like "$HOME" and
"{{.WinetricksPath}}" from being expanded and saved that way back
into your env's cfg file.
The "--save" argument is required to save changes to your env config.
Saving writes a new config, including any changed values from CLI
argument values, to the env cfg file. If the "--no-render" argument
is ommited, rendered values will be saved instead of the ones with
variables.
The cfg file may also be edited with any text editor.
Press q to continue...
======================= WEM TUTORIAL PAGE FOUR ======================
Step Three: run - Install & Run
This step is skipped if no "InstallExe" and "InstallExpected" values
are set.
With those options, running the env for the first time will run the
configured "InstallExe":
wem run tes3
You may also explicitly run only the install step:
wem install tes3
Since I passed the "--quiet-wine" and "--gog-silent-install"
arguments to init, I won't get any output from wine or the game
installer, and the install path is going to be automatically set to
$WINEPREFIX/drive_c/game.
When the install process completes, the "InstallExpected" file will
be checked for. If it isn't found, a warning will be emitted.
If it is found, the install process will be skipped and the main run
executable will be ran.
If you configured a "RunExe" before installing, it will be ran after
the install process completes. If not, now's a good time to get that
setup.
Note that some applications will fail to run immediately following
installation, in this case it may suffice to re-run wem.
Press q to continue...
======================= WEM TUTORIAL PAGE FIVE ======================
Step Four: run - Just Run
Without anything to install, doing "wem run" will run the "RunExe":
wem run tes3
This will run the game or application as configured. Great Job!
Press q to continue...
======================= WEM TUTORIAL PAGE SIX =======================
Step Five: Sandboxing
If the "firejail" executable is available on your system, you can use
"--sandbox" and related run options to enable extra sandboxing for
your process. See the manpage or your cfg file for all available
options.
wem cfg tes3 | grep Sandbox
wem run tes3 --sandbox
The individual options are useful for when a game doesn't work with
all features (or you just don't want them all):
wem run tes3 --sandbox --no-sandbox-private-cwd
Please note that it is not uncommon for some games and/or mods to not
work properly with sandboxing. If you have issues, try disabling the
sandbox.
Press q to continue...
======================= WEM TUTORIAL PAGE SEVEN ======================
Step Six: run - Choosing A Wine Runner
A "wine runner" typically refers to a pre-packaged build of wine that's more or
less immediately usable after being extracted.
You can choose one of two wine runners with WEM:
*Kron4ek Wine Builds*
https://github.com/Kron4ek/Wine-Builds
Custom wine builds that come in a variety of different types, including:
staging-amd64
staging-amd64-wow64
staging-tkg-amd64
staging-tkg-ntsync-amd64-wow64
staging-x86
amd64
amd64-wow64
staging-tkg-amd64-wow64
staging-tkg-x86
In order to use it, set the "Kron4ekType" and "Kron4ekVersion" options in your
env's cfg file, you can find valid versions at the below link, each version
lists available types:
https://github.com/Kron4ek/Wine-Builds/releases
*umu-launcher*
https://github.com/Open-Wine-Components/umu-launcher
umu-launcher is a tool that enables using Valve's Proton and related
tooling/runtimes outside of Steam.
In order to use it, simply set the "UmuVersion" option in your env's cfg file,
you can find valid versions at the below link:
https://github.com/Open-Wine-Components/umu-launcher/releases
To use umu-launcher as a wine runner:
1. In an env's cfg file, set "UmuVersion" to the version of umu-launcher that
you wish to use (see the releases link above to find valid version options).
Press q to continue...
======================= WEM TUTORIAL PAGE EIGHT =====================
Step Seven: Check An Env
You can use the check command to validate some of the options in an env:
wem check tes3
This will check if configured files and directories exist and/or are
accessible. You can also use the --versions argument to check your configured
versions of DXVK, Kron4ek Wine, umu-launcher, and VKD3D-Proton:
wem check tes3 --versions
Press q to continue...
======================= WEM TUTORIAL PAGE NINE =====================
Step Eight: Extras
WEM supports a few other things:
* Install DXVK and VKD3D from GitHub releases. To list versions:
wem list --dxvk --vkd3d
To install, configure a listed version and run the env.
* List installed things:
wem list --dxvk --env --vkd3d --installed
* Build wine from source:
wem build wine-6.6 --staging
The version argument should be a valid git tag from the wine git
repository.
For more information about configuring and using WEM, please consult
the online documentation at:
https://wem.hristos.co/
Thank you for reading!
Press q to finish...