Hidden Settings in Oolite

Oolite has a number of settings that are potentially interesting for advanced users – mostly those working on OXPs – or for those who are experiencing graphical problems. This article focuses on settings stored on disk; for other tools that can be used while the game is running, see Debugging Facilities in Oolite. All changes described below should be made when the game is not running.

All of these settings were introduced at some point after Oolite 1.65. Most of them will only apply to test releases at the moment.

Startup Parameters

Windows

In Windows you can add a parameter to Oolite's shortcut (so that instead of pointing at C:\Oolite\oolite.app\oolite.exe it'll point at C:\Oolite\oolite.app\oolite.exe parameter). See here for an example.

Available parameters

The parameters are:

• -nosplash

This removes the splash screen that appears when loading, and is useful to fix some graphical issues with certain graphics cards.

• -splash

This forces Oolite to always display the splash screen. If you try to use both -splash and -nosplash, -nosplash "wins".

• -fullscreen

This forces Oolite to start in fullscreen mode, not windowed.

• -noshaders

This forces shaders to be disabled when loading. This may be useful on some older graphics cards (e.g. the Intel GMA series) which report shader support to Oolite but don't do it particularly well.

• -load path_to_savegame

This forces Oolite to load the specified saved game. Use the full path, eg: -load c:\oolite\oolite.app\oolite-saves\Jameson.oolite-save

• -verify-oxp path_to_oxp

Rather than starting Oolite, perform some basic syntax checks on the OXP at the specified path. This is only available in the OXP developer builds of Oolite.

• -message message_to_display

Prints the argument that follows it as a message on the title game screen, e.g. -message "Hello World from Oolite".

• -showversion

Prints the version of the game on the title screen.

• --compile-sysdesc, --export-sysdesc, --xml, --openstep

These parameters are handling options to transform the system_description array for easier localization. The latter two are output format specifiers and are used only if either of the former two have been also set.

Changing settings

Mac OS X

For Oolite under Mac OS X, there are several ways to modify these settings.

• Most of them can be set with the Secrets preference pane for Mac OS X 10.5. (download the tool by selecting the "prefPane" option on the top right, click the downloaded prefPane to install it, choose Oolite in the list on the left)
• If you have Xcode tools installed, they can be edited with Property List Editor. The preferences file can be found at ~/Library/Preferences/org.aegidian.oolite.plist. (This is human-readable in Mac OS X 10.3.9 and earlier, but binary in 10.4 and later.)
• On all systems, the defaults command line tool can be used. To set a boolean value, use: defaults write org.aegidian.oolite key -bool YES (or NO). For numerical values, use defaults write org.aegidian.oolite key 42.

Windows, Linux and other platforms

For platforms other than Mac OS X, you must edit a text file called .GNUstepDefaults. This file is created when you change a preference in Oolite, then quit.

Under Windows, this file is found at <Oolite installation directory>\oolite.app\GNUstep\Defaults\.GNUstepDefaults.

Under Linux and other platforms, the file is at ~/GNUstep/Defaults/.GNUstepDefaults. Since its name starts with a full stop, it is hidden by default. If you’re using Gnome/Nautilus or KDE/Konqueror, you can show it by selecting Show Hidden Files from the View menu. In any event, it should be accessible from the command line.

The .GNUstepDefaults file is a kind of property list, but uses a slightly different syntax than usual; you may see values like <*I300>. However, when you edit it by hand it’s safe to write numbers in plain form, and booleans are written as YES or NO. All Oolite settings are in the dictionary named “oolite”.

Settings

Graphics

Key: max-texture-size
Type: integer
Default: Determined by graphics card and driver, typically 4096.
Minimum: 64
Limit the size (side length) of textures; textures larger than this size will be scaled down. The value should be a power of two; if it isn’t, it will be rounded up to the next power of two. Note: if reduced detail mode is enabled, textures with a side length larger than 512 pixels will be scaled down to half their size regardless of this setting. (This is done independently on each side; for instance, a 1024×2048 pixel texture will be scaled down to 512×1024 pixels, while a 512×1024 pixel texture will be scaled to 512×512 pixels.)

Key: polygon-sprite-dump-svg
Type: boolean
Default: NO
Introduced: 1.74
Test release 1.74 uses a more sophisticated mechanism for drawing missile and mine icons, which involves turning each one into two sets of triangles. This setting causes the generated triangle data to be written to SVG files in the logs folder.

Key: sky-render-inset-coords
Type: boolean
Default: NO
If set to YES, the outermost edges of stars and nebula parts will be cut off. This is intended to help with a rendering problem where boxes are drawn around stars and nebula parts on certain systems with defective graphics drivers.

Key: splash-screen
Type: boolean
Default: YES
Introduced: 1.73.4
If set to NO, Oolite will not show the splash screen while loading. This works around a problem which causes some Windows systems with NVIDIA graphics accelerators to fall back to software rendering. No effect on Mac OS X.

Key: texture-anisotropy-scale
Type: real
Default: 0.5
Range: 0–1
Introduced: 1.73/1.72.3 (implementation was previously broken)
Anisotropic filtering is a technique that improves the clarity of textures seen at a shallow angle, but has a significant performance cost. This setting changes the amount of anisotropic filtering applied, with 0 meaning none and 1 meaning as much as supported by your graphics hardware and drivers.

Key: use-texture-lod-bias
Type: boolean
Default: YES
Introduced: 1.73
Texture LOD bias is an extension used to control the tradeoff between blurriness and graphical artefacts in textures. On certain ATi hardware under Windows, the use of texture LOD bias causes graphical problems, notably untextured stars and nebulae.

Key: dump-synthesized-shaders
Type: boolean
Default: NO
Introduced: 1.77
Dumps the synthesized shaders that will be introduced in 1.77 in a folder beside the normal log.

Logging

Key: logging-echo-to-stderr
Type: boolean
Default: NO
If set to YES, log messages are written to the standard error output as well as the log file.

Key: logging-show-function
Type: boolean
Default: NO
If set to YES, log messages will be prefixed with the function or method in which they occurred. This is of limited use.

Key: logging-show-file-and-line
Type: boolean
Default: NO
If set to YES, log messages will be prefixed with the source code location where they occurred. This is potentially convenient for developers.

Key: logging-show-time
Type: boolean
Default: YES
If set to YES, log messages will be prefixed with the time on which they occurred. The time string is of the format hh:mm:ss.mil. This is potentially convenient for developers.

Key: logging-show-class
Type: boolean
Default: YES (but disabled when running the OXP verifier)
If set to YES, log messages will be prefixed with their log message class, an identifier that can be used to enable or disable messages by editing logcontrol.plist.

OXP verifier

All keys in this section are only relevant for the OXP Developer builds of Oolite.

Key: enforce-oxp-standards
Type: integer
Default: 1
Available: Oolite 1.81 onwards This sets the level of run time checking of OXP standards.

• 0: Off (always the case in standard builds, regardless of this setting)
• 1: Warn (logs if deprecated or other common errors are found, default in OXP Developer builds)
• 2: Enforce (as 1, and it where possible will disable deprecated content)
• 3: Quit (as 1, and after reporting the error will immediately exit Oolite

Setting a higher level than the default may be useful for some styles of OXP development, though is unlikely to be suitable for playing the game.

Key: oxp-verifier-dump-debug-graphviz
Type: boolean
Default: NO
If set to YES, a Graphviz dot file named OXPVerifierStageDependencies.dot will be generated (in the ../Oolite/Oolite.app/Logs/ folder) when the OXP verifier is run. This is used to analyze and debug the OXP verifier and is of little interest to end-users, unless they like technical-looking graphs. (If you do like technical-looking graphs, see universe-dump-debug-graphviz below.)

Key: oxp-verifier-open-log
Type: boolean
Default: YES
Platform: Mac OS X only.
If set to YES, the log file will be opened after the OXP verifier is run.

Key: plist-schema-verifier-dump-structure
Type: boolean
Default: NO
If set to YES, OXP verifier logs will be filled with meaningless gobbledegook. (The plist schema verifier is a tool used to verify the structure of property lists, currently used only for shipdata.plist entries. This setting causes detailed information to be logged for every property list element inspected by the verifier. It is unlikely to be useful except for debugging the verifier.)

Miscellaneous

Key: always-flush-cache
Type: boolean
Default: NO
Introduced: 1.73
If set to YES, the data cache will be rebuilt each time Oolite runs. This is roughly equivalent to placing a brick on your shift key.

Key: debug-show-extra-menu-items
Type: boolean
Default: NO
Mac-specific: if set to YES, a few extra menu items appear in the Debug menu when the Debug OXP is installed (specifically, Graphics Reset, Clear Texture Cache, Reset and Clear and Clear All Caches).

Key: disable-operation-queue-work-manager
Type: boolean
Default: NO
Introduced: 1.74
Test release 1.74 introduces a new way of managing certain operations, primarily texture loading, under Mac OS X 10.5 and later, which should also automatically be used with GNUstep 0.20 and later. In the event that this causes problems, it can be disabled with this preference.

Key: dump-stack-for-errors
Type: boolean
Default: NO
Introduced: 1.75
(Test releases only) If this preference is set, additional debugging information is logged when a script encounters an error. If the Debug OXP is active, this is ignored in favour of the setting debugConsole.dumpStackForErrors (which defaults to true).

Key: dump-stack-for-warnings
Type: boolean
Default: NO
Introduced: 1.75
(Test releases only) If this preference is set, additional debugging information is logged when a script encounters an warning. If the Debug OXP is active, this is ignored in favour of the setting debugConsole.dumpStackForWarnings (which defaults to true).

Key: escape-pod-activation-immediate
Type: boolean
Default: NO
Introduced: 1.75
If true, the escape pod is activated by a single key press. If false, two key presses are needed (except in strict mode).

Key: flight-arrow-key-precision-factor
Type: real
Default: 0.5
Range: 0–1
Set a slower precision movement with keyboard arrows when you hold control down. For more precise long-range aim you can set it to 0.1.

Key: generate-ai-graphviz
Type: boolean
Default: NO
Introduced: 1.74
When enabled, each time an AI is loaded (uncached), a Graphviz dot file is generated showing the AI’s states and the transitions between them. For an example, see hardMissileAI.plist.pdf.

Key: groolite-disable
Type: boolean
Default: NO
Introduced: 1.74
Completely disables Growl integration (Mac OS X only).

Key: mouse-control-in-windowed-mode
Type: boolean
Default: NO
Introduced: 1.74
Enables the player to use mouse control in windowed Oolite.

Key: universe-dump-debug-graphviz
Type: boolean
Default: NO
If set to YES, various Graphviz dot files will be generated (in the ../Oolite/Oolite.app/Logs/ folder) when Oolite starts. At the moment, this means SystemDescription.dot, which is used to analyze the system_description table in descriptions.plist. This is primarily useful to those writing localization OXPs.

Key: issue_136_fix
Type: boolean
Default: NO
This is a workaround for a graphical glitch on Macs with a retina display which affects the short range chart - see the issue at github. Set to YES to enable.