Peds, blips and props
LocalPed, Blips, createBlip, attachProp, PreviewVehicle and player.holdAnim - local NPCs, map blips, held props, showroom vehicles and held animations.
Things only this client sees: an NPC behind a counter, map blips, a prop in the player's hand, a showroom car. None of them is networked, so they never fight with entity lockdown and cost the server nothing. A point already makes its own NPC and blip (ped and blip of points.add); use these classes for the ones without a point.
Local peds
new LocalPed
A ped only this client sees (a shopkeeper, a job NPC). It is created when the player comes within distance of coords and deleted when they leave, so a thousand NPCs on the map cost nothing until someone walks up. It stands frozen, cannot be hurt, and ignores events (gunshots, being pushed).
Side: Client · Waits: no (the model loads in the background when the player comes near)
new LocalPed(options: LocalPedOptions)local ped = aiLib.LocalPed.new(options)Parameters
Prop
Type
LocalPedOptions
Prop
Type
Members
Prop
Type
Example
import { LocalPed } from "@aicore-fivem/lib/client";
const guard = new LocalPed({
model: "s_m_m_security_01",
coords: { x: -1037.6, y: -2737.8, z: 20.2, heading: 330 },
scenario: "WORLD_HUMAN_GUARD_STAND",
distance: 80,
onSpawn: (ped) => SetPedComponentVariation(ped, 0, 1, 0, 0),
});
// Later, when the job ends:
guard.remove();The distance is measured from coords, not from an attached parent. A ped that follows a moving entity (attach or seat on a vehicle that drives away) needs a large distance and its own range check, or it stays where it was created.
Blips
createBlip
Creates one named map blip and returns its handle. You remove it yourself with RemoveBlip(handle); for blips you rebuild when the panel changes, use a Blips group.
Side: Client · Waits: no
createBlip(options: BlipOptions): numberlocal blip = aiLib.Blips.create(options)Parameters
Prop
Type
BlipOptions
Prop
Type
A blip style picked in your admin panel (the blip widget, read with readBlipStyle) spreads straight into these options: createBlip({ ...style, coords, label }).
Returns
number: the blip handle.
Example
import { createBlip, createLocale } from "@aicore-fivem/lib/client";
const Locale = createLocale<typeof import("../../locales/en.json")>();
// A delivery target with a GPS route; removed when delivered.
const target = createBlip({
coords: { x: 1197.4, y: -3253.6, z: 7.1 },
sprite: 478,
color: 5,
label: Locale("DELIVERY"),
shortRange: false,
route: true,
});
// ... on delivery:
RemoveBlip(target);new Blips
A group of blips by id: add replaces a blip with the same id and clear removes them all. Use one group per feature.
Side: Client · Waits: no
new Blips()local blips = aiLib.Blips.new()Methods
Prop
Type
In Lua call the methods with a colon: blips:add(id, options).
Example
import { Blips, createLocale } from "@aicore-fivem/lib/client";
const Locale = createLocale<typeof import("../../locales/en.json")>();
const blips = new Blips();
const GARAGES = [
{ id: "legion", coords: { x: 215.8, y: -810.1, z: 30.7 } },
{ id: "airport", coords: { x: -796.5, y: -2023.3, z: 9.2 } },
];
for (const garage of GARAGES)
blips.add(garage.id, { coords: garage.coords, sprite: 357, color: 3, label: Locale("GARAGE") });
// A garage was closed:
blips.remove("airport");Props and held animations
attachProp
Creates a local prop and attaches it to a ped bone (a phone in the hand, a box carried in front). The prop has no collision unless you ask for it.
Side: Client · Waits: yes (Promise: it loads the model first)
attachProp(model: string | number, options: AttachPropOptions): Promise<number>No Lua twin: create the object and call AttachEntityToEntity yourself.
Parameters
Prop
Type
AttachPropOptions
Prop
Type
Returns
Promise<number>: the prop entity, or 0 when the model does not load or the ped no longer exists. It never rejects.
Example
import { attachProp, player } from "@aicore-fivem/lib/client";
export async function readNewspaper(): Promise<void> {
const paper = await attachProp("prop_cliff_paper", {
bone: 18905,
offset: { x: 0.12, y: 0.03, z: 0.02 },
rotation: { x: 10, y: 0, z: 0 },
});
const hold = player.holdAnim("amb@world_human_tourist_map@male@base", "base");
setTimeout(() => {
hold.stop();
if (paper) DeleteEntity(paper);
}, 10_000);
}You delete the prop yourself with DeleteEntity. Props you forgot are deleted when your resource stops.
player.holdAnim
Keeps an animation playing until you stop it. When a fall, a bump or a ragdoll interrupts it, it is put back within half a second. Use it for carrying, holding a phone, or a work loop. One hold per resource: a new one replaces the old.
Side: Client · Waits: no
player.holdAnim(dict: string, clip: string, options?: HoldAnimOptions): { stop(): void }No Lua twin: play the animation with aiLib.player.playAnim and check it with an aiLib.every job.
Parameters
Prop
Type
HoldAnimOptions
Prop
Type
Returns
{ stop(): void }: call stop() to end the hold and clear the ped's tasks. Calling stop() on a hold that was already replaced does nothing.
Example
import { attachProp, cache, player } from "@aicore-fivem/lib/client";
export async function carryBox(): Promise<void> {
const box = await attachProp("hei_prop_heist_box", {
bone: 60309,
offset: { x: 0.025, y: 0.08, z: 0.255 },
rotation: { x: -145, y: 290, z: 0 },
});
// Ends by itself when the player gets into a vehicle.
player.holdAnim("anim@heists@box_carry@", "idle", {
while: () => cache.vehicle === false,
});
setTimeout(() => box && DeleteEntity(box), 60_000);
}Showroom vehicles
new PreviewVehicle
A local preview vehicle for showrooms and shops: frozen, cannot be damaged, locked and clean. Showing a new model replaces the old one, and the latest call always wins (an older call still loading its model does nothing). Deleted on clear() and when your resource stops. Nothing networked.
Side: Client · Waits: show does (Promise)
new PreviewVehicle()No Lua twin.
Members
Prop
Type
Example
import { PreviewVehicle, setVehicleSetup } from "@aicore-fivem/lib/client";
const preview = new PreviewVehicle();
const STAGE = { x: -44.4, y: -1097.1, z: 26.4, heading: 120 };
export async function showCar(model: string, color: number): Promise<void> {
const vehicle = await preview.show(model, STAGE, (v) => setVehicleSetup(v, { colors: [color, color] }));
if (vehicle) SetVehicleNumberPlateText(vehicle, "SHOWROOM");
}
export function leaveShowroom(): void {
preview.clear();
}