scpui.tbl

The scpui.tbl is used by SCPUI to define what 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.

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

Code: /content/data/scripts/scpui_sm_parser.lua; #Medal Placements is read by /content/data/scripts/ctrlr_medals.lua. See Tables for every table.

Badges show the SCPUI version a field or behavior was added in. Fields without a badge are from SCPUI 0.5.0 or earlier.

Contents

1. Format
2. #Settings
3. #State Replacement
4. #Background Replacement
5. #Briefing Stage Background Replacement
6. #Loading Text
7. #Loading Screens
8. #Mission Screens
9. #Medal Placements
10. Sample

Field index (every field, one per line in table order; click one to jump to it)

#Settings

• $Mod ID:
• $Default FSO Font Name:
• $Hide Multiplayer:
• $Disable during Multiplayer:
• $Data Saver Multiplier:
• $Ship Icon Width:
• $Ship Icon Height:
• $Weapon Icon Width:
• $Weapon Icon Height:
• $Use Legacy Slider For Volume:
• $Database Unread Show String Badge:
• $Database Unread String Badge Class:
• $Database Unread String Badge Text:
• $Database Unread Show Icon Badge:
• $Database Unread Icon Badge Class:
• $Database Unread Icon Badge Filename:
• $Database Unread Badge Position:
• $Database Unread Item Class:
• $Minimum Splash Time:
• $Fade Splash Images:
• $Draw Splash Images:
• $Draw Splash Text:
• $Always Allow Show All:

#State Replacement

• $State:
• +Substate:
• +Markup:

#Background Replacement

• $Campaign Background:
  • +Campaign Filename:
  • +RCSS Class Name:
• $Mainhall Background:
  • +Mainhall Name:
  • +RCSS Class Name:

#Briefing Stage Background Replacement

• $Briefing Grid Background:
  • +Mission Filename:
  • +Default Background Filename:
  • +Stage Override:
    • +Background Filename:

#Loading Text

• $Name:
  • $Text:

#Loading Screens

• $Name:
  • $Loading Bar Image:
  • +Background Class:
  • $Tip:

#Mission Screens

• $Filename:
  • $Loading Screen:

#Medal Placements

• $Medal:
  • +Alt Bitmap:
  • +Alt Debrief Bitmap:
  • +Position X:
  • +Position Y:
  • +Width:
• FS1 Medal Numbering Chart

---

Format

• SCPUI defines what game states and substates exist for SCPUI through the use of this table file and modular -ui.tbms.
• Every section is optional, but the sections that are present must appear in the order they are listed on this page. The parser reads them in a fixed sequence, so a section placed out of order is not recognised.
• Fields within a section must also appear in the order listed here.
• Must end with #End. This applies to every -ui.tbm as well, since each one is parsed as a complete table.

#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, Between the Ashes has a -mod line like -mod BTA-2.0.0\content and so the default Mod ID will resolve to BTA. 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".
• Any character that is not a letter, number or underscore is replaced with _.
• 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.
• If no font with that name or index exists, SCPUI shows a warning and keeps the default font.
• Syntax: String
• Default: the font at index 1

$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:

• Optional. Specifies the width of the icon used for ships in the SCPUI system.
• Syntax: Integer
• Default: 128

$Ship Icon Height:

• Optional. Specifies the height of the icon used for ships in the SCPUI system.
• Syntax: Integer
• Default: 112

$Weapon Icon Width:

• Optional. Specifies the width of the icon used for weapons in the SCPUI system.
• Syntax: Integer
• Default: 112

$Weapon Icon Height:

• Optional. Specifies the height of the icon used for weapons in the SCPUI system.
• Syntax: Integer
• Default: 48

$Use Legacy Slider For Volume:

• Optional. Forces SCPUI to use the retail style 10-dot slider for volume controls instead of the more modern range slider controls.
• Syntax: Boolean
• Default: false

$Database Unread Show String Badge:

• Optional. If true, then unread database entries will display a text badge (such as "NEW!").
• Syntax: Boolean
• Default: true

$Database Unread String Badge Class:

• Optional. Specifies the RCSS class(es) to apply to the unread string badge element.
• This allows customization of font color, weight, or other text styling.
• Only letters, numbers, _ and - are kept; any other character separates class names, and duplicate class names are removed.
• Syntax: String (RCSS class name or space-separated list of class names)
• Default: no class is applied

$Database Unread String Badge Text:

• Specifies the text displayed in the unread string badge.
• Syntax: String
• Default: the localized "NEW!" string

$Database Unread Show Icon Badge:

• Optional. If true, then unread database entries will display an icon badge (an image).
• Syntax: Boolean
• Default: false

$Database Unread Icon Badge Class:

• Optional. Specifies the RCSS class(es) to apply to the unread icon <img> element.
• This allows control of icon sizing, margins, and positioning.
• Only letters, numbers, _ and - are kept; any other character separates class names, and duplicate class names are removed.
• Syntax: String (RCSS class name or space-separated list of class names)
• Default: no class is applied

$Database Unread Icon Badge Filename:

• Optional. Specifies the filename of the icon to use for the unread badge.
• The path is relative to the mod’s interface art directory.
• Syntax: String (filename, e.g. "new_badge.png")
• Default: no icon is shown

$Database Unread Badge Position:

• Optional. 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".
• CURRENTLY NOT SUPPORTED AND HARD RESETS TO LEFT
• Syntax: String
• Default: left

$Database Unread Item Class:

• Optional. 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).
• Only letters, numbers, _ and - are kept; any other character separates class names, and duplicate class names are removed.
• Syntax: String (RCSS class name or space-separated list of class names)
• Default: no additional class is applied

$Minimum Splash Time:

• Optional. Specifies the minimum time each splash screen should be shown in seconds during preload.
• Syntax: Integer
• Default: 2

$Fade Splash Images:

• Optional. Determines if the splash images should fade in and out during preload.
• Syntax: Boolean
• Default: true

$Draw Splash Images:

• Optional. Determines if the splash images should be drawn at all during preload.
• Syntax: Boolean
• Default: true

$Draw Splash Text:

• Optional. Determines if the splash text should be drawn at all during preload.
• Syntax: Boolean
• Default: true

$Always Allow Show All:

• Optional. Allows the Ctrl-Shift-S "show all" feature used in the tech room and other UIs to be used in release builds.
• Syntax: Boolean
• Default: false

#State Replacement

• This section defines what RML files are used to replace specific game states.

$State:

• The game state to replace from FSO's game states
• Syntax: String

+Substate:

• The name of the substate
• Required for GS_STATE_SCRIPTING and GS_STATE_SCRIPTING_MISSION, and only read for those two states
• GS_STATE_SCRIPTING_MISSION (SCPUI 1.1.0 and later) is for custom UIs that should not end the mission when loaded. Substates defined for it are also added to the SCPUI_Menus SEXP enum.
• 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 general_bg.
• All $Campaign Background: entries must come before any $Mainhall Background: entries.

$Campaign Background:

• Designates that a new define will follow
• Has no arguments

+Campaign Filename:

• The campaign filename. Any extension is stripped
• 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:

• SCPUI 1.1.0 to 1.1.2 read this in #Settings instead, with the same fields.
• Designates that a new define will follow
• Has no arguments

+Mainhall Name:

• The mainhall name. Everything from the first . onward is stripped, so the name must not contain a period
• 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 br-black.png 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
• Any extension is stripped
• Syntax: String

+Default Background Filename:

• The new default background file to use for the mission
• WITH extension. SCPUI shows a warning if the extension is missing
• 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 background file to use for the stage
• WITH extension. SCPUI shows a warning if the extension is missing
• Syntax: String

#Loading Text

• Defines named tip strings that loading screen profiles can display. Reference them from #Loading Screens with $Tip:.
• The tip is drawn in the div#loadscreen_tip element. All styling is done in RCSS.

$Name:

• The name of the tip. Used to reference it from $Tip:
• Syntax: String

$Text:

• Required. The tip text.
• XSTR is supported
• Syntax: String

#Loading Screens

• Defines named loading screen profiles. Assign them to missions in #Mission Screens.
• The table only carries data. Fonts, colors, positions and sizes are set in RCSS.

$Name:

• The name of the profile. Used to reference it from $Loading Screen:
• Syntax: String

$Loading Bar Image:

• Optional. The loading bar animation to use for this profile instead of the default.
• Syntax: String

+Background Class:

• Optional. An RCSS class that sets the loading screen background. Make sure this class exists in a loaded rcss file, such as load_screen_bgs.rcss!
• Can be repeated. If more than one is listed, one is picked at random on each load
• Syntax: String

$Tip:

• Optional. The name of a tip from #Loading Text to show on this screen.
• Can be repeated. If more than one is listed, one is picked at random on each load
• SCPUI shows a warning if the tip name does not exist
• Syntax: String

#Mission Screens

• Assigns a loading screen profile to a mission.

$Filename:

• The mission filename. Any extension is stripped
• Syntax: String

$Loading Screen:

• Required. The name of a profile from #Loading Screens.
• SCPUI shows a warning if the profile name does not exist
• 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.
• 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 Bitmap defined in medals.tbl.

$Medal:

• The name of the medal as defined in 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 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 below.
• Syntax: String

+Position X:

• Required. The X coordinate for the medal, as a percentage of the medals area.
• Syntax: Float

+Position Y:

• Required. The Y coordinate for the medal, as a percentage of the medals area.
• Syntax: Float

+Width:

• Required. The width of the medal, as a percentage of the medals area.
• A medal with no $Medal: entry is placed at 0, 0 with a width of 10
• 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.

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

Sample

#Settings

$Hide Multiplayer: true
$Database Unread String Badge Class: brightred

#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

$State: GS_STATE_SCRIPTING_MISSION
+Substate: MyInMissionMenu
+Markup: data/interface/markup/my_menu.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

#Loading Text

$Name: bta_tip_01
$Text: XSTR("Remember to match speed with your target.", -1)

#Loading Screens

$Name: bta1_screen
+Background Class: bta1_load_a
+Background Class: bta1_load_b
$Tip: bta_tip_01

#Mission Screens

$Filename: bta1_m1_01.fs2
$Loading Screen: bta1_screen

#Medal Placements

$Medal: Epsilon Pegasi Liberation
+Position X: 10.5
+Position Y: 20
+Width: 12

#End