GE Global Objects & Functions

log('I', 'myMod', 'Info message')   -- Info level
log('W', 'myMod', 'Warning!')       -- Warning level
log('E', 'myMod', 'Error!')         -- Error level
log('D', 'myMod', 'Debug data')     -- Debug level

-- Get player vehicle (0 = first player)
local veh = be:getPlayerVehicle(0)

-- Get vehicle by ID
local veh = be:getObjectByID(vehID)

-- Get all vehicles
local vehicles = be:getObject(0)  -- Group object containing vehicles

-- Find object by name (use scenetree, not be)
local obj = scenetree.findObject("myObject")

-- Get object count
local count = be:getObjectCount()

-- Get object by index
local obj = be:getObject(0)

-- Pause/resume via simTimeAuthority
simTimeAuthority.pause(true)   -- Pause
simTimeAuthority.pause(false)  -- Resume

-- Time scale (slow motion)
be:setPhysicsSpeedFactor(0.5)  -- Half speed
be:setPhysicsSpeedFactor(1.0)  -- Normal

-- Start/stop physics simulation
be:physicsStartSimulation()
be:physicsStopSimulation()

-- Spawn vehicle (use the spawn module, not be directly)
local veh = spawn.spawnVehicle("etk800", "vehicles/etk800/default.pc", vec3(0,0,100), quat(0,0,0,1))

-- Enter/switch to a vehicle
be:enterVehicle(0, veh)  -- playerIndex, vehicleObj

-- Remove a vehicle
veh:delete()

-- Delete all vehicles (iterate backwards)
for i = be:getObjectCount() - 1, 0, -1 do
    be:getObject(i):delete()
end

-- Time of day is controlled via core_environment, not be directly
core_environment.setTimeOfDay({time = 0.5})  -- 0.0-1.0 (0.5 = noon)

-- Or via scenetree TimeOfDay object
local tod = scenetree.findObject("TimeOfDay")
if tod then
    tod.time = 0.5
    tod.play = false  -- Stop day/night cycle
end

-- Send Lua command to vehicle's VE context
local veh = be:getObjectByID(vehID)
if veh then
    veh:queueLuaCommand("electrics.values.hazard = 1")
end

-- Send command to all vehicles
be:queueAllObjectLua("obj:setGravity(-9.81)")

-- Load extension by name (from lua/ge/extensions/)
extensions.load('myExtension')
extensions.load('gameplay/missions/myMission')

-- Unload extension
extensions.unload('myExtension')

-- Reload (hot-reload during development)
extensions.reload('myExtension')

-- Check if loaded
local loaded = extensions.isExtensionLoaded('myExtension')

-- Get list of loaded extensions
local loadedExts = extensions.getLoadedExtensionsNames()

-- Trigger a hook (calls all registered handlers)
extensions.hook('onResetGameplay', playerID)
extensions.hook('onVehicleSpawned', vehID)

-- Trigger hook with notification (processes fresh-loaded extensions immediately)
extensions.hookNotify('onClientStartMission', levelPath)

local M = {}

-- Optional: Declare dependencies
M.dependencies = {'core_settings_settings', 'gameplay_sites_sitesManager'}

-- Lifecycle hooks
function M.onExtensionLoaded()
    -- Called when this extension loads
end

function M.onUpdate(dtReal, dtSim, dtRaw)
    -- Called every frame, before physics
end

function M.onPreRender(dtReal, dtSim, dtRaw)
    -- Called every frame, after physics, before render
end

function M.onClientPostStartMission(levelPath)
    -- Called when level Lua loaded, scene objects available
end

function M.onVehicleSpawned(vid, vehObj)
    -- Called when vehicle spawns
end

function M.onVehicleDestroyed(vid)
    -- Called when vehicle is destroyed
end

return M

-- Send event to UI (one-way)
guihooks.trigger('EventName', data)

-- Examples
guihooks.trigger('MenuOpenModule', 'vehicleselect')
guihooks.trigger('MissionStateChanged', {active = true})
guihooks.trigger('Notification', {
    type = 'info',
    title = 'Hello',
    message = 'World'
})

-- Queue data for streaming (high frequency updates)
guihooks.queueStream('key', value)

-- Send all queued streams
guihooks.sendStreams()

-- Immediate stream transmission
guihooks.triggerStream('streamName', streamData)

-- Send to specific UI target
guihooks.triggerClient(targetDsmId, 'EventName', data)

-- Simple message popup
guihooks.message("Hello!", 5, "info")

-- Get current level data
local levelData = map.getMap()

-- Access map nodes (road network)
local nodes = levelData.nodes
local node = nodes[nodeName]

-- Node properties
local pos = node.pos        -- Point3F position
local links = node.links    -- Connected nodes

-- Find closest road to position
local road = map.findClosestRoad(pos)

-- Force map load (usually automatic)
map.assureLoad()

-- Find object by name
local obj = scenetree.findObject("objectName")

-- Find object by ID
local obj = scenetree.findObjectById(id)

-- Find all objects of a class
local ids = scenetree.findClassObjects("PointLight")

-- Direct access to well-known objects
scenetree.tod.play = false  -- Stop time-of-day cycle

-- Common object operations
if obj then
    -- Get transform
    local pos = obj:getPosition()
    local rot = obj:getRotation()
    
    -- Set transform
    obj:setPosition(pos)
    obj:setRotation(rot)
    
    -- Visibility
    obj:setHidden(true)
    obj:setHidden(false)
    
    -- Get class name
    local className = obj:getClassName()
    
    -- Delete object
    obj:delete()
end

-- Encode table to JSON string
local jsonStr = jsonEncode({key = "value", num = 42})
-- Result: {"key":"value","num":42}

-- Decode JSON string to table
local data = jsonDecode('{"key": "value"}')
print(data.key)  -- "value"

-- Pretty print (with indentation)
local pretty = jsonEncodePretty({a = 1, b = 2})

-- Structured logging
log('I', 'myMod', 'Info message')   -- Info level
log('W', 'myMod', 'Warning!')       -- Warning level
log('E', 'myMod', 'Error!')         -- Error level
log('D', 'myMod', 'Debug data')     -- Debug level

-- Deep copy a table
local copy = deepcopy(original)

-- Shallow clone
local clone = shallowcopy(original)

-- Dump table to string (debugging)
local str = dump(myTable)
print(dump(myTable))

-- Print table recursively
rdump(myTable, "prefix")

-- Check if table is empty
local empty = tableIsEmpty(tbl)

-- Get table size (for non-array tables)
local size = tableSize(tbl)

-- Clear table
table.clear(tbl)

-- Find key in table
local key = tableFind(tbl, value)

-- Merge tables
local merged = tableMerge(tbl1, tbl2)

-- Clamp value
local value = clamp(x, min, max)

-- Linear interpolation
local value = lerp(a, b, t)

-- Smooth step (takes single 0-1 value)
local value = smoothstep(x)

-- Sign function
local s = sign(x)  -- -1, 0, or 1

-- Round number
local r = round(x)         -- Nearest integer
local r = roundNear(x, 0.01)  -- Round to nearest 0.01

-- Square
local sq = square(x)

-- Degrees/radians conversion
local rad = math.rad(deg)
local deg = math.deg(rad)

-- Split string (global function)
local parts = split("a,b,c", ",")  -- {"a", "b", "c"}

-- Also available as string method (regex delimiter)
local parts = string.split("a,b,c", ",")

-- Trim whitespace (global function)
local trimmed = trim("  hello  ")  -- "hello"

-- String starts/ends with
local yes = string.startswith("hello", "he")   -- true
local yes = string.endswith("hello", "lo")     -- true

-- Formatting
local formatted = string.format("Value: %.2f", 3.14159)

-- Standard Lua type checking
local isTbl = type(value) == "table"
local isNum = type(value) == "number"
local isStr = type(value) == "string"
local isFunc = type(value) == "function"

-- Read file to string (global)
local content = readFile("/path/to/file.txt")

-- Write file (global)
writeFile("/path/to/file.txt", content)

-- Filesystem operations (C++ FS binding)
FS:fileExists("path/to/file.txt")
FS:directoryExists("path/to/dir/")
FS:directoryCreate("path/to/dir/")
FS:findFiles("dir/", "*.lua", -1, true, false)  -- dir, pattern, depth, files, dirs
FS:getFileRealPath("path")  -- Resolve VFS path to disk path

-- vec3 (aliased as Point3F)
local v = vec3(x, y, z)
local dist = v:distance(other)
local len = v:length()
local norm = v:normalized()
local dot = v:dot(other)
local cross = v:cross(other)

-- quat / QuatF rotations
local q = quat(x, y, z, w)
local q2 = quatFromEuler(rx, ry, rz)  -- global function

-- Point2F (2D vector)
local point2d = Point2F(x, y)

-- ColorF (RGBA 0-1)
local color = ColorF(r, g, b, a)

-- Send command to vehicle
local veh = be:getPlayerVehicle(0)
if veh then
    veh:queueLuaCommand("electrics.setLightsState(2)")
end

-- Send data via JSON
local data = jsonEncode({speed = 50})
veh:queueLuaCommand("myMod.receiveData('" .. data .. "')")

-- From vehicle Lua (VE context)
obj:queueGameEngineLua("extensions.hook('onVehicleEvent', " .. obj:getId() .. ")")

-- Iterate all vehicles (be manages the object pool directly)
for i = 0, be:getObjectCount() - 1 do
    local veh = be:getObject(i)
    local vehID = veh:getID()
    -- Process vehicle...
end

-- Always check if object exists
local veh = be:getPlayerVehicle(0)
if veh then
    local pos = veh:getPosition()
    -- Use pos...
end

-- Update state
myMod.state.active = true

-- Persist if needed
myMod.saveState()

-- Sync UI (no ghost values!)
guihooks.trigger('MyModStateChanged', myMod.state)

local M = {}

-- Track vehicles
local vehicles = {}

function M.onVehicleSpawned(vid, vehObj)
    vehicles[vid] = {
        spawnTime = os.clock()
    }
end

function M.onVehicleDestroyed(vid)
    vehicles[vid] = nil
end

function M.onResetGameplay(playerID)
    table.clear(vehicles)
end

return M

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

local veh = be:getPlayerVehicle(0)
if veh then
    -- ID and name
    local id = veh:getID()
    local name = veh:getName()
    local jbeam = veh:getJBeamFilename()
    
    -- Transform
    local pos = veh:getPosition()
    local rot = veh:getRotation()
    local vel = veh:getVelocity()
    local angVel = veh:getAngularVelocity()
    
    -- State
    local active = veh:isActive()
    local visible = not veh:isHidden()
    
    -- Control
    veh:setPositionRotation(x, y, z, rx, ry, rz, rw)
    veh:reset()  -- Reset to spawn position
    veh:delete()  -- Remove vehicle
    
    -- Communication
    veh:queueLuaCommand("print('hello from GE')")
end

-- Vehicle Access
be:getPlayerVehicle(0)               -- Get player vehicle object
be:getObjectByID(id)                 -- Get vehicle by ID (also global getObjectByID)
be:getObjectCount()                  -- Number of managed objects
be:enterVehicle(0, veh)              -- Switch player to vehicle

-- Level/Scene
map.getMap()                         -- Current level data
map.getMapName()                     -- Level name
scenetree.findObject("name")         -- Find entity by name
scenetree.findObjectById(id)         -- Find entity by ID

-- Extensions
extensions.load('name')              -- Load extension
extensions.unload('name')            -- Unload extension
extensions.hook('onResetGameplay', playerID)  -- Trigger hook
extensions.isExtensionLoaded('name') -- Check if extension loaded

-- UI Communication
guihooks.trigger('Event', data)      -- Send event to UI
guihooks.queueStream('key', value)   -- Stream data to UI
guihooks.sendStreams()               -- Flush queued streams
reloadUI()                           -- Force UI reload

-- JSON
jsonEncode({data = true})            -- Serialize to JSON
jsonDecode('{"key": "value"}')      -- Parse JSON
jsonEncodePretty(tbl)                -- Pretty-print JSON

-- Logging
log('I', 'mod', 'message')           -- Log info message
print("message")                     -- Print to console

-- Utilities
dumps(table)                         -- Debug dump to string
deepcopy(original)                   -- Deep copy table
shallowcopy(original)                -- Shallow copy table
clamp(x, min, max)                   -- Clamp value
lerp(a, b, t)                        -- Linear interpolation
round(x)                             -- Round to nearest integer
roundNear(x, m)                      -- Round to nearest m
sign(x)                              -- Sign of number
split(str, delimiter)                -- Split string
trim(str)                            -- Trim whitespace
string.startswith(str, prefix)       -- Check prefix
string.endswith(str, suffix)         -- Check suffix