Vehicle Vicinity App

Sends nearby vehicle bounding box and coupler data to the UI each frame.

Overview

ui_vehicleVicinityApp provides real-time spatial data about all vehicles in the scene to the UI. Each frame it sends oriented bounding boxes, vehicle types, and fifth-wheel coupler positions for use by the vicinity/proximity UI app.

Extension path: lua/ge/extensions/ui/vehicleVicinityApp.lua

Exports (M)

Internals

Data Format

Each frame triggers onVehicleVicinityData with:

{
  playerVehicleId = <id>,
  objects = {
    [vehId] = {
      centerX, centerY, centerZ,  -- OBB center
      sizeX, sizeY, sizeZ,        -- OBB full extents
      rotX,                        -- rotation angle (atan2)
      type = "vehicle"|"traffic"|"parked"|"trailer",
      couplers = { ... },          -- fifth-wheel coupler nodes
    }
  }
}

Vehicle Type Detection

Type is determined by checking vehicle fields:

• veh.isTraffic == 'true' → "traffic"
• veh.isParked == 'true' → "parked"
• JBeam name contains "trailer" → "trailer"
• Otherwise → "vehicle"

Coupler Cache

getCouplerPoints(veh, vehId) scans vehicle node data for nodes with couplerTag or tag containing "fifthwheel". Results are cached per vehicle ID. Live positions are updated each frame using veh:getNodePosition(node.cid).

Cache is invalidated on onVehicleSwitched and onVehicleSpawned.

How It Works

1. Each GUI frame, iterates all scene objects via be:getObjectCount().
2. Gets the spawn-world oriented bounding box for each vehicle.
3. Determines type from vehicle metadata.
4. Fetches/caches fifth-wheel coupler positions.
5. Triggers onVehicleVicinityData with the complete data set.

Lua Examples

-- The UI listens for this guihook:
-- guihooks.trigger('onVehicleVicinityData', data)

-- Access from another extension (data is sent to UI, not typically read from Lua)

Hooks Triggered

Additional Exports

The following exports are available but not yet documented in detail:

• M.onGuiUpdate
• M.onVehicleSpawned
• M.onVehicleSwitched

See Also

• ui/ambientSound - Ambient Sound Stream Player - Related reference
• UI Apps Manager - Related reference
• UI Audio - Related reference
• UI System Guide - Guide