Difference between revisions of "Hidden Settings in Oolite"

From Elite Wiki
m (Miscellaneous: Added polygon-sprite-dump-svg)
(Added how to change start-up picture)
(42 intermediate revisions by 13 users not shown)
Line 1: Line 1:
[[Oolite]] has a number of settings that are potentially interesting for advanced users – mostly those working on [[OXP]]s – 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.
+
[[Oolite]] has a number of settings that are potentially interesting for advanced users – mostly those working on [[OXP]]s – 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 [[Debug_OXP]]. 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, and as such only apply to test releases at the moment.
+
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.
  
== Changing settings ==
+
== 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''). [[:File:Oolite_Windows_Shortcut_Parameters.jpg|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.
 +
 
 +
== How to Change Settings ==
 
=== Mac OS X ===
 
=== Mac OS X ===
 
For Oolite under Mac OS X, there are several ways to modify these settings.
 
For Oolite under Mac OS X, there are several ways to modify these settings.
* Some of them can be set with the [http://secrets.blacktree.com/ Secrets preference pane] for Mac OS X 10.5.
+
* Most of them can be set with the [http://secrets.blacktree.com/ 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.)
 
* 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 <code>defaults</code> command line tool can be used. To set a boolean value, use: <code>defaults write org.aegidian.oolite '''key''' -bool YES</code> (or <code>NO</code>). For numerical values, use <code>defaults write org.aegidian.oolite '''key''' 42</code>.
 
* On all systems, the <code>defaults</code> command line tool can be used. To set a boolean value, use: <code>defaults write org.aegidian.oolite '''key''' -bool YES</code> (or <code>NO</code>). For numerical values, use <code>defaults write org.aegidian.oolite '''key''' 42</code>.
 +
 +
*See Tips below for an example using '''Terminal''' (on the AppleMac in the ''Utilities'' folder in ''Launchpad'').
  
 
=== Windows, Linux and other platforms ===
 
=== 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.
+
For platforms other than Mac OS X, you must edit a text file called <code>.GNUstepDefaults</code>. This file is created when you change a preference in Oolite, then quit. Depending on which version of GNUstep has been used to build Oolite, this file might be called <code>oolite.plist</code> instead.
  
 
Under Windows, this file is found at <code><Oolite installation directory>\oolite.app\GNUstep\Defaults\.GNUstepDefaults</code>.
 
Under Windows, this file is found at <code><Oolite installation directory>\oolite.app\GNUstep\Defaults\.GNUstepDefaults</code>.
Line 17: Line 46:
 
Under Linux and other platforms, the file is at <code>~/GNUstep/Defaults/.GNUstepDefaults</code>. 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.
 
Under Linux and other platforms, the file is at <code>~/GNUstep/Defaults/.GNUstepDefaults</code>. 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 <code><*I300></code>. However, when you edit it by hand it’s safe to write numbers in plain form, and booleans are written as <code>YES</code> or <code>NO</code>. All Oolite settings are in the dictionary named “oolite”.
+
The <code>.GNUstepDefaults</code> file is a kind of [[property list]], but uses a slightly different syntax than usual; you may see values like <code><*I300></code>. However, when you edit it by hand it’s safe to write numbers in plain form, and booleans are written as <code>YES</code> or <code>NO</code>. All Oolite settings are in the dictionary named “oolite”.
  
 
== Settings ==
 
== Settings ==
 
=== Graphics ===
 
=== Graphics ===
 +
'''Key:''' anti-aliasing<br />
 +
'''Type:''' boolean<br />
 +
'''Default:''' <code>NO</code><br />
 +
Turn on anti-aliasing. No effect if the hardware does not support it, like integrated Intel graphics cards.
 +
 
'''Key:''' max-texture-size<br />
 
'''Key:''' max-texture-size<br />
 
'''Type:''' integer<br />
 
'''Type:''' integer<br />
Line 26: Line 60:
 
'''Minimum:''' 64<br />
 
'''Minimum:''' 64<br />
 
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.)
 
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<br />
 +
'''Type:''' boolean<br />
 +
'''Default:''' <code>NO</code><br />
 +
'''Introduced:''' 1.74<br />
 +
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<br />
 
'''Key:''' sky-render-inset-coords<br />
Line 42: Line 82:
 
'''Default:''' 0.5<br />
 
'''Default:''' 0.5<br />
 
'''Range:''' 0–1<br />
 
'''Range:''' 0–1<br />
'''Introduced:''' 1.73/1.72.3 (implementation was previously broken)
+
'''Introduced:''' 1.73/1.72.3 (implementation was previously broken)<br />
 
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.
 
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.
  
Line 51: Line 91:
 
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.
 
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.
  
=== Logging ===
+
'''Key:''' dump-synthesized-shaders<br />
'''Key:''' logging-echo-to-stderr<br />
 
 
'''Type:''' boolean<br />
 
'''Type:''' boolean<br />
 
'''Default:''' <code>NO</code><br />
 
'''Default:''' <code>NO</code><br />
If set to <code>YES</code>, log messages are written to the standard error output as well as the log file. This is primarily useful when working on Oolite using Xcode.
+
'''Introduced:''' 1.77<br />
 +
Dumps the synthesized shaders that will be introduced in 1.77 in a folder beside the normal log.
  
'''Key:''' logging-show-app-name<br />
+
=== Logging ===
 +
'''Key:''' logging-echo-to-stderr<br />
 
'''Type:''' boolean<br />
 
'''Type:''' boolean<br />
 
'''Default:''' <code>NO</code><br />
 
'''Default:''' <code>NO</code><br />
If set to <code>YES</code>, log messages will be prefixed with the name of the application, i.e. Oolite. This no longer serves any purpose and will be removed.
+
If set to <code>YES</code>, log messages are written to the standard error output as well as the log file.
  
 
'''Key:''' logging-show-function<br />
 
'''Key:''' logging-show-function<br />
Line 71: Line 112:
 
'''Default:''' <code>NO</code><br />
 
'''Default:''' <code>NO</code><br />
 
If set to <code>YES</code>, log messages will be prefixed with the source code location where they occurred. This is potentially convenient for developers.
 
If set to <code>YES</code>, log messages will be prefixed with the source code location where they occurred. This is potentially convenient for developers.
 +
 +
'''Key:''' logging-show-time<br />
 +
'''Type:''' boolean<br />
 +
'''Default:''' <code>YES</code><br />
 +
If set to <code>YES</code>, 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<br />
 
'''Key:''' logging-show-class<br />
Line 78: Line 124:
  
 
=== OXP verifier ===
 
=== OXP verifier ===
 +
All keys in this section are only relevant for the OXP Developer builds of Oolite.
 +
 +
'''Key:''' enforce-oxp-standards<br />
 +
'''Type:''' integer<br />
 +
'''Default:''' <code>1</code><br />
 +
'''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<br />
 
'''Key:''' oxp-verifier-dump-debug-graphviz<br />
 
'''Type:''' boolean<br />
 
'''Type:''' boolean<br />
 
'''Default:''' <code>NO</code><br />
 
'''Default:''' <code>NO</code><br />
If set to <code>YES</code>, a [http://www.graphviz.org/ Graphviz] dot file named ''OXPVerifierStageDependencies.dot'' will be generated (in the [[Oolite logs|log 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 '''[[#Miscellaneous|universe-dump-debug-graphviz]]''' below.)
+
If set to <code>YES</code>, a [http://www.graphviz.org/ Graphviz] dot file named ''OXPVerifierStageDependencies.dot'' will be generated (in the <code>../Oolite/Oolite.app/Logs/</code> 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 '''[[#Miscellaneous|universe-dump-debug-graphviz]]''' below.)
  
 
'''Key:''' oxp-verifier-open-log<br />
 
'''Key:''' oxp-verifier-open-log<br />
Line 100: Line 161:
 
'''Introduced:''' 1.73<br />
 
'''Introduced:''' 1.73<br />
 
If set to <code>YES</code>, the data cache will be rebuilt each time Oolite runs. This is roughly equivalent to placing a brick on your shift key.
 
If set to <code>YES</code>, the data cache will be rebuilt each time Oolite runs. This is roughly equivalent to placing a brick on your shift key.
 +
 +
In Linux, add a snippet like this to your <code>.GNUstepDefaults</code>:
 +
 +
<key>always-flush-cache</key>
 +
<string>YES</string>
 +
 +
 +
'''Key:''' animation_timer_interval<br />
 +
'''Type:''' real<br />
 +
'''Default:''' <code>0.05</code><br />
 +
'''Introduced:''' 1.82<br />
 +
Sets the maximum desired frames per second. The number of FPS attempted to be achieved will be <code>1.0/animation_timer_interval</code>. So, a value of 0.0167 will result in 1.0/0.0167 = 60.0 FPS and a value of 0.03333 will result in a maximum of 30 FPS. This setting can be used for testing purposes to emulate low-end systems, or alternatively, to determine the maximum performance of a given system while running Oolite. A value of 0.001 will practically achieve this, as it will set the desired FPS to 1000. The default value is 0.05, which corresponds to a maximum of 200 frames per second.
  
 
'''Key:''' debug-show-extra-menu-items<br />
 
'''Key:''' debug-show-extra-menu-items<br />
Line 110: Line 183:
 
'''Default:''' <code>NO</code><br />
 
'''Default:''' <code>NO</code><br />
 
'''Introduced:''' 1.74<br />
 
'''Introduced:''' 1.74<br />
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.19 and later. In the event that this causes problems, it can be disabled with this preference.
+
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<br />
 +
'''Type:''' boolean<br />
 +
'''Default:''' <code>NO</code><br />
 +
'''Introduced:''' 1.75<br />
 +
(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 <code>debugConsole.dumpStackForErrors</code> (which defaults to <code>true</code>).
 +
 
 +
'''Key:''' dump-stack-for-warnings<br />
 +
'''Type:''' boolean<br />
 +
'''Default:''' <code>NO</code><br />
 +
'''Introduced:''' 1.75<br />
 +
(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 <code>debugConsole.dumpStackForWarnings</code> (which defaults to <code>true</code>).
 +
 
 +
'''Key:''' jsruntime-size-mib<br />
 +
'''Type:''' integer<br />
 +
'''Default:''' <code>32</code><br />
 +
'''Introduced:''' 1.89<br />
 +
Adjusts the JavaScript runtime size. The value is expressed in MiB and in the absense of this key, the default value of 32 MiB is used.This can prove useful when too many script-heavy OXPs are in use.
 +
 
 +
'''Key:''' escape-pod-activation-immediate<br />
 +
'''Type:''' boolean<br />
 +
'''Default:''' <code>NO</code><br />
 +
'''Introduced:''' 1.75<br />
 +
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<br />
 +
'''Type:''' real<br />
 +
'''Default:''' 0.5<br />
 +
'''Range:''' 0–1<br />
 +
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<br />
 +
'''Type:''' boolean<br />
 +
'''Default:''' <code>NO</code><br />
 +
'''Introduced:''' 1.74<br />
 +
When enabled, each time an AI is loaded (uncached), a [http://www.graphviz.org/ Graphviz] dot file is generated showing the AI’s states and the transitions between them. For an example, see [http://jens.ayton.se/oolite/ai-graphs/hardMissileAI.plist.pdf hardMissileAI.plist.pdf].
 +
 
 +
'''Key:''' grab-mouse-on-mouse-control<br />
 +
'''Type:''' boolean<br />
 +
'''Default:''' <code>NO</code><br />
 +
'''Introduced:''' 1.82<br />
 +
This setting is currently Windows-only. When enabled and mouse control is also enabled, it will confine the mouse pointer within the game's window. This can be useful in cases where Oolite is run fullscreen on multi-monitor systems, where accidentally clicking the mouse button while the cursor has moved out of the gameplay area to another monitor, would result in the game losing focus. It can also be useful when mouse is active in windowed mode.
  
 
'''Key:''' groolite-disable<br />
 
'''Key:''' groolite-disable<br />
Line 118: Line 233:
 
Completely disables Growl integration (Mac OS X only).
 
Completely disables Growl integration (Mac OS X only).
  
'''Key:''' polygon-sprite-dump-svg<br />
+
'''Key:''' mouse-control-in-windowed-mode<br />
 
'''Type:''' boolean<br />
 
'''Type:''' boolean<br />
 
'''Default:''' <code>NO</code><br />
 
'''Default:''' <code>NO</code><br />
 
'''Introduced:''' 1.74<br />
 
'''Introduced:''' 1.74<br />
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.
+
Enables the player to use mouse control in windowed Oolite.
 +
 
 +
'''Key:''' show-ship-model-in-status-screen<br />
 +
'''Type:''' boolean<br />
 +
'''Default:''' <code>NO</code><br />
 +
Shows a model of the players current ship on the F5 Status screen.
  
 
'''Key:''' universe-dump-debug-graphviz<br />
 
'''Key:''' universe-dump-debug-graphviz<br />
 
'''Type:''' boolean<br />
 
'''Type:''' boolean<br />
 
'''Default:''' <code>NO</code><br />
 
'''Default:''' <code>NO</code><br />
If set to <code>YES</code>, various [http://www.graphviz.org/ Graphviz] dot files will be generated (in the [[Oolite logs|log 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.
+
If set to <code>YES</code>, various [http://www.graphviz.org/ Graphviz] dot files will be generated (in the <code>../Oolite/Oolite.app/Logs/</code> 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<br />
 +
'''Type:''' boolean<br />
 +
'''Default:''' <code>NO</code><br />
 +
This is a workaround for a graphical glitch on Macs with a retina display which affects the short range chart - see the issue at [https://github.com/OoliteProject/oolite/issues/136 github].  Set to <code>YES</code> to enable.
 +
 
 +
== Tips ==
 +
=== Increase memory allotment (AppleMac/Linux) ===
 +
[http://aegidian.org/bb/viewtopic.php?p=275919#p275919 From Commander_X (2021)] - reading your hidden settings, and increasing memory allotment for Oolite. How to do it on AppleMac & Linux:
 +
 
 +
For further reference, from above:
 +
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
 +
 
 +
For the curious, entering in a terminal:
 +
 
 +
defaults read org.aegidian.oolite
 +
 
 +
will present a list of the settings Oolite saves without your knowledge!
 +
 
 +
 
 +
Applying this to what another_commander suggested (in the thread linked above), after you enter in a terminal:
 +
 
 +
defaults write org.aegidian.oolite jsruntime-size-mib 64
 +
 
 +
you should be all set (maybe use quotes, i.e. "jsruntime-size-mib").
 +
 
 +
 
 +
This works also on '''Linux''', when gnustep(-dev?) package is installed. Replace "org.aegidian.oolite" above with "oolite", though. I'd expect it to work with another_commander's dev environment, on '''Windows''', too, if one placed "<mountpoint>/Devlibs[32]/gnustep1201/Local/Tools" in their path variable.
 +
 
 +
=== Change start-up picture from Cobra MkIII ===
 +
This is not strictly a hidden settings matter, and involves changing the Vanilla game code (back up first!):
 +
 
 +
http://aegidian.org/bb/viewtopic.php?f=2&t=18682 (2017)
 +
 
 +
There is also an alternative in ZygoUgo's [http://www.aegidian.org/bb/viewtopic.php?f=4&t=8541 collection] of oxp's.
  
 
[[Category:Oolite]]
 
[[Category:Oolite]]

Revision as of 19:46, 17 January 2023

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 Debug_OXP. 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.

How to Change 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.
  • See Tips below for an example using Terminal (on the AppleMac in the Utilities folder in Launchpad).

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. Depending on which version of GNUstep has been used to build Oolite, this file might be called oolite.plist instead.

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: anti-aliasing
Type: boolean
Default: NO
Turn on anti-aliasing. No effect if the hardware does not support it, like integrated Intel graphics cards.

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.

In Linux, add a snippet like this to your .GNUstepDefaults:

<key>always-flush-cache</key>
<string>YES</string>


Key: animation_timer_interval
Type: real
Default: 0.05
Introduced: 1.82
Sets the maximum desired frames per second. The number of FPS attempted to be achieved will be 1.0/animation_timer_interval. So, a value of 0.0167 will result in 1.0/0.0167 = 60.0 FPS and a value of 0.03333 will result in a maximum of 30 FPS. This setting can be used for testing purposes to emulate low-end systems, or alternatively, to determine the maximum performance of a given system while running Oolite. A value of 0.001 will practically achieve this, as it will set the desired FPS to 1000. The default value is 0.05, which corresponds to a maximum of 200 frames per second.

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: jsruntime-size-mib
Type: integer
Default: 32
Introduced: 1.89
Adjusts the JavaScript runtime size. The value is expressed in MiB and in the absense of this key, the default value of 32 MiB is used.This can prove useful when too many script-heavy OXPs are in use.

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: grab-mouse-on-mouse-control
Type: boolean
Default: NO
Introduced: 1.82
This setting is currently Windows-only. When enabled and mouse control is also enabled, it will confine the mouse pointer within the game's window. This can be useful in cases where Oolite is run fullscreen on multi-monitor systems, where accidentally clicking the mouse button while the cursor has moved out of the gameplay area to another monitor, would result in the game losing focus. It can also be useful when mouse is active in windowed mode.

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: show-ship-model-in-status-screen
Type: boolean
Default: NO
Shows a model of the players current ship on the F5 Status screen.

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.

Tips

Increase memory allotment (AppleMac/Linux)

From Commander_X (2021) - reading your hidden settings, and increasing memory allotment for Oolite. How to do it on AppleMac & Linux:

For further reference, from above:

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

For the curious, entering in a terminal:

defaults read org.aegidian.oolite

will present a list of the settings Oolite saves without your knowledge!


Applying this to what another_commander suggested (in the thread linked above), after you enter in a terminal:

defaults write org.aegidian.oolite jsruntime-size-mib 64

you should be all set (maybe use quotes, i.e. "jsruntime-size-mib").


This works also on Linux, when gnustep(-dev?) package is installed. Replace "org.aegidian.oolite" above with "oolite", though. I'd expect it to work with another_commander's dev environment, on Windows, too, if one placed "<mountpoint>/Devlibs[32]/gnustep1201/Local/Tools" in their path variable.

Change start-up picture from Cobra MkIII

This is not strictly a hidden settings matter, and involves changing the Vanilla game code (back up first!):

http://aegidian.org/bb/viewtopic.php?f=2&t=18682 (2017)

There is also an alternative in ZygoUgo's collection of oxp's.