GE Boot Sequence

[Engine Core] → Create Lua VM → Load lua/ge/main.lua

Level Load Request → Unload Current Level → Load New Level → Trigger onClientPostStartMission

lua/ge/extensions/
├── core/                    # Core extensions
│   ├── settings/settings.lua # Settings system (aliased as global `settings`)
│   ├── input/actionFilter.lua # Input filtering
│   ├── camera.lua           # Camera system
│   ├── modmanager.lua       # Mod manager
│   └── ...
├── gameplay/                # Gameplay extensions
│   ├── missions/            # Mission system
│   └── traffic.lua          # Traffic system
├── career/                  # Career extensions
│   ├── career.lua           # Career main module
│   └── modules/             # Career sub-modules
└── freeroam/                # Freeroam extensions
    └── freeroam.lua         # Freeroam game mode

-- When extensions.load('myMod') is called:
-- 1. Check if already loaded (return if true - idempotent)
-- 2. Convert name to path: extNameToLuaPath('myMod') → 'myMod'
-- 3. Resolve dependencies - load any M.dependencies first
-- 4. Execute lua/ge/extensions/myMod.lua (via require)
-- 5. Register module as global: _G['myMod'] = M
-- 6. Call M.onExtensionLoaded() if it exists (self-init, no args)
-- 7. Call M.onInit() if it exists (GE second-phase init)
-- 8. Trigger onExtensionLoaded('myMod') hook on ALL other loaded extensions

C++ Engine → main.lua loaded
  ↓
main.lua: require core modules (mathlib, utils, json, guihooks, extensions, etc.)
  ↓
C++ calls onGameEngineStartup()
  → clientCore.initializeCore()
  → client_init.initClient()
  ↓
C++ calls init()
  → settings.initSettings()
  → detectGlobalWrites()
  → extensions.load(startupExtensions)  [~60 extensions loaded]
  → Each ext: onExtensionLoaded(deserializedData) (self only), then onInit(deserializedData) (GE only)
  → importPersistentData()
  → core_modmanager.onUiReady()
  ↓
C++ calls updateFirstFrame()
  → extensions.hook('onFirstUpdate')
  → settings.finalizeInit()
  ↓
C++ calls uiReady()
  → extensions.hook('onUiReady')
  ↓
Level Load Request
  → clientPreStartMission(levelPath)  → hook('onClientPreStartMission')
  → clientPostStartMission(levelPath) → hook('onClientPostStartMission')
  → clientStartMission(levelPath)     → hookNotify('onClientStartMission')
  ↓
luaPreRender detects worldReadyState == 1 → materials done → worldReadyState = 2
  → hook('onWorldReadyState', 2)
  ↓
Per-frame: update() → hook('onUpdate'), hook('onGuiUpdate')
Per-frame: luaPreRender() → hook('onPreRender'), hook('onDrawDebug')

local state = {}

local function onExtensionLoaded(deserializedData)
    state = deserializedData or {}
    log('I', 'myMod', 'I have loaded!')
end

M.onExtensionLoaded = onExtensionLoaded

local M = {}

M.dependencies = {'core_settings', 'gameplay_sites_sitesManager'}

local hasCareer = false

local function onExtensionLoaded(deserializedData)
    log('I', 'myExtension', 'Extension initialized')
end

local function onInit(deserializedData)
    if career_career then
        hasCareer = true
    end
end

local function onExtensionUnloaded()
    -- Cleanup resources here
end

M.onExtensionLoaded = onExtensionLoaded
M.onInit = onInit
M.onExtensionUnloaded = onExtensionUnloaded

return M

local ready = false

local function onExtensionLoaded()
    if not extensions.isExtensionLoaded('requiredMod') then
        log('W', 'myExtension', 'Required mod not found, disabling')
        return false  -- abort loading
    end
    ready = true
end

M.onExtensionLoaded = onExtensionLoaded

local pendingSetup = false

local function onExtensionLoaded()
    pendingSetup = true
end

local function onInit()
    if pendingSetup and freeroam_freeroam then
        doFullSetup()
        pendingSetup = false
    end
end

M.onExtensionLoaded = onExtensionLoaded
M.onInit = onInit

-- Set unload mode in your modScript.lua (NOT inside the extension)
-- scripts/mymod/modScript.lua
setExtensionUnloadMode("myExtension", "manual")
loadManualUnloadExtensions()

-- Check at runtime if optional extension is available
local function someFunction()
    if optionalMod and optionalMod.doSomething then
        optionalMod.doSomething()
    else
        -- Fallback behavior
    end
end
M.someFunction = someFunction

local function onExtensionLoaded()
    if not extensions.isExtensionLoaded('requiredMod') then
        log('E', 'myExtension', 'Missing required extension: requiredMod')
        return false  -- abort loading
    end
end
M.onExtensionLoaded = onExtensionLoaded

-- BAD: May fail if career loads after myMod
local function onExtensionLoaded()
    career_career.setSomething()  -- May not exist yet!
end

-- GOOD: Use onInit for second-phase init (other extensions are ready)
local function onInit()
    if career_career then
        career_career.setSomething()
    end
end

-- BAD: Blocks boot
local function onExtensionLoaded()
    for i = 1, 10000 do
        heavyComputation()
    end
end

-- GOOD: Defer to first update
local function onFirstUpdate()
    -- Heavy work here
end

-- BAD: map not ready during boot
local function onExtensionLoaded()
    local nodes = map.getMap().nodes  -- Nil!
end

-- GOOD: Wait for level loaded
local function onClientPostStartMission()
    local nodes = map.getMap().nodes
end

-- In console or early in main.lua
log('I', 'Boot', 'Starting extension load')

-- In console (F11)
extensions.isExtensionLoaded('myExtension')  -- true/false
dump(extensions.getLoadedExtensionsNames())             -- List all loaded extensions

-- Add to your extension for debugging
local function onExtensionLoaded()
    log('I', 'myMod', 'onExtensionLoaded called')
    debug.traceback()  -- Print stack trace
end
M.onExtensionLoaded = onExtensionLoaded

local state = nil

local function onExtensionLoaded(deserializedData)
    if deserializedData then
        log('I', 'myMod', 'Reload detected, restoring state')
        state = deserializedData
    else
        state = {}
    end
end

M.onExtensionLoaded = onExtensionLoaded

-- Load/unload
extensions.load('name')        -- Load extension
extensions.unload('name')      -- Unload extension  
extensions.reload('name')      -- Reload extension
extensions.isExtensionLoaded('name')    -- Check if loaded

-- Hooks
extensions.hook('eventName', arg1, arg2)  -- Trigger hook
-- (no hookExists API available)

-- Registry
extensions.getLoadedExtensionsNames()  -- List of loaded extension names