lx-navigation — GPS & HUD

lx-navigation provides live GPS route guidance, turn-by-turn instructions, and a driver HUD. LX transport products (like Advanced Bus Job) drive it automatically — players get stop-by-stop guidance with no extra setup.

Developers can also use its public client exports in other resources. See the complete Client Exports reference.

Install

Follow the standalone lx-navigation installation guide for placement, consumer setup, lifecycle requirements, and verification.

There is no database, framework, inventory, oxmysql, or ox_lib dependency.

Buyer configuration (config/shared.lua)

These are the supported owner-facing settings. Additional effective defaults live in escrow-protected shared/internals.lua (path sampling, session hysteresis, instruction/HUD internals). That internals file is not buyer configuration — do not treat the buyer page as a full dump of every runtime knob.

Debug

Config.Debug = false

Named route profiles

Config.Profiles defines named threshold presets selected by StartRoute({ profile = ... }). They are not auto-selected from GTA vehicle class. Default profile is bus; an unknown name falls back to vehicle values.

Config.Profiles = {
    vehicle = {
        destinationArriveMeters = 15.0,  -- distance that counts as "arrived"
        waypointArriveMeters = 12.0,     -- distance to advance to the next waypoint
        offRouteMeters = 35.0,           -- deviation before a reroute triggers
        stuckMs = 15000,                 -- stationary time before recovery logic
        blacklist = {
            -- spatial zones the path sampler avoids (not vehicle model hashes)
            -- { coords = vec3(x, y, z), radius = 25.0 },
        },
    },
    bus = {
        destinationArriveMeters = 18.0,
        waypointArriveMeters = 14.0,
        offRouteMeters = 40.0,
        stuckMs = 18000,
        blacklist = {},
    },
}

blacklist entries are spatial route-exclusion zones ({ coords, radius }). They are not model-hash blacklists.

Buses use slightly wider thresholds because they stop at curbs, not exact points.

Guide & HUD

Config.Guide = {
    gpsColour = 5,          -- route line + destination blip colour
    statusEnabled = true,   -- enables status/recalculation status handling
    recalcNotify = false,   -- when true (and statusEnabled), shows a recalculation notification
    hudEnabled = true,      -- driver HUD panel
    hudPanel = {
        bottom = '34vh',
        left = '1rem',
        width = 'min(340px, 36vw)',
    },
}

statusEnabled gates status/recalculation handling. It does not emit general status notifications by itself. Recalc toast copy only appears when both statusEnabled and recalcNotify are true.

hudPanel accepts any CSS length values — move or resize the HUD to fit your server’s HUD layout without touching the UI build.

Debug drawing (optional override)

Config.DebugDraw is an advanced optional table you may declare in config/shared.lua to toggle path/maneuver overlays while developing. It is not required in the default buyer config. Leave it unset or off in production; overlays only render when debugging is active.

Notes

• Treat lx-navigation as one active player-facing route at a time. Multiple session IDs can exist internally, but GPS blip and HUD presentation are singleton
• Consumers must keep calling Tick — the internal guidance loop refreshes HUD/instructions only; progression, arrival, and rerouting live in Tick
• The HUD is a local Vite/React build inside ui/dist — never point it at external URLs or a CDN