Options.tbl

From FreeSpace Wiki
Revision as of 14:19, 9 October 2023 by MjnMixael (talk | contribs) (+Valid Values:)
Jump to: navigation, search

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

Options.tbl can be extended with xxx-optn.tbm.

Options.tbl

  • Begins with #Custom Options and ends with #End

$Name:

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

+Description:

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

+Key:

  • This is a unique key identifier that can be used to access the option's data
  • Required
  • Syntax: string

+Type:

+Column:

  • The column to put the option in within the interface
  • Valid values are 1-4
  • Required
  • Syntax: integer

+Valid Values

  • Starts a section of value definitions
  • Must be followed by exactly 2 +Val: values for Binary options
  • Must be followed by at least 2 +Val: values for Multi options
  • Required only for Binary and Multi 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
  • Must be followed by exactly 5 +Val: values for FivePoint options
  • Must be followed by at least 2 +Val: values for Multi options and must match the number of values defined
  • Required only for Binary, Multi, and FivePoint 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
  • 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
  • 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
  • Syntax: FivePoint or TenPoint integer, Range float, Binary or Multi string

+Force Selector:

  • 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
  • Defaults to false
  • Syntax: boolean

+No Default:

  • 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
  • Defaults to false
  • Syntax: boolean

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.

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.

Example

#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