Skip to content

options.tbl

Jump to bottom
github-actions[bot] edited this page Oct 28, 2026 · 1 revision

SCPUI 0.9.0 The options.tbl is used by SCPUI to define special user or script preferences in the built-in SCPUI Options Interface.

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

Code: /content/data/scripts/scpui_sm_options.lua. See Tables for every table.

Badges show the SCPUI version a field or behavior was added in. Fields without a badge arrived with the table.

Contents

  1. Format
  2. #Custom Options
  3. Types
  4. Sample
Field index (every field, one per line in table order; click one to jump to it)

#Custom Options

Types

Format

  • Table begins with #Custom Options and ends with #End. Both are required in options.tbl and in every -optn.tbm.
  • Individual options, each starting with $Name:
  • Fields must appear in the order listed below.

#Custom Options

$Name:

  • Required. The user-facing name of the option.
  • Can be XSTR
  • Syntax: String

+Description:

  • Optional. A description for the option.
  • Can be XSTR
  • Displayed on mouseover of an option.
  • Syntax: String

+Key:

  • Required. This is a unique key identifier that can be used to access the option's data.
  • A key that is already used by another option is an error.
  • Syntax: String

+Type:

+Column:

  • Optional. The column to put the option in within the interface.
  • Valid values are 1-4. Values outside that range are clamped to it.
  • Syntax: Integer
  • Default: 1

+Valid Values

  • Starts a section of value definitions
  • Must be followed by exactly 2 +Val: values for Binary options. Fewer is an error; extra values are ignored with a warning.
  • Must be followed by at least 2 +Val: values for Multi options. Fewer is an error.
  • Required only for Binary and Multi types, and only read for those types

+Val:

  • Defines the internal values this option can have
  • Syntax: String

+Display Names

  • Starts a section of value display names
  • Display names should match the order of Valid Values.
  • Must be followed by exactly 2 +Val: values for Binary options. Fewer is an error; extra names are ignored with a warning.
  • Must be followed by exactly 5 +Val: values for FivePoint options. Fewer is an error; extra names are ignored with a warning.
  • Must be followed by at least 2 +Val: values for Multi options and must match the number of values defined. A mismatch is an error.
  • Required only for Binary, Multi, and FivePoint types, and only read for those types

+Val:

  • Defines the user-facing value name for value
  • Can be XSTR
  • Syntax: String

+Min:

  • Defines the low number for a Range option
  • Required only for Range types
  • Cannot be less than zero. A negative value is set to 0.
  • Syntax: Float

+Max:

  • Defines the high number for a Range option
  • Required only for Range types
  • Cannot be less than or equal to the Min value. If it is, an error is shown.
  • Syntax: Float

+Default Value:

  • Defines the default value the option will be set at
  • Required if option is not of type Header
  • Different option types require a different syntax
  • Range defaults are clamped to Min-Max, FivePoint defaults to 1-5 and TenPoint defaults to 1-10
  • Syntax: Integer for FivePoint or TenPoint, Float for Range, String for Binary or Multi

+Force Selector:

  • Optional. A binary option defaults to a two button style. This flag will force a binary option to use the same style as a Multi type option.
  • Not read for Header options
  • Syntax: Boolean
  • Default: false

+No Default:

  • Optional. Designates the behavior of this option for the Mod Default button within the SCPUI Option Interface.
  • If true then the option will be ignored
  • If false then the option will be reset to the default setting if the player clicks on the Mod Default button
  • Not read for Header options
  • Syntax: Boolean
  • Default: false

Types

Below is a list of valid option types that can be defined.

Header

This is not an actual option, but can be used for categorizing options under related headings. Will display as larger underlined text. Only $Name:, +Description:, +Key:, +Type: and +Column: are read for a Header.

Binary

This is an option with only two valid values. It can be displayed as a two-button style or like a multi selector. Returned values are always strings.

Multi

This is an option with any number of valid values and is displayed as a dropdown box selector. Returned values are always strings.

Range

This is an option that has a horizontal slider between min/max float values. Returned value will be a float.

FivePoint

This is an option with five settings that have a relationship from low to high. It will be displayed as five unique clickable points on a bar line and each point has a display string. It's the same kind of option that Difficulty uses. Returned value will be 1-5.

TenPoint

This is an option with ten settings that have a relationship from low to high. It will be displayed as ten unique clickable points on a bar line. Unlike FivePoint, it does not have a display string. Returned values will be 1-10.

Sample

#Custom Options

$Name: XSTR("Example Header", -1)
+Description: XSTR("Category header", -1)
+Key: Header_Example
+Type: Header
+Column: 2

$Name: XSTR("Example Binary Option", -1)
+Description: XSTR("This is a binary option. You can force it to be a selector with ForceSelector True.", -1)
+Key: Example_Binary
+Type: Binary
+Column: 2
+Valid Values
	+Val: Off
	+Val: On
+Display Names
	+Val: XSTR("Off", -1)
	+Val: XSTR("On", -1)
+Default Value: On
+Force Selector: false

$Name: XSTR("Example Selector Option", -1)
+Description: XSTR("This is a selector option.", -1)
+Key: Example_Selector
+Type: Multi
+Column: 2
+Valid Values
	+Val: String1
	+Val: String2
	+Val: String3
+Display Names
	+Val: XSTR("String1", -1)
	+Val: XSTR("String2", -1)
	+Val: XSTR("String3", -1)
+Default Value: String1

$Name: XSTR("Example Range Option", -1)
+Description: XSTR("This is a range option. It needs more testing. Min cannot be negative!", -1)
+Key: Example_Range
+Type: Range
+Column: 2
+Min: 0
+Max: 2
+Default Value: 1

$Name: XSTR("Example Ten Point", -1)
+Description: XSTR("This is a ten point dot selector. It functions as a range where saved values will be 1-10.", -1)
+Key: Example_Ten_Point
+Type: TenPoint
+Column: 2
+Default Value: 1

$Name: XSTR("Example Five Point", -1)
+Description: XSTR("This is a five point dot selector. It functions as a range where saved values will be 1-5.", -1)
+Key: Example_Five_Point
+Type: FivePoint
+Column: 2
+Display Names
	+Val: XSTR("String1", -1)
	+Val: XSTR("String2", -1)
	+Val: XSTR("String3", -1)
	+Val: XSTR("String4", -1)
	+Val: XSTR("String5", -1)
+Default Value: 1

#End

SCPUI

Tables

libRocket

RML

RCSS

Lua API

Clone this wiki locally