`spawn` - Vehicle Spawning & Safe Placement

Core vehicle spawning, safe teleportation, and collision-free placement system. Handles creating vehicles, finding non-intersecting positions, ground snapping, and trailer coupling.

Exports

How It Works

Spawning a Vehicle

spawnVehicle creates a BeamNGVehicle object, registers it, configures paint/config, and places it safely:

local pos = vec3(100, 200, 50)
local rot = quat(0, 0, 0, 1)
local veh = spawn.spawnVehicle("pickup", "vehicles/pickup/sport.pc", pos, rot, {
  vehicleName = "myPickup",
  paint = createVehiclePaint({x=1, y=0, z=0, w=1}),
  autoEnterVehicle = true,
  safeSpawn = true,          -- default: true, uses safe placement
  visibilityPoint = camPos,  -- optional: avoid spawning behind walls relative to this point
  removeTraffic = true,      -- default: true, teleport traffic away from spawn
})

Note: Vehicles are spawned rotated 180° around Z-axis internally (the engine convention).

Safe Teleportation

safeTeleport moves a vehicle to a position, then uses the safe placement algorithm to avoid collisions:

local veh = getPlayerVehicle(0)
local pos = vec3(500, 300, 100)
local rot = quatFromDir(vec3(0, 1, 0), vec3(0, 0, 1))

-- Full signature:
spawn.safeTeleport(veh, pos, rot,
  false,   -- checkOnlyStatics: skip vehicle intersection checks
  camPos,  -- visibilityPoint: ensure visible from here
  true,    -- removeTraffic: teleport traffic away
  true,    -- centeredPosition: pos is center, not refnode
  true     -- resetVehicle: reset physics (default true)
)

Safe Placement Algorithm

The placement system finds a collision-free, ground-snapped position using a spiral search:

1. Build bounding box from vehicle's collidable nodes (oriented OBB)
2. Snap to ground via raycasts (3-point ground detection with terrain-following rotation)
3. Check intersections against other vehicles (OBB vs node-level) and static geometry (raycasts)
4. Visibility check via raycasts from the intended viewpoint - avoids spawning inside walls
5. Spiral search if position is blocked - tests positions in expanding grid pattern (up to 400 candidates)

-- The algorithm prioritizes:
-- 1. No vehicle/static intersections
-- 2. Visible from camera (both directions)
-- 3. Not floating in air
-- 4. Closest to intended position

Teleport to Last Road

Recovers the vehicle to the nearest valid road position using the navigation map:

-- Basic recovery
spawn.teleportToLastRoad()

-- With options
spawn.teleportToLastRoad(veh, {
  resetVehicle = true,       -- reset physics on teleport
  destinationPos = vec3(...) -- face toward this destination
})

The algorithm:

1. Scans recovery history points for one on a valid road
2. Projects onto the road segment, offset to the legal driving side
3. Respects one-way roads and driving-side rules (rightHandDrive)
4. Falls back to closest road, then current position if no road found

Picking a Spawn Point

pickSpawnPoint searches for a valid spawn location in priority order:

local sp = spawn.pickSpawnPoint("player")
local pos = sp:getPosition()
local rot = quat(sp:getRotation())

Search order:

1. User's saved default spawn point (via setSpawnpoint.loadDefaultSpawnpoint())
2. Random point from groups: CameraSpawnPoints → PlayerSpawnPoints → PlayerDropPoints
3. DefaultPlayerSpawnSphere (backward compatibility)
4. Creates a new SpawnSphere as fallback

Trailer Placement

-- Place trailer at coupler position relative to tow vehicle
spawn.placeTrailer(vehId,
  vec3(0, 3, 0.2),      -- coupler offset on tow vehicle
  trailerId,
  vec3(0.3, -3.3, 0),   -- coupler offset on trailer
  "tag_t",               -- coupler tag
  rotOffset              -- optional rotation offset
)

If the coupler tag is configured for "autoCouple", it automatically activates coupling after placement.

Internals

• Bounding boxes: Two BB builders - buildBoundingBox uses initialCollidableNodePosBB (for reset vehicles), buildClusterBoundingBox uses live node clusters (for deformed vehicles)
• Ground snapping: 3-point raycast system that detects terrain angle and tilts the vehicle to match, with fallback for underground positions
• Intersection testing: OBB-OBB broad phase → per-node narrow phase. Large vehicles use distance checks; small vehicles (avgSideLength < 0.5) use relaxed distance checks
• Traffic handling: When removeTraffic=true, traffic vehicles in the spawn area are force-teleported away via gameplay_traffic.forceTeleport
• Per-frame cache: vehiclesPositionedThisFrame tracks vehicles spawned in the current frame so their BB can be computed from initial positions rather than (not-yet-updated) physics positions
• 180° rotation: All rotations are pre-multiplied by quat(0,0,1,0) to match engine convention where vehicles face backward in local space
• Spiral search: Grid-based spiral pattern with step size proportional to vehicle dimensions, expanding outward up to 400 iterations

Common Patterns

-- Spawn and immediately drive
local veh = spawn.spawnVehicle("etk800", "vehicles/etk800/touring.pc", pos, rot)
core_vehicleBridge.executeAction(veh, 'setIgnitionLevel', 3)

-- Safe teleport for mission checkpoint
local cp = scenetree.findObject("checkpoint_3")
spawn.safeTeleport(veh, cp:getPosition(), quat(cp:getRotation()))

-- Recovery keybind
spawn.teleportToLastRoad()

Exported Variables

• preventPlayerSpawning - Exported variable - initialized as nil

Additional Exports