Launcher engine interaction

A launcher for the FreeSpace Open engine is responsible for letting the user configure what mod data FSO should use and also how it should use the available hardware (e.g. joysticks or sound devices). It is also important with what flags FSO is started to allow how the game behaves and looks like. In order for this to work, the launcher needs to follow certain conventions which allow FSO to interpret the data the launcher sets for the engine.

This article describes the situation as of FSO version 3.8.0. Previous versions used different configuration mechanisms but those will not be listed here.

Writing data for the engine to read

The engine will look for the files described below in the "preferences" path. This path is determined by using the SDL2 function SDL_GetPrefPath("HardLightProductions", "FreeSpaceOpen"). Newer engine versions have a way of getting this information without having to link against SDL2, see JSON output for an alternative way of determining this path.

There are two major configuration mechanisms FSO uses for reading data which was set by the launcher:

data/cmdline_fso.cfg

This file should contain all the command line options FSO should use. They should be on a single line and parameters which contain spaces (e.g. mods line "Vassago's Dirge") must be enclosed in quotes:

-mod "Vassago's Dirge,MediaVPs_2014" -nomotiondebris -missile_lighting -3dshockwave -post_process -soft_particles -fxaa -fb_explosions -fb_thrusters -enable_shadows -cache_bitmaps -dualscanlines -targetinfo -orbradar -rearm_timer -ballistic_gauge -3dwarp -snd_preload -nosound -nomovies -fps -window -no_unfocused_pause -benchmark_mode -fxaa_preset 6 -ambient_factor 100 -spec_exp 15 -spec_point 1.2 -spec_static 1.5 -spec_tube 1.5 -ogl_spec 20 -bloom_intensity 45

The available flags should not be hardcoded by the launcher. Instead, it should use -get_flags for determining which flags are supported by the launcher.

fs2_open.ini

This file contains more "permanent" options and is saved in a standard ini format. The file is separated into multiple "sections" which each contain options specific to that part of the engine:

Default 

This is the default section used by FSO if no specific section is selected.

VideocardFs2open

This value determines what display mode FSO will use. It has the following format: [API]-([width]x[height])x[bits] bit. [API] must be exactly 4 characters long. The only valid option here is "OGL " for using the OpenGL API. The other options are pretty obvious. The width and height should match one of the video modes supported by the display (see JSON output for a way of getting this information without linking against SDL2). The bits parameter should either be 16 or 32 but in almost all cases this should be hard-coded to 32.

OGL_AntiAliasSamples

This should be the level of anti-aliasing desired for OpenGL rendering. This should be the multiple of 2 for how many samples should be taken (e.g. a value of 3 means 8x MSAA). If set to 0 anti-aliasing will be disabled. Note: As of FSO 3.8.0 this option has no effect!

TextureFilter

Sets how textures should be filtered. Valid values are 0 for bilinear filtering and 1 for trilinear filtering.

OGL_AnisotropicFilter

Specifies the level of anisotropic texture filtering if supported by the OpenGL implementation.

CurrentJoystickGUID

Specifies the GUID of the primary joystick. The case of alphabetic characters will be normalized so it doesn't matter if this string is upper or lower case. This GUID can be determined by using SDL2 or with the JSON output if supported by the current build).

Note: This is the part of the legacy method of defining the joystick. See Joy0GUID and Joy0ID below.

CurrentJoystick

Specified the index of the primary joystick. This will only be used if there are multiple joysticks with the same GUID. This is the index used to open the joystick in SDL2 or the index into the joysticks array in the JSON output.

Note: This is the part of the legacy method of defining the joystick. See Joy0GUID and Joy0ID below.

Joy0ID

For defining your first of multiple joysticks. Get this ID from the id listed in the exported flags.txt. For details on how to export visit the FAQ FAQ.

Joy0GUID

For defining your first of multiple joysticks. Get this GUID from the GUID listed in the exported flags.txt, matching the entry used for Joy0ID. For details on how to export visit the wiki's FAQ.

Joy1ID

Same as above, for defining your second joystick.

Joy1GUID

Same as above, for defining your second joystick.

Joy2ID

Same as above, for defining your third joystick.

Joy2GUID

Same as above, for defining your third joystick.

Joy3ID

Same as above, for defining your fourth joystick.

Joy3GUID

Same as above, for defining your fourth joystick.

LastPlayer

The name of the last pilot used. Used by the engine to determine which pilot should be at the top of the list and pre-loaded.

GammaD3D

The gamma (brightness) value to be used to display the game.

EnableJoystickFF

Used to determine if force feedback should be enabled if the joystick supports it. If using the JSON output then it's possible to determine if a joystick supports this by looking at the is_haptic field of the joystick object.

EnableHitEffect

This can be used to enable or disable a directional hit effect if Force Feedback is enabled.

Language

Sets the language of the game. Possible values are "English", "German", "French", and "Polish".

ForceFullscreen 

If set to 1, forces the game to start in full screen mode.

ScreenshotNum 

The number of screenshots taken by the player.

MaxFPS 

Used to set the framerate cap for the game. If set to zero, framerate cap is disabled.

ForcePort 

Used to force a specific port for multiplayer connections

ConnectionSpeed

Used for setting how fast the internet connection is. Possible values are "Slow", "56K", "ISDN", "Cable", and "Fast".

SpeechTechroom 

Enables or disables text-to-speech in the techroom. Valid values are 1 and 0. Defaults to 0.

SpeechBriefings 

Enables or disables text-to-speech in the briefings. Valid values are 1 and 0. Defaults to 0.

SpeechIngame 

Enables or disables text-to-speech in game. Valid values are 1 and 0. Defaults to 0.

SpeechMulti 

Enables or disables text-to-speech in the multiplayer. Valid values are 1 and 0. Defaults to 0.

SpeechVolume 

The volume scale of the text-to-speech sound. Should be in the range of 0 to 100.

SpeechVoice 

Sets which voice to use. See JSON output for a cross-platform way of determining which voices are available.

PXOBanners 

Whether or not to use Banners for multiplayer. Valid values are 1 and 0. Defaults to 1.

LowMem 

Use Low Memory mode (Allows 2d animations to drop frames)

ProcessorAffinity 

Set which processor should be assigned to the game. Defaults to 2. This setting applies only on Windows.

Video 

Contains options specific to the video display of FSO.

Display

Used to choose on which display FSO should be displayed on. The JSON output contains a list of display detected on the system and their index. Alternatively, SDL2 can be used to enumerate this information.

ForceFeedback 

Contains options for configuring the force feedback subsystem of FSO.

Strength 

A percentage scale of how strong the effect should be. 0 means completely disabled, 100 means full strength.

Sound 

Contains options specific to how sound should be handled in FSO.

Quality 

Specifies the quality of the sound output. The value should be in [1, 3] where 3 is the highest quality and 1 is the lowest.

SampleRate 

Explicitly specifies the sample rate the OpenAL context should use.

EnableEFX 

Enables or disables usage of OpenAL EFX.

PlaybackDevice 

Sets the playback device OpenAL should use. The JSON output contains a list of available playback devices.

CaptureDevice 

Sets the capture device OpenAL should use. The JSON output contains a list of available capture devices.

PXO 

Contains settings related to the PXO multiplayer service

Login 

The login number for the player's account

Password 

The password the player uses for logging into the PXO service (not the account's password)

SquadName 

The Squad Name the player uses.

Getting a list of supported flags and devices

As of 3.8.1, FSO has two ways of determining what flags are supported by the engine. The JSON output has more information and should be easier to parse but is only supported by newer builds.

The flags can be queries by passing the -get_flags option to FSO (this should be done directly instead of overwriting cmdline_fso.cfg). When doing this, the command line should also contain the -parse_cmdline_only to make sure that FSO only reads the actual command line and not cmdline_fso.cfg. This avoids issues when cmdline_fso.cfg contains options not supported by the selected FSO binary. Since 3.8.1, -get_flags optionally accepts one string parameter for selecting how the flags data is formatted and where it is written.

If FSO does not support the parameter for -get_flags then it will be ignored silently and the legacy binary format will be used. Every version before 3.8.1 will behave this way. This allows to gracefully degrade to the old legacy behavior if support for older builds is desired. Also, if the build does not support the given -get_flags mode then it will print the string "OUTPUT TYPE NOT SUPPORTED!" to stdout and default to the version 1 of the JSON output. This is designed so that it is easy for a launcher to be notified if the selected format is not supported.

JSON output

This mode for -get_flags was introduced in 3.8.1 and can be enabled by using "json_v1" as the mode parameter -get_flags (e.g. -get_flags json_v1). In this mode FSO will output a JSON formatted data structure to stdout which will contain information about the supported flags and available devices that FSO detected. The object structure of this output is described in the following by using hierarchical lists for symbolizing if an object key is a child of another element. The root of the output will be a JSON object.

"version" 

Contains information about the version of this executable.

"full" 

The full version string as is displayed in the main menu.

"major" 

The major part of the version as an integer number.

"minor" 

The minor part of the version as an integer number.

"build" 

The build part of the version as an integer number.

"has_revision" 

A boolean to indicate if this version has a valid revision part.

"revision" 

An integer indicating the revision part of the build version.

"revision_str" 

A string indicating the full revision part of the build version. This may contain the Git hash of the commit in the case of nightly builds or something like "RC2" for release candidates.

"easy_flags" 

This is an array of the available "Easy flags" configuration names. The flags array will contain two bitfields where a bit at position n (starting from the last significant bit) will reference the entry of this array which is at position n.

"flags" 

This is an array of all the flags supported by this binary.

"name" 

A string which specifies the name of the flag (e.g. -soft_particles).

"description" 

A short description of what this flag does. This should be displayed in the launcher overview.

"fso_only" 

A boolean indicating whether this flag is only available in FSO builds or not.

"on_flags" 

An integer which represents a bitfield for which easy flags enable this flag. If the bit n is set in this integer then selecting the easy flag at index n will enable this flag. No action should be taken for the bits that are not set in this bitfield.

"off_flags" 

An integer which represents a bitfield for which easy flags disable this flag. If the bit n is set in this integer then selecting the easy flag at index n will disable this flag. No action should be taken for the bits that are not set in this bitfield.

"type" 

Specifies the category of this flag. Typically all flags with the same category will be grouped together.

"web_url" 

Specifies an URL where more information about this flag can be found.

"caps"

A string array of what capabilities this build has. The following strings may be present in the array:

OpenAL 

This build uses OpenAL for sound.

No D3D 

This build has no support for Direct3D rendering, only OpenGL.

New Sound 

This build has support for the new, enhanced sound code.

SDL 

This build uses SDL on all platforms.

"voices" 

An array of all the possible voice names detected by FSO. If a specific voice should be used then to set the SpeechVoice key to the index of that voice in this array.

"displays" 

Contains information about all the displays currently connected to the system.

"index" 

The index in the array of this display. This should be used for the value of Video.Display

"name" 

A more or less human-readable name of this display.

"x" 

The x offset of where this display is located. This is only relevant for multi-monitor systems where this value specifies the x-offset relative to the other displays.

"y" 

The y offset of where this display is located. This is only relevant for multi-monitor systems where this value specifies the y-offset relative to the other displays.

"width" 

The x-resolution of this display.

"height" 

The y-resolution of this display.

"modes" 

Possible video modes of this display.

"x"

The x-resolution of this video mode.

"y"

The y-resolution of this video mode.

"bits"

The bit depth of this video mode (this is typically 32).

"openal" 

Contains information about detected OpenAL properties and devices.

"version_major" 

The major version of OpenAL as detected by FSO.

"version_minor" 

The minor version of OpenAL as detected by FSO.

"default_playback" 

The default playback device as reported by OpenAL. It is possible that this device does not appear in the playback device list.

"default_capture" 

The default capture device as reported by OpenAL. It is possible that this device does not appear in the capture device list.

"playback_devices" 

A string array of all the playback devices detected by OpenAL.

"capture_devices" 

A string array of all the capture devices detected by OpenAL.

"joysticks" 

An array of all the joysticks that FSO detected.

"name" 

A string which specifies a human-readable name of this joystick.

"guid" 

The GUID (Globally Unique Identifier) of this joystick. This should be used for setting CurrentJoystickGUID in fs2_open.ini

"num_axes" 

The number of axes detected on this joystick.

"num_balls" 

The number of balls detected in this joystick.

"num_buttons" 

The number of buttons detected on this joystick.

"num_hats" 

The number of hats detected on this joystick.

"is_haptic" 

A boolean indicating if this device supports haptic (Force Feedback) effects.

"pref_path" 

A string indicating where the preferences path is located.

Binary output

The binary output is basically a dump of the internal data structure used by FSO for representing the supported flags. If -get_flags is called without a parameter or with the parameter binary then this output mode will be chosen. In this mode FSO will create a file called "flags.lcg" in the working directory of the executable and write the binary representation of the flags in that file. The exact format will not be documented here but there are multiple examples of how to parse this (e.g. wxLauncher or Knossos). Please note that the binary format depends on the current architecture and is not normalized to little- or big-endian. Since FSO currently only support x86 based machines this file will always be little endian encoded.