Module app🔗

Module controlling high level functions for the application, can be used to manipulate save games.

 
global record App  
record ProgressMonitor    getProgress: function(ProgressMonitor): number
    getTask: function(ProgressMonitor): string
end

  quit: function(instant : boolean)
  restart: function()
  printMemoryStats: function()
  startGame: function(startGameParams : StartGameParams)
  startGame2: function(map : GameMap, seed : string, startDate : Date, startTimeOfDaySeconds : integer, startCloudCoverage : number, isMapEditor : boolean, mods : {Mod.ModId}, configDict : {{string, string}}, modParams : {string : {string : integer}})
  stopGame: function()
  findAllSavegames: function(namespace : string): {SaveGameInfo}
  loadGame: function(saveId : SaveGameId, isMapEditor : boolean, info : SaveGameData.SaveGameDetails)
  loadMission: function(saveId : SaveGameId, campaign : string, mission : string)
  saveGame: function(name : string, callBack : function(), isMapEditor : boolean, skipSetName : boolean)
  parseSavegameName: function(savegameName : string): ParsedSavegameName
  getSavegameComplexity: function(saveGameDetails : SaveGameData.SaveGameDetails): integer
  getSavegameComplexityLimit: function(): integer
  getSavegameInfo: function(saveId : SaveGameId): Async<SaveGameData>
  getSavegameImage: function(saveId : SaveGameId): GameScreenshot | nil
  deleteSavegame: function(saveId : SaveGameId): boolean
  getUserProfile: function(): UserProfile
  findBuiltinSavegames: function(isMapSave : boolean): {SaveGameInfo}
  getSaveGameStorageInfo: function(): SaveGameStorageInfo
  getSupportedMSAASampleCounts: function(): {integer}
  loadUserdata: function(directory : string, fileName : string): {<any type> : <any type>}
  saveUserdata: function(directory : string, fileName : string, table : {<any type> : <any type>})
  removeUserdata: function(directory : string, fileName : string)
  getAllUserdata: function(directory : string): {string}
  playVoiceOverOrStop: function(resName : string)
  makeEmptyMap: function(climate : string, numTiles : Vec2i, waterLevel : number): GameMap
  getInputActionRep: function(): InputActionRep
  refreshMods: function()
  setWaitForStartReadyGame: function()
  isWaitForStartReadyGame: function(): boolean
  startReadyGame: function()
  getRandomTips: function(): {string}
  getModTagTranslation: function(tag : string): string
  getProgressMonitor: function(): ProgressMonitor
  openUserDataFolder: function()
  openUserDataSubFolder: function(directory : string)
  getUserDataFolder: function(): string
  getAllHeightmaps: function(): {string}
  getGPUCapabilities: function(): GPUCapabilities
  writeHeightmap: function(map : GameMap, path : string, writeStl : boolean, sixteenBits : boolean): boolean
  showNodeEditor: function()
  
record SaveGameNamespace    getUserdata: function(): string
    getSavegame: function(): string
    getSavemap: function(): string
end

  
record Debug    setForcedGamepadDynamicScrollRepeatSpeed: function(speed : integer)
    pushGamepadButtonKeyInputEvent: function(gamepadButtonName : string, press : boolean)
end

  debug: Debug
end

Category: globals🔗

App🔗

 
global record App  
record ProgressMonitor    getProgress: function(ProgressMonitor): number
    getTask: function(ProgressMonitor): string
end

  quit: function(instant : boolean)
  restart: function()
  printMemoryStats: function()
  startGame: function(startGameParams : StartGameParams)
  startGame2: function(map : GameMap, seed : string, startDate : Date, startTimeOfDaySeconds : integer, startCloudCoverage : number, isMapEditor : boolean, mods : {Mod.ModId}, configDict : {{string, string}}, modParams : {string : {string : integer}})
  stopGame: function()
  findAllSavegames: function(namespace : string): {SaveGameInfo}
  loadGame: function(saveId : SaveGameId, isMapEditor : boolean, info : SaveGameData.SaveGameDetails)
  loadMission: function(saveId : SaveGameId, campaign : string, mission : string)
  saveGame: function(name : string, callBack : function(), isMapEditor : boolean, skipSetName : boolean)
  parseSavegameName: function(savegameName : string): ParsedSavegameName
  getSavegameComplexity: function(saveGameDetails : SaveGameData.SaveGameDetails): integer
  getSavegameComplexityLimit: function(): integer
  getSavegameInfo: function(saveId : SaveGameId): Async<SaveGameData>
  getSavegameImage: function(saveId : SaveGameId): GameScreenshot | nil
  deleteSavegame: function(saveId : SaveGameId): boolean
  getUserProfile: function(): UserProfile
  findBuiltinSavegames: function(isMapSave : boolean): {SaveGameInfo}
  getSaveGameStorageInfo: function(): SaveGameStorageInfo
  getSupportedMSAASampleCounts: function(): {integer}
  loadUserdata: function(directory : string, fileName : string): {<any type> : <any type>}
  saveUserdata: function(directory : string, fileName : string, table : {<any type> : <any type>})
  removeUserdata: function(directory : string, fileName : string)
  getAllUserdata: function(directory : string): {string}
  playVoiceOverOrStop: function(resName : string)
  makeEmptyMap: function(climate : string, numTiles : Vec2i, waterLevel : number): GameMap
  getInputActionRep: function(): InputActionRep
  refreshMods: function()
  setWaitForStartReadyGame: function()
  isWaitForStartReadyGame: function(): boolean
  startReadyGame: function()
  getRandomTips: function(): {string}
  getModTagTranslation: function(tag : string): string
  getProgressMonitor: function(): ProgressMonitor
  openUserDataFolder: function()
  openUserDataSubFolder: function(directory : string)
  getUserDataFolder: function(): string
  getAllHeightmaps: function(): {string}
  getGPUCapabilities: function(): GPUCapabilities
  writeHeightmap: function(map : GameMap, path : string, writeStl : boolean, sixteenBits : boolean): boolean
  showNodeEditor: function()
  
record SaveGameNamespace    getUserdata: function(): string
    getSavegame: function(): string
    getSavemap: function(): string
end

  
record Debug    setForcedGamepadDynamicScrollRepeatSpeed: function(speed : integer)
    pushGamepadButtonKeyInputEvent: function(gamepadButtonName : string, press : boolean)
end

  debug: Debug
end

App.ProgressMonitor🔗

record App.ProgressMonitor  getProgress: function(ProgressMonitor): number
  getTask: function(ProgressMonitor): string
end

App.ProgressMonitor.getProgress🔗

function App.ProgressMonitor.getProgress(ProgressMonitor): number

Returns the current progress as a value from 0 to 1

Parameters
  • ProgressMonitor
Returns
  1. number

App.ProgressMonitor.getTask🔗

function App.ProgressMonitor.getTask(ProgressMonitor): string

Returns the current task being executed

Parameters
  • ProgressMonitor
Returns
  1. string

App.quit🔗

function App.quit(instant : boolean)

Quit the application.

Parameters
  • instant :boolean — immediately quit one exit

App.restart🔗

function App.restart()

Restart the application

App.printMemoryStats🔗

function App.printMemoryStats()

Prints memory statistics to the log output.

App.startGame🔗

function App.startGame(startGameParams : StartGameParams)

Starts a new test game by specifying some basic parameters

Parameters
  • startGameParams :StartGameParams — start game parameters (optional) - if not set, the game will start with default values

App.startGame2🔗

function App.startGame2(map : GameMap, seed : string, startDate : Date, startTimeOfDaySeconds : integer, startCloudCoverage : number, isMapEditor : boolean, mods : {Mod.ModId}, configDict : {{string, string}}, modParams : {string : {string : integer}})

Starts a new game

Parameters
  • map :GameMap — the map to use
  • seed :string — the seed use for the map generation
  • startDate :Date — the start date
  • startTimeOfDaySeconds :integer — is the start time of the day in seconds
  • startCloudCoverage :number — is the start cloud coverage
  • isMapEditor :boolean — starting from map editor
  • mods :{Mod.ModId} — list of mods to start the game with
  • configDict :{{string, string}} — list of game settings
  • modParams :{string : {string : integer}} — list of mod params

App.stopGame🔗

function App.stopGame()

Stops the current game.

App.findAllSavegames🔗

function App.findAllSavegames(namespace : string): {SaveGameInfo}

Obtain list of all savegames.

Parameters
  • namespace :string — from which to obtain information (see app.SaveGameNamespace.getSavemap() or app.SaveGameNamespace.getSavegame() for the namespaces)
Returns
  1. {SaveGameInfo} — a list of all savegame

App.loadGame🔗

function App.loadGame(saveId : SaveGameId, isMapEditor : boolean, info : SaveGameData.SaveGameDetails)

Loads a savegame

Parameters
  • saveId :SaveGameId — the savegame id
  • isMapEditor :boolean — if the savegame is loaded in the map editor
  • info :SaveGameData.SaveGameDetails — savegame info (optional)

App.loadMission🔗

function App.loadMission(saveId : SaveGameId, campaign : string, mission : string)

Loads a mission

Parameters
  • saveId :SaveGameId — the savegame id
  • campaign :string — campaign name
  • mission :string — mission name

App.saveGame🔗

function App.saveGame(name : string, callBack : function(), isMapEditor : boolean, skipSetName : boolean)

Saves the current game.

Parameters
  • name :string — the name of the savegame
  • callBack :function() — callback when the savegame is finished
  • isMapEditor :boolean — is saving from the map editor
  • skipSetName :boolean — skips setting the savegame name as the current default savegame name (optional)

App.parseSavegameName🔗

function App.parseSavegameName(savegameName : string): ParsedSavegameName

Parse savegame info from its file name

Parameters
  • savegameName :string — the name of the savegame
Returns
  1. ParsedSavegameName — The info (most notably, savegame type and group name)

App.getSavegameComplexity🔗

function App.getSavegameComplexity(saveGameDetails : SaveGameData.SaveGameDetails): integer

Get an estimated value of the savegame complexity

Parameters
  • saveGameDetails :SaveGameData.SaveGameDetails — the savegame data of the savegame
Returns
  1. integer — a value that represents the estimate size of the savegame

App.getSavegameComplexityLimit🔗

function App.getSavegameComplexityLimit(): integer

Get an limit for the savegame complexity for the current platform

Returns
  1. integer — the complexity limit for the current platform

App.getSavegameInfo🔗

function App.getSavegameInfo(saveId : SaveGameId): Async<SaveGameData>

Loads savegame metadata asynchronously.

Parameters
  • saveId :SaveGameId — the savegame id
Returns
  1. Async<SaveGameData> — an async object with the savegame data

App.getSavegameImage🔗

function App.getSavegameImage(saveId : SaveGameId): GameScreenshot | nil

Obtains the savegame preview image
Note: This is - usually, if not explicitly changed in userdata - the same image as GameMetadata.screenshot but with the full available resolution

Parameters
  • saveId :SaveGameId — the savegame id
Returns
  1. GameScreenshot | nil — the image, or nil if no preview image is available

App.deleteSavegame🔗

function App.deleteSavegame(saveId : SaveGameId): boolean

Deletes a savegame

Parameters
  • saveId :SaveGameId — the savegame to delete
Returns
  1. boolean — if the savegame was successfully deleted

App.getUserProfile🔗

function App.getUserProfile(): UserProfile

Obtain the user profile.

Returns
  1. UserProfile — the user profile

App.findBuiltinSavegames🔗

function App.findBuiltinSavegames(isMapSave : boolean): {SaveGameInfo}

Obtains a list of built-in savegames.

Parameters
  • isMapSave :boolean — true to list built-in maps, false to list built-in savegames
Returns
  1. {SaveGameInfo} — list of savegames

App.getSaveGameStorageInfo🔗

function App.getSaveGameStorageInfo(): SaveGameStorageInfo

Returns the savegame storage infos

Returns
  1. SaveGameStorageInfo — savegame storage info

App.getSupportedMSAASampleCounts🔗

function App.getSupportedMSAASampleCounts(): {integer}

Returns the supported MSAA sample counts

Returns
  1. {integer} — list of supported sample counts

App.loadUserdata🔗

function App.loadUserdata(directory : string, fileName : string): {<any type> : <any type>}

Load a custom userdata file

Parameters
  • directory :string — a folder in the userdata directory
  • fileName :string — a lua filename (without .lua extension)
Returns
  1. {<any type> : <any type>} — the deserialized lua data

App.saveUserdata🔗

function App.saveUserdata(directory : string, fileName : string, table : {<any type> : <any type>})

Saves a custom table as lua file.

Parameters
  • directory :string — a folder in the userdata directory
  • fileName :string — the filename to save to (without .lua extension)
  • table :{<any type> : <any type>} — the table to serialize

App.removeUserdata🔗

function App.removeUserdata(directory : string, fileName : string)

Removes a userdata.

Parameters
  • directory :string — a folder in the userdata directory
  • fileName :string — the filename to remove (without .lua extension)

App.getAllUserdata🔗

function App.getAllUserdata(directory : string): {string}

Returns a list of all saved mod preset names.

Parameters
  • directory :string — a folder in the userdata directory
Returns
  1. {string} — a list of mod preset names

App.playVoiceOverOrStop🔗

function App.playVoiceOverOrStop(resName : string)

Plays a voice over if not currently playing, otherwise stops it.

Parameters
  • resName :string — the file to play

App.makeEmptyMap🔗

function App.makeEmptyMap(climate : string, numTiles : Vec2i, waterLevel : number): GameMap

Creates an empty map (for tooling / map generation workflows).

Parameters
  • climate :string — climate resource name
  • numTiles :Vec2i — map dimension in tiles
  • waterLevel :number — water level height
Returns
  1. GameMap — the map

App.getInputActionRep🔗

function App.getInputActionRep(): InputActionRep

Returns the global input action repository.

Returns
  1. InputActionRep — input action repository

App.refreshMods🔗

function App.refreshMods()

Refreshes the installed mods

App.setWaitForStartReadyGame🔗

function App.setWaitForStartReadyGame()

Wait for the game to be ready to start. This is called when loading a game to prevent the game from starting automatically

App.isWaitForStartReadyGame🔗

function App.isWaitForStartReadyGame(): boolean

Return if the setWaitForStartReadyGame had been called for this game.

Returns
  1. boolean

App.startReadyGame🔗

function App.startReadyGame()

Start Game that is fully loaded and ready to play. This is called after the progress page has finished loading the game.

App.getRandomTips🔗

function App.getRandomTips(): {string}

Gets the list of random tips

Returns
  1. {string} — a list of tips as string

App.getModTagTranslation🔗

function App.getModTagTranslation(tag : string): string

Returns a translated name for a mod tag.

Parameters
  • tag :string — tag to translate
Returns
  1. string — the translated tag

App.getProgressMonitor🔗

function App.getProgressMonitor(): ProgressMonitor

Gets the load progress monitor

Returns
  1. ProgressMonitor

App.openUserDataFolder🔗

function App.openUserDataFolder()

Opens the user data folder in the OS file manager

App.openUserDataSubFolder🔗

function App.openUserDataSubFolder(directory : string)

Opens the heightmaps folder in the OS file manager

Parameters
  • directory :string — subfolder

App.getUserDataFolder🔗

function App.getUserDataFolder(): string

Gets the directory containing userdata

Returns
  1. string

App.getAllHeightmaps🔗

function App.getAllHeightmaps(): {string}

Gets a list of all heightmaps in the userdata directory

Returns
  1. {string} — list of heightmaps files

App.getGPUCapabilities🔗

function App.getGPUCapabilities(): GPUCapabilities

Get information about the GPU

Returns
  1. GPUCapabilities

App.writeHeightmap🔗

function App.writeHeightmap(map : GameMap, path : string, writeStl : boolean, sixteenBits : boolean): boolean

Writes a heightmap image (and optionally an STL) for a map.

Parameters
  • map :GameMap — the map to write
  • path :string — the relative path (extension will be added if missing)
  • writeStl :boolean — write as an STL file as well
  • sixteenBits :boolean — use 16 bits depth for the heightmap (default 8 bits depth)
Returns
  1. boolean — if the heightmap was successfully written

App.showNodeEditor🔗

function App.showNodeEditor()

Shows the node editor.

App.SaveGameNamespace🔗

record App.SaveGameNamespace  getUserdata: function(): string
  getSavegame: function(): string
  getSavemap: function(): string
end

Savegame namespace constants.

App.SaveGameNamespace.getUserdata🔗

function App.SaveGameNamespace.getUserdata(): string

Returns the userdata savegame namespace.

Returns
  1. string

App.SaveGameNamespace.getSavegame🔗

function App.SaveGameNamespace.getSavegame(): string

Returns the savegame namespace.

Returns
  1. string

App.SaveGameNamespace.getSavemap🔗

function App.SaveGameNamespace.getSavemap(): string

Returns the savemap namespace.

Returns
  1. string

App.Debug🔗

record App.Debug  setForcedGamepadDynamicScrollRepeatSpeed: function(speed : integer)
  pushGamepadButtonKeyInputEvent: function(gamepadButtonName : string, press : boolean)
end

App.Debug.setForcedGamepadDynamicScrollRepeatSpeed🔗

function App.Debug.setForcedGamepadDynamicScrollRepeatSpeed(speed : integer)

Overrides gamepad dynamic scroll repeat speed.

Parameters
  • speed :integer — the scroll speed (0: 1/sec, 3: max speed), or nil to clear the override

App.Debug.pushGamepadButtonKeyInputEvent🔗

function App.Debug.pushGamepadButtonKeyInputEvent(gamepadButtonName : string, press : boolean)

Pushes a gamepad button event into the input queue.

Parameters
  • gamepadButtonName :string — the button to push
  • press :boolean — if pressed

App.debug🔗

App.debug: Debug