Vehicle Boot Sequence & Lifecycle

Understanding the order in which the vehicle environment boots is critical for ensuring your code runs at the right time. Getting the timing wrong means your extension tries to read data that doesn't exist yet, or misses the window to configure systems before they start running.

:::tip[Quick Rule] Use onInit for setup, onVehicleLoaded for anything that needs the physical vehicle, and updateGFX for per-frame logic. :::

1. The Boot Sequence (Startup)

When a vehicle is spawned or the Lua VM is reloaded:

1. Environment Setup: main.lua sets up global constants (vmType, package.path).
2. Core Initialization: init() in main.lua is called.
   • Raw JBeam is loaded and compiled into v.data.
   • Core modules (electrics, powertrain, wheels, beamstate) are required.
3. initSystems():
   • Stage 1: electrics.init(), damageTracker.init(), beamstate.init().
   • Stage 2: powertrain.init(), controller.init().
   • Stage 3: sounds.init(), props.init(), fire.init().
4. Extension Hooks: extensions.hook("onInit") is called for all loaded extensions.
5. Post-Spawn: extensions.hook("onVehicleLoaded") is called. The vehicle is now physically in the world.

2. The Frame Loop (Runtime)

Every frame (Graphics Step):

1. sensors.updateGFX()
2. input.updateGFX()
3. electrics.updateGFX()
4. extensions.hook("updateGFX") -- Your extension logic usually goes here.
5. powertrain.updateGFX()
6. guihooks.sendStreams() -- Data sent to UI.
7. props.updateGFX() -- Needle/prop movement.

3. The Physics Loop (High-Frequency)

Only runs if a module requests it via obj:setPhysicsStepEnabled(true). Runs at 2000Hz.

1. powertrain.update()
2. controller.update()
3. extensions.hook("onPhysicsStep")

4. Reset Sequence (Pressing 'R')

When the user resets the vehicle:

1. onVehicleReset() is called in main.lua.
2. guihooks.reset().
3. extensions.hook("onReset").
4. Every core module's .reset() function is called (e.g., electrics.reset(), powertrain.reset()).

Key Hooks for Developers