[index](index.html) / app --- # Module app[🔗](#app) Module controlling high level functions for the application, can be used to manipulate save games. ``` [Expand All] [Collapse All] 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 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): { : } saveUserdata: function(directory : string, fileName : string, table : { : }) 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[🔗](#category-globals) ### App[🔗](#$app~App) ``` [Expand All] [Collapse All] 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 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): { : } saveUserdata: function(directory : string, fileName : string, table : { : }) 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[🔗](#$app~App.ProgressMonitor) ``` record App.ProgressMonitor getProgress: function(ProgressMonitor): number getTask: function(ProgressMonitor): string end ``` ### App.ProgressMonitor.getProgress[🔗](#$app~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[🔗](#$app~App.ProgressMonitor.getTask) ``` function App.ProgressMonitor.getTask(ProgressMonitor): string ``` Returns the current task being executed **Parameters** * `ProgressMonitor` **Returns** 1. `string` ### App.quit[🔗](#$app~App.quit) ``` function App.quit(instant : boolean) ``` Quit the application. **Parameters** * `instant` :`boolean` — immediately quit one exit ### App.restart[🔗](#$app~App.restart) ``` function App.restart() ``` Restart the application ### App.printMemoryStats[🔗](#$app~App.printMemoryStats) ``` function App.printMemoryStats() ``` Prints memory statistics to the log output. ### App.startGame[🔗](#$app~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[🔗](#$app~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[🔗](#$app~App.stopGame) ``` function App.stopGame() ``` Stops the current game. ### App.findAllSavegames[🔗](#$app~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[🔗](#$app~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[🔗](#$app~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[🔗](#$app~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[🔗](#$app~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[🔗](#$app~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[🔗](#$app~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[🔗](#$app~App.getSavegameInfo) ``` function App.getSavegameInfo(saveId : SaveGameId): Async ``` Loads savegame metadata asynchronously. **Parameters** * `saveId` :`SaveGameId` — the savegame id **Returns** 1. `Async` — an async object with the savegame data ### App.getSavegameImage[🔗](#$app~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[🔗](#$app~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[🔗](#$app~App.getUserProfile) ``` function App.getUserProfile(): UserProfile ``` Obtain the user profile. **Returns** 1. `UserProfile` — the user profile ### App.findBuiltinSavegames[🔗](#$app~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[🔗](#$app~App.getSaveGameStorageInfo) ``` function App.getSaveGameStorageInfo(): SaveGameStorageInfo ``` Returns the savegame storage infos **Returns** 1. `SaveGameStorageInfo` — savegame storage info ### App.getSupportedMSAASampleCounts[🔗](#$app~App.getSupportedMSAASampleCounts) ``` function App.getSupportedMSAASampleCounts(): {integer} ``` Returns the supported MSAA sample counts **Returns** 1. `{integer}` — list of supported sample counts ### App.loadUserdata[🔗](#$app~App.loadUserdata) ``` function App.loadUserdata(directory : string, fileName : string): { : } ``` Load a custom userdata file **Parameters** * `directory` :`string` — a folder in the userdata directory * `fileName` :`string` — a lua filename (without .lua extension) **Returns** 1. `{ : }` — the deserialized lua data ### App.saveUserdata[🔗](#$app~App.saveUserdata) ``` function App.saveUserdata(directory : string, fileName : string, table : { : }) ``` 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` :`{ : }` — the table to serialize ### App.removeUserdata[🔗](#$app~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[🔗](#$app~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[🔗](#$app~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[🔗](#$app~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[🔗](#$app~App.getInputActionRep) ``` function App.getInputActionRep(): InputActionRep ``` Returns the global input action repository. **Returns** 1. `InputActionRep` — input action repository ### App.refreshMods[🔗](#$app~App.refreshMods) ``` function App.refreshMods() ``` Refreshes the installed mods ### App.setWaitForStartReadyGame[🔗](#$app~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[🔗](#$app~App.isWaitForStartReadyGame) ``` function App.isWaitForStartReadyGame(): boolean ``` Return if the `setWaitForStartReadyGame` had been called for this game. **Returns** 1. `boolean` ### App.startReadyGame[🔗](#$app~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[🔗](#$app~App.getRandomTips) ``` function App.getRandomTips(): {string} ``` Gets the list of random tips **Returns** 1. `{string}` — a list of tips as string ### App.getModTagTranslation[🔗](#$app~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[🔗](#$app~App.getProgressMonitor) ``` function App.getProgressMonitor(): ProgressMonitor ``` Gets the load progress monitor **Returns** 1. `ProgressMonitor` ### App.openUserDataFolder[🔗](#$app~App.openUserDataFolder) ``` function App.openUserDataFolder() ``` Opens the user data folder in the OS file manager ### App.openUserDataSubFolder[🔗](#$app~App.openUserDataSubFolder) ``` function App.openUserDataSubFolder(directory : string) ``` Opens the heightmaps folder in the OS file manager **Parameters** * `directory` :`string` — subfolder ### App.getUserDataFolder[🔗](#$app~App.getUserDataFolder) ``` function App.getUserDataFolder(): string ``` Gets the directory containing userdata **Returns** 1. `string` ### App.getAllHeightmaps[🔗](#$app~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[🔗](#$app~App.getGPUCapabilities) ``` function App.getGPUCapabilities(): GPUCapabilities ``` Get information about the GPU **Returns** 1. `GPUCapabilities` ### App.writeHeightmap[🔗](#$app~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[🔗](#$app~App.showNodeEditor) ``` function App.showNodeEditor() ``` Shows the node editor. ### App.SaveGameNamespace[🔗](#$app~App.SaveGameNamespace) ``` record App.SaveGameNamespace getUserdata: function(): string getSavegame: function(): string getSavemap: function(): string end ``` Savegame namespace constants. ### App.SaveGameNamespace.getUserdata[🔗](#$app~App.SaveGameNamespace.getUserdata) ``` function App.SaveGameNamespace.getUserdata(): string ``` Returns the userdata savegame namespace. **Returns** 1. `string` ### App.SaveGameNamespace.getSavegame[🔗](#$app~App.SaveGameNamespace.getSavegame) ``` function App.SaveGameNamespace.getSavegame(): string ``` Returns the savegame namespace. **Returns** 1. `string` ### App.SaveGameNamespace.getSavemap[🔗](#$app~App.SaveGameNamespace.getSavemap) ``` function App.SaveGameNamespace.getSavemap(): string ``` Returns the savemap namespace. **Returns** 1. `string` ### App.Debug[🔗](#$app~App.Debug) ``` record App.Debug setForcedGamepadDynamicScrollRepeatSpeed: function(speed : integer) pushGamepadButtonKeyInputEvent: function(gamepadButtonName : string, press : boolean) end ``` ### App.Debug.setForcedGamepadDynamicScrollRepeatSpeed[🔗](#$app~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[🔗](#$app~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~App.debug) ``` App.debug: Debug ```