Running xoreos

First, you need to fully install and/or copy the game you want to play with xoreos onto your hard disk. How you do this depends on the game, your operating system and where/how you have bought the game.

xoreos does not yet have a launcher GUI or anything like this. You need to start it from the command line. Run xoreos with the command line option "--help" (without the quotes) to get a help text about further command line options.

The quickest way to start a game in path /path/to/game/ would be to call

xoreos -p/path/to/game/

If you're on Windows and the path is, say, D:\Path\To\Game\, call

xoreos -pD:\Path\To\Game\

Config file

In general, xoreos can read the configuration which game to run from either the command line, a config file or both. Additionally, when you first specify a new game on the command line, xoreos will add a related entry in the config file (creating it first, if necessary).

To accurately identify a specific instance of an installed game, xoreos uses the concept of a "target". Each target has a separate section in the config file, and each of their options apply only to that target. The special target "xoreos" is a global section applying to all games, although the same option in a game target overrides the global option.

The format of the config file is also relatively simple: It's in essence an INI file. Targets are enclosed in [] and options are assigned values with a =. Comments can begin with either a ";" or a "#" and run to the end of the line. When changing the file, xoreos will try to preserve all comments it encounters, so you don't need to fear about losing them.

For example:

# This is an example for a xoreos.conf file, where xoreos reads and
# saves game configuration options. xoreos expects this file in the
# user conf directory, whose location depends on the operating
# system.
#
# - On GNU/Linux, the place is $XDG_CONFIG_HOME/xoreos/xoreos.conf.
#   $XDG_CONFIG_HOME defaults to $HOME/.config/
# - On Mac OS X, the place is $HOME/Library/Preferences/xoreos/xoreos.conf
# - On Windows, xoreos.conf is in the subdirectory xoreos in either
#   $APPDATA or $USERPROFILE, depending on your Windows version
#
# You can also specify a different xoreos.conf with the command line
# option -c/--config.
#
# If the xoreos.conf does not exist, xoreos will create one with
# default values on the first successful game start.
#
# The encoding of this file *must* be UTF-8.
#
# When a setting is changed using the in-game menus, like the options
# menu in Neverwinter Nights, xoreos will save the changes back to the
# config file on exit, inside the section for the current game.
# Settings given on the command line are not saved back. When xoreos
# saves the config file, all unchanged settings and all comments in it
# will be preserved.
#
# The "xoreos" section is used for global configuration; the other
# sections are targets, entries to describe games. If the same setting
# exists in the global section and in the section for the current
# game, the setting in the game section overrides the global setting.
#
# The name of the game section is not used for game identification.
# As such, the name is arbitrary and up to the user. There are
# restrictions on the name, though: only these characters are allowed:
# [-_. A-Za-z0-9], i.e. alphanumerical characters plus hyphen,
# underscore, full stop and space. All section names have to be
# unique, too. Since the section name "xoreos" is already used for
# global options, it is not a valid game section name.
#
# The section names can be used to start xoreos with. This example
# file has a section called "nwn"; to start xoreos with that game, and
# automatically apply the settings in that "nwn" section (in addition
# to the global options), start xoreos with "nwn" as a command line
# option. Like so:
#
# xoreos nwn
#
# All setting keys are also valid command line options for xoreos, and
# vice versa. For example, you can start xoreos thusly:
#
# xoreos --width=800 --height=600 nwn
#
# This will start xoreos with Neverwinter Nights, with a window of
# size 800x600. These two added settings will not be saved to the
# config file. But if you then change the resolution in the options
# menu of Neverwinter Nights, xoreos will add width and height to the
# "nwn" section, with the values you selected inside the game.
#
# Moreover, if a give an option on the command line that already
# exists in the game section, it will override the setting in the game
# section, but only for this session. It will not save back to the
# config file. For example
#
# xoreos --largefonts=false nwn
#
# Will start Neverwinter Nights in xoreos with the small in-game
# conversation font, but this setting will not be remembered for the
# next time.

# Global options
[xoreos]
# These are default settings that can be overridden by the targets.

# Window size.
width=1024
height=768

# Window positioning. Forces the game window to appear at these
# coordinates. When x and/or y are not specified, the placement of
# the window is left to your operating system.
x=0
y=0

# Fullscreen or windowed mode.
fullscreen=false

# Fullscreen anti-aliasing.
fsaa=4

# If set to false, a changed configuration will not be saved back.
# By default, changes are saved.
saveconf=true

# The xoreos log file will be written here. By default, the log
# will be written into a file located in the OS-specific user
# data directory.
logfile=/home/drmccoy/xoreos.log
# If set to true, no log file will be written at all. The default
# is to write a log file.
nologfile=false

# A log of the debug console will be written here.
consolelog=/home/drmccoy/xoreos-console.log
# If set to true, no console log will be written at all. The default
# is to write a console log.
noconsolelog=false

# Show a frames-per-second counter in the top left corner.
showfps=true

# Volume options.
volume=1.000000        # Master volume.
volume_music=0.500000  # Music.
volume_sfx=0.850000    # Sound effects.
volume_voice=0.850000  # Voices.
volume_video=0.850000  # Sound from the videos.

# Don't show any videos at all.
skipvideos=false

# Neverwinter Nights
[nwn]
# The path where to find the game. Both / and \ are valid as
# directory separators. Relative paths are supported. ~/ at the
# start of the path string will be replaced with the user's home
# directory. All targets need to have a path, the rest is
# optional.
path=/home/drmccoy/games/nwn/

# A description of the game. Will appear in the window title and a
# potential future xoreos GUI. If left out, a default description
# containing the game name (in English) plus the detected platform
# of the game will be used.
# For example "Neverwinter Nights (GNU/Linux)".
description=Neverwinter Nights (English)

# The language of the game. Most of the supported games can only
# be installed in one language at the same time. There, specifying
# the language of the game is optional, and will be autodetected
# anyway. A wide variety of strings are recognized here, including
# the English name of a language and country, the name of the
# language and country in the language in question, the ISO 693-1,
# 693-2 and 693-3 language codes, the ISO 3166-2 country codes and
# the usual combinations of ISO 693 and ISO 3166 ("de_DE", ...).
lang=English

# Override these options for Neverwinter Nights.
fullscreen=true
fsaa=8

# Options specific to Neverwinter Nights:

# Which texture pack to use. From 0 (very low) to 3 (highest).
texturepack=3

# The amount of time in ms until a tooltip appears.
tooltipdelay=100

# Use the large in-game conversation font.
largefonts=true

# Game difficulty. From 0 (Easy) to 3 (Very Difficult).
difficulty=0 # Easy

# Show mouse-over feedback. If set to true, a creature's health
# will be displayed in its feedback bubble.
# This option is not yet evaluated by xoreos.
mouseoverfeedback=false
# How the feedback bubble should look.
# 0: Off
# 1: Text only
# 2: Text and portrait
feedbackmode=2

# Neverwinter Nights 2
[nwn2]
# The ~/ will be replaced with the user's home directory.
# For a user with the name of "drmccoy", this will be:
# - On GNU/Linux, $HOME (usually /home/drmccoy/)
# - On Mac OS X, $HOME (usually /Users/drmccoy/)
# - On Windows, %USERPROFILE%
path=~/games/nwn2/

# Options specific to Neverwinter Nights 2:

# This is a debug option to disable the tinting of meshes.
# Currently, we're tinting the meshes on the CPU, which is slow and
# eats a lot of RAM, both on the GPU and the system. This will
# change in the future.
tint=false

# Knights of the Old Republic
[kotor]
# An example of a path on Windows, with forward slashes.
path=C:/games/kotor/

# The Witcher
[witcher]
# An example of a path on Windows, with backward slashes.
path=C:\games\witcher\

# This whole file, including user-visible strings and paths, has
# to be encoded as UTF-8.
description=The Witcher (Wiedźmin)

# The Witcher has separate language settings for text and voice.
# Only setting the option "lang" will set both text and voice, but
# both "langtext" and "langvoice" will override this setting for
# text or voice, respectively.
langtext=English
langvoice=German

You can then start the game with the target "nwn" with

xoreos nwn

and xoreos will do the rest. This will start the game in the path /home/drmccoy/games/nwn/, running it in fullscreen at 1024x768.

As you can see with the volume options, xoreos also saves settings you made in the game' actual GUI into the target's section of the config file.

Command line parameters

xoreos - A reimplementation of BioWare's Aurora engine
Usage: xoreos [options] [target]

          --help              Display this text and exit.
          --version           Display version information and exit.
  -cFILE  --config=FILE       Load the config from file FILE.
  -pDIR   --path=DIR          Override the game path with DIR.
  -wSIZE  --width=SIZE        Set the window's width to SIZE.
  -hSIZE  --height=SIZE       Set the window's height to SIZE.
  -fBOOL  --fullscreen=BOOL   Switch fullscreen on/off.
  -kBOOL  --skipvideos=BOOL   Disable videos on/off.
  -vVOL   --volume=VOL        Set global volume to VOL.
  -mVOL   --volume_music=VOL  Set music volume to VOL.
  -sVOL   --volume_sfx=VOL    Set SFX volume to VOL.
  -oVOL   --volume_voice=VOL  Set voice volume to VOL.
  -iVOL   --volume_video=VOL  Set video volume to VOL.
  -qLANG  --lang=LANG         Set the game's language.
          --langtext=LANG     Set the game's text language.
          --langvoice=LANG    Set the game's voice language.
  -dLVL   --debuglevel=LVL    Set the debug level to LVL.
          --debugchannel=CHAN Set the enabled debug channel(s) to CHAN.
          --listdebug         List all available debug channels.
          --listlangs         List all available languages for this target.
          --logfile=FILE      Write all debug output into this file too.
          --nologfile=BOOL    Don't write a log file.
          --consolelog=FILE   Write all debug console output into this file too.
          --noconsolelog=BOOL Don't write a debug console log file.

FILE: Absolute or relative path to a file.
DIR:  Absolute or relative path to a directory.
SIZE: A positive integer.
BOOL: "true", "yes", "y", "on" and "1" are true, everything else is false.
VOL:  A double ranging from 0.0 (min) - 1.0 (max).
LANG: A language identifier. Full name, ISO 639-1 or ISO 639-2 language code;
      or IETF language tag with ISO 639-1 and ISO 3166-1 country code.
      Examples: en, de_de, hun, Czech, zh-tw, zh_cn, zh-cht, zh-chs.
LVL:  A positive integer.
CHAN: A comma-separated list of debug channels.
      Use "All" to enable all debug channels.

Examples:
xoreos -p/path/to/nwn/
  xoreos will start the game in /path/to/nwn/. Should a target with this
  path not yet exist in the config file, xoreos will create one named "nwn".
xoreos -p/path/to/nwn/ foobar
  xoreos will start the game in /path/to/nwn/. If a target "foobar"
  does not yet exist in the config file, xoreos will create it.
xoreos nwn
  xoreos will start the game specified by target "nwn", which must exit
  in the config file already.

Long-form command line option, like --skipvideos, map directly to config options. Options given on the command line will override any options found in the config file for this session, but will not save back to that config file.

Common hotkeys

Hotkey	Effect
Ctrl+Q Apple+Q	Quit
Alt+Enter	Toggle fullscreen
Alt+S	Take a screenshot
Ctrl+D	Open a debug console

In games that show an area in xoreos, you can fly through the areas in spectator-mode:

Hotkey	Effect
W Up	Forward
S Down	Backward
A Left	Turn left
D Right	Turn right
Q	Strafe left
E	Strafe right
Page Up	Look up
Page Down	Look down
End	Look straight ahead
Insert	Fly up
Delete	Fly down

You can also hold the middle mouse button down to look around.