Seat belt

A seat belt can come from ai-smallresources, from qbx_seatbelt, or from a HUD with its own belt (tgiann-lumihud, tgiann-hudv2, tgiann-modern-hud). ai-core reads whichever one runs; when several run, a HUD's own belt wins over ai-smallresources. Scripts that need the belt (an ejection on crash, a "buckle up" hint, a HUD icon) ask ai-core and work with any of them.

ai-core passes belt changes on as the client event ai-core:client:seatbelt (lib seatbelt.onChange), from the scripts that tell changes: ai-smallresources and qbx_seatbelt. For the HUD belts, read the state when you need it.

GetSeatbeltCopy Anchor Link

Tells whether the local player wears a seat belt right now. Read it when you need it (a crash, an action), not every frame.

Side: Client · Waits: no

GetSeatbelt(): boolean | null

local worn = exports['ai-core']:GetSeatbelt() -- or aiLib.seatbelt.isOn()

ParametersCopy Anchor Link

None.

ReturnsCopy Anchor Link

boolean | null: true when the belt is on, false when it is off. null (nil in Lua) when no supported seat belt script runs, or the running one gives no clear answer (for example outside a vehicle with a belt).

ExampleCopy Anchor Link

import { cache, seatbelt } from "@aicore-fivem/lib/client";

// Called by your crash detection: throw the driver out only without a belt.
export function onHardCrash(): void {
  if (cache.vehicle === false) return;
  if (seatbelt.isOn() === true) return; // null = no belt script: treat as no belt
  const [x, y, z] = GetEntityCoords(cache.ped, true);
  SetEntityCoords(cache.ped, x, y, z + 1.0, false, false, false, false);
  SetPedToRagdoll(cache.ped, 3000, 3000, 0, false, false, false);
}

GetSeatbeltProviderCopy Anchor Link

Returns the resource name of the seat belt script ai-core reads.

Side: Client · Waits: no

GetSeatbeltProvider(): string | null

local provider = exports['ai-core']:GetSeatbeltProvider() -- or aiLib.seatbelt.provider()

ParametersCopy Anchor Link

None.

ReturnsCopy Anchor Link

string: the resource name ("ai-smallresources", "tgiann-lumihud"). null when none of the supported scripts runs.

ExampleCopy Anchor Link

import { seatbelt } from "@aicore-fivem/lib/client";

// A HUD that draws a belt icon only when some script provides a belt.
const hasBelt = seatbelt.provider() !== null;
SendNUIMessage({ action: "beltIcon", data: hasBelt });
if (hasBelt) seatbelt.onChange((worn) => SendNUIMessage({ action: "belt", data: worn }));