Walking

Reference for gameplay_walk, which manages the walking mode (first-person on-foot via the "unicycle" vehicle). Handles toggling between walking and driving, entering/exiting vehicles, proximity detection, and vehicle blacklisting.

Module Exports (M)

Walking State

Vehicle Interaction

Position & Rotation

Toggling Control

Vehicle Blacklist

Hooks / Lifecycle

Internals

Speed Thresholds

Hysteresis between the two prevents flickering at the threshold.

Vehicle Proximity Detection

Each frame while walking, the system:

1. Iterates all vehicles (excluding blacklisted, non-playerUsable, inactive, and unicycles)
2. Computes bounding-box distance to the player using the vehicle's OOBB
3. The closest vehicle within 2m becomes vehicleInFront
4. If that vehicle is at parking speed, shows "enter vehicle" message

Bounding Box Distance

Uses the vehicle's oriented bounding box (OOBB) with 8 corner points. Calculates minimum distance from the player position to all 16 edge segments of the box - more accurate than center-to-center distance for large vehicles.

Unicycle Management

• The "unicycle" is a special JBeam vehicle used as the walking avatar
• When entering a vehicle: unicycle is deactivated (physics stopped, hidden)
• When exiting: unicycle is teleported to the driver's door side
• In career mode, uses without_mesh.pc config (invisible unicycle)
• Unicycle mesh alpha fades based on camera distance (invisible in first person)

Driver Door Positioning

getDoorsidePosRot() calculates exit position:

1. Gets reference nodes (ref, left) for vehicle orientation
2. Gets driver node position and handedness (LHD/RHD)
3. Offsets to the door side by initialNodePosBB extents + 0.7m body offset
4. Returns position looking toward the vehicle center

How It Works

1. Player presses walk toggle → setWalkingMode(true) fires onBeforeWalkingModeToggled
2. Unicycle spawned/teleported to driver door side via getOutOfVehicle()
3. Player enters unicycle, unicycle camera activated
4. onUpdate checks proximity to vehicles, shows enter message
5. Player presses toggle near a stopped vehicle → setWalkingMode(false)
6. Unicycle deactivated, player enters the nearby vehicle

Usage Example

-- Check if player is walking
if gameplay_walk.isWalking() then
  local x, y, z = gameplay_walk.getPosXYZ()
  log("I", "", string.format("Walking at %0.1f, %0.1f, %0.1f", x, y, z))
end

-- Programmatically enter walking mode at a position
gameplay_walk.setWalkingMode(true, vec3(100, 200, 50))

-- Blacklist traffic vehicles from being enterable
gameplay_walk.addVehicleToBlacklist(trafficVehId)

-- Get the vehicle the player is looking at
local veh = gameplay_walk.getVehicleInFront()
if veh then
  log("I", "", "Near vehicle: " .. veh:getJBeamFilename())
end

See Also

• Gameplay Achievement - Related reference
• Gameplay City - Related reference
• discover - Discover / Experience System - Related reference
• Gameplay Systems Guide - Guide