Core Command Handler

Handles beamng: URL scheme commands for mod management, map loading, toolchain, debugger control, and other async tasks triggered via protocol URLs or startup arguments.

Overview

The command handler processes beamng:v1/command/data protocol URLs. Commands arrive via OS-level URL scheme registration or startup arguments (-command "beamng:...") and are dispatched to the appropriate extension. Commands received before UI is ready are cached and replayed once onUiReady fires.

Public Functions

URL Format

beamng:v1/command/data
       │   │       │
       │   │       └── Optional data payload (URL-encoded)
       │   └────────── Command name
       └────────────── Version string

Supported Commands

Startup Argument Processing

-- Parse startup args for -command "beamng:..." 
local cmdArgs = Engine.getStartingArgs()
for i = 1, #cmdArgs do
  if cmdArgs[i] == '-command' then
    local arg = cmdArgs[i + 1]:stripcharsFrontBack('"\'')
    if arg:startswith('beamng:') then
      onSchemeCommand(arg:sub(8), true)  -- strip 'beamng:'
    end
  end
end

Command Caching

-- Commands received before UI ready are cached
if not uiReady then
  table.insert(cachedSchemes, {sc = scheme, startArg = isStartingArg})
  return
end
-- Flushed in onUiReady()

Mod Commands

-- Download and install a mod from repository
beamng:v1/downloadMod/MKA5UZHYS/6902/spanishpoliceroamerpack.zip
-- Handler:
extensions.core_repository.installMod(data, filename, 'mods/repo/')

Key Notes

• URL data is unescaped (%20 → space) before parsing
• ignoreStartupCmd flag prevents re-executing startup commands on GE Lua reload
• openMap loads core_loadMapCmd with manual unload mode for queued navigation
• core_input_actions supports arbitrary function calls with /-separated params
• Unknown commands log an error but don't crash

Module State

• M.onExtensionLoaded - Hook: extension loaded (nop).
• M.onSchemeCommand(scheme, isStartingArg) - Handles URI scheme commands.
• M.onFirstUpdate() - Hook: first update tick.
• M.onUiReady() - Hook: UI is ready.
• M.onSerialize() - Serializes command handler state.
• M.onDeserialized(data) - Restores command handler state.