docs(research): TpF3 mod tooling and structure, offline wiki/script-doc copies

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-04 22:01:16 +02:00
commit 0213e22d66
@@ -0,0 +1,788 @@
+<!-- Source: https://wiki.transportfever3.com/script-doc/app.html (fetched 2026-10-04) -->
+
+[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<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[🔗](#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<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[🔗](#$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<SaveGameData>
+```
+
+Loads savegame metadata asynchronously.
+
+**Parameters**
+
+* `saveId` :`SaveGameId` — the savegame id
+
+**Returns**
+
+1. `Async<SaveGameData>` — 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): {<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[🔗](#$app~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[🔗](#$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
+```