Zones
Zones - areas with enter and exit callbacks (sphere, cylinder, polygon), checked at their own interval, never every frame.
A zone is an area that runs code when the player enters or leaves it: entering a district, a speed limit area, a marker that draws only nearby. When the player should do something at the place (press a key, pick a target option), use a point instead: it is a zone with the prompt, target, ped and blip already wired.
In TypeScript every zone is checked by ai-lib's one checker for all resources (zones sit in a 64 m grid, so a million zones cost the same as a few). Your resource checks its own zones only while ai-lib is not running. In Lua each resource runs one scheduler job for its zones.
new Zones
Creates a group of zones. Make one group per feature at the top of the file.
Side: Client · Waits: no
new Zones()local zones = aiLib.Zones.new()Returns
A Zones group with the methods below.
Example
import { Zones } from "@aicore-fivem/lib/client";
const zones = new Zones();zones.add
Adds a zone, or replaces the zone with the same id. When the replaced zone had the player inside, its onExit runs first.
Side: Client · Waits: no
zones.add(id: string, options: ZoneOptions): voidzones:add(id, options)Parameters
Prop
Type
ZoneOptions
Prop
Type
ZoneShape
ZoneShape is one of three objects, picked by type:
Prop
Type
In Lua, center may be a vector3 and the points { x = ..., y = ... } tables.
Returns
void.
Example
import { createLocale, notify, Zones } from "@aicore-fivem/lib/client";
const Locale = createLocale<typeof import("../../locales/en.json")>();
const zones = new Zones();
zones.add("safezone", {
shape: { type: "cylinder", center: { x: 298.6, y: -584.5, z: 43.3 }, radius: 60, height: 30 },
onEnter: () => notify(Locale("SAFEZONE_IN"), "info"),
onExit: () => notify(Locale("SAFEZONE_OUT"), "info"),
});
zones.add("yard", {
shape: {
type: "poly",
points: [
{ x: 1700.1, y: 2560.4 },
{ x: 1780.6, y: 2560.4 },
{ x: 1780.6, y: 2620.2 },
{ x: 1700.1, y: 2620.2 },
],
minZ: 40,
maxZ: 60,
},
interval: 1000,
onEnter: () => SetPedMoveRateOverride(PlayerPedId(), 0.8),
});A zone drawn in your admin panel with the zone widget gives corners; turn them into a polygon with polyFromCorners(corners, height) from @aicore-fivem/lib/shared. The server can test the same shapes with zoneContains(shape, x, y, z).
zones.remove
Removes one zone. When the player was inside, onExit runs. An unknown id does nothing.
Side: Client · Waits: no
zones.remove(id: string): voidzones:remove(id)Parameters
Prop
Type
Returns
void.
Example
zones.remove("safezone");zones.clear
Removes every zone of the group; onExit runs for the ones the player is in.
Side: Client · Waits: no
zones.clear(): voidzones:clear()Returns
void.
Example
onServerEvent("myscript:eventOver", () => zones.clear());zones.isInside
Whether the player is inside a zone, as of its last check.
Side: Client · Waits: no
zones.isInside(id: string): booleanlocal inside = zones:isInside(id)Parameters
Prop
Type
Returns
boolean: true while inside; false outside or for an unknown id. It reflects the last check, so it can be up to interval ms old.
Example
if (zones.isInside("safezone")) return notify(Locale("NO_WEAPONS_HERE"), "error");zones.size
How many zones the group holds.
Side: Client · Waits: no
zones.size: number // read-only propertyNo Lua twin.
Returns
number: the count of zones in this group.
Example
console.log(`${zones.size} zones loaded`);