new_game_react_util¶

Source: base/tealdef/gui/menu/new_game_react_util.d.tl

Notes

Helpers of the "new game" and "new map" settings pages, loaded with ug_require "/gui/menu/new_game_react_util.tl".

NewGameReactUtil¶

record global base/tealdef/gui/menu/new_game_react_util.d.tl:3

global record NewGameReactUtil

Load: local new_game_react_util = ug_require "/gui/menu/new_game_react_util.tl"

Notes

Helpers for building the new game / new map settings pages.

Functions

makeDefaultBaseModParams() : {string : Index} base/tealdef/gui/menu/new_game_react_util.d.tl:4

Call as new_game_react_util.makeDefaultBaseModParams

Notes

Returns the default index of every script parameter of the base game (mod "").

Returns {string : Index}: Parameter keys mapped to their default value index.

makeDefaultConfigDictForClimate(climate : string) : {{string, string}} base/tealdef/gui/menu/new_game_react_util.d.tl:5

Call as new_game_react_util.makeDefaultConfigDictForClimate

Notes

Builds the default config dictionary for a climate.

Parameter	Type	Description
`climate`	`string`	Name of the climate resource.

Returns {{string, string}}: List of {key, value} pairs: climate, economy and nameList (the climate's default economy and name list). Empty, with an error logged, if the climate does not exist.

gatherMapConfig(configDict : {{string, string}}) : MapConfig base/tealdef/gui/menu/new_game_react_util.d.tl:16

Call as new_game_react_util.gatherMapConfig

Notes

Finds the climate of a config dictionary and the terrain generators that can be used with it.

Parameter	Type	Description
`configDict`	`{{string, string}}`	Config dictionary (`{key, value}` pairs) with a `climate` entry.

Returns MapConfig: The climate description and the visible terrain generators of that climate that are neither editor-only nor import generators, sorted by order.

autoActivateConfigDictMods(activeMods : {string}, initialConfigDict : {{string, string}}) : {string} base/tealdef/gui/menu/new_game_react_util.d.tl:18

Call as new_game_react_util.autoActivateConfigDictMods

Notes

Adds the mods that config dictionary values refer to to a list of active mods.

Parameter	Type	Description
`activeMods`	`{string}`	Names of the active mods.
`initialConfigDict`	`{{string, string}}`	Config dictionary; a value of the form `<mod>::...` requires the mod `<mod>`.

Returns {string}: A copy of activeMods with the required mods added.

prepareState(initialConfigDict : {{string, string}}, possibleGenerators : {NewGameReactUtil.Generator}, initial : integer, autoActivateMods : boolean) : StatesBundle base/tealdef/gui/menu/new_game_react_util.d.tl:26

Call as new_game_react_util.prepareState

Notes

Reads the last used new game settings from the app config (mainMenuState) and completes them.

Parameter	Type	Description
`initialConfigDict`	`{{string, string}}`	Config dictionary of the map; used to auto-activate the mods it requires.
`possibleGenerators`	`{NewGameReactUtil.Generator}`	Available terrain generators; if the stored generator is not among them, the last one is used.
`initial`	`integer`	If set, a new random seed is generated.
`autoActivateMods`	`boolean`	If set (or `initial` is set), active mods that are no longer installed or are invisible are removed, and mods required by the config dictionary or marked `autoActivate` are added.

Returns StatesBundle: The initial states. Missing base-game parameters get their default index.

searchBuildAndAddScriptParamComp(settings : {NewGameReactUtil.SettingsEntry}, activeModsParamsState : ReactStateT<{string : {string : integer}}>, key : string, addSpacer? : boolean, filterTags? : {string}, otherKeysToSet? : {string}) : TreeNodeId base/tealdef/gui/menu/new_game_react_util.d.tl:41

Call as new_game_react_util.searchBuildAndAddScriptParamComp

Notes

Builds the control for a base-game script parameter and appends it to settings.

Parameter	Type	Description
`settings`	`{NewGameReactUtil.SettingsEntry}`	List the entry is appended to.
`activeModsParamsState`	`ReactStateT<{string : {string : integer}}>`	Parameter state; the base-game values (`[""]`) are read and written.
`key`	`string`	Key of the script parameter, for example `"map.size"`.
`addSpacer?`	`boolean`	Whether to add a spacer to the control.
`filterTags?`	`{string}`	Tags used to select the platform-specific variant of the parameter (see `getFilterTags`).
`otherKeysToSet?`	`{string}`	Further parameter keys that are set to the same value index.

Returns TreeNodeId

Details

Nothing is added if the parameter is not found.

addNamesSettingsEntry(settings : {NewGameReactUtil.SettingsEntry}, configDictState : ReactStateT<{{string, string}}>) base/tealdef/gui/menu/new_game_react_util.d.tl:48

Call as new_game_react_util.addNamesSettingsEntry

Notes

Adds the "Names" setting, a combo box of all name lists, which sets the nameList entry of the config dictionary.

addStartYearSettingsEntry(settings : {NewGameReactUtil.SettingsEntry}, mapState : ReactStateT<GameMap>, mapParamsState : ReactStateT<NewGameReactUtil.NewGameState>) base/tealdef/gui/menu/new_game_react_util.d.tl:50

Call as new_game_react_util.addStartYearSettingsEntry

Notes

Adds the "Start Year" slider, which sets startYearIndex of the map parameters.

Details

Changing the start year does not reset the map preview.

addTutorialSettingsEntry(settings : {NewGameReactUtil.SettingsEntry}, activeModsParamsState : ReactStateT<{string : {string : integer}}>, filterTags : {string}) base/tealdef/gui/menu/new_game_react_util.d.tl:51

Call as new_game_react_util.addTutorialSettingsEntry

Notes

Adds the control for the script parameter guideSystemConfig.tutorial.

addSeedSettingsEntry(settings : {NewGameReactUtil.SettingsEntry}, mapState : ReactStateT<GameMap>, mapParamsState : ReactStateT<NewGameReactUtil.NewGameState>) base/tealdef/gui/menu/new_game_react_util.d.tl:53

Call as new_game_react_util.addSeedSettingsEntry

Notes

Adds the "Seed" text field with a button that generates a random seed.

Details

Changing the seed sets mapState to nil, so the map preview is generated again.

addMapSizeSettingsEntry(settings : {NewGameReactUtil.SettingsEntry}, activeModsParamsState : ReactStateT<{string : {string : integer}}>, filterTags? : {string}) base/tealdef/gui/menu/new_game_react_util.d.tl:54

Call as new_game_react_util.addMapSizeSettingsEntry

Notes

Adds the control for the script parameter map.size.

addMapFormatSettingsEntry(settings : {NewGameReactUtil.SettingsEntry}, activeModsParamsState : ReactStateT<{string : {string : integer}}>, filterTags? : {string}) base/tealdef/gui/menu/new_game_react_util.d.tl:55

Call as new_game_react_util.addMapFormatSettingsEntry

Notes

Adds the control for the script parameter map.format.

addInitialWeatherSettingsEntry(settings : {NewGameReactUtil.SettingsEntry}, activeModsParamsState : ReactStateT<{string : {string : integer}}>, filterTags? : {string}) base/tealdef/gui/menu/new_game_react_util.d.tl:57

Call as new_game_react_util.addInitialWeatherSettingsEntry

Notes

Adds the control for the script parameter weatherConfig.dynamicWeather.

addInitialTimeOfDaySettingsEntry(settings : {NewGameReactUtil.SettingsEntry}, activeModsParamsState : ReactStateT<{string : {string : integer}}>, filterTags? : {string}) base/tealdef/gui/menu/new_game_react_util.d.tl:58

Call as new_game_react_util.addInitialTimeOfDaySettingsEntry

Notes

Adds the control for the script parameter gameTimeConfig.timeOfDayMode.

addGeneratorSettingsEntry(settings : {NewGameReactUtil.SettingsEntry}, possibleGenerators : {NewGameReactUtil.Generator}, mapState : ReactStateT<GameMap>, mapParamsState : ReactStateT<NewGameReactUtil.NewGameState>) base/tealdef/gui/menu/new_game_react_util.d.tl:60

Call as new_game_react_util.addGeneratorSettingsEntry

Notes

Adds the "Generator" combo box for choosing the terrain generator. Nothing is added if there is only one generator.

Details

Changing the generator sets mapState to nil, so the map preview is generated again.

addTerrainParameterSettingsEntry(settings : {NewGameReactUtil.SettingsEntry}, mapState : ReactStateT<GameMap>, mapParamsState : ReactStateT<NewGameReactUtil.NewGameState>, mapGenParamsState : ReactStateT<{string : integer}>) base/tealdef/gui/menu/new_game_react_util.d.tl:65

Call as new_game_react_util.addTerrainParameterSettingsEntry

Notes

Adds one control per parameter of the selected terrain generator; values are stored in mapGenParamsState.

Details

Changing a value sets mapState to nil, so the map preview is generated again.

getYearValues() : {integer} base/tealdef/gui/menu/new_game_react_util.d.tl:70

Call as new_game_react_util.getYearValues

Notes

Returns the selectable start years.

Returns {integer}: The years 1900 to 2020 in steps of 10.

getYearScriptParam() : ScriptParam base/tealdef/gui/menu/new_game_react_util.d.tl:71

Call as new_game_react_util.getYearScriptParam

Notes

Returns the script parameter for the start year slider.

Returns ScriptParam: A slider parameter with key startYear, values "1900" to "2020" in steps of 10 and default index 1.

getInitialTimeOfDayValues() : {integer} base/tealdef/gui/menu/new_game_react_util.d.tl:73

Call as new_game_react_util.getInitialTimeOfDayValues

Notes

Start time of day for each value of the gameTimeConfig.timeOfDayMode parameter.

Returns {integer}: Seconds since midnight, indexed like the parameter values.

getInitialCloudCoverageValues() : {number} base/tealdef/gui/menu/new_game_react_util.d.tl:74

Call as new_game_react_util.getInitialCloudCoverageValues

Notes

Initial cloud coverage for each value of the weatherConfig.dynamicWeather parameter.

Returns {number}: Cloud coverage from 0 to 1, indexed like the parameter values.

calculateSeedString(maxLen : integer) : string base/tealdef/gui/menu/new_game_react_util.d.tl:76

Call as new_game_react_util.calculateSeedString

Notes

Generates a random seed of letters and digits.

Parameter	Type	Description
`maxLen`	`integer`	Maximum length; the base game passes 10, which gives a 10-character seed.

Returns string

Used in the base game: 3 times in 1 file

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

setSeed(new_game_react_util.calculateSeedString(10))

getFilterTags() : {string} base/tealdef/gui/menu/new_game_react_util.d.tl:78

Call as new_game_react_util.getFilterTags

Notes

Returns the tags used to select script parameter variants for the current platform.

Returns {string}: The tags of getPlatformFilterTags, plus "experimentalMapFeatures" if that app config option is enabled.

Used in the base game: 2 times in 1 file

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

local filterTags = new_game_react_util.getFilterTags()

getPlatformFilterTags() : {string} base/tealdef/gui/menu/new_game_react_util.d.tl:79

Call as new_game_react_util.getPlatformFilterTags

Notes

Returns the platform tag for script parameter variants.

Returns {string}: {"console"} on consoles, {"desktop"} on desktop.

findConfigDictIndex<K, V>(dict : {{K, V}}, key : K) : integer base/tealdef/gui/menu/new_game_react_util.d.tl:81

Call as new_game_react_util.findConfigDictIndex

Notes

Finds the position of a key in a config dictionary (a list of {key, value} pairs).

Returns integer: The index of the pair, or 0 if the key is not present.

NewGameReactUtil.Generator¶

record base/tealdef/gui/menu/new_game_react_util.d.tl:7

record Generator

Notes

A terrain generator offered for a new map.

Used in the base game: 10 times in 2 files

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

possibleGenerators : {NewGameReactUtil.Generator},

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

new_game_react_util.prepareState = function(initialConfigDict : {{string, string}}, possibleGenerators : {NewGameReactUtil.Generator},

Fields

Name	Type	Description
`name`	`string`	Resource name of the terrain generator.
`order`	`integer`	Sort order from the generator definition.

NewGameReactUtil.MapConfig¶

record base/tealdef/gui/menu/new_game_react_util.d.tl:12

record MapConfig

Notes

Result of gatherMapConfig.

Used in the base game: 1 time in 1 file

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

new_game_react_util.gatherMapConfig = function(configDict : {{string, string}}) : NewGameReactUtil.MapConfig

Fields

Name	Type	Description
`possibleGenerators`	`{Generator}`	Terrain generators available for the climate, sorted by `order`.
`climateDesc`	`ClimateDesc`	Description of the selected climate.

NewGameReactUtil.StatesBundle¶

record base/tealdef/gui/menu/new_game_react_util.d.tl:20

record StatesBundle

Notes

Initial values of the new game page states, returned by prepareState.

Used in the base game: 1 time in 1 file

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

initial : integer, autoActivateMods : boolean) : NewGameReactUtil.StatesBundle

Fields

Name	Type	Description
`mapParamsState`	`NewGameReactUtil.NewGameState`	Start year, terrain generator and seed.
`mapGenParamsState`	`{string : integer}`	Selected value index per terrain generator parameter key.
`activeModsState`	`{string}`	Names of the active mods.
`activeModsParamsState`	`{string : {string : integer}}`	Selected value index per script parameter key, per mod name (`""` is the base game).

NewGameReactUtil.NewGameState¶

record base/tealdef/gui/menu/new_game_react_util.d.tl:28

record NewGameState

Notes

Basic settings of a new map; stored in the app config as mainMenuState.newGameState.

Used in the base game: 13 times in 2 files

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

mapParamsState : ReactStateT<NewGameReactUtil.NewGameState>,

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

local readAndPatchState = function() : NewGameReactUtil.NewGameState

Fields

Name	Type	Description
`startYearIndex`	`integer`	Index into `getYearValues()`.
`terrainGenerator`	`string`	Resource name of the selected terrain generator.
`seed`	`string`	Seed string for the map generator.

NewGameReactUtil.SettingsEntry¶

record base/tealdef/gui/menu/new_game_react_util.d.tl:34

record SettingsEntry

Notes

One row of the settings list of the new game page.

Used in the base game: 25 times in 2 files

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

settings : {NewGameReactUtil.SettingsEntry}

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

settings : {NewGameReactUtil.SettingsEntry},

Fields

Name	Type	Description
`title`	`string`	Title of the setting.
`description`	`string`	Description shown in the hint panel when the row is hovered or focused.
`hintIdKey`	`string`	Key that links the row to its hint; the helpers use `"hintIdKey" .. title`.
`element`	`TreeNodeId`	The control of the setting.