script_param_util¶

Source: base/tealdef/gui/main/script_param_util.d.tl

Notes

Widgets for script parameters (ScriptParam): the settings of the base game and of mods that are shown as buttons, icon buttons, sliders, combo boxes or checkboxes, e.g. in the new-game and mod settings and in the construction menu.

ScriptParamUtil¶

record global base/tealdef/gui/main/script_param_util.d.tl:3

global record ScriptParamUtil

Load: local script_param_util = ug_require "/gui/main/script_param_util.tl"

Notes

Builds UI widgets for script parameters and looks up the base game's parameters.

Details

A parameter's value is either an entry of its numbers list or, when it has no numbers, the 1-based index of the chosen entry of values.

Functions

buildScriptParamCompSimple(param : CompSimpleParam) : TreeNodeId base/tealdef/gui/main/script_param_util.d.tl:40

Call as script_param_util.buildScriptParamCompSimple

Notes

Builds the widget (with label) for a parameter described by ParamForUi.

Returns TreeNodeId

Example

-- from town_eow.script.tl
local scriptParam = script_param_util.getScriptParam(optionName)
script_param_util.buildScriptParamCompSimple({
    scriptParam = {
        uiType = scriptParam.uiType,
        name = scriptParam.name,
        values = scriptParam.values,
    },
    currentValue = sensitivityState:old(),
    onValueChange = function(index) commit(index, nil, nil) end,
    vertical = false,
})

Used in the base game: 4 times in 3 files

base/content/gui/gui/menu/mod_manager_react_util.tl:5857

scriptparamutil.buildScriptParamCompSimple({

base/content/gui/gui/construction/construction.tl:1161

scriptParamForUiOld and scriptParamUtil.buildScriptParamCompSimple({

base/content/gui/gui/entity_window/town/town_eow.script.tl:917

script_param_util.buildScriptParamCompSimple({

buildScriptParamComp(scriptParam : ScriptParam, initialIndex : integer, onValueChange : function(integer), addSpacer? : boolean, toggleButtonsFlowLayout? : boolean, onHover? : function(boolean), allowCoalesce? : boolean) : TreeNodeId base/tealdef/gui/main/script_param_util.d.tl:43

Call as script_param_util.buildScriptParamComp

filteredIndices are expected to be unique and sorted ascending --> these indices get filtered AWAY!

Notes

Builds the widget for a ScriptParam, starting at the choice initialIndex; onValueChange receives the new value.

Returns TreeNodeId

Used in the base game: 10 times in 3 files

base/content/gui/gui/map_editor/map_editor.tl:368

return scriptparamutil.buildScriptParamComp(scriptParam, scriptParam.defaultIndex, function(newValue : integer)

base/content/gui/gui/menu/advanced_settings.tl:181

local object = script_param_util.buildScriptParamComp(

base/content/gui/gui/menu/new_game_react_util.tl:385

element = script_param_util.buildScriptParamComp(

searchAndBuildScriptParamComp(key : string, getModParam : function(field : string) : number, setModParamField : function(field : string, value : number), addSpacer? : boolean, onHover? : function(isSelected : boolean), filterTags? : {string}, allowCoalesce? : boolean) : MenuIconReactUtil.HintWidgetParam.Data, TreeNodeId base/tealdef/gui/main/script_param_util.d.tl:52

Call as script_param_util.searchAndBuildScriptParamComp

filteredIndices are expected to be unique and sorted ascending --> these indices get filtered AWAY!

Notes

Looks up a base-game parameter by key (see getScriptParam) and builds its widget. The value is read with getModParam and written with setModParamField.

Returns MenuIconReactUtil.HintWidgetParam.Data, TreeNodeId: The hint data (title and description of the parameter) and the widget, or nil, nil when no parameter matches.

Used in the base game: 2 times in 2 files

base/content/gui/gui/menu/advanced_settings.tl:96

local data, object = script_param_util.searchAndBuildScriptParamComp(

base/content/gui/gui/menu/new_game_react_util.tl:283

local data, object = script_param_util.searchAndBuildScriptParamComp(

wrap(text : string, vertical : boolean, node : TreeNodeId, addSpacer? : boolean, onHover? : function(boolean), extraClass? : string) : TreeNodeId base/tealdef/gui/main/script_param_util.d.tl:62

Call as script_param_util.wrap

Notes

Puts a label text and a widget into one row (or column, when vertical), optionally with a spacer and a hover callback on the label.

Returns TreeNodeId

Used in the base game: 8 times in 4 files

base/content/gui/gui/map_editor/map_editor.tl:220

return scriptparamutil.wrap(text, bool, builtin.Component{

base/content/gui/gui/menu/new_game_or_map_settings_page.tl:223

element = script_param_util.wrap(

base/content/gui/gui/menu/advanced_settings.tl:227

table.insert(nodesAndTitle.nodes, script_param_util.wrap(

base/content/gui/gui/menu/new_game_react_util.tl:505

element = script_param_util.wrap(_("Seed"), false, builtin.BoxLayout{

getScriptParam(key : string, filterTags? : {string}) : ScriptParam base/tealdef/gui/main/script_param_util.d.tl:71

Call as script_param_util.getScriptParam

Notes

Finds a parameter of the base game (the mod with the empty name) by key.

Parameter	Type	Description
`key`	`string`	Key of the parameter.
`filterTags?`	`{string}`	Tags the parameter must have (compared case-insensitively, all must match); parameters without tags always match.

Returns ScriptParam: The parameter, or nil.

Used in the base game: 7 times in 4 files

base/content/gui/gui/map_editor/map_editor.tl:2113

local scriptParamIndustryDensity = scriptparamutil.getScriptParam("locations.industry.initialIndustryDensity", filterTags)

base/content/gui/gui/menu/new_game_or_map_settings_page.tl:19

local mapSizeParam = script_param_util.getScriptParam("map.size", filterTags)

base/content/gui/gui/menu/savegame_react_util.tl:55

local param = script_param_util.getScriptParam(key, filterTags)

base/content/gui/gui/entity_window/town/town_eow.script.tl:907

local scriptParam = script_param_util.getScriptParam(optionName)

clampScriptParamToDiscreteValue(value : number, scriptParam : ScriptParam) : number base/tealdef/gui/main/script_param_util.d.tl:72

Call as script_param_util.clampScriptParamToDiscreteValue

Notes

Returns the entry of the parameter's numbers closest to value, or, without numbers, value limited to the number of values.

Returns number

clampScriptParamValueIndex(value : number, scriptParam : ScriptParam) : integer base/tealdef/gui/main/script_param_util.d.tl:73

Call as script_param_util.clampScriptParamValueIndex

Notes

clampScriptParamToDiscreteValue, rounded to an integer.

Returns integer

Used in the base game: 4 times in 2 files

base/content/gui/gui/map_editor/map_editor.tl:534

params[scriptParam.key] = scriptparamutil.clampScriptParamValueIndex(params[scriptParam.key], scriptParam)

base/content/gui/gui/menu/new_game_or_map_settings_page.tl:23

size = script_param_util.clampScriptParamValueIndex(size, mapSizeParam) - 1

getScriptParamDefaultValue(numbers : {number}, defaultIndex : integer) : number base/tealdef/gui/main/script_param_util.d.tl:75

Call as script_param_util.getScriptParamDefaultValue

Notes

Returns numbers[defaultIndex] when numbers has more than defaultIndex entries, otherwise defaultIndex itself.

Returns number

Used in the base game: 1 time in 1 file

base/content/gui/gui/construction/construction.tl:1253

values[p.key] = scriptParamUtil.getScriptParamDefaultValue(

getScriptParamDefaultValueIndex(numbers : {number}, defaultIndex : integer) : integer base/tealdef/gui/main/script_param_util.d.tl:76

Call as script_param_util.getScriptParamDefaultValueIndex

Notes

getScriptParamDefaultValue, rounded to an integer.

Returns integer

Used in the base game: 1 time in 1 file

base/content/gui/gui/map_editor/map_editor.tl:536

params[scriptParam.key] = scriptparamutil.getScriptParamDefaultValueIndex(scriptParam.numbers, scriptParam.defaultIndex)

getScriptParamLabel(key : string, value : number, filterTags? : {string}) : string base/tealdef/gui/main/script_param_util.d.tl:77

Call as script_param_util.getScriptParamLabel

Notes

Returns the display text of the choice of a base-game parameter that is closest to value.

Returns string

getScriptParamLabelUnfiltered(key : string, value : number) : string base/tealdef/gui/main/script_param_util.d.tl:80

Call as script_param_util.getScriptParamLabelUnfiltered

get first match of the value (among all filterTags), or nil of no exact match

Returns string

Used in the base game: 4 times in 2 files

base/content/gui/gui/menu/new_game_or_map_settings_page.tl:216

local formatText = script_param_util.getScriptParamLabelUnfiltered("map.format", savegameData.info.modParams[""]["map.format"])

base/content/gui/gui/menu/savegame_react_util.tl:562

local formatText = script_param_util.getScriptParamLabelUnfiltered("map.format", param.savegameData.info.modParams[""]["map.format"])

ScriptParamUtil.ParamForUi¶

record base/tealdef/gui/main/script_param_util.d.tl:4

record ParamForUi

Notes

Description of a parameter for buildScriptParamCompSimple; usually copied from a ScriptParam.

Used in the base game: 17 times in 4 files

base/content/gui/gui/menu/mod_manager_react_util.tl:5841

local paramForUI : ScriptParamUtil.ParamForUi = {

base/content/gui/gui/construction/construction.tl:1003

scriptParamForUi : ScriptParamUtil.ParamForUi -- mutual exclusive to filterObjects

base/content/gui/gui/main/script_param_util.tl:55

local getNumChoices = function(scriptParam : ScriptParamUtil.ParamForUi) : integer

base/content/gui/gui/entity_window/town/town_eow.script.tl:908

local paramForUI : ScriptParamUtil.ParamForUi = {

Fields

Name	Type	Description
`uiType`	`ScriptParamType`	Kind of widget (button, icon button, slider, combo box, checkbox).
`iconStyle`	`IconStyle`	Style of the icons of an icon-button parameter.
`name`	`string`	Label of the parameter.
`values`	`{string}`	Display texts of the choices (for icon buttons, the icon paths).
`numbers`	`{number}`	Optional value of each choice; without it, the value is the 1-based choice index.
`tooltips`	`{string}`	Optional tooltip per choice.
`defaultIndex`	`integer`
`hideLabel`	`boolean`	In compact mode, hides the label of an icon-button parameter.
`allowCoalesce`	`boolean`	allows to delay onValueChange (e.g. when dragging a slider, it will delay onValueChange to mouse release)

Functions

makeCompactButtonFn(value : number) : TreeNodeId base/tealdef/gui/main/script_param_util.d.tl:21

Notes

Optional; builds the button content for a value (in compact mode and for button choices) instead of the default icon or text.

Returns TreeNodeId

formatValueFn(value : number) : string base/tealdef/gui/main/script_param_util.d.tl:22

Notes

Optional; formats a value for the text next to a slider.

Returns string

stepValueFn(value : number, direction : integer, precise : boolean) : number base/tealdef/gui/main/script_param_util.d.tl:23

No description in the game files yet.

Returns number

ScriptParamUtil.ParamForUi.IconStyle¶

enum base/tealdef/gui/main/script_param_util.d.tl:5

enum IconStyle

Notes

Display style of icon buttons.

Value	Description
`"Default"`	Icons as they are.
`"Colored"`	Icons with the coloured style class `forever-fair`.

ScriptParamUtil.CompSimpleParam¶

record base/tealdef/gui/main/script_param_util.d.tl:26

record CompSimpleParam is IRecipeParamWithMeta

Notes

Parameters of buildScriptParamCompSimple.

Used in the base game: 5 times in 1 file

base/content/gui/gui/main/script_param_util.tl:145

local ScriptParamCalloutWrapper = react.RegisterRecipe("ScriptParamCalloutWrapper", function(params : ScriptParamUtil.CompSimpleParam) : TreeNodeId

Fields

Name	Type	Description
`scriptParam`	`ParamForUi`	The parameter to show.
`currentValue`	`number`	Current value (see `ScriptParamUtil` for the meaning of values).
`toggleButtonsFlowLayout`	`boolean`	For button parameters, lay the buttons out in a flow instead of uniform cells.
`vertical`	`boolean`	Places the label above the widget instead of to its left; `nil` returns the widget without label.
`compact`	`boolean`	Shows only a small button that opens the full widget in a callout.
`addSpacer`	`boolean`	Adds a spacer on the right side of the row.
`disableGamepadNavigation`	`boolean`	Passed to the widget (e.g. the slider) to disable its gamepad navigation.
`gameCtx`	`GameContext`	Game context; needed in compact mode for the callout container.
`updateCurrentValue`	`boolean`

Functions

onValueChange(number) base/tealdef/gui/main/script_param_util.d.tl:29

Notes

Called with the new value when the user changes it.

onHover(boolean) base/tealdef/gui/main/script_param_util.d.tl:35

Notes

Called with true/false when the label gains or loses attention.