Testing & Debugging Your Mod

Building a mod is only half the work — testing and debugging is where you make it actually work. This guide covers the essential tools and workflows for iterating quickly on your BeamNG mods.

The Console

Press ~ (tilde) to open the in-game console. The console supports multiple execution contexts:

• GE-Lua — Game Engine Lua (global scope: traffic, UI, maps, extensions)
• Current Vehicle - Lua — The active vehicle's Lua VM (electrics, powertrain, controllers)
• CEF/UI - JS — The browser-based UI layer

Switch contexts using the dropdown at the top of the console. Type Lua directly and press Enter to execute.

-- In GE-Lua context: get the player vehicle and print its name
local veh = be:getPlayerVehicle(0)
if veh then print(veh:getName()) end

-- In Vehicle-Lua context: dump all electrics values
dump(electrics.values)

Logging

Use log() instead of print() — it includes severity level, a tag for filtering, and timestamps:

log('I', 'myMod', 'Extension loaded successfully')     -- Info
log('W', 'myMod', 'Config not found, using defaults')  -- Warning
log('E', 'myMod', 'Failed to parse vehicle data')      -- Error
log('D', 'myMod', 'State: ' .. dumps(state))           -- Debug

Severity levels in order: D (debug), I (info), W (warning), E (error).

Log output appears in the console and in the log file at ~/AppData/Local/BeamNG.drive/latest.log on Windows. Keep a terminal open with tail -f on the log file for real-time monitoring.

Live Reload

The single most important shortcut for mod development:

Ctrl+L is your best friend. Edit a VE extension, save, press Ctrl+L, and your changes take effect immediately — no restart needed. This works for any Lua file in the vehicle context.

For GE extensions, use Ctrl+S or manually reload:

-- In GE-Lua console
extensions.reload("mymod_myfeature")

Common Console Commands

Extension Management

extensions.load("mymod_myfeature")     -- Load an extension
extensions.unload("mymod_myfeature")   -- Unload an extension
extensions.reload("mymod_myfeature")   -- Reload (unload + load)
dump(extensions.mymod_myfeature)       -- Inspect extension table

Vehicle Testing

-- In Vehicle-Lua context
beamstate.breakHinges()              -- Break all hinges
beamstate.breakAllBreakgroups()      -- Break all breakgroups
beamstate.deflateTires()             -- Deflate all tires
fire.igniteVehicle()                 -- Start a fire
fire.explodeVehicle()                -- Explode the vehicle

Environment Control

-- In GE-Lua context
core_environment.setGravity(-9.81)                   -- Normal gravity
core_environment.setGravity(-1)                      -- Moon gravity
core_environment.setTimeOfDay({time = 0.5})          -- Noon
core_environment.setTimeOfDay({time = 0.0})          -- Midnight

AI Control

-- In Vehicle-Lua context
ai.setMode('chase')     -- Chase the player
ai.setMode('flee')      -- Flee from the player
ai.setMode('traffic')   -- Normal traffic behavior
ai.setMode('random')    -- Drive randomly
ai.setMode('disabled')  -- Stop AI

Multi-Vehicle Commands

-- In GE-Lua context: run a command on ALL vehicles
for vid, veh in activeVehiclesIterator() do
  veh:queueLuaCommand("beamstate.deflateTires()")
end

Data Inspection

Use dump() and dumps() to inspect tables:

-- dump() prints to console with formatting
dump(electrics.values)

-- dumps() returns a string (useful inside log())
log('D', 'myMod', 'Config: ' .. dumps(config))

World Editor for Inspection

Press F11 to open the World Editor. Key tools for debugging:

• Edit Object Mode (default) — Select and inspect any object's properties
• Node/Beam Visualizer — The skeleton VE extension renders the physics mesh. Enable via the debug menu to see nodes, beams, and stress coloring
• Aero Debug — The aeroDebug VE extension visualizes aerodynamic forces

The World Editor lets you inspect object transforms, material assignments, and scene hierarchy — invaluable for debugging placement and visual issues.

Debugging Strategies

1. Isolate the Problem

If your mod isn't working, narrow down where the failure occurs:

• Does the extension load? Add log('I', 'myMod', 'onInit fired') to onInit
• Does the hook fire? Log at the entry point of each hook
• Is the data correct? Use dumps() on inputs before processing

2. Check the Log File

Many errors are silent in-game but appear in the log. Search for your mod's tag or for ERROR / WARN messages.

3. Use the Console Interactively

Test individual functions in the console before wiring them into your extension. This lets you verify API behavior without the full reload cycle.

4. Binary Search for Bugs

If a large change broke something, comment out half the code, test, and narrow down. Combined with Ctrl+L live reload, you can iterate in seconds.

5. List Available Commands

-- In GE-Lua context: list all registered console functions
dumpConsoleFunctions()

See Also

• Debugging Your Mod — Common Lua errors and data inspection patterns
• Error Handling — pcall, nil safety, defensive patterns
• Creating a GE Extension — Extension structure and lifecycle
• Hook Catalog — All available hooks