FreeSpace Wiki - User contributions [en]

Template:Table270

2026-11-10T17:29:51Z

MjnMixael: Created page with "<noinclude>Table270</noinclude> <div style="padding: 1px 2px 1px 2px; background-color: #16210A; border: solid 1px #51BE08; padding: 0px 4px; font-size:..."

<noinclude>[[Category:Templates|Table270]]</noinclude>
<div style="padding: 1px 2px 1px 2px; background-color: #16210A; border: solid 1px #51BE08; padding: 0px 4px; font-size: -1; color: #7BE833">'''FS2 Open, 27.0:''' {{{1}}}</div>

Guide to FS mod translations

2026-10-28T18:39:36Z

MjnMixael:

Translations have been quite rare in [[FreeSpace 2]] despite the longevity of the community, so community member '''Achille44''' decided to create this guide, hoping it will motivate some people to join the endeavor. The objective of this tutorial is to explain how to translate FreeSpace 2 mods into non English languages.

This guide will be divided in 2 parts:
# Internationalization - this part will be interesting for modders who want to make their mod easily translatable, or translators really motivated and who are ready to dive into technical stuff themselves.
# Localization - this part will focus on the translation itself, so translators can directly skip to this part.

===Internationalization (i18n)===
Let's start with a bit of wikipedia explanation: "internationalization is the process of designing a software application so that it can be adapted to various languages and regions without engineering changes."

Historically, FreeSpace 2 has always been terrible in terms of internationalization, many parts of the original game were "hardcoded", which means that they were just not translatable, so translations could only be partial. But thanks to the hard work of the SCP devs, most of the game is now translatable.

BUT so far, most of the modders don't use the recent internationalization features for their mods, probably because the process is quite tedious and difficult to maintain. And given the small number of translations and translators, the effort may not seem worth it.

Here is the list of folders/files which may contain strings that need to be internationalized: 
/data 
* /fiction: if the mod uses visual novel briefings, those cannot handle localized files by just appending the language suffix, unlike fiction viewer files. so you need to adapt the vn script to use XSTR features. You can find an example in the French translation of Solaris.
* /missions:
** <nowiki>*</nowiki>.fc2 files: all '$Name' properties must use XSTR.
** <nowiki>*</nowiki>.fs2 files:
*** '$label', '$Callsign', and '$Name' properties must use XSTR.
*** Convert sexp show-subtitle to show-subtitle-text, and then extract hardcoded strings from show-subtitle-text and put them into new messages so they can be translated.
*** Convert ship alt names to sexp variables so that they can be translated via modify-variable-xstr sexp.
*** Convert hardcoded texts in hud-set-text sexp to variables to be treated by XSTR.
*** Convert the special senders to variables in the following sexps: send-random-message, send-message, send-message-list, send-message-chain.
*** Add +Display Name property for all jump nodes.
*** Convert the first sexp parameter to variable for the following sexps: add-nav-waypoint, add-nav-ship, del-nav, hide-nav, restrict-nav, unhide-nav, unrestrict-nav, set-nav-visited, unset-nav-visited, select-nav, unselect-nav, is-nav-visited, lua-mark-ship, lua-mark-wing, ship-create, lua-staged-countdown-start, set-cargo, ship-change-alt-name.
*** Convert the second sexp parameter to variable for the following sexps: change-subsystem-name, lua-mark-subsystem.
*** Convert the fourth sexp parameter to variable for the following sexp: lua-turrethotkey-add.
*** Convert all sexp parameters to variables for the following sexps: set-nav-color, Add-Object-Role.
*** All the new variables must be modified at the beginning of the mission in a new event with the modify-variable-xstr sexp.
*** When using FRED, check 'Always save Dipplay Names' in the Settings to allow the use of ship display names. Keep in mind that the ship display names are not added automatically by Fred, so you'll have to edit the file manually to add them.
* /tables:
** Controlconfigdefaults.tbl: all '$Text' properties must use XSTR.
** credits.tbl and *-crd.tbm files: all lines to be translated must be wrapped into XSTR function.
** cutscenes.tbl and *-csn.tbm files: all '$Name' properties must use XSTR.
** hud_gauges.tbl and *-hdg.tbm files: all 'Text' properties must use XSTR.
** mainhall.tbl and *-hall.tbm files: all '+Door description' properties must use XSTR.
** medals.tbl and *-mdl.tbm files: all '$Alt Name' and '$Name' properties must use XSTR.
** rank.tbl and *-rnk.tbm files: all '$Name' properties must use XSTR.
** *-sct.tbm files: all strings displayed in-game must use the ba.XSTR() function.
** ships.tbl and *-shp.tbm files:
*** All ships must have an '$Alt Name' property with XSTR. If the ship is present in different files (using +nocreate), you only need one $Alt Name.
*** For each '$Subsystem', unless it is 'untargetable' or it's 'afterburner', you'll need to add '$Alt Subsystem Name' (and '$Alt Damage Popup Subsystem Name' only for playable ships) with XSTR.
*** '+Tech Description' and '+Length' (only the one before '$thruster') must use XSTR.
** weapons.tbl and *-wep.tbm files:
*** All weapons must have '$Alt Name', '+Title' and 'Tech Title' properties with XSTR. If the ship is present in different files (using +nocreate), you only need one $Alt Name.
*** '$Turret Name', '+Description' and '+Tech Description' properties must use XSTR.

In order to automate the process of internationalization across several mods, I developed a tool to do most of the work automatically. You can try it here if you are interested: https://codeberg.org/AchilleParmentier/FreeSpace2TranslationTools/releases.

===Localization (l10n)===
It may seem obvious, but before you start translating a mod, you should first ask the authors for permission to avoid any unpleasant surprises.
====Setting your language====
The first step of any translation is to make your language supported by the game. To do so, create a file with the *-lcl.tbm pattern (e. g. fr-lcl.tbm) with the following content:

<pre>$Language: French
+Extension: fr
+Special Character Index: 164

#End</pre>

$Language property is the name of the section you will have to use in all the strings/tstrings files where you put your translations. This name will also be displayed in the language choice in the in-game settings.
+Extension property is the suffix you will use in all the language-specific files (see the list in the next chapter).

Note that this step is not required if you translate a mod not using [https://github.com/MjnMixael/SCPUI/wiki SCPUI] with the French, German and Polish languages, as they are already supported by the original game.

====In case your language uses special characters not provided by the original fonts====
In such case, you'll need an extra step to use another font. I can't help you to find what font you need to use, but you'll need to use a ttf file. Once you have found your desired font file, put it into /data/fonts.

Then you have to tell the mod to use that font instead of the original file. To do so, find the fonts.tbl (and/or *-fnt.tbm) file in /data/tables, and change the $TrueType property with the name of your new font file for each font you want to change.

Be aware that your new font might have a different size from the original and change how the text is displayed ingame. In that case you can modify the +Size, +Top offset and +Bottom offset properties to try to replicate the original display.

====The files to translate====
From here we consider the mod we want to translate is technically ready, so as a translator I just want to know where to find the texts to translate.

Regarding the tools, all txt/tbl/tbm files are simple text files and can be opened and modified with any text editing software, like notepad++ or VSCode.

You'll find below the list of folders/files which can contain texts to be translated.

=====Fiction=====
The *.txt files here can be translated by creating a copy of the same file with a language suffix (e. g. db_bosch.txt => db_bosch-fr.txt).

Some mods may include briefing files here, and these files cannot be translated this way. You'll have to either overwrite the original file, or modify the custom briefing script to make the content internationalized (check the French translation of Solaris to see an example).

=====Movies=====
Here you can add subtitles to cutscenes by creating a *.srt file with the name of the video with language suffix (e. g. colossus.mp4 => colossus-fr.srt).

Subtitle Edit (https://www.nikse.dk/subtitleedit) is a good user-friendly tool to create your subtitles.

If you want to use a distinct font for movie subtitles, create a new one in fonts.tbl, and in game_settings.tbl or any *-mod.tbm file, add the $Movie Subtitle Font property (in the following example, 'Movie' is the name of the new font):

<pre>#OTHER SETTINGS
$Movie Subtitle Font: Movie

#END</pre>

=====HUD and interface=====
Some mods use custom interfaces, with images containing text. You will need some basic image editing skill to translate them. Beware that these files are not internationalized, so you will have to overwrite the original files!

=====Maps=====
In some mods you can find *.dds files which contain nameplates for terran ships. You will need some basic image editing skill to translate them. Beware that these files are not internationalized, so you will have to overwrite the original files!

=====Tables=====
The following files are the most important, as they contain most of the text displayed in the game:

strings.tbl, and all files with the *-lcl.tbm pattern (these contain all the menu strings)
tstrings.tbl and all files with the *-tlc.tbm pattern (these contain the mod content strings, so all missions, ship and weapon descriptions, credits...)

They can be translated by adding a new section with the name of your language copying inside all the original XSTR entries replaced with your new translation.

Example of an original strings.tbl:

<pre>#Default

0, "Player ship changed to %s"

#End</pre>

Example of a translated strings.tbl:

<pre>#Default

0, "Player ship changed to %s"
;the rest of the strings

#End

#French

0, "Vaisseau du joueur à présent %s"
;the rest of the strings

#End</pre>

The number at the beginning of each row must stay the same between languages, as it is the ID used by the game to look for the matching string.

Note that the new translated section can also be placed in a distinct *-lcl.tbm/*-tlc.tbm file if you are familiar enough with modular tables.

Some variables can be used inside the strings for special uses. These are the most useful but there are probably more:
* $quote: replaces the " character, as it is already used by the table format to recognize the string
* $rank: this will be replaced by the current rank of the player ($Alt Name property in rank.tbl)
* $rtitle: similar to $rank, but can be used in case your language uses different names for the same rank depending on the context ($Title property in rank.tbl)

=====Voices=====
Contains all the voice acting files, if you are extremely motivated. Beware that these files are not internationalized, so you will have to overwrite the original files!

====Updating your existing translation====
Let's say you previously translated the v1 of a mod, and now you want to translate v2 but you are not sure what strings changed or were added between both versions.

For this case, I developed a tool you can use: https://codeberg.org/AchilleParmentier/FreeSpace2TranslationTools/releases.
In the second tab 'Update translations' of this tool, you can automatically transfer all unchanged texts from your translated v1 to your new translated v2 file (even if they don't have the same ID anymore). Then you will only have to translate the new and modified strings.

===Related Links===
[https://www.hard-light.net/forums/index.php?topic=99978.0 '''Discussion thread | Hard-Light Productions'''] 

[[Category:Tutorials]]

Briefing Text

2026-10-28T18:39:03Z

MjnMixael:

These tags can be used to manipulate text messages in command and mission briefings, and the fiction viewer. As of r10846, they work in debriefings, too.

[https://github.com/MjnMixael/SCPUI/wiki SCPUI] has its own HTML-based syntax to styling text.

==Colors==

The hue of these colors can be changed with the [[Colors.tbl]] but the tags will remain the same. As of r10926, the tags can also be customized.

A note about color tags: The color tag will work on all font until a space is encountered. There needs to be a space after the tag, before the text to be colorized (although it's not actually required after r5840, it is recommended due to the way FSO wordwrapping works). There is a method to color spans of text, which is discussed in the Misc section below.

Example: '$b This is $b blue $b text' will show as 'This is blue text'

*'''Bright White: $W'''
*'''Standard (default) White: $w'''
*'''Black: $k (Black)'''
*'''Standard Blue: $b'''
*'''Bright Blue: $B'''
*'''Standard Green: $g'''
*'''Bright Green: $G'''
*'''Standard Yellow: $y'''
*'''Bright Yellow: $Y'''
*'''Gray: $e'''
*'''Silver: $E'''
*'''Violet Gray: $v'''
*'''Violet: $V'''
*'''Standard Red: $r'''
*'''Bright Red: $R'''
*'''Pink: $p'''
*'''Bright Pink: $P'''
*'''Orange: $o'''

==Misc==

*The breaking tag $| can be used to stop a color before a character.
**$g Standard Green = '''Standard Green'''.
**$g Stand$|ard Green = '''Standard Green'''.
***If the above causes wordwrapping oddness, you may want to write $g Stand$| ard Green (output is identical: '''Standard Green''').
*$quote will create double quotes.
**Goober is $quotesilly$quote = Goober is "silly".
*$semicolon will create a semicolon.
*$callsign places the pilot name in its place.
*$rank places the player's rank in its place.
*$f, $h, & $n will color the text with the default colors for Friendly, Hostile and Neutral respectively. The colors are defined in the [[iff_defs.tbl]].
*Most special characters such as the comma ',', question mark '?', and exclamation point '!' cannot be colored as of 3.6.14.
*To color spans of text use $c{ and $}.
**The $y{ quick $g{ brown fox $r jumps over $} the lazy $} dog. = '''The quick brown fox jumps over the lazy dog.'''
**This method will color special characters such as the comma ',', question mark '?', and exclamation point '!'
**This method requires FSO build 8786 or later.
**As of r10846, color spans work across linebreaks as well (either manually-added, or automatic from wordwrapping).

==Styling text in SCPUI==

[https://github.com/MjnMixael/SCPUI/wiki SCPUI] has its own HTML-based approach to styling text. It works everywhere that classic color tags do - briefings (including command, loop, and red alert briefings), debriefings, and the fiction viewer - but also the tech room, campaign descriptions, and nearly everywhere that long-form text is supported. For it to work in briefings, the text must be put in "HTML mode" by putting <code>!html</code> at the start, followed by a space. Everywhere else will work without that tag.

Text in HTML mode may contain HTML markup. Text may be styled using <code></code> tags with appropriate classes drawn from common.rcss; inline styles are also supported. FSO and HTML both make use of double quotes and slashes; to minimize conflicts, using single quotes and writing slashes as <code>$slash</code> is recommended. A complete example might look something like this: <code>!html Pilot attend!<$slashspan> Today, we'll be escorting the GTC Examplar<$slashspan> as she raids Shivan<$slashspan> positions throughout Gamma Draconis<$slashspan>.</code>

It is, however, rarely necessary to perform simple styling like this manually: SCPUI's [https://github.com/MjnMixael/SCPUI/wiki/keywords.tbl Keywords.tbl] may be used to automate common styling rules.

[[Category:FRED Tips]]

Game settings.tbl

2026-10-28T18:37:51Z

MjnMixael:

{{SCP_table}}
{{TableVersionGit|2025-02-10|642111676012bc6696f4024c40296a6c20b3b958}}
{{Tables}}
The '''game_settings.tbl''', also known as mod.tbl, defines options that can be changed globally. All settings are optional.

This table is one of the [[Modular Tables]] and can be extended with xxx-mod.tbm

If the version targeted in [[game_settings.tbl#$Target_Version:|target version]] is equal to or later than these listed, the following options are enabled by default:
{{Table220|
*[[game_settings.tbl#$Fixed_Turret_Collisions:|Fixed Turret Collisions]]
*[[game_settings.tbl#$Fixed_Missile_Detonation:|Fixed Missile Detonation]]
*[[game_settings.tbl#$Shockwaves_Damage_All_Object_Types_Once:|Shockwaves Damage All Object Types Once]]
*[[game_settings.tbl#$AI_use_framerate_independent_turning:|AI use framerate independent turning]]
*[[game_settings.tbl#$Use_host_orientation_for_set-camera-facing:|Use host orientation for set-camera-facing]]
}}
{{Table230|
*[[game_settings.tbl#$Shockwaves_Inherit_Parent_Weapon_Damage_Type:|Shockwaves Inherit Parent Weapon Damage Type]]
*[[game_settings.tbl#$Fixed_Chaining_To_Repeating_Events:|Fixed Chaining To Repeating Events]]
}}
{{Table240|
*[[game_settings.tbl#$Calculate_subsystem_hitpoints_after_parsing:|Calculate subsystem hitpoints after parsing]]}}
{{Table242|
*[[game_settings.tbl#$Fix_scripted_velocity:|Fix scripted velocity]]}}
{{Table250|
*[[game_settings.tbl#$Use_model_eyepoint_for_set-camera-host:|Use model eyepoint for set-camera-host]]
*[[game_settings.tbl#$Use_model_eyepoint_normals:|Use model eyepoint normals]]
*[[game_settings.tbl#$Fix_asteroid/debris_field_bounding_box_checks:|Fix asteroid/debris field bounding box checks]]
*[[game_settings.tbl#$Disable_expensive_turret_target_check:|Disable expensive turret target check]]
*[[game_settings.tbl#$Skybox_internal_depth_consistency:|Skybox internal depth consistency]]
}}
{{Table260|
*[[game_settings.tbl#$Zero-radius_explosions_skip_fireballs:|Zero-radius explosions skip fireballs]]
*[[game_settings.tbl#$Render_insignias_as_decals:|Render insignias as decals:]]}}
{{Table262|
*[[game_settings.tbl#$Fix collision moment of inertia:|Fix collision moment of inertia]]}}

==#GAME SETTINGS==
Contains settings that affect how the engine works.

===$Target Version:===
{{Table373|
Specifies the minimum version of FreeSpace Open that this mod supports. If the version specified here is greater than the version of the current build, an error message is displayed.
}}
{{Table381|
The $Minimum version option has been renamed to $Target Version. The old name is kept with the same functionality for backwards-compatibility.

The target version specifies what version of the FSO engine this mod was created for. It will be used by the engine to enable or disable backwards-incompatible changes by default. The default value is 2.0 which specifies that the mod targets the retail engine version.
}}

====+Major:====
{{Table373|
Required. Sets the major component of the target version.
*Syntax: '''''Integer'''''
*Example: '''''3''''' (for a minimum version of 3.7.3.20151121)
}}

====+Minor:====
{{Table373|
Required. Sets the minor component of the target version.
*Syntax: '''''Integer'''''
*Example: '''''7''''' (for a minimum version of 3.7.3.20151121)
}}

====+Build:====
{{Table373|
Required. Sets the build component of the target version.
*Syntax: '''''Integer'''''
*Example: '''''3''''' (for a minimum version of 3.7.3.20151121)
}}

====+Revision:====
{{Table373|
Sets the revision component of the target version. If no revision is given then all builds of that release are supported (even nightly builds if there are any).
For nightly builds this is the date in YYYYMMDD format.
*Syntax: '''''Integer'''''
*Example: '''''20151121''''' (for a minimum version of 3.7.3.20151121)
}}

===$Window title:===
{{Table382|
Specifies the name of the FSO window when this mod is running. If blank or unspecified, the window will have the default title of "FreeSpace 2".
*Syntax: '''''String'''''
}}

===$Window icon:===
{{Table382|
Specifies the icon filename of the FSO window when this mod is running. If blank or unspecified, the window will have the default icon.

The icon should be in data/maps or data/interface, and can apparently be any single-frame image format supported by FSO. The default icon is .png.

*Syntax: '''''String'''''
}}

===$Mod title:===
{{Table224|
Specifies the title of the mod and will be displayed at the mainhall near the FSO version.
*Syntax: '''''String'''''
}}
{{Table250|
It is now possible to display the mod title on its own. Previously, the mod version was also required.
}}

===$Mod version:===
{{Table224|
Specifies the version of the mod and will be displayed at the mainhall near the FSO version. Can be a string or it can be semantic versioning such as 2.0.0.
*Syntax: '''''String'''''
}}
{{Table250|
It is now possible to display the mod version on its own. Previously, the mod title was also required.
}}

===$Unicode mode:===
{{Table382|
Enabled the Unicode text mode for this mod. In Unicode mode all text is assumed to be UTF-8 encoded Unicode and certain features are disabled if they do not have full Unicode support. Most notably, if this is enabled then the engine will no longer support the old bitmap fonts that were used by Retail FreeSpace. Only the newer TrueType fonts will be supported.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Splash screens:===
{{Table232|
Defines a list of splash screens that FSO can display upon game startup. The actual image displayed is chosen at random from the applicable entries. Entries with exact aspect ratio matches will be prioritized first, followed by aspect ratio ranged matches, followed by entries without an aspect ratio specified.}}

====+Bitmap:====
{{table232|
The name of the bitmap to use as a splash screen. Extension will be removed if included.
*Syntax: '''''+Bitmap: String'''''}}

====+Aspect Ratio:====
{{table234|
Only consider this bitmap to be an applicable entry if the user's screen aspect ratio matches the specified number within +/- 0.01.
*Syntax: '''''+Aspect Ratio: Float'''''}}

====+Aspect Ratio Min:====
{{table234|
Only consider this bitmap to be an applicable entry if the user's screen aspect ratio is at least the specified number.
*Syntax: '''''+Aspect Ratio Min: Float'''''}}

====+Aspect Ratio Max:====
{{table234|
Only consider this bitmap to be an applicable entry if the user's screen aspect ratio is at most the specified number.
*Syntax: '''''+Aspect Ratio Max: Float'''''}}

===$Splash fade in time:===
{{Table232|
Sets the time in milliseconds it takes for a splash screen to fade in.
*Syntax: '''''Integer'''''
*Default Value: '''''0'''''}}

===$Splash fade out time:===
{{Table232|
Sets the time in milliseconds it takes for a splash screen to fade out.
*Syntax: '''''Integer'''''
*Default Value: '''''0'''''}}

===$Center splash logo:===
{{Table232|
Sets whether the splash logo will be displayed in the middle of the screen. If this is false (the default), it will be displayed at the top-left.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Disable FSO Internal Loadout Restoration System:===
{{Table234|
When the player configures the ships and weapons of the wings in the loadout screen, FSO will remember these settings and attempt to apply them again if the player quits the mission and comes back to it later. FSO will only remember the most recent mission's loadout, so it will not attempt to restore the loadout if the player loads a different mission. It will also not attempt this if the mission's ''$Modified:'' date has changed. This flag can be used to prevent FSO from attempting restoration even if it normally would.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Lua API returns nil instead of invalid object:===
{{Table242|
A design choice very early in FSO's scripting development established that invalid results return invalid objects. By using this flag, invalid results will return nil instead.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

==#LOCALIZATION SETTINGS==
Contains various settings related to localization and language support.

===$Use tabled strings for the default language:===
{{Table202|
Causes the game to use the text in strings.tbl and tstrings.tbl even when the current language is English. By default, the game will use the literal text in the source code and the data files (tables and missions) and will not look up the entry when the language is English. For other languages, the translation is always used, if it exists, regardless of this setting.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''
}}

===$Don't initalize built-in languages by default:===
{{Table240|
Prevent FSO from initializing the three additional built-in languages (German, French, and Polish). This allows mods which don't support those languages to remove them from the [https://github.com/MjnMixael/SCPUI/wiki SCPUI] language selector.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''
}}

===$Don't pre-empt training message voice:===
{{Table214|
Prevents training messages from being interrupted by other training messages. If a training message has a voice file associated with it, or simulated speech is active, the next message will not be played until the current message has finished.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''
}}

==#CAMPAIGN SETTINGS==
This group contains various Campaign related settings and overrides.

===$Default Campaign File Name:===
Defines which campaign will be selected by default for new pilots. A file extension is not needed and, if present, is removed by the code.
*Syntax: '''''String'''''

===#Ignored Campaign File Names===
Defines which campaigns, if present, will not appear in the Campaign Room. In the original implementation, only single-player campaigns could be ignored and file extensions were required, but see below.
{{Table371|As of 3.7.1, file extensions are not required and, if present, are removed by the code.}}
{{Table382|As of 3.8.2, file name comparisons are not case sensitive and multiplayer campaigns can be ignored.}}
====$Campaign File Name:====
File name of the campaign to ignore. Multiple entries may exist.
*Syntax: '''''String'''''

===#Ignored Mission File Names===
{{Table382|Defines which standalone missions, if present, will not appear in the Tech Room or Multiplayer Lobby. Both single-player and multiplayer missions can be ignored, but missions which appear in a campaign cannot. File extensions are not required and, if present, are removed by the code. File name comparisons are not case sensitive.
====$Mission File Name:====
File name of the mission to ignore. Multiple entries may exist.
*Syntax: '''''String'''''
}}

===$Red-alert applies to delayed ships:===
{{Table372|Controls whether red-alert saved statistics (hitpoints, weapons, subsystem strengths) will be restored for ships that are not present at mission start.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''
}}

==#HUD SETTINGS==
This group contains various HUD behavior settings and overrides

===$Directive Wait Time:===
*Defines how long the game will wait before displaying a directive.
*Syntax: '''''Integer'''''
*Values: '''''Greater than or equal to 0 ms'''''

===$Cutscene camera displays HUD:===
Show the HUD when the cutscene camera is enabled.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''

In earlier versions of the code, this option was controlled by $Cutscene camera disables HUD: and had a default of YES.

===$Full color head animations:===
Enables full-color head ANIs. Normal head ANIs will appear in gray.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''

In earlier versions of the code, this option was controlled by $Color head animations with hud colors: and had a default of YES.

===$Don't automatically select a turret when targeting a ship:===
{{Table220|Uses FS1 behavior where targeting a new ship did not target any turrets. In FS2 a turret is automatically targeted.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Auto select subsystem under reticle when targeting same ship:===
{{Table242|This is a streamlining of functionality, that makes it so one doesn't need to hit a second key to select the subsystem under the reticle. Instead once you have the capital ship selected, hit Target Under Reticle and it will target a subsystem under the reticle if the feature is enabled and there isn't a new target under the reticle.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Supernova hits at zero:===
{{Table222|
Adjusts the HUD timer so that the timer reaches zero when the supernova hits the player. The actual timing is not affected -- whether the flag is enabled or not, the supernova will always hit the player when 5 seconds remain in the time specified in the sexp.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''
}}

===$Always warn player about unbound keys used in Directives Gauge:===
{{Table222|
Ensures that the "Key Unbound" message will pop up for a directive with an unbound key in any single-player mission, not just a training mission. Note, that the default string (index 426) will still say "Warning\nYou have no control bound to the action \"%s\". You must do so before you can continue with training." Thus, it is advised to change the string at index 426 using the -lcl.tbm to "Warning\nYou have no control bound to the action \"%s\". You must do so before you can continue with this mission."
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''
}}

===$HUD drop shadows enabled by default:===
{{Table232|
If this flag is active, certain elements displayed on the HUD (all text, the main targeting reticle, and the background of the ETS gauges) will have a "drop shadow" effect. Note that whether or not the flag is active, the player can set this using the "Toggle HUD Drop Shadows" control.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''
}}

===$Unify scanning behavior:===
{{Table242|
*Unifies scanning behavior between subsystem, regular, and cargo allowing missions to use all scan types in all situations.
*Also allows changing the "Cargo:" text line in a mission by adding "$Cargo Title: STRING" after the "$Cargo 1:" or "$Cargo 2:" lines in the mission file. FRED UI support not yet added for $Cargo Title so you have to do it manually.
*When this flag is enabled, all ships, no matter the ship class, will react the same way to the cargo-related or scanning-related ship flags:
**They are not scannable by default
**Setting the "scannable" flag makes them scannable, and scanning the subsystem will reveal the cargo
**A new flag available with alter-ship-flag, "no-scanned-cargo", changes the behavior to scanned/unscanned instead of revealing the cargo
**The "toggle-subsystem-scanning" flag must be set to swap full-ship scanning mode into subsystem scanning mode and works for all ship types
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''
}}

===$Don't show callsigns in the escort list:===
{{Table242|
By default, callsigns are shown in the escort list using the same format as in the target box. If this flag is active, callsigns will not be displayed.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''
}}

===$Hide main Rearm/Repair items in Comms Gauge:===
{{Table250|
Prevents 5. Rearm/Repair Subsys and 6. Abort Rearm from being shown in the squad messaging menu.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''
}}

===$Always show selected item in Comms Gauge:===
{{Table262|
Ensures that the visual indicator for which is the active item in the squad messaging menu is always shown. Useful if you are using the select Comms menu item keys. By default this is not shown until the player presses the up or down key for the select Comms menu item keys.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''
}}

==#SEXP SETTINGS==
This group contains SEXP settings and overrides.

===$Loop SEXPs Then Arguments:===
Flips how when-argument settings loop. See: [http://www.hard-light.net/forums/index.php?topic=79602.0 SEXP Argument changes via mod.tbl]
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''

===$Use Alternate Chaining Behavior:===
When set, this allows all events in a chain to repeat, instead of only the last one. It makes the event chaining behavior act as people expected it to be in [http://scp.indiegames.us/mantis/view.php?id=82 Mantis #82].
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''

===$Fixed Chaining To Repeating Events:===
{{Table230|When set, this makes event chaining to repeated events work as designed - that is, the chained event will only be evaluated after the chain delay. If the repeating event's interval is shorter than the chain delay, then the delay countdown will continually be restarted until all repetitions have completed. Without this flag, FSO will emulate retail behavior which, due to a bug, allowed chained events to be evaluated immediately after a repeating event is first evaluated.

NOTE: Although the name does not reflect it, the same issue affects repeating events that are evaluated by <tt>is-event-true-delay</tt> and <tt>is-event-false-delay</tt>. Without this flag, FSO will emulate retail behavior which causes these SEXP operators to ignore any delay when evaluating repeated events. With this flag, the delay will be measured from when the final repeat iteration occurs.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Use host orientation for set-camera-facing:===
{{Table220|When set, this will take into account the host orientation for cutscene cameras. This is a bugfix for [https://github.com/scp-fs2open/fs2open.github.com/issues/3889 GitHub issue #3889].
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Use model eyepoint for set-camera-host:===
{{Table250|The default behavior for set-camera-host is to position the camera at the origin coordinates (0,0,0) of the host. This flag will make the camera use the model eyepoint instead.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Use model eyepoint normals:===
{{Table250|If set, model eyepoints will respect the normal vector set for the eyepoint in the model file for the eyepoint. If not set, model eyepoints will use the model's orientation.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Show-subtitle uses pixels:===
{{Table222|When set, SEXPs which display subtitles will read their arguments as pixels, not percentages. If <code>$Show-subtitle base resolution:</code> is set, these pixels will be scaled up or down as needed.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Show-subtitle base resolution:===
{{Table222|When set, subtitles are assumed to display at the appropriate size in the specified resolution, and will be scaled up or down if the current screen resolution is different. If this is not set, or is set to a resolution less than (640, 480), subtitles will not be scaled.
*Syntax: '''''(Integer, Integer)'''''
*Default Value: '''''(-1, -1)'''''}}

===$HUD-set-coords base resolution:===
{{Table232|The hud-set-coords SEXP has always used exact pixels, without regard for the current screen resolution. This setting enables a similar scaling mechanism as ''$Show-subtitle base resolution:''.
*Syntax: '''''(Integer, Integer)'''''
*Default Value: '''''(-1, -1)'''''}}

===$Always Show Directive Value Count:===
{{Table250|
*If this setting is enabled, Directive-as-Value values in Directives will always show the number. By default this is disabled, and only values > 1 are shown.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

==#GRAPHICS SETTINGS==
This group contains settings related to graphics.

===$Enable External Shaders:===
Enables the use of external shader files. By default, the engine will use the built-in shaders.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''

===$Default Detail Level:===
{{Table3615|
Determines which graphics detail level preset (low, medium, high, very high) acts as the default for new pilots.
*Syntax: '''''Integer''''' (0-3)
*Default Value: '''''3''''' (very high)}}

===$Briefing Window FOV:===
{{Table371|
Determines the FOV in the briefing Icon window. Retail default for this is 0.29375; some previous versions of FSO used a value of 0.5.
*Syntax: '''''Float''''' (0.0 to 1.0)
*Default Value: '''''0.29375'''''}}

===$Generic Pain Flash Factor:===
{{Table373|
Determines the intensity of the pain red flash when the player is hit.
*Syntax: '''''Float'''''
*Default Value: '''''1.0'''''}}

===$Shield Pain Flash Factor:===
{{Table373|
Determines the intensity of a pain flash when the player's shields are hit. Color will match the current ships shield color defined in ships.tbl. A value of 0 will give retail behavior (no shield effect). Positive values will cause the effect to start at full intensity at full shields and go to next to no intensity at zero shields. Negative values will cause no effect at full shields and full effect at no shields. Values should be kept between -1.0 and 1.0 for good pilot visibility.
*Syntax: '''''Float'''''
*Default Value: '''''0.0'''''}}

===$EMP Pain Flash Factor:===
{{Table224|
Determines the intensity of the flash when the player is hit by an EMP blast or weapon.
*Syntax: '''''Float'''''
*Default Value: '''''1.0'''''}}

===$EMP Pain Flash Color:===
{{Table224|
Determines the RGB color value of the flash when the player is hit by an EMP blast or weapon.
*Syntax: Color, (red, green, blue) respectively, integer value from 0 to 255
*Default Value: '''''(255, 255, 127)'''''}}

===$BMPMAN Slot Limit:===
{{Table382|
Determines the maximum number of textures that can be loaded simultaneously. This includes every frame of an animation, unless that animation is streaming (e.g. command briefing animations, message talking heads, etc). Also includes dynamically-created textures (used internally for various functions).
*Syntax: '''''Int'''''
*Values: '''''Greater than or equal to 3500'''''
*Default Value: '''''4750'''''}}

===$EMP Arc Color:===
{{Table382|
Allows custom RGB color values to be set for the EMP lightning arc effect.
*'''+Primary Color Option 1:'''
**The RGB color of the first primary color for the EMP lightning arc effect.
**The actual lightning arc color shown in-game is randomly selected between the first and second primary color.
**Syntax: '''''Color''''', (red, green, blue) respectively, integer value from 0 to 255
**Default value: (64, 64, 5)
*'''+Primary Color Option 2:'''
**The RGB color of the second primary color for the EMP lightning arc effect.
**The actual lightning arc color shown in-game is randomly selected between the first and second primary color.
**Syntax: '''''Color''''', (red, green, blue) respectively, integer value from 0 to 255
**Default value: (128, 128, 10)
*'''+Secondary Color Option 1:'''
**The RGB color of the secondary color for the EMP lightning arc effect.
**Syntax: '''''Color''''', (red, green, blue) respectively, integer value from 0 to 255
**Default value: (255, 255, 10)
}}

===$EMP Arc Width:===
{{Table224|
Allows setting how the width is calculated for the EMP lightning arc effect.
*'''+Width Default:'''
**The default width of the arc. This value will be multiplied by `+Width Radius Multiplier:` if the radius of the ship is less than or equal to `+Do Not Use Width Multiplier Over Radius:`.
**Syntax: '''''Float'''''
**Default value: 0.9
*'''+Width Radius Multiplier:'''
**The value that the width is multiplied by if the radius of the ship is less than or equal to `+Do Not Use Width Multiplier Over Radius:`.
**Syntax: '''''Float'''''
**Default value: 0.01
*'''+Do Not Use Width Multiplier Over Radius:'''
**If the object is larger than this radius, the `+Width Default:` value is used.
**Syntax: '''''Float'''''
**Default value: 500
*'''+Width Radius Minimum:'''
**Minimum width that the arc can be. Any calculated widths lower than this value will be set to this value.
**Syntax: '''''Float'''''
**Default value: 0.2
}}

===$Damage Arc Color:===
{{Table382|
Allows custom RGB color values to be set for the damage lightning arc effect.
*'''+Primary Color Option 1:'''
**The RGB color of the first primary color for the damage lightning arc effect.
**The actual lightning arc color shown in-game is randomly selected between the first and second primary color.
**Syntax: '''''Color''''', (red, green, blue) respectively, integer value from 0 to 255
**Default value: (64, 64, 255)
*'''+Primary Color Option 2:'''
**The RGB color of the second primary color for the damage lightning arc effect.
**The actual lightning arc color shown in-game is randomly selected between the first and second primary color.
**Syntax: '''''Color''''', (red, green, blue) respectively, integer value from 0 to 255
**Default value: (128, 128, 255)
*'''+Secondary Color Option 1:'''
**The RGB color of the secondary color for the damage lightning arc effect.
**Syntax: '''''Color''''', (red, green, blue) respectively, integer value from 0 to 255
**Default value: (64, 64, 5)
}}

===$Damage Arc Width:===
{{Table224|
Allows setting how the width is calculated for the EMP lightning arc effect.
*'''+Width Default:'''
**The default width of the arc. This value will be multiplied by `+Width Radius Multiplier:` if the radius of the ship is less than or equal to `+Do Not Use Width Multiplier Over Radius:`.
**Syntax: '''''Float'''''
**Default value: 0.9
*'''+Width Radius Multiplier:'''
**The value that the width is multiplied by if the radius of the ship is less than or equal to `+Do Not Use Width Multiplier Over Radius:`.
**Syntax: '''''Float'''''
**Default value: 0.01
*'''+Do Not Use Width Multiplier Over Radius:'''
**If the object is larger than this radius, the `+Width Default:` value is used.
**Syntax: '''''Float'''''
**Default value: 500
*'''+Width Radius Minimum:'''
**Minimum width that the arc can be. Any calculated widths lower than this value will be set to this value.
**Syntax: '''''Float'''''
**Default value: 0.2
}}

===$Requires Rendering Feature:===
{{Table210|Needs description}}

===$Render player muzzle flashes in cockpit:===
{{Table212|
Determines whether muzzle flashes will be shown within the cockpit view.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Glowpoint nebula visibility factor:===
{{Table220|
*Specifies the degree to which glowpoints are affected by nebula fog. 1.0 is exactly the same as regular ship hull obscurity, higher means they stay visible for longer.
*Syntax: '''''Float'''''
*Default Value: 1.2}}

===$Shield nebula visibility factor:===
{{Table220|
*Specifies the degree to which shield effects are affected by nebula fog. 1.0 is exactly the same as regular ship hull obscurity, higher means they stay visible for longer.
*Syntax: '''''Float'''''
*Default Value: 1.2}}

===$Thruster nebula visibility factor:===
{{Table220|
*Specifies the degree to which thruster flares are affected by nebula fog. 1.0 is exactly the same as regular ship hull obscurity, higher means they stay visible for longer.
*Syntax: '''''Float'''''
*Default Value: 1.5}}

===$Beams affected by nebula visibility:===
{{Table212|
Determines whether beam weapons will be faded by nebula fog.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

====+Constant visibility factor:====
{{Table220|
*Specifies the degree to which beam effects are affected by nebula fog. 1.0 is exactly the same as regular ship hull obscurity, higher means they stay visible for longer.
*Syntax: '''''Float'''''
*Default Value: 4.0}}

====+Scaled visibility factor:====
{{Table220|
*Specifies the degree to which the ''size'' of a beam effect affects its visibility. This is multiplied by the radius of the beam and added to the above for the final value. This results in larger beams being visible from farther away.
*Syntax: '''''Float'''''
*Default Value: 0.1}}

===$Weapons affected by nebula visibility:===
{{Table212|
Determines whether lasers, missiles, countermeasures, etc will be faded by nebula fog.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

====+Weapon visibility factor:====
{{Table220|
*Specifies the degree to which laser-type weapons are affected by nebula fog. 1.0 is exactly the same as regular ship hull obscurity, higher means they stay visible for longer.
*Syntax: '''''Float'''''
*Default Value: 1.3}}

====+$Trail visibility factor:====
{{Table220|
*Specifies the degree to which trails (weapon and ship contrails) are affected by nebula fog. 1.0 is exactly the same as regular ship hull obscurity, higher means they stay visible for longer.
*Syntax: '''''Float'''''
*Default Value: 1.0}}

====+Shockwave visibility factor:====
{{Table220|
*Specifies the degree to which shockwave effects are affected by nebula fog. 1.0 is exactly the same as regular ship hull obscurity, higher means they stay visible for longer.
*Syntax: '''''Float'''''
*Default Value: 2.5}}

===$Particles affected by nebula visibility:===
{{Table212|
Determines whether particle effects, including impact effects, will be faded by nebula fog.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

====+Constant visibility factor:====
{{Table220|
*Specifies the degree to which particle effects are affected by nebula fog. 1.0 is exactly the same as regular ship hull obscurity, higher means they stay visible for longer.
*Syntax: '''''Float'''''
*Default Value: 1.0}}

====+Scaled visibility factor:====
{{Table220|
*Specifies the degree to which the ''size'' of a particle effect affects its visibility. This is multiplied by the radius of the particle and added to the above for the final value. This results in larger particles being visible from farther away.
*Syntax: '''''Float'''''
*Default Value: 0.08}}

===$Fireballs affected by nebula visibility:===
{{Table212|
Determines whether fireballs from ship explosions will be faded by nebula fog.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

====+Constant visibility factor:====
{{Table220|
*Specifies the degree to which fireballs are affected by nebula fog. 1.0 is exactly the same as regular ship hull obscurity, higher means they stay visible for longer.
*Syntax: '''''Float'''''
*Default Value: 1.2}}

====+Scaled visibility factor:====
{{Table220|
*Specifies the degree to which the ''size'' of a fireball affects its visibility. This is multiplied by the radius of the fireball and added to the above for the final value. This results in larger fireballs being visible from farther away.
*Syntax: '''''Float'''''
*Default Value: 0.08}}

===$Shadow Quality Default:===
{{Table220|
Sets the default level for shadow quality if the 'enable_shadows' command line is used and 'shadow_quality' is not used. By default, the FSO will set the shadow detail level to 2. Valid values are 0 (shadows disabled), 1 (Low, 512x512 shadow map), 2 (Medium, 1024x1024 shadow map), 3 (High, 2048x2048 shadow map), or 4 (Ultra, 4096x4096). Note, the command line 'shadow_quality' will override any value set here.
*Syntax: '''''Integer'''''
*Default Value: '''''2'''''}}

===$Shadow Cascade Distances:===
{{Table214|
Sets the distances that the shadow map for the game scene uses. Float values must all be greater than 0 and successively larger than each consecutive value.
{{Table262|
*Can now be an arbitrary non-zero number of floats. If not set to 4, you must table [[#$Shadow Smoothness Factor:]]
}}
*Syntax: '''''List of floats'''''
*Default Value: '''''(200.0, 600.0, 2500.0, 8000.0)'''''}}

===$Shadow Cascade Distances Cockpit:===
{{Table214|
Sets the distances that the shadow map for the cockpit pass scene uses. Will only shadow the cockpit model, and does not interact with the external game scene shadow map. Float values must all be greater than 0 and successively larger than each consecutive value.
{{Table262|
*Can now be an arbitrary non-zero number of floats. If not set to 4, you must table [[#$Shadow Smoothness Factor:]]
}}
*Syntax: '''''List of floats'''''
*Default Value: '''''(0.25, 0.75, 1.5, 3.0)'''''}}

{{Table262|
===$Shadow Smoothness Factor:===
Sets the strength of the smoothing for each shadow cascade. Larger values mean smoother / softer shadows. Shadow smoothness also scales with cascade distance, so the same value for a larger cascade will be perceived to be smoother.
The number of smoothness factors ''must'' match the number of Shadow Cockpit Cascades + Shadow Cascades (each 4 by default).
The list should first contain the smoothness factors for the cockpit cascades in order, and then the smoothness factors for the main cascades in order
*Syntax: '''''List of floats'''''
*Default Value: '''''(0.00333, 0.004, 0.005, 0.005, 0.00333, 0.004, 0.005, 0.005)'''''}}

===$Shadow Disable Techroom:===
{{Table224|
Disables shadows on ships in the techroom.
*Syntax: '''''Boolean'''''
}}

===$Shadow Disable Cockpit:===
{{Table224|
Disables shadows on the player cockpit in mission.
*Syntax: '''''Boolean'''''
}}

===$Shadow Disable Mission Brief Weapons:===
{{Table224|
Disables shadows on weapons in the mission briefing.
*Syntax: '''''Boolean'''''
}}

===$Shadow Disable Mission Brief Ships:===
{{Table224|
Disables shadows on ships in the mission briefing.
*Syntax: '''''Boolean'''''
}}

===$Show Ship Casts Shadow:===
{{Table224|
When cockpit shadows are enabled, enabling this setting will cause the players ship model shown with "show ship" to cast shadow onto the cockpit.
*Syntax: '''''Boolean'''''
}}

===$Ship Model And Cockpit Share Coordinate Space:===
{{Table224|
When having the "show ship" flag enabled and cockpit models for a ship, this flag should be on if the cockpits can fit into the actual geometry of the ship model. Disable this flag if this is not the case and the cockpit needs to be rendered on top of the ship regardless of actual coordinates. If this can be enabled, the external show ship model can be rendered using deferred rendering.
*Syntax: '''''Boolean'''''
}}

===$Show Ship enabled only if Cockpits enabled:===
{{Table250|
Enabling this setting will only use the 'show-ship' flag if cockpits are enabled. Useful if your ship uses both 'show-ship' and cockpits that exist within the 'show-ship' space, and you want to allow players to toggle off cockpits. Note, 'show-ship' always only appears if in first-person view.
*Syntax: '''''Boolean'''''
}}

===$Minimum Pixel Size Thrusters:===
{{Table220|
*Specifies the smallest pixel size that thrusters will be rendered. Setting this > 0 can be expensive in larger missions.
*Syntax: '''''Float'''''
*Default Value: 0.0}}

===$Minimum Pixel Size Beams:===
{{Table220|
*Specifies the smallest pixel size that beams will be rendered. Setting this > 0 can be expensive in larger missions.
*Syntax: '''''Float'''''
*Default Value: 0.0}}

===$Minimum Pixel Size Muzzle Flashes:===
{{Table220|
*Specifies the smallest pixel size that muzzle flashes will be rendered. Setting this > 0 can be expensive in larger missions.
*Syntax: '''''Float'''''
*Default Value: 0.0}}

===$Minimum Pixel Size Trails:===
{{Table220|
*Specifies the smallest pixel size that trails will be rendered. Setting this > 0 can be expensive in larger missions.
*Syntax: '''''Float'''''
*Default Value: 0.0}}

===$Minimum Pixel Size Lasers:===
{{Table220|
*Specifies the smallest pixel size that lasers will be rendered. Setting this > 0 can be expensive in larger missions.
*Syntax: '''''Float'''''
*Default Value: 0.0}}

===$Do Not Render Lasers Below Length:===
{{Table250|
*Specifies the smallest length that lasers will be rendered.
*Syntax: '''''Float'''''
*Default Value: 0.0001}}

===$Do Not Render Lasers Below Radius:===
{{Table250|
*Specifies the smallest radius that lasers will be rendered.
*Syntax: '''''Float'''''
*Default Value: 0.0001}}

===$Thruster Easing Value:===
{{Table220|
*Smooths out the behavior of maneuvering thruster flares the higher above 0 it is.
*This is the exponential time constant for the visual flare length to reach it's true length.
*Syntax: '''''Float'''''
*Default Value: 0.0}}

===$Primary Thruster Glow Depth Factor:===
{{Table262|
*This value is a multiplier of the Primary Thruster glow's computed size. By default, Primary Thrusters showed through model geometry, but setting this value to less than or equal to 0 will fix the issue.
*Syntax: '''''Float'''''
*Default Value: 0.325f}}

===$Tertiary Thruster Glow Depth Factor:===
{{Table262|
*This value is a multiplier of the Tertiary Thruster glow's computed size. By default, Tertiary Thrusters does not show through model geometry, but you could make it so by setting this value to greater than 0.
*Syntax: '''''Float'''''
*Default Value: -0.5f}}

===$SCPUI attempts to load hires animations:===
{{Table230|
*Prevents [https://github.com/MjnMixael/SCPUI/wiki SCPUI] from trying to load anims prefixed with "2_"
*Syntax: '''''Boolean'''''
*Default Value: true}}

{{Table230|
===$Max draw distance:===
===$Min draw distance:===
*These values do more than just cutoff the visuals at certain distances, and they must be adjusted carefully to ensure unintentional rendering artifacts are not introduced.
*The rendering engine has limited amount of 'depth resolution', the degree to which it can tell a certain polygon is closer or farther away than another. When two polygons are too close, they will Z-fight, picking arbitrarily which is closer. It is the span between the min and max draw distance that determines how well the engine can determine depth, if they are too far from one another, the Z-fighting will become more common as it has to spread its resolution over a wider range. If they are close, Z-fighting will be lessened at the cost of a smaller range of distance able to be rendered.
*Syntax: '''''Float''''', meters
*Default Values: 10,000,000,000 and 1, respectively
}}

{{Table232|
===$Randomize particle rotation:===
*Particle bitmaps are typically screen-aligned; the upper portion of the bitmap will always be mapped to the upper portion of the particle, from the point of view of the camera. Enabling this option makes ''all'' particles have a random 'tilt' in an arbitrary direction when created.
*Syntax: '''''Boolean'''''
*Default Value: false
}}

===$Disable shield effects:===
{{Table250|
*Specifies if FSO attempts to use the shield mesh impact effects. Enabling this flag will prevent the game from preforming any shield mesh effect code, which can be useful if a mod does not use those shield mesh effects.
*Syntax: '''''Boolean'''''
*Default Value: false}}

===$Disable all non-custom generic debris:===
{{Table250|
*Provides one simple control to turn off all non-custom generic debris (the tiny debris shards that are typically spawned when a ship/subsystem explodes). Note, generic debris that is manually specified in the ships table will still be spawned, this is only for turning off non-custom debris.
*Syntax: '''''Boolean'''''
*Default Value: false}}

===$Render insignias as decals:===
{{Table260|
*If set, insignias will be rendered using the decal system. This will make insignias render with correct and deferred lighting, and fix issues with apparent fading
*Models must be set up correctly for this to work! A model can have multiple insignias, with multiple polygon faces each. To enable this option, each visible insignia must have its own insignia entry in the model. If multiple visible insignias are incorrectly consolidated into one insignia entry with disjointed polygons, this will cause graphical artifacts.
*For reference, check out the retail FS2 models, which are set up correctly.
*Syntax: '''''Boolean'''''
*Default Value: false}}

==#NETWORK SETTINGS==
This group contains network-related settings

===$FS2NetD port:===
*(description required)

===$Default object update level for multiplayer:===
{{Table220|
Sets the distances default object update rate for multiplayer matches. By default, the FSO will set the object update level to 2. Valid values are 0 (Low), 1 (Medium), 2 (High), 3 (LAN). FSO caps the bandwidth it uses based on these settings, but they were designed for connections from 1999. LAN has the least restrictive limits and does not require an actual LAN connection. Also, if a player's connection is within the dial-up speed range then game auto force the use of the lowest level during a match.
*Syntax: '''''Integer'''''
*Default Value: '''''2'''''}}

==#SOUND SETTINGS==
This group contains sound-related settings

===$Default Sound Volume:===
{{Table371|
*Defines the default sound fx volume for new pilots.
*Syntax: '''''Float''''', between 0.0 and 1.0
*Default Value: '''''1.0'''''}}

===$Default Music Volume:===
{{Table371|
*Defines the default music volume for new pilots.
*Syntax: '''''Float''''', between 0.0 and 1.0
*Default Value: '''''0.5'''''}}

===$Default Voice Volume:===
{{Table371|
*Defines the default voice volume for new pilots.
*Syntax: '''''Float''''', between 0.0 and 1.0
*Default Value: '''''0.7'''''}}

===$Use weapon class impact sounds for hits to player:===
{{Table224|
Allows weapons that hit the player to play their specific impact sounds, not the hard-coded default sounds.
*Syntax: '''''Boolean'''''
}}

===$Play thruster sounds for the player:===
{{Table232|
If the player's ship has thruster sounds defined, this will ensure they are played like normal, since they are typically suppressed.
*Syntax: '''''Boolean'''''
}}

===$Unify minimum engine sound:===
{{Table250|
Allows $Minimum Engine Volume in ships.tbl to work for all ship classes. By default, that value only triggers for non-huge ships.
*Syntax: '''''Boolean'''''
}}

===$Disabled or disrupted engines are silent:===
{{Table250|
If set, engines will not play their engine noise if the ship is disabled or a disrupted (such as disruptions caused by an active EMP effect or a weapon with the "electronics" flag).
*Syntax: '''''Boolean'''''
}}

==#FRED SETTINGS==
This group contains settings for FRED.

===$Disable Hard Coded Message Head Ani Files:===
{{table371|
If set, FRED will not fill the head ani selection in the Event Editor with the retail head ani filenames.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Add Message Head Ani Files:===
{{table224|
FRED will append each +Head entry listed below to the head ani selection list in the Event Editor.}}

====+Head:====
{{table224|
The head ani filename to add. Extensions will be stripped if included.
NOTE: Pay attention to file names or anis with a,b, c variation not display in-game (unless called directly). Proper name seems to be Head-xxxNa, Head-xxxNb, with N being some number and XXX being whatever you want. Needs further testing and confirmation
*Syntax: '''''+Head: String'''''}}

===$Enable scripting in FRED:===
{{table382|
If set, scripting will be enabled in FRED. Use with extreme caution. The effects of scripts on FRED have not been fully tested. You can check if a script is running in FRED by using ba.inMissionEditor().
*Default Value: '''''NO'''''}}

===$FRED Briefing window resolution:===
{{table224|
The width and height of the briefing window in FRED. Defaults to 888x371. Note that changing this only affects FRED and can cause a mismatch to the ingame briefing view which defaults to 888x371 (or 555x232 for 640 base res).
*Syntax: '''''integer, integer'''''
*Default Value: '''''888,371'''''}}

===$Ignore Music Files In Music Player:===
{{table232|Music files in this section will not be added to FRED's built-in music player.}}
====+File:====
{{table232|Specifies a file
*Syntax: '''''string'''''}}

===$FRED spacemouse nonlinearities:===
{{table232|
Allows setting custom nonlinearities and scaling for controlling FRED with a spacemouse.
}}
====+Sideways exponent:====
{{table232|
The exponent for input for Sideways spacemouse motion.
*Syntax: '''''float'''''
*Default Value: '''''1'''''}}
====+Sideways scale:====
{{table232|The multiplier for input for Sideways spacemouse motion.
*Syntax: '''''float'''''
*Default Value: '''''1'''''}}
====+Forwards exponent:====
{{table232|The exponent for input for Forwards spacemouse motion.
*Syntax: '''''float'''''
*Default Value: '''''1'''''}}
====+Forwards scale:====
{{table232|The multiplier for input for Forwards spacemouse motion.
*Syntax: '''''float'''''
*Default Value: '''''1'''''}}
====+Upwards exponent:====
{{table232|The exponent for input for Upwards spacemouse motion.
*Syntax: '''''float'''''
*Default Value: '''''1'''''}}
====+Upwards scale:====
{{table232|The multiplier for input for Upwards spacemouse motion.
*Syntax: '''''float'''''
*Default Value: '''''1'''''}}
====+Pitch exponent:====
{{table232|The exponent for input for Pitch spacemouse rotation.
*Syntax: '''''float'''''
*Default Value: '''''1'''''}}
====+Pitch scale:====
{{table232|The multiplier for input for Pitch spacemouse rotation.
*Syntax: '''''float'''''
*Default Value: '''''1'''''}}
====+Bank exponent:====
{{table232|The exponent for input for Bank spacemouse rotation.
*Syntax: '''''float'''''
*Default Value: '''''1'''''}}
====+Bank scale:====
{{table232|The multiplier for input for Bank spacemouse rotation.
*Syntax: '''''float'''''
*Default Value: '''''1'''''}}
====+Heading exponent:====
{{table232|The exponent for input for Heading spacemouse rotation.
*Syntax: '''''float'''''
*Default Value: '''''1'''''}}
====+Heading scale:====
{{table232|The multiplier for input for Heading spacemouse rotation.
*Syntax: '''''float'''''
*Default Value: '''''1'''''}}

===$Skybox internal depth consistency:===
{{table250|If enabled, this will allow skyboxes that use submodels to render the submodels with proper Z-sorting if the 'No Z-Buffer' check box is set to on in FRED. In other words, parts of the skybox closer to the origin point will render in front of sections further away, as might be expected. This flag is enabled by default for FSO version 25.0 onwards
*Syntax: '''''Boolean'''''
*Default Value: '''''YES'''''}}

==#OTHER SETTINGS==
This group contains miscellaneous settings.

===$Fixed Turret Collisions:===
Makes all hits to a turret's barrels count as hits to the turret subsystem. By default, this does not happen unless the point of impact falls inside the model radius of the turret's base.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''

===$Fixed Missile Detonation:===
{{Table220|
*When this flag is set, missiles which reach the center of a submodel will not detonate immediately; they will delay detonation until they have traveled another radius of the submodel. This fixes missile impacts to submodels whose center lies outside the geometry of the submodel. In other words, without this flag, a missile might detonate in the middle of the "bowl" of a concave submodel; with this flag, the missile will travel to the other side of the submodel before it detonates.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Damage Impacted Subsystem First:===
If set, a hit to a physical subsystem will always deal damage to that subsystem first, even if another subsystem is closer to the point of impact. By default, the closest subsystem will always receive damage first.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''

===$Use 3d ship select:===
{{Table224|
*Whether or not to use 3D models for ship select instead of animations
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Default ship select effect:===
{{Table3615|
*This specifies which effect to use for ship select animations when no .ani can be found, or the 3d ship select effect is active. This will default to the FS2 effect.
*Syntax: '''''String'''''
*Possible options are "FS2", "FS1", and "off"}}

===$Use 3d ship icons:===
{{Table224|
*Whether or not to use 3D models for ships in ship/weapon select instead of icons
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Use 3d weapon select:===
{{Table224|
*Whether or not to use 3D models for weapon select instead of animations
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Default weapon select effect:===
{{Table3615|
*This specifies which effect to use for weapon select animations when no .ani can be found, or the 3d weapon select effect is active. This will default to the FS2 effect.
*Syntax: '''''String'''''
*Possible options are "FS2", "FS1", and "off"}}

===$Use 3d weapon icons:===
{{Table224|
*Whether or not to use 3D models for weapons in weapon select instead of icons
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$FS2 effect grid color:===
{{Table250|
*Specifies the grid color for the FS2 loadout animation effect
*Syntax: '''''Integer, Integer, Integer'''''
*Default Value: '''''0, 200, 0'''''}}

===$FS2 effect scanline color:===
{{Table250|
*Specifies the scan-line color for the FS2 loadout animation effect
*Syntax: '''''Integer, Integer, Integer'''''
*Default Value: '''''0, 255, 0'''''}}

===$FS2 effect grid density:===
{{Table250|
*Specifies the number of grid lines in the FS2 loadout animation effect
*Syntax: '''''Integer'''''
*Default Value: '''''7'''''}}

===$FS2 effect wireframe color:===
{{Table250|
*Specifies the wireframe color for the FS2 loadout animation effect
*Syntax: '''''Integer, Integer, Integer'''''
*Default Value: '''''80, 49, 160'''''}}

===$Use 3d overhead ship:===
{{Table224|
*Whether or not to use 3D models for ship overhead view instead of a bitmap in weapon select
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Default overhead ship style:===
{{Table224|
*This specifies which style of overhead view to use if 3d overhead view is active
*Syntax: '''''String'''''
*Possible options are "ROTATE" or "TOPVIEW"
}}
{{Table250|
*'''+Overhead Line Color 1:'''
** The RGB color for ship secondary bank 1.
**Syntax: '''''Color''''', (red, green, blue) respectively, integer value from 0 to 255
**Default value: (64, 192, 192)
*'''+Overhead Line Color 2:'''
** The RGB color for ship secondary bank 1.
**Syntax: '''''Color''''', (red, green, blue) respectively, integer value from 0 to 255
**Default value: (192, 128, 64)
*'''+Overhead Line Color 3:'''
** The RGB color for ship secondary bank 1.
**Syntax: '''''Color''''', (red, green, blue) respectively, integer value from 0 to 255
**Default value: (175, 175, 175)
*'''+Overhead Line Color 4:'''
** The RGB color for ship secondary bank 1.
**Syntax: '''''Color''''', (red, green, blue) respectively, integer value from 0 to 255
**Default value: (100, 100, 100)
}}

===$Always refresh selected weapon when viewing loadout:===
{{Table232|
*When set to true, this always refreshes the weapon shown in view box on the right side of the screen when opening the weapon loadout view. This ensures the viewed weapon is one that can actually be on the selected ship when first clicking on the weapon loadout screen.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Weapons inherit parent collision group:===
{{Table3615|
*When set to true, Weapons fired by a ship will inherit their parents' collision group setting.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Flight controls follow eyepoint orientation:===
{{Table371|
*Specifies that if the player ship's eyepoint happens to rotate into a non-standard orientation, pitch and yaw axes should stay relative to the eyepoint orientation, not the ship. Note that this does not affect the pitch/yaw turning speed, which always remains relative to the ship.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Beams Use Damage Factors:===
{{Table371|
*Specifies that beam weapons will use the tabled damage factors for Armour, Shields and Subsystems. Default is false (i.e. all factors are treated as 1.0)
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Default fiction viewer UI:===
{{Table373|
*Specifies which fiction viewer layout to use in missions that don't specify one. Possible values are as follows:
**"FS2": Standard layout. Requires (2_)fictionviewer and (2_)fictionviewer-m to be present in data\interface.
**"WCS": Moves the "Accept" button to the lower-left corner of the screen. Requires (2_)fictionviewerb and (2_)fictionviewer-mb to be present in data\interface.
**"auto": Selects "WCS" if the appropriate files are present; otherwise, selects "FS2". This is the default setting.}}

===$Movie subtitle font:===
{{Table382|
*Specifies which font should be used for displaying subtitles in the cutscene player. This should be the name given to this font in the fonts table. Since movie subtitles can contain Unicode text it is a good idea to enable Unicode mode when movie subtitles are used but this is not enforced by this option.
*Syntax: '''''String'''''}}

===$Movie subtitle color:===
{{Table242|
*Specifies which color should be used for displaying subtitles in the cutscene player.
*Syntax: '''''Integer, Integer, Integer, Integer'''''
*Default Value: '''''255, 255, 255, 255'''''}}

===$Disable built-in translations:===
{{Table382|
*Turns off hard-coded translations, e.g. Transport -> Transporter in German. All strings will either use their XSTR entry or else not be translated.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Weapon shockwave damage respects huge ship flags:===
{{Table382|
*Controls whether weapon shockwaves will respect the huge/supercap ship flags. In retail they do not.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Enable external default scripts:===
{{Table382|
*Enables the loading of external scripts with the same name as a built-in script. Otherwise, uses the version of the script included in the executable (currently, just cfile_require.lua).
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Player warpout speed:===
{{Table190|
*Defines the speed the player must reach to warp out.
*Syntax: '''''Float'''''
*Default Value: '''''40.0'''''}}

===$Target warpout match percent:===
{{Table190|
*Defines how close to the warpout speed the player needs to be to actually warp out.
*Syntax: '''''Float''''', between 0.0 and 1.0
*Default Value: '''''0.05''''' (5%)}}

===$Minimum player warpout time:===
{{Table190|
*The [[Ships.tbl#.24Warpout_Engage_Time:|default amount of time]], in seconds, warping out will take before actually starting to check whether the player is the right speed.
*Syntax: '''''Float'''''
*Default Value: '''''3.0'''''}}

===$Enable in-game options:===
{{Table190|
*Mode whereby various settings can be modified by FSO while it's still running, rather than being set by the launcher before execution. By default is now ON, and can be accessed by going to the Options menu and pressing F3.
*Syntax: '''''Boolean'''''
*Default Value: '''''YES'''''}}

===$Dinky Shockwave Default Multiplier:===
{{Table190|
*Amount of damage, as a multiple of normal shockwave damage, assigned to a weapon's [[Weapons.tbl#.24Dinky shockwave:|dinky shockwave]] by default. To get the same behavior FSO had from 2005-2019, set this to 0.25.
*Syntax: '''''Float'''''
*Default Value: '''''1.0'''''}}

===$Shockwaves Always Damage Bombs:===
{{Table202|
*Enables all bombs being damaged by shockwaves. Previously only those marked with flags could be damaged.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Shockwaves Damage All Object Types Once:===
{{Table202|
*Keeps any object from being damaged more than once by a shockwave. The default behavior is for asteroids and flagged missiles to be damaged every frame by the shockwave.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Shockwaves Inherit Parent Weapon Damage Type:===
{{Table224|
*When enabled, the shockwaves of weapons that have a defined damage type automatically inherit that damage type, rather than dealing "typeless" damage. As this behavior is more intuitive than when this flag is disabled, mods targeting 22.4 or newer versions of FSO will have it enabled by default.
*Syntax: '''''Boolean'''''
*Default Value: '''''True''''' for mods targeting 22.4 or newer versions of FSO, otherwise '''''False'''''}}

===$Inherited Shockwave Damage Type Added Suffix:===
{{Table224|
*When combined with "$Shockwaves Inherit Parent Weapon Damage Type:", this string is added to the inherited damage type to define the shockwave's damage type. For example, if a weapon has the damage type "heavy" and the provided suffix is "-shock", then that weapon's shockwave's damage type would default to "heavy-shock".
*Note: When defined, this also implicitly sets the equivalent value for dinky shockwaves, below.
*Syntax: '''''String'''''}}

===$Inherited Dinky Shockwave Damage Type Added Suffix:===
{{Table224|
*The same as "$Inherited Shockwave Damage Type Added Suffix:", except specifically for "dinky" shockwaves.
*Syntax: '''''String'''''}}

===$Default Shockwave Damage Type:===
{{Table224|
*If a weapon's shockwave doesn't have a damage type set, it will have this damage type instead (when "$Shockwaves Inherit Parent Weapon Damage Type:" is enabled, this will only be used if the weapon itself also doesn't have a damage type set).
*Note: When defined, this also implicitly sets the equivalent value for dinky shockwaves, below.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Default Dinky Shockwave Damage Type:===
{{Table224|
*The same as "$Default Shockwave Damage Type:", except specifically for "dinky" shockwaves.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Use Engine Wash Intensity:===
{{Table190|
*Allows the game to use the [[ships.tbl#.24Intensity::|Intensity]] value when calculating Engine Wash effects.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Apply HUD shudder to chase view:===
{{Table232|
*Applies hud shudder (afterburner and engine wash) also to chase view. Does not override the command line toggle.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Swarmers Lead Targets:===
{{Table202|
*Causes swarm missiles to lead their targets by default, and will make use of [[Weapons.tbl#.2BTarget_Lead_Scaler:|Target Lead Scaler]] if specified, like normal aspect seekers.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''}}

===$Damage Threshold for Weapons Subsystems to Trigger Turret Inaccuracy:===
{{Table202|
*Specifies the damage threshold for when turrets become less accurate due to weapon subsystem damage. In other words, how damaged do a ship's aggregated weapons systems have to be before the turrets become inaccurate? Value must be between 0.0-1.0 (includes 0.0 and 1.0).
*Syntax: '''''Float'''''
*Default Value: '''''0.7'''''}}

===$AI use framerate independent turning:===
{{Table202|
*Without this flag, missiles turn rate is directly dependent on the current framerate. When enabled their turn rate will be consistent, with the "true" turning taken to be observed turning at 60fps. This flag also affects ships, but the instability is only apparent at extremely low framerates, and so the change will not be apparent.
*Syntax: '''''Boolean'''''
*Default Value: '''''True'''''}}

====+AI respect tabled turn time and rotdamp:====
{{Table202|
*Due to complicated physics issues caused by retail not using the above method, tabled turn times on ships and missiles are not representative of actual observed turn times. The above flag makes it consistent, but this flag will make it accurate to what is actually listed in the table.
*Additionally, rotdamp is now used properly by the AI in a similar manner to players. More rotdamp will result in slower rotational acceleration, and less results in faster acceleration.
*NOTE: BEWARE OF ADDING THIS FLAG TO AN EXISTING MODPACK. NEARLY EVERY SINGLE TURN TIME WILL NEED TO BE CHANGED.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Player starts in third person/chase view by default:===
{{Table212|
*When this flag is set, a player will start the mission in the chase view, not in the cockpit view.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Custom briefing icons always override standard icons:===
{{Table214|
*Custom ship briefing icons will always be shown when the briefing icon is a ship, but not when it is a non-ship icon such as a planet. Set this flag to use custom briefing icons in all cases.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Lead indicator behavior:===
{{Table224|
Changes how Lead Indicators behave when multiple weapon banks are linked and in range.
When set to default, if you have linked weapons, only the indicator for the one with the farthest range will be drawn.
When set to multiple, a lead indicator is drawn for all primary weapons in range when you have them linked.
When set to average, a single lead indicator is drawn in the average of the position where each of them would usually be drawn.
*Syntax: '''''String'''''
** Valid options are '''''default''''', '''''multiple''''' and '''''average'''''
*Default Value: '''''default'''''
}}

===$Use distant firepoint for all turrets:===
{{Table224|
*Causes the game to use firepoint-based target leading calculations for all turrets. This is useful if all or most turrets in a given mod has firepoints that are distant from their center-point.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Enable Discord rich presence:===
{{Table224|
*Enables or disables the built-in Discord game-status reporting.
*Syntax: '''''Boolean'''''
*Default Value: '''''True'''''}}

===$Always hide hidden ships in hotkey list:===
{{Table224|
*Whether or not to always hide ships with HIDDEN hotkey (set in FRED), even in the in-mission hotkey menu.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Allow automatically assigning personas:===
{{Table232|
*Whether or not the game will automatically assign personas to ships that have no persona set.
*Syntax: '''''Boolean'''''
*Default Value: '''''True'''''}}

===$Countermeasures use capacity:===
{{Table232|
*Whether or not Countermeasures use tabled capacity.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Calculate subsystem hitpoints after parsing:===
{{Table234|
*Causes subsystem hitpoints to be calculated after all ships.tbl and -shp.tbm files have been parsed. This allows subsystem percentages to correctly reflect the final hull value rather than the first hull value encountered.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Contrails use absolute speed:===
{{Table240|
*Causes contrails to be created based on speed in any direction, rather than just forward speed. This allows contrails to appear when a ship is moving in a direction other than forwards.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Fix scripted velocity:===
{{Table242|
*If this setting is enabled, object velocity set via script will wholly determine the change in position for that frame, ignoring ''all'' other in-engine concerns. Otherwise, the game engine will likely overwrite/ignore any changes, depending on when the changes were made in the frame.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Preload briefing icon models:===
{{Table250|
*If set, this forces preloading of models used for briefing icons. This only loads models used for icons that haven't already been loaded for the mission. This is useful for [https://github.com/MjnMixael/SCPUI/wiki SCPUI]'s where hovering over an icon shows the model without having to click on it and the stutter when it loads models not used in mission.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Behavior for pressing Escape key in options menu:===
{{Table250|
*If set to 'save', the escape key for the HUD and Options screen saves options when leaving those screens (ie it does the same thing as pressing Ctrl-Enter/Accept). By default (or if set to 'default') the Escape key will not save any changed values when exiting those screens.
*Syntax: '''''String'''''
*Default Value: '''''default'''''}}

===$Use closest distance method for 'Target Hostile Bomb or Bomber' control:===
{{Table250|
*If set to true, the 'Target Hostile Bomb or Bomber' control will target the closest hostile bomb or bomber, similar to how the 'Target Closest Hostile' key works. By default, the 'Target Hostile Bomb or Bomber' control will not sort by distance and simply only target in order of oldest to youngest objects (ie which object spawned first in the mission).
*Syntax: '''''Boolean'''''
*Default Value: '''''false'''''}}

===$Objects targeted with 'Target Hostile Bomb or Bomber' control:===
{{Table250|
*Determines what can be targeted when using the 'Target Hostile Bomb or Bomber' control. By default this control targets both bombs and bombers, which is the behavior if this field is set to 'default' or 'bombs and bombers'. If set to 'only bombs', the key will only target bombs and not target bombers. If set to 'only bombers', the key will only target bombers and not target bombs.
*Syntax: '''''String'''''
*Default Value: '''''default'''''}}

===$Fix asteroid/debris field bounding box checks:===
{{Table250|
*Fixes a bug where asteroid and debris fields did not properly check for whether large ships were within bounds.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Disable intro cutscene:===
{{Table250|
*If set, this disables loading of any cutscenes as the game starts that might play before the player reaches the pilot select screen.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Show locked status for scramble missions:===
{{Table250|
*If set, scramble mission will show a text line right below the words 'Weapons Loadout' that states "Ships/Weapons Locked" (XSTR 749), thus the player can easily see their loadouts are locked and they do not have to check the loaoout buttons on every mission.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Disable expensive turret target check:===
{{Table250|
*If set, this value speeds up turret target checking. By default, turret target acquisition was spending a lot of time doing a raycast, the result of which was barely used at all. If we don't need the target normal, all it does is get a target point slightly more accurate, but in practice it really isn't noticeable at all whether the target point of the turret is actually on the surface of the ship, or maybe on the other side of the ship.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Threshold below which shield skips damage:===
{{Table250|
*By default, FSO logic dictates that shields collisions and any related sound or visuals related to shields are skipped if the shields are under 10%. This value allows modders to customize the value, though the value must be between 0.0 and 1.0.
*Syntax: '''''Float'''''
*Default Value: '''''0.1'''''}}

===$Minimum ship radius for persistent debris::===
{{Table250|
*Ships with a radius larger than this value will have infinite debris lifetimes.
*Syntax: '''''Float'''''
*Default Value: '''''50'''''}}

===$Zero-radius explosions skip fireballs:===
{{Table260|
*If set, explosions with a visual radius of 0 will not have fireballs created, and will not have the fireball lifetime added to the explosion lifetime.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Link special-point subsystems to -destroyed submodels:===
{{Table260|
*If set, a special-point subsystem will be linked to its corresponding -destroyed submodel (if one exists). The -destroyed submodel will be shown when the subsystem is destroyed, and hidden again if the subsystem is repaired. By default, only submodel subsystems are linked to their corresponding -destroyed submodels.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

===$Fix collision moment of inertia:===
{{Table262|
*Fixes a bug in collision physics where an object's moment of inertia was applied as though the object were facing the inverse of its actual orientation (that is, an orientation that would rotate it back to the identity orientation). Without this flag, a ship that is not aligned with the coordinate axes may rotate around the wrong axis, or by the wrong amount, when something collides with it. This applies to collisions among ships, asteroids, and debris. It does not apply to weapon impacts, which were never affected by the bug.
*Syntax: '''''Boolean'''''
*Default Value: '''''False'''''}}

==#END==
Required. The last line of the table must be #END

==Sample Entry==

#CAMPAIGN SETTINGS
$Default Campaign File Name: NewCampaignFile

#Ignored Campaign File Names
$Campaign File Name: FreeSpace2.fc2

#HUD SETTINGS
$Directive Wait Time: 5000

#SEXP SETTINGS
$Loop SEXPs Then Arguments: True

#OTHER SETTINGS
$Fix Turret Collisions: True

#END

[[Category:Tables]]

RCSS Properties

2026-10-28T18:35:13Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-Properties}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-Properties}}

RCSS Scrollbars

2026-10-28T18:35:04Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-Scrollbars}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-Scrollbars}}

RCSS FontEffects

2026-10-28T18:34:53Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-FontEffects}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-FontEffects}}

RCSS Decorators

2026-10-28T18:34:42Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-Decorators}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-Decorators}}

RCSS CursorsDragTab

2026-10-28T18:34:31Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-CursorsDragTab}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-CursorsDragTab}}

RCSS Text

2026-10-28T18:34:15Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-Text}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-Text}}

RCSS Fonts

2026-10-28T18:34:06Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-Fonts}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-Fonts}}

RCSS ColorsBackgrounds

2026-10-28T18:33:56Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-ColorsBackgrounds}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-ColorsBackgrounds}}

RCSS VisualEffects

2026-10-28T18:33:46Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-VisualEffects}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-VisualEffects}}

RCSS VisualModel

2026-10-28T18:33:36Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-VisualModel}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-VisualModel}}

RCSS BoxModel

2026-10-28T18:33:27Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-BoxModel}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-BoxModel}}

RCSS Selectors

2026-10-28T18:33:17Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-Selectors}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-Selectors}}

RCSS Syntax

2026-10-28T18:33:08Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-Syntax}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RCSS-Syntax}}

RML Events

2026-10-28T18:32:56Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RML-Events}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RML-Events}}

RML Templates

2026-10-28T18:32:47Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RML-Templates}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RML-Templates}}

RML DataDisplay

2026-10-28T18:32:38Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RML-DataDisplay}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RML-DataDisplay}}

RML Controls

2026-10-28T18:32:26Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RML-Controls}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RML-Controls}}

RML Forms

2026-10-28T18:32:16Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RML-Forms}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RML-Forms}}

RML StyleSheets

2026-10-28T18:32:01Z

MjnMixael:

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RML-StyleSheets}}

RML Images

2026-10-28T18:31:48Z

MjnMixael:

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RML-Images}}

RML Elements

2026-10-28T18:31:34Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RML-Elements}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RML-Elements}}

RML Documents

2026-10-28T18:31:22Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RML-Documents}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/RML-Documents}}

Librocket API Event

2026-10-28T18:31:08Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/Librocket-API-Event}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/Librocket-API-Event}}

Librocket API Element

2026-10-28T18:30:55Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/Librocket-API-Element}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/Librocket-API-Element}}

Librocket API Document

2026-10-28T18:30:44Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/Librocket-API-Document}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/Librocket-API-Document}}

Librocket API Context

2026-10-28T18:30:31Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/Librocket-API-Context}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/Librocket-API-Context}}

Librocket API Reference

2026-10-28T18:30:19Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/Librocket-API-Reference}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/Librocket-API-Reference}}

Librocket

2026-10-28T18:30:02Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/Librocket}}"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/Librocket}}

System map.tbl

2026-10-28T18:29:50Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/system_map.tbl}} Category:SCPUI Category:Tables"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/system_map.tbl}} [[Category:SCPUI]] [[Category:Tables]]

Options.tbl

2026-10-28T18:29:38Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/options.tbl}} Category:SCPUI Category:Tables"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/options.tbl}} [[Category:SCPUI]] [[Category:Tables]]

Nodemap.tbl

2026-10-28T18:29:27Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/nodemap.tbl}} Category:SCPUI Category:Tables"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/nodemap.tbl}} [[Category:SCPUI]] [[Category:Tables]]

Keywords.tbl

2026-10-28T18:29:15Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/keywords.tbl}} Category:SCPUI Category:Tables"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/keywords.tbl}} [[Category:SCPUI]] [[Category:Tables]]

Journal.tbl

2026-10-28T18:29:01Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/journal.tbl}} Category:SCPUI Category:Tables"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/journal.tbl}} [[Category:SCPUI]] [[Category:Tables]]

Achievements.tbl

2026-10-28T18:28:50Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/achievements.tbl}} Category:SCPUI Category:Tables"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/achievements.tbl}} [[Category:SCPUI]] [[Category:Tables]]

Scpui.tbl

2026-10-28T18:28:37Z

MjnMixael: Replaced content with "{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/scpui.tbl}} Category:SCPUI Category:Tables"

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki/scpui.tbl}} [[Category:SCPUI]] [[Category:Tables]]

Scpui

2026-10-28T18:28:18Z

MjnMixael: Replaced content with "500px {{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki}} Category:SCPUI"

[[Image:SCPUI-trim.png|center|500px]]

{{SCPUI moved|https://github.com/MjnMixael/SCPUI/wiki}} [[Category:SCPUI]]

Template:SCPUI moved

2026-10-28T18:24:10Z

MjnMixael: Notice for pages moved to the SCPUI GitHub wiki

<div style="border:1px solid #888; padding:8px 12px; margin-bottom:1em;">
'''This page has moved.''' SCPUI documentation now lives on the [https://github.com/MjnMixael/SCPUI/wiki SCPUI GitHub wiki]. 
See '''[{{{1}}} the new version of this page]'''. The old content is still available in this page's history.
</div>

Scpui.tbl

2026-03-26T14:42:50Z

MjnMixael: /* #Settings */

{{SCPUI_table}}
{{Tables}}
Scpui.tbl is used by the [[SCPUI]] script system to define what [[List_of_Game_States|engine game states]] are linked to [[librocket]] RML files. This effectively allows SCPUI to override a built-in game UI with one of its own. This table also allows setting various background definitions for UIs on a granular basis.

SCPUI.tbl can be extended with xxx-ui.tbm.

==SCPUI.tbl==
*SCPUI defines what game states and substates exist for SCPUI through the use of this table file and modular -ui.tbms.
*Begins with one of the section names and ends with #End

==#Settings==
*This section defines a few global SCPUI settings

===$Mod ID:===
*The mod ID to use. By default this will match your mod's path root folder. For example, [[bta|Between the Ashes]] has a -mod line like <code>-mod BTA-2.0.0\content</code> and so the default Mod ID will resolve to <code>BTA</code>. If your game runs without a -mod command line then it would be a good idea to set an ID here to prevent it from being "unknown_mod_id".
*Syntax: '''''string'''''

===$Default FSO Font Name:===
*The Font name or index from fonts.tbl that SCPUI should use to get a base pixel value from. By default it will use the font at index 1.
*Syntax: '''''string'''''

===$Hide Multiplayer:===
*Hides all references and navigation to multiplayer UI screens and options. Useful if your mod does not support Multi.
*Syntax: '''''boolean'''''

===$Disable during Multiplayer:===
*Entirely disables SCPUI when in multiplayer mode.
*Syntax: '''''boolean'''''

===$Data Saver Multiplier:===
*A numeric multiplier used to generate SCPUI's save data hash. Generally this is not needed but can be useful if there are conflicts between mods.
*Syntax: '''''integer'''''

===$Ship Icon Width:===
*Specifies the width of the icon used for ships in the SCPUI system.
*This value is optional. If not provided, a default width of 128 will be used.
*Syntax: '''''integer'''''

===$Ship Icon Height:===
*Specifies the height of the icon used for ships in the SCPUI system.
*This value is optional. If not provided, a default height of 112 will be used.
*Syntax: '''''integer'''''

===$Weapon Icon Width:===
*Specifies the width of the icon used for weapons in the SCPUI system.
*This value is optional. If not provided, a default width of 112 will be used.
*Syntax: '''''integer'''''

===$Weapon Icon Height:===
*Specifies the height of the icon used for weapons in the SCPUI system.
*This value is optional. If not provided, a default height of 48 will be used.
*Syntax: '''''integer'''''

===$Use Legacy Slider For Volume:===
*Forces SCPUI to use the retail style 10-dot slider for volume controls instead of the more modern range slider controls.
*This value is optional. If not provided, a default false will be used.
*Syntax: '''''boolean'''''

===$Database Unread Show String Badge:===
*If true, then unread database entries will display a text badge (such as "NEW!").
*This value is optional. If not provided, the default is false.
*Syntax: '''''boolean'''''

===$Database Unread String Badge Class:===
*Specifies the RCSS class(es) to apply to the unread string badge element.
*This allows customization of font color, weight, or other text styling.
*This value is optional. If not provided, no class will be applied.
*Syntax: '''''string''''' (RCSS class name or space-separated list of class names)

===$Database Unread String Badge Text:===
*Specifies the text displayed in the unread string badge.
*If not provided, the default is the localized "NEW!" string.
*Syntax: '''''string'''''

===$Database Unread Show Icon Badge:===
*If true, then unread database entries will display an icon badge (an image).
*This value is optional. If not provided, the default is false.
*Syntax: '''''boolean'''''

===$Database Unread Icon Badge Class:===
*Specifies the RCSS class(es) to apply to the unread icon <img> element.
*This allows control of icon sizing, margins, and positioning.
*This value is optional. If not provided, no class will be applied.
*Syntax: '''''string''''' (RCSS class name or space-separated list of class names)

===$Database Unread Icon Badge Filename:===
*Specifies the filename of the icon to use for the unread badge.
*The path is relative to the mod’s interface art directory.
*This value is optional. If not provided, no icon is shown.
*Syntax: '''''string''''' (filename, e.g. "new_badge.png")

===$Database Unread Badge Position:===
*Controls whether the unread badge (text and/or icon) is displayed before or after the entry title.
*Valid values are "left" or "right". Any invalid value will default to "left".
*This value is optional. If not provided, the default is "left".
*CURRENTLY NOT SUPPORTED AND HARD RESETS TO LEFT
*Syntax: '''''string'''''

===$Database Unread Item Class:===
*Specifies the RCSS class(es) to apply to the entire title text when the entry is unread.
*This allows you to change the appearance of the entry header (e.g. brighter text, bold, highlight).
*This value is optional. If not provided, no additional class is applied.
*Syntax: '''''string''''' (RCSS class name or space-separated list of class names)

===$Minimum Splash Time:===
*Specifies the minimum time each splash screen should be shown in seconds during preload.
*This value is optional. If not provided, a default time of 2 will be used.
*Syntax: '''''integer'''''

===$Fade Splash Images:===
*Determines if the splash images should fade in and out during preload.
*This value is optional. If not provided, a default value of true is used.
*Syntax: '''''boolean'''''

===$Draw Splash Images:===
*Determines if the splash images should be drawn at all during preload.
*This value is optional. If not provided, a default value of true is used.
*Syntax: '''''boolean'''''

===$Draw Splash Text:===
*Determines if the splash text should be drawn at all during preload.
*This value is optional. If not provided, a default value of true is used.
*Syntax: '''''boolean'''''

===$Always Allow Show All:===
*Allows the Ctrl-Shift-S "show all" feature used in the tech room and other UIs to be used in release builds
*This value is optional. If not provided, a default value of false is used.
*Syntax: '''''boolean'''''

==#State Replacement==
*This section defines what RML files are used to replace specific game states.

===$State:===
*The game state to replace from [[List_of_Game_States|FSO's game states]]
*Syntax: '''''string'''''

===+Substate:===
*The name of the substate
*Required for GS_STATE_SCRIPTING
*Syntax: '''''string'''''

===+Markup:===
*The path to the RML file definition to use for the game state
*Must include the file path
*Syntax: '''''string'''''

==#Background Replacement==
*Defines what css class to use to set the background for UIs on a per-campaign or per-mainhall basis.
*Mainhall defines take priority over Campaign defines.
*By default all UIs use the css class<code>general_bg</code>.

===$Campaign Background:===
*Designates that a new define will follow
*Has no arguments

====+Campaign Filename:====
*The campaign filename without extension
*Syntax: '''''string'''''

====+RCSS Class Name:====
*The css class name to use as a replacement. Make sure this class exists in a loaded rcss file!
*Syntax: '''''string'''''

===$Mainhall Background:===
*Designates that a new define will follow
*Has no arguments

====+Mainhall Name:====
*The mainhall name
*Syntax: '''''string'''''

====+RCSS Class Name:====
*The css class name to use as a replacement. Make sure this class exists in a loaded rcss file!
*Syntax: '''''string'''''

==#Briefing Stage Background Replacement==
*Defines customized briefing grid backgrounds on a per-mission or per-briefing-stage level.
*The background is <code>br-black.png</code> by default.

===$Briefing Grid Background:===
*Designates that a new define will follow
*Has no arguments

====+Mission Filename:====
*The mission filename where the briefing background will be replaced
*Without extension
*Syntax: '''''string'''''

====+Default Background Filename:====
*The new default background file to use for the mission
*WITH extension
*Syntax: '''''string'''''

====+Stage Override:====
*The briefing stage of the mission to define an override for
*Not required for every stage. Any stage without an override will use the mission default
*Syntax: '''''integer'''''

=====+Background Filename:=====
*The new default background file to use for the stage
*WITH extension
*Syntax: '''''string'''''

==#Medal Placements==
*This section defines how medals are placed in SCPUI's ui because SCPUI cannot use the definitions in the retail [[medals.tbl|medals.tbl.]]
*SCPUI expects 5 image files for each medal, a blank indent of the medal (no medal), the medal with no badge, the medal with bronze badge, the medal with silver badge, the medal with gold badge. These should be named MEDALNAME_00, MEDALNAME_01, MEDALNAME_02, MEDALNAME_03, MEDALNAME_04 where MEDALNAME is the [[Medals.tbl#.24Bitmap:|Bitmap defined in medals.tbl]].

===$Medal:===
*The name of the medal as defined in [[Medals.tbl#.24Name:|medals.tbl]].
*Syntax: '''''string'''''

====+Alt Bitmap:====
*Allows specifying an alternate SCPUI specific bitmap to use in the medals ui instead of the bitmap tabled for the retail UI
*This is mostly for FSPort since SCPUI carries artwork for all retail medals but sequentially numbers them for FS1 medals. A translation list of medal numbers is [[Scpui.tbl#FS1_Medal_Numbering_Chart|below.]]
*Syntax: '''''string'''''

====+Alt Debrief Bitmap:====
*Allows specifying an alternate SCPUI specific bitmap to use in the debrief ui instead of the bitmap tabled for the retail UI
*This is mostly for FSPort since SCPUI carries artwork for all retail medals but sequentially numbers them for FS1 medals. A translation list of medal numbers is [[Scpui.tbl#FS1_Medal_Numbering_Chart|below.]]
*Syntax: '''''string'''''

====+Position X:====
*The X coordinate for the medal
*Syntax: '''''float'''''

====+Position Y:====
*The Y coordinate for the medal
*Syntax: '''''float'''''

====+Width:====
*The width of the medal
*Syntax: '''''float'''''

===FS1 Medal Numbering Chart===
SCPUI carries artwork for all FS1 and FS2 medals. The bitmaps for FS1 and FS2 in retail are numerically numbered in such a way that they would overlap so SCPUI, technically being a mod of FS2, adds the FS1 medal artwork and sequentially numbers them starting after the last FS2 medal. Here is a quick conversion chart.

{| class="wikitable"
! FS1 Original Number
! SCPUI Number
|-
| 00
| 20
|-
| 01
| 01
|-
| 02
| 02
|-
| 03
| 12
|-
| 04
| 15
|-
| 05
| 17
|-
| 06
| 18
|-
| 07
| 07
|-
| 08
| 14
|-
| 09
| 19
|-
| 10
| 16
|-
| 11
| 13
|}

===Example===
<pre>
#State Replacement

$State: GS_STATE_INITIAL_PLAYER_SELECT
+Markup: data/interface/markup/pilot_select.rml

$State: GS_STATE_SCRIPTING
+Substate: Newsroom
+Markup: data/interface/markup/journal.rml

#Background Replacement

$Campaign Background:
+Campaign Filename: bta1_m
+RCSS Class Name: bta1_bg

#Briefing Stage Background Replacement

$Briefing Grid Background:
+Mission Filename: bta2_m1_01
+Default Background Filename: br-black.png
+Stage Override: 1
+Background Filename: br-deltaserpentis.png
+Stage Override: 2
+Background Filename: br-stars.png
+Stage Override: 5
+Background Filename: br-luyten.png

#End
</pre>
[[Category:Tables]]
[[Category:SCPUI]]

Scpui

2026-03-17T14:39:12Z

MjnMixael: /* Custom Data */

[[Image:SCPUI-trim.png|center|500px]]

SCPUI is a term that refers to both the LUA Script implementation and the user interface LUA API in the FreespaceOpen engine available from versions 23.2 onwards. It is intended to be used with the [[librocket|librocket libraries]] to replace the base Freespace Open interface in an easily customizable way through LUA scripts.

The original implementation of SCPUI was started by m!m and finished by MjnMixael. This specific implementation attempts to replicate the original Freespace UI experience while offering enhancements such as in-game options not normally available.

[[librocket|For documentation on the Librocket API, go here.]]

The GitHub source files for SCPUI are available [https://github.com/MjnMixael/SCPUI here.] However, it is highly recommended that you have your game or mod rely on the core SCPUI mod on Knossos.NET [https://fsnebula.org/mod/SCPUI here.]

==Overview==
SCPUI works by completely overriding a given game state's internal code. Everything that interface should be expected to do must be handled in the Lua scripts. Methods to get and set appropriate game data are supplied by FSO's UI API. The core file that handles this is <code>scpui_system_core.lua</code>. This file is SCPUI's state management controller. If it detects a valid SCPUI interface for a given game state, it will load a librocket file and begin execution of the appropriate scripts.

An SCPUI game state definition has three main files; RML, RCSS, and LUA. More information is available on those specific pages, but for now it's enough to know that RML is a kind of base HTML, RCSS is a base CSS, and LUA is an FSO compatible LUA file.

The lua file for that state will be run until an FSO game state change is detected. When that happens, the ui_system-sct will clean up the librocket elements and then check if a new set of SCPUI files should be loaded.

The FSO Engine's Lua API provides a library of methods for interfacing with UI code. Please consult the [[Command-Line_Reference#-output_scripting|scripting.html]] file and the '''''UserInterface (ui)''''' library for details.

==Scpui.tbl==
SCPUI's global settings can be modified with scpui.tbl or xxx-ui.tbm files.
[[scpui.tbl|Documentation on scpui.tbl is available here.]]

==Visual Customization==
Unlike FSO's built-in User Interface, SCPUI liberally re-uses visual assets wherever possible. Because of this, there are only about 225 image files compared to retail's thousands. This makes changing the look and feel of the UI incredibly easy even for those who are not interested in modifying the underlying Lua code.

===Custom.RCSS===
Every UI screen loads <code>custom.rcss</code> as its primary style sheet in addition to the rest of the style sheets for that UI screen. The idea here is that you can list all of your custom styles in that file stored in your own mod's game data. The file should be <code>data/interface/css/custom.rcss</code> and you can start by copying the file directly out of SCPUI's base install. This is also where you'll set your mod's primary font file.

===Fonts===
Fonts are defined in SCPUI using an <code>.rcss</code> style sheet. In the base install of SCPUI, the primary font is defined in <code>custom.rcss</code> like this

<pre>
body
{
font-family: BankGothic Md BT;
font-weight: normal;
font-style: normal;
}
</pre>

Note that the font-family is the font's name as defined in the font metadata and not the filename. In some fonts that may strictly be the font family name only, but not always. For example, <code>Noto Sans Medium</code> actually needs to be listed as <code>Noto Sans</code>.

You will want to put all family variant font files (for example: BankGothic.ttf, BankGothic-bold.ttf, BankGotic-italic.ttf) in the <code>data/fonts</code> directory.

SCPUI will try to match it's default font size to FSO's internal font size, which be default is the first font in fonts.tbl. You can customize this setting in [[scpui.tbl|scpui.tbl.]]. You will also want to enable <code>+Auto Scale</code> and <code>+Can Scale</code> on your default FSO font in [[fonts.tbl|fonts.tbl]] so that SCPUI's font and FSO's font can scale together as players will expect.

===Background===
You can change the main background image for all SCPUI screens by simply replacing <code>bg.png</code>. Other background features are covered in the [[scpui.tbl|scpui.tbl documentation.]]

===Logo===
There are several UI screens that use a logo image. It comes in three main variants...

*Standard
**Replace <code>logo.png</code> to replace the standard logo throughout all of SCPUI.
*Wide
**For FS2, this logo is the version with the "wings". Replace <code>logo-wide.png</code> to change this one.
*Loop
**In FS2 this is the [[Special_Operations_Command|SOC]] logo used in the Loop Brief UI. For this one replace <code>loop-logo.png</code>

===Loading Screen Backgrounds===
Loading screen backgrounds are handled a little differently than in base FreespaceOpen. You must create or modify the <code>load_screen_bgs.rcss</code> file to add the custom backgrounds you wish to use. In that file create a css class with the mission filename that is to have a custom screen and then define the file like the example below.

<pre>
.bta1_m1_01 {
background-decorator: image;
background-image: 3_Load_1M1_01.png;
}
</pre>

Mission <code>bta_m1_01.fs2</code> will now have the image <code>3_Load_1M1_01.png</code> used as it's background.

To modify the loading bar see [[scpui#UI_Topics|UI Topics.]]

===Keywords===
SCPUI has a built in feature to allow coloring keywords automatically for UI the various briefing screens. It can also, optionally, add tooltips to these keywords. This feature works in Briefing, Command Briefing, Debriefing, Fiction Viewer, Loop Briefing, and Red Alert. Definitions for keywords are tabled in a special table. See [[keywords.tbl|keywords.tbl documentation]] for more information.

===Elements===
The main UI elements (window boxes, button panels, etc) are all re-used liberally throughout SCPUI. At the time of writing this article, there are 53 of these files in total. You can modify them however you like.

*It is highly recommended you do not change the aspect ratio of these images if you do not want to have to modify RML and RCSS files.

===Buttons===
There are a number of button styles that SCPUI uses to match FS2's retail UI. Each button has at least three images: Main, Hover, and On. Generally they are designated like the following example:
<pre>
arrow-up.png ;;Main
arrow-up-h.png ;;Hover
arrow-up-o.png ;;On
</pre>

In some cases there are Positive and Negative versions. These are named like the following example:
<pre>
select.png ;;Main
select-pos-h.png ;;Positive Hover
select-pos-o.png ;;Positive On
select-neg-h.png ;;Negative Hover
select-neg-o.png ;;Negative On
</pre>

===Custom Data===
SCPUI often uses special [[Ships.tbl#$Custom data:|Custom Data]] for various special cases. This provides a way to set values per-object without needing additional tables. All keys are optional.
{| class="wikitable"
! Key
! Value Type
! Supported Tables
! Description
|-
| <code>HideInTechRoom</code>
| Boolean (default: false)
| ships.tbl, weapons.tbl
| If true, the object is always hidden from the tech room, including when using Ctrl+S.
|-
| <code>LoadoutListPriority</code>
| Integer (default: -1)
| ships.tbl, weapons.tbl
| Controls sorting in ship and weapon loadout UIs. 1 is highest priority; -1 means no priority.
|}

==Briefing Color Tags==
SCPUI supports two methods for coloring text in briefings. It supports the retail style [[Briefing Text|color tag]] system out of the box. However, SCPUI also has its own HTML-based approach to styling text. It works everywhere that classic color tags do - briefings (including command, loop, and red alert briefings), debriefings, and the fiction viewer - but also the tech room, campaign descriptions, and nearly everywhere that long-form text is supported. For it to work in briefings, the text must be put in "HTML mode" by putting <code>!html</code> at the start, followed by a space. Everywhere else will work without that tag.

Text in HTML mode may contain HTML markup. Text may be styled using <code></code> tags with appropriate classes drawn from common.rcss; inline styles are also supported. FSO and HTML both make use of double quotes and slashes; to minimize conflicts, using single quotes and writing slashes as <code>$slash</code> is recommended. A complete example might look something like this: <code>!html Pilot attend!<$slashspan> Today, we'll be escorting the GTC Examplar<$slashspan> as she raids Shivan<$slashspan> positions throughout Gamma Draconis<$slashspan>.</code> The list of color classes available by default is at the bottom of <code>common.rcss</code>. You can add more to <code>custom.rcss</code> if needed.

It is, however, rarely necessary to perform simple styling like this manually: SCPUI's [[Keywords.tbl]] may be used to automate common styling rules.

==Loadout Select Icons==
SCPUI supports both 2D pre-drawn icons as well as generated 3D icons. However, they are handled a little differently than inside base FSO. SCPUI pre-generates icon images on game start and displays those in place of the actual icons. Icons are generated during SCPUI's splash screens and cached to the appdata directory to speed up load times on subsequent gameplay instances.

To use 3D icons generated from ship models you must have 3D icons enabled in your [[game_settings.tbl#.24Use_3d_ship_select:|game_settings.tbl]] and for weapons you must have a [[Weapons.tbl#.24Tech_Model:|Tech Model defined]].

To use 2D icons you must have a Select Icon defined for the [[Ships.tbl#.24Ship_Icon:|ship]] or [[Weapons.tbl#.24Icon:|weapon]].

You can set the icon dimensions in [[Scpui.tbl|scpui.tbl]].

==Ribbons==
SCPUI comes with a brand new award system called Ribbons. This is meant as a way for players to show off how many FreespaceOpen Engine games they have completed. Ribbons are granted via the <code>grant-scpui-ribbon</code> sexp and once granted cannot be modified. Ribbons are saved to global data that spans all Freespace campaigns, mods, and other games. An example of what ribbons look like is below.
[[Image:Scpui_ribbons.jpg|center]]

==Achievements==
SCPUI comes with a full achievements system. Achievements can be automatically granted in some cases or granted by sexp in others. Achievements must be defined in the new [[Achievements.tbl|achievements.tbl]]. Achievement progress is stored automatically on a per-player and per-mod basis. When an achievement is unlocked, a notification is automatically shown to the player.

==Loadout Handling==
SCPUI includes an entirely custom loadout handler that bypasses some of FSO's built-in methods. The biggest change is that each loadout is saved to a json file in the player's appdata directory as <code>scpui_loadouts.cfg</code>. Note this is saved in the mod's appdata directory and not the players directory.

The past loadout will be reloaded across game instances and much more reliably across gameplay entirely. Loadout saves differentiate between missions played in Campaign and missions played via Simulator room.

==Optional Extensions==
SCPUI comes with several optional extension UIs that can be used for specific tasks that the base FreespaceOpen interface is not equipped for. These packages must be enabled in your SCPUI configuration with buttons for access added where desired. Each one has its own set of UI Topics, table parsers, SEXPs, or other features.

===Journal===
The Journal extension was based heavily of Axem's original Lua-only version. SCPUI's iteration is not backwards compatible with it but comes with several enhancements for easier translation and management.

The Journal is configured on a per-campaign basis where each campaign loads from a table matching the format <code>CAMPAIGN_FILE_NAME-journal.tbl</code>. [[Journal.tbl|Documentation is available here.]]

===Node Map===
The Node Map extension was originally created for [[bta|Between the Ashes]] and was intended to be used in the tech room. Some configuration with UI Topics may be necessary to modify its appearance to work in other contexts.

The Node Map features a robust progression system so the map can optionally update as the campaign progresses. All configuration is done with the [[Nodemap.tbl|nodemap.tbl]]. The progression system must be defined by the mod's own Lua scripts through the use of UI Topics.

===Local System Map===
The Local System Map extension was originally by Axem as a Lua only interface. This version was rebuilt from the ground up for [[bta|Between the Ashes]] and, notably, cannot be used in-mission like Axem's original version.

The Local System Map configuration is done with the [[System_map.tbl|system_map.tbl]].

==Advanced Customization==
'''The following sections assume a working knowledge of Lua and are intended for users who wish to extend SCPUI in more advanced ways.'''

SCPUI is a highly flexible system that allows for extensive customization through Lua scripting. To fully take advantage of these features, you will need to understand Lua and be comfortable writing, debugging, and integrating Lua scripts within the FreespaceOpen Engine environment.

This section introduces the types of scripts used in SCPUI and how they fit into the overall architecture.

===Script Architecture===
SCPUI organizes its scripts into distinct categories to improve modularity, maintainability, and extensibility. Each type of script serves a specific purpose:

*'''Submodules''': Submodules are core components of SCPUI or one of its extensions, designed to handle specific tasks or functionality. They are automatically loaded during initialization. Submodules help organize code into manageable files that work together to deliver SCPUI's core features.
** Naming convention: `scpui_sm_*.lua`
** Naming convention for extensions: `scpui_SUBMODULE_sm*.lua`
** Loading: Core submodules are loading during SCPUI's core initialization. Submodules for extensions are loaded after that extension has been initialized.
** Examples: A submodule to manage table parsing or handle preload operations.

*'''Extensions''': Extensions are optional add-ons that provide entirely new functionality or custom UI elements for SCPUI. They can include their own submodules, controllers, and other assets. Extensions are ideal for games that require unique user interfaces as part of the SCPUI system.
**Naming convention: `scpui_ext_*.lua`
**Variables: Each extension must include the following variables:
***Name: The user-facing name of the extension.
***Version: The current version of the extension.
***Submodule: The text used to find the extension's submodules.
***Key: The key that will be used to access the Extension within the <code>ScpuiSystem.extensions</code> table.
**Initialization: Each extension must include an init function. SCPUI will call this function as soon as the extension is loaded.
**Post Initialization: Each extension may optionally include a postInit function. SCPUI will call this function after init and all submodules are loaded.
**Structure: Extensions must return themselves as a table when called.
**Loading: Extensions are loaded after SCPUI's core submodules during SCPUI's initialization.
**Examples: A custom campaign journal interface or a map UI.

*'''Plugins''': Plugins are lightweight, optional scripts that are loaded after SCPUI has initialized. They allow downstream mods or users to add custom behavior or extend functionality without modifying SCPUI's core files. Plugins are intended for advanced users who want to integrate new features or adjust existing ones.
**Naming convention: `scpui_plg_*.lua`
**Loading: Plugins are loaded last during SCPUI's initialization after everything else is ready.
**Examples: A plugin to log custom analytics data or define [[#UI_Topics|UI Topics]] binds.

*'''Controllers''': Controllers are Lua scripts associated with a specific UI. They manage the logic, data handling, and interactions for that UI state.
**Naming convention: `ctrlr_*.lua`
**Loading: Controllers are loaded by a markdown (RML) file; defined in the header section of that file.
**Examples: A controller for the main menu, mission briefing screen, or in-game options screen.

*'''Libraries''': Libraries are reusable utility scripts that provide specific functionality without being tied to a particular UI state or task. They are designed to be called from other scripts as needed.
**Naming convention: `lib_*.lua`
**Structure: Libraries should return themselves as a table when called.
**Loading: Libraries are loaded when needed by using a <code>require()</code> method call.
**Examples: A library for data saving/loading, dialog pop-ups, or utility methods.

===Librocket===
[[librocket|Librocket]] is a pseudo html/css rendering library included with FSO. It is designed as a complete solution for any project's interface needs.SCPUI uses this library to create and manage each UI context.

LibRocket uses the time-tested open standards XHTML1.0 and CSS2.0 (while borrowing features from HTML5 and CSS3), and extends them with features suited towards real-time applications.

Documentation on how to interface with the librocket API can be found [[librocket|here]].

===Game State Management===
SCPUI's game state management is handled by the [[scpui.tbl]] file that simply lists the game state from [[List_of_Game_States|FSO's game states]] and matches it with an RML file that will be associated. One notable exception is GS_STATE_SCRIPTING** which allows for substates. This feature means that you can effectively create an unlimited amount of custom UIs that all exist within GS_STATE_SCRIPTING**.

*To call a built-in game state use ba.postGameEvent("gamestate").
*To call a scripting substate use ScpuiSystem:beginSubstate("substate")

<nowiki>**</nowiki>GS_STATE_SCRIPTING_MISSION can be used for custom UIs that should not end the mission when loaded.

===UI Topics===
SCPUI implements a way to essentially do modular scripting which allows downstream games to modify how SCPUI works without having to carry a complete copy of SCPUI itself. This system is called UI Topics. These work very similar to FSO engine hooks. There are listeners throughout the SCPUI script base that can be attached to in order to modify behavior of various screens, buttons, or other elements. Every screen contains an initialize topic which is the last code run when a game state is started and a screen is created. As a basic example, [[bta|Between the Ashes]] uses this to modify the background image that is used throughout. Here is the Topic code that is used to change the Fiction Viewer background.
<pre>
local Topics = require('lib_ui_topics')
local Utils = require ('lib_utils')

Topics.fictionviewer.initialize:bind(1, function(message, context)
campaignfilename = ba.getCurrentPlayer():getCampaignFilename()
local main = message.document:GetElementById("main_background")
if useSubspaceBG(main) then return end
if Utils.isOneOf(campaignfilename, "bta1_m", "bta2_m", "bta-tem_m") then
main:SetClass("fiction_viewer_bg", true)
end
end)
</pre>
Topics sometimes include relevant data in the parameters called <code>message</code> and can change specific values by settings <code>context.value</code>. The initialize topics, like the example above, always send the entire UI document reference. There are others, like the loading screen loading bar that sends the loading bar filename only and expects a filename return. Here is an example that changes the default loading bar image to something else.
<pre>
Topics.loadscreen.load_bar:bind(9999, function(message, context)
context.value = "fancyloadingbar"
end)
</pre>

Topics are run based on the priority value, the argument in the bind() method, in order from lowest number to highest. You can prevent higher priority topics from being run at all by setting <code>context.done = true</code> inside a Topic.

A full list of available topics can be found in SCPUI's <code>lib_ui_topics.lua</code> file.

===Data Saver===
SCPUI comes with a set of Lua functions to handle saving and loading custom data quickly and easily for any kind of custom data you need. The data is saved to a json file using a hashed version of the mod's [[Game_settings.tbl#.24Mod_title:|mod title]] and the hash can be further randomized by setting a custom seed in [[Scpui.tbl#.24Data_Saver_Multiplier:|scpui.tbl]].

Data can be saved as 'persistent' or 'not persistent'. Persistent data is saved to <pre>data/players</pre>, meaning it will be available to your mod even across mod versions. Non persistent data is saved to <pre>data/config</pre> instead.

All data is saved on a per-pilot basis.

====Saving Arbitrary Data====
Make sure the data you intend to save can be converted to JSON. Basically don't send any userdata. Access datasaver by calling <pre>local DataSaver = require("lib_datasaver")</pre>. You can then save arbitrary data with a call like this <pre>DataSaver:saveDataToFile("data title", saveData, true)</pre>.

Saving data takes three arguments. First is the name of the data. It should be a string. Second is the data to save. The last argument defines if the data is saved as 'persistent' (true) or 'not persistent' (false) which defines where the data is saved to.

====Loading Arbitrary Data====
Loading arbitrary data is just as easy. Set up datasaver with a call like this <pre>local DataSaver = require("lib_datasaver")</pre>. Then simply ask for the data you want to load like this <pre>local saveData = DataSaver :loadDataFromFile("data title", true) or {}</pre>.

Loading data takes two arguments. First is the name of the data and should match the name you used to save with. It should be a string. The second argument defines if the data is loaded as 'persistent' (true) or 'not persistent' (false) which defines where the data is loaded from.

===Custom Mod Options===
[[Image:Screen0594.png|thumb|right|480px|The Custom Options in the [[bta|Between the Ashes]] mod.]]
SCPUI comes with a built-in feature to allow for custom in-game options specific to a particular mod. These options are defined by [[options.tbl]] and saved to the player folder as <code>scpui_options.cfg</code>. Scripts can take advantage of this feature to allow players to customize how scripts run, or if they even run at all.

For example, you could take the [https://github.com/FSO-Scripters/fso-scripts/tree/master/radaricon HUD Icons script] and create a global toggle. This allows players to turn HUD Icons on or off entirely. Furthermore you could allow customizing the max opacity of the icons, the distance at which the icons become fully transparent, and the distance at which the icons become fully opaque. These options will all within the in-game Options UI.

*''''Note that [[game_settings.tbl#$Mod_title:|$Mod_title:]] in [[game_settings.tbl]] is required for this feature to work!''''
*It's a good idea to make sure your mod title is unique to avoid mod options collisions.

====Options.tbl====
This table file is used to define the Options buttons within the Options UI.
*It can be extended with xxx-optn.tbl
*[[options.tbl|Documentation on the options.tbl is available here.]]

====Save Structure====
The player's options are saved to <code>scpui_options.cfg</code> in data/players. This makes the options available across mod versions. The save structure within the file follows a player->mod->option hierarchy. (See example below.) This allows for each player to have their own preferences for each mod they play without interfering with other players' preferences.
<pre>
"John": {
"Between The Ashes": {
"Alarm_Voice": "Vasudan",
"Verbose_Debugging": "Off",
"Font_Multiplier": 2,
"Icon_Far": 2,
"Icon_Near": 5,
"Brief_Render_Option": "Texture",
"Icon_Opacity": "1",
"Cockpit_Alarms": "On",
"HUD_Icons": "Off",
"Cockpit_Rendering": "Off",
"Easter_Eggs": "On"
}
},
"Mike": {
"Between The Ashes": {
"Cockpit_Rendering": "Off",
"Easter_Eggs": "On",
"Font_Multiplier": 5,
"Icon_Far": 2,
"Icon_Near": 5,
"Brief_Render_Option": "Texture",
"Icon_Opacity": "1",
"Cockpit_Alarms": "On",
"HUD_Icons": "Off",
"Verbose_Debugging": "On",
"Alarm_Voice": "Female"
}
}
</pre>

====Accessing Save Data====
Modifying Options within the in-game UI and saving those values to a file is just a start. In order for these options to do anything, you'll need to hook them into your scripts. After the Pilot Select screen and a player is chosen, the current Options are available in a global variable called <code>ScpuiOptionValues</code> with direct access to a specific option by specifying the [[options.tbl#+Key:|option key]]. In order to apply these options create a UI Topic connected to <code>options.apply</code> and run the appropriate code there.
<pre>
#Conditional Hooks
$Application: FS2_Open
$On State End:
[
(function()

local topics = require('lib_ui_topics')
local md = require("debugFunctions")

--Apply user settings to relevant script data
topics.options.apply:bind(9999, function(message, context)

--Handle HUD Icon Option
if ScpuiSystem.data.ScpuiOptionValues.HUD_Icons == "On" then
md.print("MOD OPTION: Player disabled HUD Icons")
RadarIcon.PlayerEnabled = true
else
md.print("MOD OPTION: Player enabled HUD Icons")
RadarIcon.PlayerEnabled = false
end

end)

end)()
]
#End
</pre>

====Pilot Select====
The pilot select UI has special handling of custom mod options because player preferences cannot be loaded until a player is selected. For this specific use case, SCPUI creates a <code>scpui_options_global.cfg</code> whenever user preferences are saved. This file contains no mod or player specific information in the save structure. It is just a list of key/value pairs for the most recently used pilot.
*This setup can be used to perform script actions before a player is selected if necessary.
*In this case, options are still available as '''''ScpuiOptionValues'''''' and accessed the same way, but there is no guarantee that the option will exist depending on the last mod the player played.

===Dialog Popups===
Freespace Open has a number of built-in dialog popups throughout the user interface. SCPUI automatically intercepts those popups and displays them as a librocket styled popup window.

You can create your own custom dialog popups within the UI scripts. To do this you must include <code>local Dialogs = require("lib_dialogs")</code> within the scope of your script. The dialogs function has several parameters for you to define.

====Title====
*Used to define the title of the dialog window.
*<code>dialog:title("yourtitle")</code>

====Text====
*Used to define the text or description your popup will contain.
*<code>dialog:text("yourtext")</code>

====Input====
*Defines if the user can type a string as input
*Useful for allowing the user to name pilots, saves, etc
*User must press ENTER to allow the code to execute on the provided string
*True to allow input, false to disallow. Defaults to false if this parameter is not provided.
**<code>dialog:input(boolean)</code>

====Buttons====
*Defines the user-clickable buttons that will be included in the dialog. It has the following parameters
*Type can be one of the following:
**Dialogs.BUTTON_TYPE_POSITIVE
**Dialogs.BUTTON_TYPE_NEGATIVE
**Dialogs.BUTTON_TYPE_NEUTRAL
*Text is the text for the button, such as "Okay".
*Value is the data that will be returned when the button is clicked.
*Keypress is the keyboard shortcut for this button.
*<code>dialog:buttons(type, text, value, keypress)</code>

====Escape====
*Used to define if the user should be able to cancel the dialog popup with the ESC key.
*A non nil value enables ESC and will be the return value if ESC is pressed
*<code>dialog:escape(value)</code>

====Show====
*This is the final step that displays the popup and defines how to handle the return values
*return values come back as the parameter ''response''
*The ui.enableInput() here specifically enables input on the dialog popup context. The dialog will automatically return input to the SCPUI context when it's closed.
<pre>
dialog:show(self.document.context)
:continueWith(function(response)
"Execute code here"
end)
ui.enableInput(self.document.context)
</pre>

===Preload Coroutines===
SCPUI has a preload system that is used to generate the loadout icon cache. However, it is possible to add any number of arbitrary preload coroutines. To add a preload, call <code>ScpuiSystem:addPreload()</code> with the following arguments:
*Debug Message
**The message to print to the log when this preload coroutine is run.
*Debug String
**The text string to draw to the screen when this preload coroutine is run and FSO is run in debug mode.
*Function
**The actual function to call. Will be called with pcall and errors with the call will halt game execution.
*Args
**Any arguments you want to pass to your function in a table.
*Priority
**This should be a 1 or 2 and determines if this coroutine runs during the first splash image or the second. This allows having coroutines build upon each other if necessary.

An example of an icon coroutine call.
<pre>
ScpuiSystem:addPreload(
"Generating icon for " .. v.Name,
"Generating " .. v.Name .. " icon",
ScpuiSystem.setIconFrames,
{ScpuiSystem, v.Name, true},
2
)
</pre>

===Individual UIs===
All game stages are now supported with the following exceptions:

*Cutscenes
**Because of FSO/Librocket limitations, viewing a cutscene actually sets SCPUI to a [[Scpui.tbl#Substate:|Scripting Substate]] for the duration of the cutscene itself.
*F3 Lab is not supported as an SCPUI style UI. It will use the Base FSO UI
*F3 In-game options is not supported as an SCPUI style UI.
**This is because SCPUI integrates in-game options directly into the main options UI.
*Multi UIs have not been thoroughly tested and may be buggy

===Development and Debugging===
There are three main things to know when developing and debugging SCPUI.

#You can view the librocket debugger by pressing '''''ctrl-shift-d'''''
#You can live-reload RML and RCSS files by pressing '''''ctrl-shift-r'''''
**It's worth noting that Librocket will drop the existing elements and lose them in memory. This will cause a warning on game-exit.
#Librocket API warnings and errors are not currently forwarded to FSO's error handling. Because of this, simple bugs in your Lua code that uses the API can cause FSO to crash.
#You can force regenerating all loadout icons by pressing F12 during FSO's splash screen.
#You can force deleting the current mission's loadout by pressing F12 during mission loading.

===Tips===
*In general, the ui system will handle passing control back and forth between the SCPUI context and FSO. In rare cases you may need to handle this manually. The FSO API methods ui.enableInput() and ui.disableInput() are provided to handle this case.

*For 3D weapon selection, SCPUI can only use [[Weapons.tbl#.24Tech_Model:|Tech models]] and you need to make sure you have [[Weapons.tbl#.2BCloseup_Pos:|Closeup_Pos]] and [[Weapons.tbl#.2BCloseup_Zoom:|Closeup_Zoom]] set. If you don't have a tech model, just set the regular model file as the tech model in your table.

===Tutorials===
*TODO
[[Category:SCPUI]]

Scpui

2026-03-17T14:36:01Z

MjnMixael: document custom data parsers

[[Image:SCPUI-trim.png|center|500px]]

SCPUI is a term that refers to both the LUA Script implementation and the user interface LUA API in the FreespaceOpen engine available from versions 23.2 onwards. It is intended to be used with the [[librocket|librocket libraries]] to replace the base Freespace Open interface in an easily customizable way through LUA scripts.

The original implementation of SCPUI was started by m!m and finished by MjnMixael. This specific implementation attempts to replicate the original Freespace UI experience while offering enhancements such as in-game options not normally available.

[[librocket|For documentation on the Librocket API, go here.]]

The GitHub source files for SCPUI are available [https://github.com/MjnMixael/SCPUI here.] However, it is highly recommended that you have your game or mod rely on the core SCPUI mod on Knossos.NET [https://fsnebula.org/mod/SCPUI here.]

==Overview==
SCPUI works by completely overriding a given game state's internal code. Everything that interface should be expected to do must be handled in the Lua scripts. Methods to get and set appropriate game data are supplied by FSO's UI API. The core file that handles this is <code>scpui_system_core.lua</code>. This file is SCPUI's state management controller. If it detects a valid SCPUI interface for a given game state, it will load a librocket file and begin execution of the appropriate scripts.

An SCPUI game state definition has three main files; RML, RCSS, and LUA. More information is available on those specific pages, but for now it's enough to know that RML is a kind of base HTML, RCSS is a base CSS, and LUA is an FSO compatible LUA file.

The lua file for that state will be run until an FSO game state change is detected. When that happens, the ui_system-sct will clean up the librocket elements and then check if a new set of SCPUI files should be loaded.

The FSO Engine's Lua API provides a library of methods for interfacing with UI code. Please consult the [[Command-Line_Reference#-output_scripting|scripting.html]] file and the '''''UserInterface (ui)''''' library for details.

==Scpui.tbl==
SCPUI's global settings can be modified with scpui.tbl or xxx-ui.tbm files.
[[scpui.tbl|Documentation on scpui.tbl is available here.]]

==Visual Customization==
Unlike FSO's built-in User Interface, SCPUI liberally re-uses visual assets wherever possible. Because of this, there are only about 225 image files compared to retail's thousands. This makes changing the look and feel of the UI incredibly easy even for those who are not interested in modifying the underlying Lua code.

===Custom.RCSS===
Every UI screen loads <code>custom.rcss</code> as its primary style sheet in addition to the rest of the style sheets for that UI screen. The idea here is that you can list all of your custom styles in that file stored in your own mod's game data. The file should be <code>data/interface/css/custom.rcss</code> and you can start by copying the file directly out of SCPUI's base install. This is also where you'll set your mod's primary font file.

===Fonts===
Fonts are defined in SCPUI using an <code>.rcss</code> style sheet. In the base install of SCPUI, the primary font is defined in <code>custom.rcss</code> like this

<pre>
body
{
font-family: BankGothic Md BT;
font-weight: normal;
font-style: normal;
}
</pre>

Note that the font-family is the font's name as defined in the font metadata and not the filename. In some fonts that may strictly be the font family name only, but not always. For example, <code>Noto Sans Medium</code> actually needs to be listed as <code>Noto Sans</code>.

You will want to put all family variant font files (for example: BankGothic.ttf, BankGothic-bold.ttf, BankGotic-italic.ttf) in the <code>data/fonts</code> directory.

SCPUI will try to match it's default font size to FSO's internal font size, which be default is the first font in fonts.tbl. You can customize this setting in [[scpui.tbl|scpui.tbl.]]. You will also want to enable <code>+Auto Scale</code> and <code>+Can Scale</code> on your default FSO font in [[fonts.tbl|fonts.tbl]] so that SCPUI's font and FSO's font can scale together as players will expect.

===Background===
You can change the main background image for all SCPUI screens by simply replacing <code>bg.png</code>. Other background features are covered in the [[scpui.tbl|scpui.tbl documentation.]]

===Logo===
There are several UI screens that use a logo image. It comes in three main variants...

*Standard
**Replace <code>logo.png</code> to replace the standard logo throughout all of SCPUI.
*Wide
**For FS2, this logo is the version with the "wings". Replace <code>logo-wide.png</code> to change this one.
*Loop
**In FS2 this is the [[Special_Operations_Command|SOC]] logo used in the Loop Brief UI. For this one replace <code>loop-logo.png</code>

===Loading Screen Backgrounds===
Loading screen backgrounds are handled a little differently than in base FreespaceOpen. You must create or modify the <code>load_screen_bgs.rcss</code> file to add the custom backgrounds you wish to use. In that file create a css class with the mission filename that is to have a custom screen and then define the file like the example below.

<pre>
.bta1_m1_01 {
background-decorator: image;
background-image: 3_Load_1M1_01.png;
}
</pre>

Mission <code>bta_m1_01.fs2</code> will now have the image <code>3_Load_1M1_01.png</code> used as it's background.

To modify the loading bar see [[scpui#UI_Topics|UI Topics.]]

===Keywords===
SCPUI has a built in feature to allow coloring keywords automatically for UI the various briefing screens. It can also, optionally, add tooltips to these keywords. This feature works in Briefing, Command Briefing, Debriefing, Fiction Viewer, Loop Briefing, and Red Alert. Definitions for keywords are tabled in a special table. See [[keywords.tbl|keywords.tbl documentation]] for more information.

===Elements===
The main UI elements (window boxes, button panels, etc) are all re-used liberally throughout SCPUI. At the time of writing this article, there are 53 of these files in total. You can modify them however you like.

*It is highly recommended you do not change the aspect ratio of these images if you do not want to have to modify RML and RCSS files.

===Buttons===
There are a number of button styles that SCPUI uses to match FS2's retail UI. Each button has at least three images: Main, Hover, and On. Generally they are designated like the following example:
<pre>
arrow-up.png ;;Main
arrow-up-h.png ;;Hover
arrow-up-o.png ;;On
</pre>

In some cases there are Positive and Negative versions. These are named like the following example:
<pre>
select.png ;;Main
select-pos-h.png ;;Positive Hover
select-pos-o.png ;;Positive On
select-neg-h.png ;;Negative Hover
select-neg-o.png ;;Negative On
</pre>

===Custom Data===
SCPUI often uses special [[Ships.tbl#$Custom data:|Custom Data]] for various special cases. This provides a way to set values per-object without needing additional tables.
{| class="wikitable"
! Key
! Value Type
! Supported Tables
! Description
|-
| <code>HideInTechRoom</code>
| Boolean (default: true)
| ships.tbl, weapons.tbl
| If true, the object is always hidden from the tech room, including when using Ctrl+S.
|-
| <code>LoadoutListPriority</code>
| Integer (default: -1)
| ships.tbl, weapons.tbl
| Controls sorting in ship and weapon loadout UIs. 1 is highest priority; -1 means no priority.
|}

==Briefing Color Tags==
SCPUI supports two methods for coloring text in briefings. It supports the retail style [[Briefing Text|color tag]] system out of the box. However, SCPUI also has its own HTML-based approach to styling text. It works everywhere that classic color tags do - briefings (including command, loop, and red alert briefings), debriefings, and the fiction viewer - but also the tech room, campaign descriptions, and nearly everywhere that long-form text is supported. For it to work in briefings, the text must be put in "HTML mode" by putting <code>!html</code> at the start, followed by a space. Everywhere else will work without that tag.

Text in HTML mode may contain HTML markup. Text may be styled using <code></code> tags with appropriate classes drawn from common.rcss; inline styles are also supported. FSO and HTML both make use of double quotes and slashes; to minimize conflicts, using single quotes and writing slashes as <code>$slash</code> is recommended. A complete example might look something like this: <code>!html Pilot attend!<$slashspan> Today, we'll be escorting the GTC Examplar<$slashspan> as she raids Shivan<$slashspan> positions throughout Gamma Draconis<$slashspan>.</code> The list of color classes available by default is at the bottom of <code>common.rcss</code>. You can add more to <code>custom.rcss</code> if needed.

It is, however, rarely necessary to perform simple styling like this manually: SCPUI's [[Keywords.tbl]] may be used to automate common styling rules.

==Loadout Select Icons==
SCPUI supports both 2D pre-drawn icons as well as generated 3D icons. However, they are handled a little differently than inside base FSO. SCPUI pre-generates icon images on game start and displays those in place of the actual icons. Icons are generated during SCPUI's splash screens and cached to the appdata directory to speed up load times on subsequent gameplay instances.

To use 3D icons generated from ship models you must have 3D icons enabled in your [[game_settings.tbl#.24Use_3d_ship_select:|game_settings.tbl]] and for weapons you must have a [[Weapons.tbl#.24Tech_Model:|Tech Model defined]].

To use 2D icons you must have a Select Icon defined for the [[Ships.tbl#.24Ship_Icon:|ship]] or [[Weapons.tbl#.24Icon:|weapon]].

You can set the icon dimensions in [[Scpui.tbl|scpui.tbl]].

==Ribbons==
SCPUI comes with a brand new award system called Ribbons. This is meant as a way for players to show off how many FreespaceOpen Engine games they have completed. Ribbons are granted via the <code>grant-scpui-ribbon</code> sexp and once granted cannot be modified. Ribbons are saved to global data that spans all Freespace campaigns, mods, and other games. An example of what ribbons look like is below.
[[Image:Scpui_ribbons.jpg|center]]

==Achievements==
SCPUI comes with a full achievements system. Achievements can be automatically granted in some cases or granted by sexp in others. Achievements must be defined in the new [[Achievements.tbl|achievements.tbl]]. Achievement progress is stored automatically on a per-player and per-mod basis. When an achievement is unlocked, a notification is automatically shown to the player.

==Loadout Handling==
SCPUI includes an entirely custom loadout handler that bypasses some of FSO's built-in methods. The biggest change is that each loadout is saved to a json file in the player's appdata directory as <code>scpui_loadouts.cfg</code>. Note this is saved in the mod's appdata directory and not the players directory.

The past loadout will be reloaded across game instances and much more reliably across gameplay entirely. Loadout saves differentiate between missions played in Campaign and missions played via Simulator room.

==Optional Extensions==
SCPUI comes with several optional extension UIs that can be used for specific tasks that the base FreespaceOpen interface is not equipped for. These packages must be enabled in your SCPUI configuration with buttons for access added where desired. Each one has its own set of UI Topics, table parsers, SEXPs, or other features.

===Journal===
The Journal extension was based heavily of Axem's original Lua-only version. SCPUI's iteration is not backwards compatible with it but comes with several enhancements for easier translation and management.

The Journal is configured on a per-campaign basis where each campaign loads from a table matching the format <code>CAMPAIGN_FILE_NAME-journal.tbl</code>. [[Journal.tbl|Documentation is available here.]]

===Node Map===
The Node Map extension was originally created for [[bta|Between the Ashes]] and was intended to be used in the tech room. Some configuration with UI Topics may be necessary to modify its appearance to work in other contexts.

The Node Map features a robust progression system so the map can optionally update as the campaign progresses. All configuration is done with the [[Nodemap.tbl|nodemap.tbl]]. The progression system must be defined by the mod's own Lua scripts through the use of UI Topics.

===Local System Map===
The Local System Map extension was originally by Axem as a Lua only interface. This version was rebuilt from the ground up for [[bta|Between the Ashes]] and, notably, cannot be used in-mission like Axem's original version.

The Local System Map configuration is done with the [[System_map.tbl|system_map.tbl]].

==Advanced Customization==
'''The following sections assume a working knowledge of Lua and are intended for users who wish to extend SCPUI in more advanced ways.'''

SCPUI is a highly flexible system that allows for extensive customization through Lua scripting. To fully take advantage of these features, you will need to understand Lua and be comfortable writing, debugging, and integrating Lua scripts within the FreespaceOpen Engine environment.

This section introduces the types of scripts used in SCPUI and how they fit into the overall architecture.

===Script Architecture===
SCPUI organizes its scripts into distinct categories to improve modularity, maintainability, and extensibility. Each type of script serves a specific purpose:

*'''Submodules''': Submodules are core components of SCPUI or one of its extensions, designed to handle specific tasks or functionality. They are automatically loaded during initialization. Submodules help organize code into manageable files that work together to deliver SCPUI's core features.
** Naming convention: `scpui_sm_*.lua`
** Naming convention for extensions: `scpui_SUBMODULE_sm*.lua`
** Loading: Core submodules are loading during SCPUI's core initialization. Submodules for extensions are loaded after that extension has been initialized.
** Examples: A submodule to manage table parsing or handle preload operations.

*'''Extensions''': Extensions are optional add-ons that provide entirely new functionality or custom UI elements for SCPUI. They can include their own submodules, controllers, and other assets. Extensions are ideal for games that require unique user interfaces as part of the SCPUI system.
**Naming convention: `scpui_ext_*.lua`
**Variables: Each extension must include the following variables:
***Name: The user-facing name of the extension.
***Version: The current version of the extension.
***Submodule: The text used to find the extension's submodules.
***Key: The key that will be used to access the Extension within the <code>ScpuiSystem.extensions</code> table.
**Initialization: Each extension must include an init function. SCPUI will call this function as soon as the extension is loaded.
**Post Initialization: Each extension may optionally include a postInit function. SCPUI will call this function after init and all submodules are loaded.
**Structure: Extensions must return themselves as a table when called.
**Loading: Extensions are loaded after SCPUI's core submodules during SCPUI's initialization.
**Examples: A custom campaign journal interface or a map UI.

*'''Plugins''': Plugins are lightweight, optional scripts that are loaded after SCPUI has initialized. They allow downstream mods or users to add custom behavior or extend functionality without modifying SCPUI's core files. Plugins are intended for advanced users who want to integrate new features or adjust existing ones.
**Naming convention: `scpui_plg_*.lua`
**Loading: Plugins are loaded last during SCPUI's initialization after everything else is ready.
**Examples: A plugin to log custom analytics data or define [[#UI_Topics|UI Topics]] binds.

*'''Controllers''': Controllers are Lua scripts associated with a specific UI. They manage the logic, data handling, and interactions for that UI state.
**Naming convention: `ctrlr_*.lua`
**Loading: Controllers are loaded by a markdown (RML) file; defined in the header section of that file.
**Examples: A controller for the main menu, mission briefing screen, or in-game options screen.

*'''Libraries''': Libraries are reusable utility scripts that provide specific functionality without being tied to a particular UI state or task. They are designed to be called from other scripts as needed.
**Naming convention: `lib_*.lua`
**Structure: Libraries should return themselves as a table when called.
**Loading: Libraries are loaded when needed by using a <code>require()</code> method call.
**Examples: A library for data saving/loading, dialog pop-ups, or utility methods.

===Librocket===
[[librocket|Librocket]] is a pseudo html/css rendering library included with FSO. It is designed as a complete solution for any project's interface needs.SCPUI uses this library to create and manage each UI context.

LibRocket uses the time-tested open standards XHTML1.0 and CSS2.0 (while borrowing features from HTML5 and CSS3), and extends them with features suited towards real-time applications.

Documentation on how to interface with the librocket API can be found [[librocket|here]].

===Game State Management===
SCPUI's game state management is handled by the [[scpui.tbl]] file that simply lists the game state from [[List_of_Game_States|FSO's game states]] and matches it with an RML file that will be associated. One notable exception is GS_STATE_SCRIPTING** which allows for substates. This feature means that you can effectively create an unlimited amount of custom UIs that all exist within GS_STATE_SCRIPTING**.

*To call a built-in game state use ba.postGameEvent("gamestate").
*To call a scripting substate use ScpuiSystem:beginSubstate("substate")

<nowiki>**</nowiki>GS_STATE_SCRIPTING_MISSION can be used for custom UIs that should not end the mission when loaded.

===UI Topics===
SCPUI implements a way to essentially do modular scripting which allows downstream games to modify how SCPUI works without having to carry a complete copy of SCPUI itself. This system is called UI Topics. These work very similar to FSO engine hooks. There are listeners throughout the SCPUI script base that can be attached to in order to modify behavior of various screens, buttons, or other elements. Every screen contains an initialize topic which is the last code run when a game state is started and a screen is created. As a basic example, [[bta|Between the Ashes]] uses this to modify the background image that is used throughout. Here is the Topic code that is used to change the Fiction Viewer background.
<pre>
local Topics = require('lib_ui_topics')
local Utils = require ('lib_utils')

Topics.fictionviewer.initialize:bind(1, function(message, context)
campaignfilename = ba.getCurrentPlayer():getCampaignFilename()
local main = message.document:GetElementById("main_background")
if useSubspaceBG(main) then return end
if Utils.isOneOf(campaignfilename, "bta1_m", "bta2_m", "bta-tem_m") then
main:SetClass("fiction_viewer_bg", true)
end
end)
</pre>
Topics sometimes include relevant data in the parameters called <code>message</code> and can change specific values by settings <code>context.value</code>. The initialize topics, like the example above, always send the entire UI document reference. There are others, like the loading screen loading bar that sends the loading bar filename only and expects a filename return. Here is an example that changes the default loading bar image to something else.
<pre>
Topics.loadscreen.load_bar:bind(9999, function(message, context)
context.value = "fancyloadingbar"
end)
</pre>

Topics are run based on the priority value, the argument in the bind() method, in order from lowest number to highest. You can prevent higher priority topics from being run at all by setting <code>context.done = true</code> inside a Topic.

A full list of available topics can be found in SCPUI's <code>lib_ui_topics.lua</code> file.

===Data Saver===
SCPUI comes with a set of Lua functions to handle saving and loading custom data quickly and easily for any kind of custom data you need. The data is saved to a json file using a hashed version of the mod's [[Game_settings.tbl#.24Mod_title:|mod title]] and the hash can be further randomized by setting a custom seed in [[Scpui.tbl#.24Data_Saver_Multiplier:|scpui.tbl]].

Data can be saved as 'persistent' or 'not persistent'. Persistent data is saved to <pre>data/players</pre>, meaning it will be available to your mod even across mod versions. Non persistent data is saved to <pre>data/config</pre> instead.

All data is saved on a per-pilot basis.

====Saving Arbitrary Data====
Make sure the data you intend to save can be converted to JSON. Basically don't send any userdata. Access datasaver by calling <pre>local DataSaver = require("lib_datasaver")</pre>. You can then save arbitrary data with a call like this <pre>DataSaver:saveDataToFile("data title", saveData, true)</pre>.

Saving data takes three arguments. First is the name of the data. It should be a string. Second is the data to save. The last argument defines if the data is saved as 'persistent' (true) or 'not persistent' (false) which defines where the data is saved to.

====Loading Arbitrary Data====
Loading arbitrary data is just as easy. Set up datasaver with a call like this <pre>local DataSaver = require("lib_datasaver")</pre>. Then simply ask for the data you want to load like this <pre>local saveData = DataSaver :loadDataFromFile("data title", true) or {}</pre>.

Loading data takes two arguments. First is the name of the data and should match the name you used to save with. It should be a string. The second argument defines if the data is loaded as 'persistent' (true) or 'not persistent' (false) which defines where the data is loaded from.

===Custom Mod Options===
[[Image:Screen0594.png|thumb|right|480px|The Custom Options in the [[bta|Between the Ashes]] mod.]]
SCPUI comes with a built-in feature to allow for custom in-game options specific to a particular mod. These options are defined by [[options.tbl]] and saved to the player folder as <code>scpui_options.cfg</code>. Scripts can take advantage of this feature to allow players to customize how scripts run, or if they even run at all.

For example, you could take the [https://github.com/FSO-Scripters/fso-scripts/tree/master/radaricon HUD Icons script] and create a global toggle. This allows players to turn HUD Icons on or off entirely. Furthermore you could allow customizing the max opacity of the icons, the distance at which the icons become fully transparent, and the distance at which the icons become fully opaque. These options will all within the in-game Options UI.

*''''Note that [[game_settings.tbl#$Mod_title:|$Mod_title:]] in [[game_settings.tbl]] is required for this feature to work!''''
*It's a good idea to make sure your mod title is unique to avoid mod options collisions.

====Options.tbl====
This table file is used to define the Options buttons within the Options UI.
*It can be extended with xxx-optn.tbl
*[[options.tbl|Documentation on the options.tbl is available here.]]

====Save Structure====
The player's options are saved to <code>scpui_options.cfg</code> in data/players. This makes the options available across mod versions. The save structure within the file follows a player->mod->option hierarchy. (See example below.) This allows for each player to have their own preferences for each mod they play without interfering with other players' preferences.
<pre>
"John": {
"Between The Ashes": {
"Alarm_Voice": "Vasudan",
"Verbose_Debugging": "Off",
"Font_Multiplier": 2,
"Icon_Far": 2,
"Icon_Near": 5,
"Brief_Render_Option": "Texture",
"Icon_Opacity": "1",
"Cockpit_Alarms": "On",
"HUD_Icons": "Off",
"Cockpit_Rendering": "Off",
"Easter_Eggs": "On"
}
},
"Mike": {
"Between The Ashes": {
"Cockpit_Rendering": "Off",
"Easter_Eggs": "On",
"Font_Multiplier": 5,
"Icon_Far": 2,
"Icon_Near": 5,
"Brief_Render_Option": "Texture",
"Icon_Opacity": "1",
"Cockpit_Alarms": "On",
"HUD_Icons": "Off",
"Verbose_Debugging": "On",
"Alarm_Voice": "Female"
}
}
</pre>

====Accessing Save Data====
Modifying Options within the in-game UI and saving those values to a file is just a start. In order for these options to do anything, you'll need to hook them into your scripts. After the Pilot Select screen and a player is chosen, the current Options are available in a global variable called <code>ScpuiOptionValues</code> with direct access to a specific option by specifying the [[options.tbl#+Key:|option key]]. In order to apply these options create a UI Topic connected to <code>options.apply</code> and run the appropriate code there.
<pre>
#Conditional Hooks
$Application: FS2_Open
$On State End:
[
(function()

local topics = require('lib_ui_topics')
local md = require("debugFunctions")

--Apply user settings to relevant script data
topics.options.apply:bind(9999, function(message, context)

--Handle HUD Icon Option
if ScpuiSystem.data.ScpuiOptionValues.HUD_Icons == "On" then
md.print("MOD OPTION: Player disabled HUD Icons")
RadarIcon.PlayerEnabled = true
else
md.print("MOD OPTION: Player enabled HUD Icons")
RadarIcon.PlayerEnabled = false
end

end)

end)()
]
#End
</pre>

====Pilot Select====
The pilot select UI has special handling of custom mod options because player preferences cannot be loaded until a player is selected. For this specific use case, SCPUI creates a <code>scpui_options_global.cfg</code> whenever user preferences are saved. This file contains no mod or player specific information in the save structure. It is just a list of key/value pairs for the most recently used pilot.
*This setup can be used to perform script actions before a player is selected if necessary.
*In this case, options are still available as '''''ScpuiOptionValues'''''' and accessed the same way, but there is no guarantee that the option will exist depending on the last mod the player played.

===Dialog Popups===
Freespace Open has a number of built-in dialog popups throughout the user interface. SCPUI automatically intercepts those popups and displays them as a librocket styled popup window.

You can create your own custom dialog popups within the UI scripts. To do this you must include <code>local Dialogs = require("lib_dialogs")</code> within the scope of your script. The dialogs function has several parameters for you to define.

====Title====
*Used to define the title of the dialog window.
*<code>dialog:title("yourtitle")</code>

====Text====
*Used to define the text or description your popup will contain.
*<code>dialog:text("yourtext")</code>

====Input====
*Defines if the user can type a string as input
*Useful for allowing the user to name pilots, saves, etc
*User must press ENTER to allow the code to execute on the provided string
*True to allow input, false to disallow. Defaults to false if this parameter is not provided.
**<code>dialog:input(boolean)</code>

====Buttons====
*Defines the user-clickable buttons that will be included in the dialog. It has the following parameters
*Type can be one of the following:
**Dialogs.BUTTON_TYPE_POSITIVE
**Dialogs.BUTTON_TYPE_NEGATIVE
**Dialogs.BUTTON_TYPE_NEUTRAL
*Text is the text for the button, such as "Okay".
*Value is the data that will be returned when the button is clicked.
*Keypress is the keyboard shortcut for this button.
*<code>dialog:buttons(type, text, value, keypress)</code>

====Escape====
*Used to define if the user should be able to cancel the dialog popup with the ESC key.
*A non nil value enables ESC and will be the return value if ESC is pressed
*<code>dialog:escape(value)</code>

====Show====
*This is the final step that displays the popup and defines how to handle the return values
*return values come back as the parameter ''response''
*The ui.enableInput() here specifically enables input on the dialog popup context. The dialog will automatically return input to the SCPUI context when it's closed.
<pre>
dialog:show(self.document.context)
:continueWith(function(response)
"Execute code here"
end)
ui.enableInput(self.document.context)
</pre>

===Preload Coroutines===
SCPUI has a preload system that is used to generate the loadout icon cache. However, it is possible to add any number of arbitrary preload coroutines. To add a preload, call <code>ScpuiSystem:addPreload()</code> with the following arguments:
*Debug Message
**The message to print to the log when this preload coroutine is run.
*Debug String
**The text string to draw to the screen when this preload coroutine is run and FSO is run in debug mode.
*Function
**The actual function to call. Will be called with pcall and errors with the call will halt game execution.
*Args
**Any arguments you want to pass to your function in a table.
*Priority
**This should be a 1 or 2 and determines if this coroutine runs during the first splash image or the second. This allows having coroutines build upon each other if necessary.

An example of an icon coroutine call.
<pre>
ScpuiSystem:addPreload(
"Generating icon for " .. v.Name,
"Generating " .. v.Name .. " icon",
ScpuiSystem.setIconFrames,
{ScpuiSystem, v.Name, true},
2
)
</pre>

===Individual UIs===
All game stages are now supported with the following exceptions:

*Cutscenes
**Because of FSO/Librocket limitations, viewing a cutscene actually sets SCPUI to a [[Scpui.tbl#Substate:|Scripting Substate]] for the duration of the cutscene itself.
*F3 Lab is not supported as an SCPUI style UI. It will use the Base FSO UI
*F3 In-game options is not supported as an SCPUI style UI.
**This is because SCPUI integrates in-game options directly into the main options UI.
*Multi UIs have not been thoroughly tested and may be buggy

===Development and Debugging===
There are three main things to know when developing and debugging SCPUI.

#You can view the librocket debugger by pressing '''''ctrl-shift-d'''''
#You can live-reload RML and RCSS files by pressing '''''ctrl-shift-r'''''
**It's worth noting that Librocket will drop the existing elements and lose them in memory. This will cause a warning on game-exit.
#Librocket API warnings and errors are not currently forwarded to FSO's error handling. Because of this, simple bugs in your Lua code that uses the API can cause FSO to crash.
#You can force regenerating all loadout icons by pressing F12 during FSO's splash screen.
#You can force deleting the current mission's loadout by pressing F12 during mission loading.

===Tips===
*In general, the ui system will handle passing control back and forth between the SCPUI context and FSO. In rare cases you may need to handle this manually. The FSO API methods ui.enableInput() and ui.disableInput() are provided to handle this case.

*For 3D weapon selection, SCPUI can only use [[Weapons.tbl#.24Tech_Model:|Tech models]] and you need to make sure you have [[Weapons.tbl#.2BCloseup_Pos:|Closeup_Pos]] and [[Weapons.tbl#.2BCloseup_Zoom:|Closeup_Zoom]] set. If you don't have a tech model, just set the regular model file as the tech model in your table.

===Tutorials===
*TODO
[[Category:SCPUI]]

RCSS Decorators

2026-03-14T17:59:36Z

MjnMixael:

{{RCSS}}
Decorators are an extension to CSS for RCSS. A decorator can be declared and named in a style sheet like a property, and then configured with decorator-specific properties. Custom decorator types can be developed to suit the needs of the user, and in this manner any kind of decoration can be applied to an element.

Important: Note that decorators can only be declared and defined in style sheets, not in style defined inline to an element.

==Declaring decorators==
The declaration of a decorator is a property of the form:

<pre>
<name>-decorator: <type>;
</pre>
where <name> is the user-specified name of the decorator to declare, and <type> is the application-specific type of decorator. libRocket ships with the following decorator types:
*image
*tiled-box
*tiled-horizontal
*tiled-vertical
The decorator type none is a reserved name that represents no decorator. For example, in the following:
<pre>
button
{
icon-decorator: tiled-horizontal;
}
</pre>
the RCSS is attaching a decorator of type tiled-horizontal called ‘icon’ to all button elements. Note that the name ‘icon’ could be anything; it is only used to uniquely identify the decorator for applying properties to it.

Decorator types can be overridden like any other property. So, in the example:
<pre>
h1
{
icon-decorator: image;
}

h1:hover
{
icon-decorator: none;
}
</pre>
all h1 tags will have an image decorator attached, except when they are being hovered, when the decorator will not be rendered.

==Decorator properties==
Decorators have their own property specifications with properties and shorthands, and these can be defined for declared decorators just like any other property. Decorator properties are set in the form:

<pre>
<name>-<property>: <value>;
</pre>
where <name> is the name the decorator was declared under, <property> is the name of the decorator’s property to set, and <value> is the value of the property. For example:
<pre>
h1
{
icon-decorator: image;
icon-image-src: ../images/header_arrow.png;
icon-image-s-begin: 5px;
}
</pre>
an image decorator is declared, called ‘icon’. On this decorator, the properties <name>-image-src is set to ‘../images/header_arrow.png’ and <name>-image-s-begin is set to ‘5px’. The other properties in the image specification are left to their defaults.

The decorator properties behave like other properties, so are subject to precedence and the cascade. For example, if the following RCSS was loaded after the previous example:
<pre>
h1
{
icon-image-s-begin: 3px;
}

h1:first-child
{
icon-decorator: none;
}
</pre>
all h1 tags will have their ‘icon’ decorators defined with an <name>-s-begin property of ‘3px’ instead of ‘5px’, and an h1 that is a first child will have no decorator.

Be careful of name conflicts! For example, in the following sample:
<pre>
h1
{
icon-decorator: image;
}

.secondary
{
icon-decorator: tiled-horizontal;
}
</pre>
an element of type h1 with a class of ‘secondary’ will have a single decorator, ‘icon’, of type tiled-horizontal. If the decorators had different names then they both would be present.

Specifying render order
If an element has more than one decorator on it, you can use the ‘z-index’ decorator property to control the render order in a similar fashion to elements. For example, in this sample:
<pre>
button
{
background-decorator: tiled-horizontal;
background-z-index: 0;

icon-decorator: image;
icon-z-index: 1;
}
</pre>
the ‘icon’ decorator will appear on top of the ‘background’ decorator. If no z-index is specified on a decorator, it will have the default z-index of 0.

Decorators and pseudo-classes
Because of the way libRocket compiles pseudo-class rules within style sheets, overriding decorator properties within dynamic pseudo-classes (:active, :hover and :focus, not any of the structural classes) might not always work the way you think it should.

In a nutshell, each decorator will only process properties from their element’s base rules (ie, those not specifying dynamic pseudo-classes in their final simple selector) and one rule specifying a dynamic pseudo-class (or classes), that with the highest specificity. For example, in the following sample:
<pre>
button
{
background-decorator: tiled-horizontal;
background-image-src: ../button.png;
background-image-s-end: 128px;
}

button:hover
{
background-image-t-begin: 32px;
background-image-t-end: 64px;
}

button:active
{
background-image-s-begin: 128px;
background-image-s-end: 256px;
}
</pre>
if both the :hover and :active pseudo-classes are active on a button element, the <name>-image-s-begin and <name>-image-s-end properties from the :active rule will be set, but the <name>-image-t-begin and <name>-image-t-end properties from the :hover rule will be ignored. The :active rule is used as it has higher precedence that the :hover rule, appearing further down the file. If you wanted both the s and t properties set, you could create another rule:
<pre>
button:active:hover
{
background-image-t-begin: 32px;
background-image-t-end: 64px;
background-image-s-begin: 128px;
background-image-s-end: 256px;
}
</pre>

==image decorators==
Image decorators in Freespace Open's instance of librocket support a custom paramter, <code>image-fit</code>. Valid values are Stretch, Contain, Fill.

==libRocket decorators==
libRocket comes with several built-in decorators for displaying images and tiled images behind elements.

*image decorator, for displaying a single stretched image.
*tiled-horizontal decorator, for tiling images horizontally.
*tiled-vertical decorator, for tiling images vertically.
*tiled-box decorator, for tiling images across a box.

Scpui

2026-03-08T18:44:58Z

MjnMixael: /* Fonts */

[[Image:SCPUI-trim.png|center|500px]]

SCPUI is a term that refers to both the LUA Script implementation and the user interface LUA API in the FreespaceOpen engine available from versions 23.2 onwards. It is intended to be used with the [[librocket|librocket libraries]] to replace the base Freespace Open interface in an easily customizable way through LUA scripts.

The original implementation of SCPUI was started by m!m and finished by MjnMixael. This specific implementation attempts to replicate the original Freespace UI experience while offering enhancements such as in-game options not normally available.

[[librocket|For documentation on the Librocket API, go here.]]

The GitHub source files for SCPUI are available [https://github.com/MjnMixael/SCPUI here.] However, it is highly recommended that you have your game or mod rely on the core SCPUI mod on Knossos.NET [https://fsnebula.org/mod/SCPUI here.]

==Overview==
SCPUI works by completely overriding a given game state's internal code. Everything that interface should be expected to do must be handled in the Lua scripts. Methods to get and set appropriate game data are supplied by FSO's UI API. The core file that handles this is <code>scpui_system_core.lua</code>. This file is SCPUI's state management controller. If it detects a valid SCPUI interface for a given game state, it will load a librocket file and begin execution of the appropriate scripts.

An SCPUI game state definition has three main files; RML, RCSS, and LUA. More information is available on those specific pages, but for now it's enough to know that RML is a kind of base HTML, RCSS is a base CSS, and LUA is an FSO compatible LUA file.

The lua file for that state will be run until an FSO game state change is detected. When that happens, the ui_system-sct will clean up the librocket elements and then check if a new set of SCPUI files should be loaded.

The FSO Engine's Lua API provides a library of methods for interfacing with UI code. Please consult the [[Command-Line_Reference#-output_scripting|scripting.html]] file and the '''''UserInterface (ui)''''' library for details.

==Scpui.tbl==
SCPUI's global settings can be modified with scpui.tbl or xxx-ui.tbm files.
[[scpui.tbl|Documentation on scpui.tbl is available here.]]

==Visual Customization==
Unlike FSO's built-in User Interface, SCPUI liberally re-uses visual assets wherever possible. Because of this, there are only about 225 image files compared to retail's thousands. This makes changing the look and feel of the UI incredibly easy even for those who are not interested in modifying the underlying Lua code.

===Custom.RCSS===
Every UI screen loads <code>custom.rcss</code> as its primary style sheet in addition to the rest of the style sheets for that UI screen. The idea here is that you can list all of your custom styles in that file stored in your own mod's game data. The file should be <code>data/interface/css/custom.rcss</code> and you can start by copying the file directly out of SCPUI's base install. This is also where you'll set your mod's primary font file.

===Fonts===
Fonts are defined in SCPUI using an <code>.rcss</code> style sheet. In the base install of SCPUI, the primary font is defined in <code>custom.rcss</code> like this

<pre>
body
{
font-family: BankGothic Md BT;
font-weight: normal;
font-style: normal;
}
</pre>

Note that the font-family is the font's name as defined in the font metadata and not the filename. In some fonts that may strictly be the font family name only, but not always. For example, <code>Noto Sans Medium</code> actually needs to be listed as <code>Noto Sans</code>.

You will want to put all family variant font files (for example: BankGothic.ttf, BankGothic-bold.ttf, BankGotic-italic.ttf) in the <code>data/fonts</code> directory.

SCPUI will try to match it's default font size to FSO's internal font size, which be default is the first font in fonts.tbl. You can customize this setting in [[scpui.tbl|scpui.tbl.]]. You will also want to enable <code>+Auto Scale</code> and <code>+Can Scale</code> on your default FSO font in [[fonts.tbl|fonts.tbl]] so that SCPUI's font and FSO's font can scale together as players will expect.

===Background===
You can change the main background image for all SCPUI screens by simply replacing <code>bg.png</code>. Other background features are covered in the [[scpui.tbl|scpui.tbl documentation.]]

===Logo===
There are several UI screens that use a logo image. It comes in three main variants...

*Standard
**Replace <code>logo.png</code> to replace the standard logo throughout all of SCPUI.
*Wide
**For FS2, this logo is the version with the "wings". Replace <code>logo-wide.png</code> to change this one.
*Loop
**In FS2 this is the [[Special_Operations_Command|SOC]] logo used in the Loop Brief UI. For this one replace <code>loop-logo.png</code>

===Loading Screen Backgrounds===
Loading screen backgrounds are handled a little differently than in base FreespaceOpen. You must create or modify the <code>load_screen_bgs.rcss</code> file to add the custom backgrounds you wish to use. In that file create a css class with the mission filename that is to have a custom screen and then define the file like the example below.

<pre>
.bta1_m1_01 {
background-decorator: image;
background-image: 3_Load_1M1_01.png;
}
</pre>

Mission <code>bta_m1_01.fs2</code> will now have the image <code>3_Load_1M1_01.png</code> used as it's background.

To modify the loading bar see [[scpui#UI_Topics|UI Topics.]]

===Keywords===
SCPUI has a built in feature to allow coloring keywords automatically for UI the various briefing screens. It can also, optionally, add tooltips to these keywords. This feature works in Briefing, Command Briefing, Debriefing, Fiction Viewer, Loop Briefing, and Red Alert. Definitions for keywords are tabled in a special table. See [[keywords.tbl|keywords.tbl documentation]] for more information.

===Elements===
The main UI elements (window boxes, button panels, etc) are all re-used liberally throughout SCPUI. At the time of writing this article, there are 53 of these files in total. You can modify them however you like.

*It is highly recommended you do not change the aspect ratio of these images if you do not want to have to modify RML and RCSS files.

===Buttons===
There are a number of button styles that SCPUI uses to match FS2's retail UI. Each button has at least three images: Main, Hover, and On. Generally they are designated like the following example:
<pre>
arrow-up.png ;;Main
arrow-up-h.png ;;Hover
arrow-up-o.png ;;On
</pre>

In some cases there are Positive and Negative versions. These are named like the following example:
<pre>
select.png ;;Main
select-pos-h.png ;;Positive Hover
select-pos-o.png ;;Positive On
select-neg-h.png ;;Negative Hover
select-neg-o.png ;;Negative On
</pre>

==Briefing Color Tags==
SCPUI supports two methods for coloring text in briefings. It supports the retail style [[Briefing Text|color tag]] system out of the box. However, SCPUI also has its own HTML-based approach to styling text. It works everywhere that classic color tags do - briefings (including command, loop, and red alert briefings), debriefings, and the fiction viewer - but also the tech room, campaign descriptions, and nearly everywhere that long-form text is supported. For it to work in briefings, the text must be put in "HTML mode" by putting <code>!html</code> at the start, followed by a space. Everywhere else will work without that tag.

Text in HTML mode may contain HTML markup. Text may be styled using <code></code> tags with appropriate classes drawn from common.rcss; inline styles are also supported. FSO and HTML both make use of double quotes and slashes; to minimize conflicts, using single quotes and writing slashes as <code>$slash</code> is recommended. A complete example might look something like this: <code>!html Pilot attend!<$slashspan> Today, we'll be escorting the GTC Examplar<$slashspan> as she raids Shivan<$slashspan> positions throughout Gamma Draconis<$slashspan>.</code> The list of color classes available by default is at the bottom of <code>common.rcss</code>. You can add more to <code>custom.rcss</code> if needed.

It is, however, rarely necessary to perform simple styling like this manually: SCPUI's [[Keywords.tbl]] may be used to automate common styling rules.

==Loadout Select Icons==
SCPUI supports both 2D pre-drawn icons as well as generated 3D icons. However, they are handled a little differently than inside base FSO. SCPUI pre-generates icon images on game start and displays those in place of the actual icons. Icons are generated during SCPUI's splash screens and cached to the appdata directory to speed up load times on subsequent gameplay instances.

To use 3D icons generated from ship models you must have 3D icons enabled in your [[game_settings.tbl#.24Use_3d_ship_select:|game_settings.tbl]] and for weapons you must have a [[Weapons.tbl#.24Tech_Model:|Tech Model defined]].

To use 2D icons you must have a Select Icon defined for the [[Ships.tbl#.24Ship_Icon:|ship]] or [[Weapons.tbl#.24Icon:|weapon]].

You can set the icon dimensions in [[Scpui.tbl|scpui.tbl]].

==Ribbons==
SCPUI comes with a brand new award system called Ribbons. This is meant as a way for players to show off how many FreespaceOpen Engine games they have completed. Ribbons are granted via the <code>grant-scpui-ribbon</code> sexp and once granted cannot be modified. Ribbons are saved to global data that spans all Freespace campaigns, mods, and other games. An example of what ribbons look like is below.
[[Image:Scpui_ribbons.jpg|center]]

==Achievements==
SCPUI comes with a full achievements system. Achievements can be automatically granted in some cases or granted by sexp in others. Achievements must be defined in the new [[Achievements.tbl|achievements.tbl]]. Achievement progress is stored automatically on a per-player and per-mod basis. When an achievement is unlocked, a notification is automatically shown to the player.

==Loadout Handling==
SCPUI includes an entirely custom loadout handler that bypasses some of FSO's built-in methods. The biggest change is that each loadout is saved to a json file in the player's appdata directory as <code>scpui_loadouts.cfg</code>. Note this is saved in the mod's appdata directory and not the players directory.

The past loadout will be reloaded across game instances and much more reliably across gameplay entirely. Loadout saves differentiate between missions played in Campaign and missions played via Simulator room.

==Optional Extensions==
SCPUI comes with several optional extension UIs that can be used for specific tasks that the base FreespaceOpen interface is not equipped for. These packages must be enabled in your SCPUI configuration with buttons for access added where desired. Each one has its own set of UI Topics, table parsers, SEXPs, or other features.

===Journal===
The Journal extension was based heavily of Axem's original Lua-only version. SCPUI's iteration is not backwards compatible with it but comes with several enhancements for easier translation and management.

The Journal is configured on a per-campaign basis where each campaign loads from a table matching the format <code>CAMPAIGN_FILE_NAME-journal.tbl</code>. [[Journal.tbl|Documentation is available here.]]

===Node Map===
The Node Map extension was originally created for [[bta|Between the Ashes]] and was intended to be used in the tech room. Some configuration with UI Topics may be necessary to modify its appearance to work in other contexts.

The Node Map features a robust progression system so the map can optionally update as the campaign progresses. All configuration is done with the [[Nodemap.tbl|nodemap.tbl]]. The progression system must be defined by the mod's own Lua scripts through the use of UI Topics.

===Local System Map===
The Local System Map extension was originally by Axem as a Lua only interface. This version was rebuilt from the ground up for [[bta|Between the Ashes]] and, notably, cannot be used in-mission like Axem's original version.

The Local System Map configuration is done with the [[System_map.tbl|system_map.tbl]].

==Advanced Customization==
'''The following sections assume a working knowledge of Lua and are intended for users who wish to extend SCPUI in more advanced ways.'''

SCPUI is a highly flexible system that allows for extensive customization through Lua scripting. To fully take advantage of these features, you will need to understand Lua and be comfortable writing, debugging, and integrating Lua scripts within the FreespaceOpen Engine environment.

This section introduces the types of scripts used in SCPUI and how they fit into the overall architecture.

===Script Architecture===
SCPUI organizes its scripts into distinct categories to improve modularity, maintainability, and extensibility. Each type of script serves a specific purpose:

*'''Submodules''': Submodules are core components of SCPUI or one of its extensions, designed to handle specific tasks or functionality. They are automatically loaded during initialization. Submodules help organize code into manageable files that work together to deliver SCPUI's core features.
** Naming convention: `scpui_sm_*.lua`
** Naming convention for extensions: `scpui_SUBMODULE_sm*.lua`
** Loading: Core submodules are loading during SCPUI's core initialization. Submodules for extensions are loaded after that extension has been initialized.
** Examples: A submodule to manage table parsing or handle preload operations.

*'''Extensions''': Extensions are optional add-ons that provide entirely new functionality or custom UI elements for SCPUI. They can include their own submodules, controllers, and other assets. Extensions are ideal for games that require unique user interfaces as part of the SCPUI system.
**Naming convention: `scpui_ext_*.lua`
**Variables: Each extension must include the following variables:
***Name: The user-facing name of the extension.
***Version: The current version of the extension.
***Submodule: The text used to find the extension's submodules.
***Key: The key that will be used to access the Extension within the <code>ScpuiSystem.extensions</code> table.
**Initialization: Each extension must include an init function. SCPUI will call this function as soon as the extension is loaded.
**Post Initialization: Each extension may optionally include a postInit function. SCPUI will call this function after init and all submodules are loaded.
**Structure: Extensions must return themselves as a table when called.
**Loading: Extensions are loaded after SCPUI's core submodules during SCPUI's initialization.
**Examples: A custom campaign journal interface or a map UI.

*'''Plugins''': Plugins are lightweight, optional scripts that are loaded after SCPUI has initialized. They allow downstream mods or users to add custom behavior or extend functionality without modifying SCPUI's core files. Plugins are intended for advanced users who want to integrate new features or adjust existing ones.
**Naming convention: `scpui_plg_*.lua`
**Loading: Plugins are loaded last during SCPUI's initialization after everything else is ready.
**Examples: A plugin to log custom analytics data or define [[#UI_Topics|UI Topics]] binds.

*'''Controllers''': Controllers are Lua scripts associated with a specific UI. They manage the logic, data handling, and interactions for that UI state.
**Naming convention: `ctrlr_*.lua`
**Loading: Controllers are loaded by a markdown (RML) file; defined in the header section of that file.
**Examples: A controller for the main menu, mission briefing screen, or in-game options screen.

*'''Libraries''': Libraries are reusable utility scripts that provide specific functionality without being tied to a particular UI state or task. They are designed to be called from other scripts as needed.
**Naming convention: `lib_*.lua`
**Structure: Libraries should return themselves as a table when called.
**Loading: Libraries are loaded when needed by using a <code>require()</code> method call.
**Examples: A library for data saving/loading, dialog pop-ups, or utility methods.

===Librocket===
[[librocket|Librocket]] is a pseudo html/css rendering library included with FSO. It is designed as a complete solution for any project's interface needs.SCPUI uses this library to create and manage each UI context.

LibRocket uses the time-tested open standards XHTML1.0 and CSS2.0 (while borrowing features from HTML5 and CSS3), and extends them with features suited towards real-time applications.

Documentation on how to interface with the librocket API can be found [[librocket|here]].

===Game State Management===
SCPUI's game state management is handled by the [[scpui.tbl]] file that simply lists the game state from [[List_of_Game_States|FSO's game states]] and matches it with an RML file that will be associated. One notable exception is GS_STATE_SCRIPTING** which allows for substates. This feature means that you can effectively create an unlimited amount of custom UIs that all exist within GS_STATE_SCRIPTING**.

*To call a built-in game state use ba.postGameEvent("gamestate").
*To call a scripting substate use ScpuiSystem:beginSubstate("substate")

<nowiki>**</nowiki>GS_STATE_SCRIPTING_MISSION can be used for custom UIs that should not end the mission when loaded.

===UI Topics===
SCPUI implements a way to essentially do modular scripting which allows downstream games to modify how SCPUI works without having to carry a complete copy of SCPUI itself. This system is called UI Topics. These work very similar to FSO engine hooks. There are listeners throughout the SCPUI script base that can be attached to in order to modify behavior of various screens, buttons, or other elements. Every screen contains an initialize topic which is the last code run when a game state is started and a screen is created. As a basic example, [[bta|Between the Ashes]] uses this to modify the background image that is used throughout. Here is the Topic code that is used to change the Fiction Viewer background.
<pre>
local Topics = require('lib_ui_topics')
local Utils = require ('lib_utils')

Topics.fictionviewer.initialize:bind(1, function(message, context)
campaignfilename = ba.getCurrentPlayer():getCampaignFilename()
local main = message.document:GetElementById("main_background")
if useSubspaceBG(main) then return end
if Utils.isOneOf(campaignfilename, "bta1_m", "bta2_m", "bta-tem_m") then
main:SetClass("fiction_viewer_bg", true)
end
end)
</pre>
Topics sometimes include relevant data in the parameters called <code>message</code> and can change specific values by settings <code>context.value</code>. The initialize topics, like the example above, always send the entire UI document reference. There are others, like the loading screen loading bar that sends the loading bar filename only and expects a filename return. Here is an example that changes the default loading bar image to something else.
<pre>
Topics.loadscreen.load_bar:bind(9999, function(message, context)
context.value = "fancyloadingbar"
end)
</pre>

Topics are run based on the priority value, the argument in the bind() method, in order from lowest number to highest. You can prevent higher priority topics from being run at all by setting <code>context.done = true</code> inside a Topic.

A full list of available topics can be found in SCPUI's <code>lib_ui_topics.lua</code> file.

===Data Saver===
SCPUI comes with a set of Lua functions to handle saving and loading custom data quickly and easily for any kind of custom data you need. The data is saved to a json file using a hashed version of the mod's [[Game_settings.tbl#.24Mod_title:|mod title]] and the hash can be further randomized by setting a custom seed in [[Scpui.tbl#.24Data_Saver_Multiplier:|scpui.tbl]].

Data can be saved as 'persistent' or 'not persistent'. Persistent data is saved to <pre>data/players</pre>, meaning it will be available to your mod even across mod versions. Non persistent data is saved to <pre>data/config</pre> instead.

All data is saved on a per-pilot basis.

====Saving Arbitrary Data====
Make sure the data you intend to save can be converted to JSON. Basically don't send any userdata. Access datasaver by calling <pre>local DataSaver = require("lib_datasaver")</pre>. You can then save arbitrary data with a call like this <pre>DataSaver:saveDataToFile("data title", saveData, true)</pre>.

Saving data takes three arguments. First is the name of the data. It should be a string. Second is the data to save. The last argument defines if the data is saved as 'persistent' (true) or 'not persistent' (false) which defines where the data is saved to.

====Loading Arbitrary Data====
Loading arbitrary data is just as easy. Set up datasaver with a call like this <pre>local DataSaver = require("lib_datasaver")</pre>. Then simply ask for the data you want to load like this <pre>local saveData = DataSaver :loadDataFromFile("data title", true) or {}</pre>.

Loading data takes two arguments. First is the name of the data and should match the name you used to save with. It should be a string. The second argument defines if the data is loaded as 'persistent' (true) or 'not persistent' (false) which defines where the data is loaded from.

===Custom Mod Options===
[[Image:Screen0594.png|thumb|right|480px|The Custom Options in the [[bta|Between the Ashes]] mod.]]
SCPUI comes with a built-in feature to allow for custom in-game options specific to a particular mod. These options are defined by [[options.tbl]] and saved to the player folder as <code>scpui_options.cfg</code>. Scripts can take advantage of this feature to allow players to customize how scripts run, or if they even run at all.

For example, you could take the [https://github.com/FSO-Scripters/fso-scripts/tree/master/radaricon HUD Icons script] and create a global toggle. This allows players to turn HUD Icons on or off entirely. Furthermore you could allow customizing the max opacity of the icons, the distance at which the icons become fully transparent, and the distance at which the icons become fully opaque. These options will all within the in-game Options UI.

*''''Note that [[game_settings.tbl#$Mod_title:|$Mod_title:]] in [[game_settings.tbl]] is required for this feature to work!''''
*It's a good idea to make sure your mod title is unique to avoid mod options collisions.

====Options.tbl====
This table file is used to define the Options buttons within the Options UI.
*It can be extended with xxx-optn.tbl
*[[options.tbl|Documentation on the options.tbl is available here.]]

====Save Structure====
The player's options are saved to <code>scpui_options.cfg</code> in data/players. This makes the options available across mod versions. The save structure within the file follows a player->mod->option hierarchy. (See example below.) This allows for each player to have their own preferences for each mod they play without interfering with other players' preferences.
<pre>
"John": {
"Between The Ashes": {
"Alarm_Voice": "Vasudan",
"Verbose_Debugging": "Off",
"Font_Multiplier": 2,
"Icon_Far": 2,
"Icon_Near": 5,
"Brief_Render_Option": "Texture",
"Icon_Opacity": "1",
"Cockpit_Alarms": "On",
"HUD_Icons": "Off",
"Cockpit_Rendering": "Off",
"Easter_Eggs": "On"
}
},
"Mike": {
"Between The Ashes": {
"Cockpit_Rendering": "Off",
"Easter_Eggs": "On",
"Font_Multiplier": 5,
"Icon_Far": 2,
"Icon_Near": 5,
"Brief_Render_Option": "Texture",
"Icon_Opacity": "1",
"Cockpit_Alarms": "On",
"HUD_Icons": "Off",
"Verbose_Debugging": "On",
"Alarm_Voice": "Female"
}
}
</pre>

====Accessing Save Data====
Modifying Options within the in-game UI and saving those values to a file is just a start. In order for these options to do anything, you'll need to hook them into your scripts. After the Pilot Select screen and a player is chosen, the current Options are available in a global variable called <code>ScpuiOptionValues</code> with direct access to a specific option by specifying the [[options.tbl#+Key:|option key]]. In order to apply these options create a UI Topic connected to <code>options.apply</code> and run the appropriate code there.
<pre>
#Conditional Hooks
$Application: FS2_Open
$On State End:
[
(function()

local topics = require('lib_ui_topics')
local md = require("debugFunctions")

--Apply user settings to relevant script data
topics.options.apply:bind(9999, function(message, context)

--Handle HUD Icon Option
if ScpuiSystem.data.ScpuiOptionValues.HUD_Icons == "On" then
md.print("MOD OPTION: Player disabled HUD Icons")
RadarIcon.PlayerEnabled = true
else
md.print("MOD OPTION: Player enabled HUD Icons")
RadarIcon.PlayerEnabled = false
end

end)

end)()
]
#End
</pre>

====Pilot Select====
The pilot select UI has special handling of custom mod options because player preferences cannot be loaded until a player is selected. For this specific use case, SCPUI creates a <code>scpui_options_global.cfg</code> whenever user preferences are saved. This file contains no mod or player specific information in the save structure. It is just a list of key/value pairs for the most recently used pilot.
*This setup can be used to perform script actions before a player is selected if necessary.
*In this case, options are still available as '''''ScpuiOptionValues'''''' and accessed the same way, but there is no guarantee that the option will exist depending on the last mod the player played.

===Dialog Popups===
Freespace Open has a number of built-in dialog popups throughout the user interface. SCPUI automatically intercepts those popups and displays them as a librocket styled popup window.

You can create your own custom dialog popups within the UI scripts. To do this you must include <code>local Dialogs = require("lib_dialogs")</code> within the scope of your script. The dialogs function has several parameters for you to define.

====Title====
*Used to define the title of the dialog window.
*<code>dialog:title("yourtitle")</code>

====Text====
*Used to define the text or description your popup will contain.
*<code>dialog:text("yourtext")</code>

====Input====
*Defines if the user can type a string as input
*Useful for allowing the user to name pilots, saves, etc
*User must press ENTER to allow the code to execute on the provided string
*True to allow input, false to disallow. Defaults to false if this parameter is not provided.
**<code>dialog:input(boolean)</code>

====Buttons====
*Defines the user-clickable buttons that will be included in the dialog. It has the following parameters
*Type can be one of the following:
**Dialogs.BUTTON_TYPE_POSITIVE
**Dialogs.BUTTON_TYPE_NEGATIVE
**Dialogs.BUTTON_TYPE_NEUTRAL
*Text is the text for the button, such as "Okay".
*Value is the data that will be returned when the button is clicked.
*Keypress is the keyboard shortcut for this button.
*<code>dialog:buttons(type, text, value, keypress)</code>

====Escape====
*Used to define if the user should be able to cancel the dialog popup with the ESC key.
*A non nil value enables ESC and will be the return value if ESC is pressed
*<code>dialog:escape(value)</code>

====Show====
*This is the final step that displays the popup and defines how to handle the return values
*return values come back as the parameter ''response''
*The ui.enableInput() here specifically enables input on the dialog popup context. The dialog will automatically return input to the SCPUI context when it's closed.
<pre>
dialog:show(self.document.context)
:continueWith(function(response)
"Execute code here"
end)
ui.enableInput(self.document.context)
</pre>

===Preload Coroutines===
SCPUI has a preload system that is used to generate the loadout icon cache. However, it is possible to add any number of arbitrary preload coroutines. To add a preload, call <code>ScpuiSystem:addPreload()</code> with the following arguments:
*Debug Message
**The message to print to the log when this preload coroutine is run.
*Debug String
**The text string to draw to the screen when this preload coroutine is run and FSO is run in debug mode.
*Function
**The actual function to call. Will be called with pcall and errors with the call will halt game execution.
*Args
**Any arguments you want to pass to your function in a table.
*Priority
**This should be a 1 or 2 and determines if this coroutine runs during the first splash image or the second. This allows having coroutines build upon each other if necessary.

An example of an icon coroutine call.
<pre>
ScpuiSystem:addPreload(
"Generating icon for " .. v.Name,
"Generating " .. v.Name .. " icon",
ScpuiSystem.setIconFrames,
{ScpuiSystem, v.Name, true},
2
)
</pre>

===Individual UIs===
All game stages are now supported with the following exceptions:

*Cutscenes
**Because of FSO/Librocket limitations, viewing a cutscene actually sets SCPUI to a [[Scpui.tbl#Substate:|Scripting Substate]] for the duration of the cutscene itself.
*F3 Lab is not supported as an SCPUI style UI. It will use the Base FSO UI
*F3 In-game options is not supported as an SCPUI style UI.
**This is because SCPUI integrates in-game options directly into the main options UI.
*Multi UIs have not been thoroughly tested and may be buggy

===Development and Debugging===
There are three main things to know when developing and debugging SCPUI.

#You can view the librocket debugger by pressing '''''ctrl-shift-d'''''
#You can live-reload RML and RCSS files by pressing '''''ctrl-shift-r'''''
**It's worth noting that Librocket will drop the existing elements and lose them in memory. This will cause a warning on game-exit.
#Librocket API warnings and errors are not currently forwarded to FSO's error handling. Because of this, simple bugs in your Lua code that uses the API can cause FSO to crash.
#You can force regenerating all loadout icons by pressing F12 during FSO's splash screen.
#You can force deleting the current mission's loadout by pressing F12 during mission loading.

===Tips===
*In general, the ui system will handle passing control back and forth between the SCPUI context and FSO. In rare cases you may need to handle this manually. The FSO API methods ui.enableInput() and ui.disableInput() are provided to handle this case.

*For 3D weapon selection, SCPUI can only use [[Weapons.tbl#.24Tech_Model:|Tech models]] and you need to make sure you have [[Weapons.tbl#.2BCloseup_Pos:|Closeup_Pos]] and [[Weapons.tbl#.2BCloseup_Zoom:|Closeup_Zoom]] set. If you don't have a tech model, just set the regular model file as the tech model in your table.

===Tutorials===
*TODO
[[Category:SCPUI]]

Template:Tables

2026-02-16T15:29:10Z

MjnMixael:

{| border=0 align=right cellpadding=2 cellspacing=1 style="margin: 0 0 1em 1em; background: #202020; border: 1px #AA2020 solid; border-collapse: collapse; font-size: 95%;"
! colspan="2" style="color: white; height: 30px; background: #512020; 70%;"|'''''List of [[Tables]] and related code files'''''
|-
! colspan="2" style="color: white; height: 30px; background: #512020; 70%;"|'''* Notes [[Modular Tables]]'''
|-
! colspan="2" style="color: white; height: 30px; background: #512020; 70%;"|'''** Notes tables which only use modular tables'''
|-
| align="center"| [[Ai.tbl]]*
| '''/ai/'''aicode.cpp
|-
| align="center"| [[Ai_profiles.tbl]]*
| '''/ai/'''ai_profiles.cpp
|-
| align="center"| [[Animation.tbl]]**
| '''/model/'''modelanimation.cpp
|-
| align="center"| [[Armor.tbl]]*
| '''/ship/'''ship.cpp
|-
| align="center"| [[Asteroid.tbl]]*
| '''/asteroid/'''asteroid.cpp
|-
| align="center"| [[Autopilot.tbl]]*
| '''/autopilot/'''autopilot.cpp
|-
| align="center"| [[Cheats.tbl]]*
| '''/cheats_table/'''cheats_table.cpp
|-
| align="center"| [[Colors.tbl]]*
| '''/globalincs/'''alphacolors.cpp
|-
| align="center"| [[Curves.tbl]]*
| '''/math/'''curves.cpp
|-
| align="center"| [[Controlconfigdefaults.tbl]]
| '''/controlconfig/'''controlsconfigcommon.cpp
|-
| align="center"| [[Credits.tbl]]*
| '''/menuui/'''credits.cpp
|-
| align="center"| [[Cutscenes.tbl]]*
| '''/cutscene/'''cutscenes.cpp
|-
| align="center"| [[Decals.tbl]]**
| '''/decals/'''decals.cpp
|-
| align="center"| [[Fireball.tbl]]*
| '''/fireball/'''fireballs.cpp
|-
| align="center"| [[Fonts.tbl]]*
| '''/graphics/'''font.cpp
|-
| align="center"| [[Game_settings.tbl]]*
| '''/mod_table/'''mod_table.cpp
|-
| align="center"| [[Glowpoints.tbl]]*
| '''/model/'''modelread.cpp
|-
| align="center"| [[Help.tbl]]*
| '''/gamehelp/'''contexthelp.cpp
|-
| align="center"| [[Hud_gauges.tbl]]*
| '''/hud/'''hudparse.cpp
|-
| align="center"| [[Icons.tbl]]*
| '''/mission/'''missionbriefcommon.cpp
|-
| align="center"| [[Iff_defs.tbl]]*
| '''/iff_defs/'''iff_defs.cpp
|-
| align="center"| [[Keywords.tbl]]*
| '''Not In Codebase'''
|-
| align="center"| [[Lighting_Profiles.tbl]]*
| '''/lighting/'''lighting_profiles.cpp
|-
| align="center"| [[Lightning.tbl]]*
| '''/nebula/'''neblightning.cpp
|-
| align="center"| [[Mainhall.tbl]]*
| '''/menuui/'''mainhallmenu.cpp
|-
| align="center"| [[Medals.tbl]]*
| '''/stats/'''medals.cpp
|-
| align="center"| [[Messages.tbl]]*
| '''/mission/'''missionmessage.cpp
|-
| align="center"| [[Mflash.tbl]]*
| '''/weapon/'''muzzleflash.cpp
|-
| align="center"| [[Music.tbl]]*
| '''/gamesnd/'''eventmusic.cpp
|-
| align="center"| [[Nebula.tbl]]*
| '''/nebula/'''neb.cpp
|-
| align="center"| [[Objecttypes.tbl]]*
| '''/ship/'''ship.cpp
|-
| align="center"| [[Options.tbl]]*
| '''Not In Codebase'''
|-
| align="center"| [[Particle Effects|Particle effects(-part.tbm)]]**
| '''/particle/effects'''...
|-
| align="center"| [[Post_processing.tbl]]
| '''/graphics/'''gropenglpostprocessing.cpp
|-
| align="center"| [[Props.tbl]]*
| '''/props/'''props.cpp
|-
| align="center"| [[Rank.tbl]]*
| '''/stats/'''scoring.cpp
|-
| align="center"| [[Scpui.tbl]]*
| '''Not In Codebase'''
|-
| align="center"| [[Scripting.tbl]]*
| '''/parse/'''scripting.cpp
|-
| align="center"| [[Ships.tbl]]*
| '''/ship/'''ship.cpp
|-
| align="center"| [[Dynamic SEXPs|Sexps.tbl]]**
| '''/parse/sexp/'''sexp_lookup.cpp
|-
| align="center"| [[Sounds.tbl]]*
| '''/gamesnd/'''gamesnd.cpp
|-
| align="center"| [[Species_defs.tbl]]*
| '''/species_defs/'''species_defs.cpp
|-
| align="center"| [[Species.tbl]]*
| '''/menuui/'''techmenu.cpp
|-
| align="center"| [[Ssm.tbl]]*
| '''/hud/'''hudartillery.cpp
|-
| align="center"| [[Stars.tbl]]*
| '''/starfield/'''starfield.cpp
|-
| align="center"| [[Strings.tbl]]*
| '''/localization/'''localize.cpp
|-
| align="center"| [[Tips.tbl]]*
| '''/menuui/'''playermenu.cpp
|-
| align="center"| [[Traitor.tbl]]*
| '''/stats/'''scoring.cpp
|-
| align="center"| [[Tstrings.tbl]]*
| '''/localization/'''localize.cpp
|-
| align="center"| [[Virtual_pofs.tbl]]*
| '''/model/'''modelreplace.cpp
|-
| align="center"| [[Weapon_expl.tbl]]*
| '''/weapon/'''weapons.cpp
|-
| align="center"| [[Weapons.tbl]]*
| '''/weapon/'''weapons.cpp
|-
|}<noinclude>[[Category:Templates|Tables]]</noinclude>

Template:Tables

2026-02-16T15:28:35Z

MjnMixael:

{| border=0 align=right cellpadding=2 cellspacing=1 style="margin: 0 0 1em 1em; background: #202020; border: 1px #AA2020 solid; border-collapse: collapse; font-size: 95%;"
! colspan="2" style="color: white; height: 30px; background: #512020; 70%;"|'''''List of [[Tables]] and related code files'''''
|-
! colspan="2" style="color: white; height: 30px; background: #512020; 70%;"|'''* Notes [[Modular Tables]]'''
|-
! colspan="2" style="color: white; height: 30px; background: #512020; 70%;"|'''** Notes tables which only use modular tables'''
|-
| align="center"| [[Ai.tbl]]*
| '''/ai/'''aicode.cpp
|-
| align="center"| [[Ai_profiles.tbl]]*
| '''/ai/'''ai_profiles.cpp
|-
| align="center"| [[Animation.tbl]]**
| '''/model/'''modelanimation.cpp
|-
| align="center"| [[Armor.tbl]]*
| '''/ship/'''ship.cpp
|-
| align="center"| [[Asteroid.tbl]]*
| '''/asteroid/'''asteroid.cpp
|-
| align="center"| [[Autopilot.tbl]]*
| '''/autopilot/'''autopilot.cpp
|-
| align="center"| [[Cheats.tbl]]*
| '''/cheats_table/'''cheats_table.cpp
|-
| align="center"| [[Colors.tbl]]*
| '''/globalincs/'''alphacolors.cpp
|-
| align="center"| [[Curves.tbl]]*
| '''/math/'''curves.cpp
|-
| align="center"| [[Controlconfigdefaults.tbl]]
| '''/controlconfig/'''controlsconfigcommon.cpp
|-
| align="center"| [[Credits.tbl]]*
| '''/menuui/'''credits.cpp
|-
| align="center"| [[Cutscenes.tbl]]*
| '''/cutscene/'''cutscenes.cpp
|-
| align="center"| [[Decals.tbl]]**
| '''/decals/'''decals.cpp
|-
| align="center"| [[Fireball.tbl]]*
| '''/fireball/'''fireballs.cpp
|-
| align="center"| [[Fonts.tbl]]*
| '''/graphics/'''font.cpp
|-
| align="center"| [[Game_settings.tbl]]*
| '''/mod_table/'''mod_table.cpp
|-
| align="center"| [[Glowpoints.tbl]]*
| '''/model/'''modelread.cpp
|-
| align="center"| [[Help.tbl]]*
| '''/gamehelp/'''contexthelp.cpp
|-
| align="center"| [[Hud_gauges.tbl]]*
| '''/hud/'''hudparse.cpp
|-
| align="center"| [[Icons.tbl]]*
| '''/mission/'''missionbriefcommon.cpp
|-
| align="center"| [[Iff_defs.tbl]]*
| '''/iff_defs/'''iff_defs.cpp
|-
| align="center"| [[Keywords.tbl]]*
| '''Not In Codebase'''
|-
| align="center"| [[Lighting_Profiles.tbl]]*
| '''/lighting/'''lighting_profiles.cpp
|-
| align="center"| [[Lightning.tbl]]*
| '''/nebula/'''neblightning.cpp
|-
| align="center"| [[Mainhall.tbl]]*
| '''/menuui/'''mainhallmenu.cpp
|-
| align="center"| [[Medals.tbl]]*
| '''/stats/'''medals.cpp
|-
| align="center"| [[Messages.tbl]]*
| '''/mission/'''missionmessage.cpp
|-
| align="center"| [[Mflash.tbl]]*
| '''/weapon/'''muzzleflash.cpp
|-
| align="center"| [[Music.tbl]]*
| '''/gamesnd/'''eventmusic.cpp
|-
| align="center"| [[Nebula.tbl]]*
| '''/nebula/'''neb.cpp
|-
| align="center"| [[Objecttypes.tbl]]*
| '''/ship/'''ship.cpp
|-
| align="center"| [[Options.tbl]]*
| '''Not In Codebase'''
|-
| align="center"| [[Particle Effects|Particle effects(-part.tbm)]]**
| '''/particle/effects'''...
|-
| align="center"| [[Post_processing.tbl]]
| '''/graphics/'''gropenglpostprocessing.cpp
|-
| align="center"| [[Props.tbl]]
| '''/props/'''props.cpp
|-
| align="center"| [[Rank.tbl]]*
| '''/stats/'''scoring.cpp
|-
| align="center"| [[Scpui.tbl]]*
| '''Not In Codebase'''
|-
| align="center"| [[Scripting.tbl]]*
| '''/parse/'''scripting.cpp
|-
| align="center"| [[Ships.tbl]]*
| '''/ship/'''ship.cpp
|-
| align="center"| [[Dynamic SEXPs|Sexps.tbl]]**
| '''/parse/sexp/'''sexp_lookup.cpp
|-
| align="center"| [[Sounds.tbl]]*
| '''/gamesnd/'''gamesnd.cpp
|-
| align="center"| [[Species_defs.tbl]]*
| '''/species_defs/'''species_defs.cpp
|-
| align="center"| [[Species.tbl]]*
| '''/menuui/'''techmenu.cpp
|-
| align="center"| [[Ssm.tbl]]*
| '''/hud/'''hudartillery.cpp
|-
| align="center"| [[Stars.tbl]]*
| '''/starfield/'''starfield.cpp
|-
| align="center"| [[Strings.tbl]]*
| '''/localization/'''localize.cpp
|-
| align="center"| [[Tips.tbl]]*
| '''/menuui/'''playermenu.cpp
|-
| align="center"| [[Traitor.tbl]]*
| '''/stats/'''scoring.cpp
|-
| align="center"| [[Tstrings.tbl]]*
| '''/localization/'''localize.cpp
|-
| align="center"| [[Virtual_pofs.tbl]]*
| '''/model/'''modelreplace.cpp
|-
| align="center"| [[Weapon_expl.tbl]]*
| '''/weapon/'''weapons.cpp
|-
| align="center"| [[Weapons.tbl]]*
| '''/weapon/'''weapons.cpp
|-
|}<noinclude>[[Category:Templates|Tables]]</noinclude>

Props.tbl

2026-02-16T15:27:18Z

MjnMixael:

{{TableVersion|20260217}}
{{Tables}}
The '''props.tbl''' is used to define all of the props in the game. Props are distinct from ships in that they are entirely non-interactable except for collisions. They cannot move and they cannot be destroyed. Props are created in FRED with SHIFT-CTRL-CLICK.

Props are available in FSO builds starting with nightly build 20260217.

This table is one of the [[Modular Tables]] and can be extended with xxx-prp.tbm

==General Format==
*'''#Prop Categories'''
*Currently only used to colorize and sort the props into the list in FRED.
*'''#End'''
*'''#Props'''
*The props
*'''#End'''

==#Prop Catregories==
*Used to define the color of the prop in the FRED list and to list props in similar categories together.

===$Name:===
*Defines the name of the category
*Syntax: '''string'''

===+Color:===
*Defines the color of the prop text in the FRED list in RGB values.
*Syntax: '''integer, integer, integer'''

==#Props==
*The actual definitions for each prop.
*Unlike ships and weapons, there is no limit to prop definitions.

===$Name:===
*Defines the name of the prop. Must be unique.
*Syntax: '''string'''

===+nocreate===
{{Table3610|
*In [[Modular Tables]] name can be followed by line '''+nocreate''' that prevent game from creating an incomplete entry by leaving the entry unread unless it already exists (either in ship.tbl or in earlier parsed *-shp.tbm files) by the time the *-shp.tbm is read.}}

===+remove===
{{Table210|
*In [[Modular Tables]] a name can be followed by the line '''+remove''' to completely remove a previously parsed entry.}}

===$POF file:===
*The POF file for the prop
*Syntax: '''string'''

===$Closeup_pos:===
*How the model will show on the Loadout Screen. The position of the camera relative to the model center. Only valid if a tech model is defined
*Syntax: '''''Vector''''', three '''floats''', x, y and z values respectively

===$Closeup_zoom:===
*How the model will show on the Loadout Screen. How far the camera's zoomed in, defines camera's FOV.
*Syntax: '''''Float''''', radians

===$Detail Distance:===
*Defines the distance where the change between different Levels-Of-Details (LODs) occurs
*Take notice that these are base values. Model detail in Detail options, (within game press F2), applies a multiplier to these values. These multipliers default to (from left to right): 1/8, 1/4, 1, 4, and 8, and may be overridden by the [[Ai_profiles.tbl#$Detail Distance Multiplier:|$Detail Distance Multiplier]]
*Syntax: '''''(Detail Distances)''''' , list of '''integers''' (same amount as LODs), distances from the model in meters
**Example: ''(0, 80, 300, 900)''

===$Category:===
*The category (listed above) that this prop belongs to
*Will be set to "Unknown Category" if not valid
*Syntax: '''string'''

===$Flags:===
*See [[Props.tbl#Props.tbl_flags|below]]
*Syntax: '''''( "String" "String" )''''', names of the flags assigned to the prop
**Example: ( "no-collide", "no fred" )

===$Custom data:===
*Defines a set of custom data that for this prop class, which can then be accessed through Lua scripts. There can be any amount of +Val: entries. It requires a $end_custom_data entry at the end.
Check the scripting documentation of Prop Class to find the CustomData Lua Table.
====+Val:====
*Specifies a custom data value and its name, in the format
*<code>+Val: Name Value</code>
*These values will always be strings of text. If you use them in Lua as other types of value, you might need to convert them in the script.
*Syntax: '''string'''

====$end_custom_data====
*Mandatory entry to indicate that the Custom Data list has ended.

===$Custom strings:===
*Defines a set of custom strings that for this prop class, which can then be accessed through Lua scripts. There can be any amount of entries. It requires a $end_custom_strings entry at the end.
Check the scripting documentation of Prop Class to find the CustomStrings Lua Table.

====$Name:====
*Specifies a custom string name
*Syntax: '''string'''

====+Value:====
*Specifies a "value" or additional data point paired with the string. A common use case is an XSTR ID.
*Syntax: '''string'''

====+String:====
*The actual string which is a multitext string
*Must end with $end_multi_text
*Syntax: '''string'''

====$end_multi_text====

===$end_custom_strings===
*Mandatory entry to indicate that the Custom Strings list has ended.

===#End===
*Mandatory entry to indicate the props definitions have ended.

==Props.tbl flags==

==="no_collide"===
*Defines ship as non-collideable, ie. everything will go through it

==="no_fred"===
*Ship will not appear in any of the FRED dropdown lists for ship classes.

==="no lighting"===
Ship will not receive lighting calculations

==Sample==
*Single Prop entry table

<pre>
#PROP CATEGORIES

$Name: Rocks
+Color: (165, 42, 42)

$Name: Planets
+Color: (0, 255, 0)

#PROPS

$Name: Planet 1
$POF file: ast01.pof
$Detail distance: (400, 1000, 2000, 4000)
$Category: Planets

$Name: Rock
$POF file: asteroid01-01.pof
$Detail distance: (400, 1000, 2000, 4000)
$Category: Rocks

$Name: Planet 2
$POF file: ast02.pof
$Detail distance: (400, 1000, 2000, 4000)
$Category: Planets

$Name: Rock 2
$POF file: asteroid02-01.pof
$Detail distance: (400, 1000, 2000, 4000)
$Category: Rocks

#END
</pre>

[[Category:tables]]

Props.tbl

2026-02-16T15:25:36Z

MjnMixael: Created page with "{{TableVersion|20260217}} {{Tables}} The '''props.tbl''' is used to define all of the props in the game. Props are distinct from ships in that they are entirely non-interactab..."

{{TableVersion|20260217}}
{{Tables}}
The '''props.tbl''' is used to define all of the props in the game. Props are distinct from ships in that they are entirely non-interactable except for collisions. They cannot move and they cannot be destroyed.

Props are available in FSO builds starting with nightly build 20260217.

This table is one of the [[Modular Tables]] and can be extended with xxx-prp.tbm

==General Format==
*'''#Prop Categories'''
*Currently only used to colorize and sort the props into the list in FRED.
*'''#End'''
*'''#Props'''
*The props
*'''#End'''

==#Prop Catregories==
*Used to define the color of the prop in the FRED list and to list props in similar categories together.

===$Name:===
*Defines the name of the category
*Syntax: '''string'''

===+Color:===
*Defines the color of the prop text in the FRED list in RGB values.
*Syntax: '''integer, integer, integer'''

==#Props==
*The actual definitions for each prop.
*Unlike ships and weapons, there is no limit to prop definitions.

===$Name:===
*Defines the name of the prop. Must be unique.
*Syntax: '''string'''

===+nocreate===
{{Table3610|
*In [[Modular Tables]] name can be followed by line '''+nocreate''' that prevent game from creating an incomplete entry by leaving the entry unread unless it already exists (either in ship.tbl or in earlier parsed *-shp.tbm files) by the time the *-shp.tbm is read.}}

===+remove===
{{Table210|
*In [[Modular Tables]] a name can be followed by the line '''+remove''' to completely remove a previously parsed entry.}}

===$POF file:===
*The POF file for the prop
*Syntax: '''string'''

===$Closeup_pos:===
*How the model will show on the Loadout Screen. The position of the camera relative to the model center. Only valid if a tech model is defined
*Syntax: '''''Vector''''', three '''floats''', x, y and z values respectively

===$Closeup_zoom:===
*How the model will show on the Loadout Screen. How far the camera's zoomed in, defines camera's FOV.
*Syntax: '''''Float''''', radians

===$Detail Distance:===
*Defines the distance where the change between different Levels-Of-Details (LODs) occurs
*Take notice that these are base values. Model detail in Detail options, (within game press F2), applies a multiplier to these values. These multipliers default to (from left to right): 1/8, 1/4, 1, 4, and 8, and may be overridden by the [[Ai_profiles.tbl#$Detail Distance Multiplier:|$Detail Distance Multiplier]]
*Syntax: '''''(Detail Distances)''''' , list of '''integers''' (same amount as LODs), distances from the model in meters
**Example: ''(0, 80, 300, 900)''

===$Category:===
*The category (listed above) that this prop belongs to
*Will be set to "Unknown Category" if not valid
*Syntax: '''string'''

===$Flags:===
*See [[Props.tbl#Props.tbl_flags|below]]
*Syntax: '''''( "String" "String" )''''', names of the flags assigned to the prop
**Example: ( "no-collide", "no fred" )

===$Custom data:===
*Defines a set of custom data that for this prop class, which can then be accessed through Lua scripts. There can be any amount of +Val: entries. It requires a $end_custom_data entry at the end.
Check the scripting documentation of Prop Class to find the CustomData Lua Table.
====+Val:====
*Specifies a custom data value and its name, in the format
*<code>+Val: Name Value</code>
*These values will always be strings of text. If you use them in Lua as other types of value, you might need to convert them in the script.
*Syntax: '''string'''

====$end_custom_data====
*Mandatory entry to indicate that the Custom Data list has ended.

===$Custom strings:===
*Defines a set of custom strings that for this prop class, which can then be accessed through Lua scripts. There can be any amount of entries. It requires a $end_custom_strings entry at the end.
Check the scripting documentation of Prop Class to find the CustomStrings Lua Table.

====$Name:====
*Specifies a custom string name
*Syntax: '''string'''

====+Value:====
*Specifies a "value" or additional data point paired with the string. A common use case is an XSTR ID.
*Syntax: '''string'''

====+String:====
*The actual string which is a multitext string
*Must end with $end_multi_text
*Syntax: '''string'''

====$end_multi_text====

===$end_custom_strings===
*Mandatory entry to indicate that the Custom Strings list has ended.

===#End===
*Mandatory entry to indicate the props definitions have ended.

==Props.tbl flags==

==="no_collide"===
*Defines ship as non-collideable, ie. everything will go through it

==="no_fred"===
*Ship will not appear in any of the FRED dropdown lists for ship classes.

==="no lighting"===
Ship will not receive lighting calculations

==Sample==
*Single Prop entry table

<pre>
#PROP CATEGORIES

$Name: Rocks
+Color: (165, 42, 42)

$Name: Planets
+Color: (0, 255, 0)

#PROPS

$Name: Planet 1
$POF file: ast01.pof
$Detail distance: (400, 1000, 2000, 4000)
$Category: Planets

$Name: Rock
$POF file: asteroid01-01.pof
$Detail distance: (400, 1000, 2000, 4000)
$Category: Rocks

$Name: Planet 2
$POF file: ast02.pof
$Detail distance: (400, 1000, 2000, 4000)
$Category: Planets

$Name: Rock 2
$POF file: asteroid02-01.pof
$Detail distance: (400, 1000, 2000, 4000)
$Category: Rocks

#END
</pre>

[[Category:tables]]