Game State
Manages the high-level game state (freeroam, campaign, etc.), loading screen lifecycle, and main menu visibility. Coordinates between Lua systems and the UI layer during level transitions.
Manages the high-level game state (freeroam, campaign, etc.), loading screen lifecycle, and main menu visibility. Coordinates between Lua systems and the UI layer during level transitions.
Public API - Game State
| Function | Signature | Description |
|---|---|---|
M.setGameState | (state, appLayout?, menuItems?, options?) | Sets the current game state and notifies UI + extensions via GameStateUpdate. |
M.requestGameState | () | Re-sends the current game state to UI and extensions. |
M.requestMainMenuState | () → bool | Sends ShowEntertainingBackground to UI. Returns true if no mission is loaded (main menu). |
Public API - Loading Screen
| Function | Signature | Description |
|---|---|---|
M.requestEnterLoadingScreen | (tagName, func?) | Requests entering the loading screen. tagName identifies the requester. Optional func is called once the loading screen is active. Multiple requesters are tracked. |
M.requestExitLoadingScreen | (tagName, ignoreMenuswitch?) | Marks tagName as done loading. When all requesters are done, hides the loading screen and shows main menu if appropriate. |
M.loading | () → bool | Returns true if any loading screen request is still active. ⚠️ Don't use inside loading process. |
M.getLoadingStatus | (tagName) → bool|nil | Returns the loading status for a specific tag. |
M.loadingScreenActive | () | Called by UI to signal the loading screen is fully rendered; triggers queued callbacks. |
Public API - UI
| Function | Signature | Description |
|---|---|---|
M.onUIInitialised | () | Called when the UI finishes loading. Triggers ChangeState to loading if waiting. |
M.onUiChangedState | (toState, fromState) | Pushes/pops pause requests for menu-related UI states (main menu, photo mode, options, etc.). |
Hooks
| Function | Description |
|---|---|
M.onExtensionLoaded | Requests UI initialization state. |
M.onUpdate | Watchdog: forces loading screen activation after 1 second if UI hasn't responded. |
M.onDeserialized | No-op placeholder. |
State Fields
M.state = {
state = "freeroam", -- game mode identifier
appLayout = {...}, -- UI app layout config
menuItems = {...}, -- menu item config
options = {...}, -- additional options
}Loading Screen Flow
- System calls
requestEnterLoadingScreen("levelLoad", callback). - UI receives
LoadingScreen { active = true }and renders the loading screen. - UI calls
loadingScreenActive()→ queued callbacks fire. - When done, system calls
requestExitLoadingScreen("levelLoad"). - If all tags are cleared, UI receives
LoadingScreen { active = false, gotoMainMenu = bool }.
Paused UI States
These UI states automatically pause the simulation:
menu.mainmenu, menu.photomode, menu.options, menu.vehiclesnew, menu.appedit, menu.levels, menu.mods, menu.appselect
Usage Example
-- Enter a loading screen for custom level transition
core_gamestate.requestEnterLoadingScreen("myMod", function()
-- Load level assets here
core_gamestate.requestExitLoadingScreen("myMod")
end)Game Context
Provides game context information for the UI, including mission state change notifications and WIP (Work In Progress) warning labels for experimental features.
Ground Marker Arrows
Manages 3D floating arrow indicators that appear at intersections along a navigation route, guiding the player through turns. Uses a pooled TSStatic approach with smooth fade/scale transitions.