View source for 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 <tt>SDL_GetPrefPath("HardLightProductions", "FreeSpaceOpen")</tt>. Newer engine versions have a way of getting this information without having to link against SDL2, see [[#JSON output|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:

<pre>
-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
</pre>

The available flags should not be hardcoded by the launcher. Instead, it should use [[#Getting a list of supported flags and devices|-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: <tt>[API]-([width]x[height])x[bits] bit</tt>. <tt>[API]</tt> 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|JSON output]] for a way of getting this information without linking against SDL2). The <tt>bits</tt> 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|JSON output]] if supported by the current build).
:; 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|JSON output]].
:; EnableJoystickFF
:: Used to determine if force feedback should be enabled if the joystick supports it. If using the [[#JSON output|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".
:; 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|JSON output]] for a cross-platform way of determining which voices are available.

; 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|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|JSON output]] contains a list of available playback devices.
:; CaptureDevice : Sets the capture device OpenAL should use. The [[#JSON output|JSON output]] contains a list of available capture devices.

=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 <tt>-get_flags</tt> option to FSO (this should be done directly instead of overwriting <tt>cmdline_fso.cfg</tt>). When doing this, the command line should also contain the <tt>-parse_cmdline_only</tt> to make sure that FSO only reads the actual command line and not <tt>cmdline_fso.cfg</tt>. This avoids issues when <tt>cmdline_fso.cfg</tt> contains options not supported by the selected FSO binary. Since 3.8.1, <tt>-get_flags</tt> 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 <tt>-get_flags</tt> 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 <tt>-get_flags</tt> mode then it will print the string "OUTPUT TYPE NOT SUPPORTED!" to <tt>stdout</tt> 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 <tt>-get_flags</tt> was introduced in 3.8.1 and can be enabled by using "json_v1" as the mode parameter <tt>-get_flags</tt> (e.g. <tt>-get_flags json_v1</tt>). 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. <tt>-soft_particles</tt>).
:; "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 <tt>SpeechVoice</tt> 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 <tt>Video.Display</tt>
:; "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 ('''G'''lobally '''U'''nique '''Id'''entifier) of this joystick. This should be used for setting <tt>CurrentJoystickGUID</tt> in <tt>fs2_open.ini</tt>
:; "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 <tt>-get_flags</tt> is called without a parameter or with the parameter <tt>binary</tt> then this output mode will be chosen. In this mode FSO will create a file called "<tt>flags.lcg</tt>" 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.