@aifivem/lib 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -38,6 +38,12 @@ export const characters = {
38
38
  */
39
39
  search: (text: string, cursor?: number): Promise<CharacterSearchPage> =>
40
40
  ask((done) => core.SearchCharacters(text, done, cursor)),
41
+ /**
42
+ * The character id of a citizenid, loaded or not (a loaded one from memory, a stored one with one indexed read);
43
+ * null when unknown or deleted.
44
+ */
45
+ idOf: (citizenid: string): Promise<number | null> =>
46
+ ask((done) => core.GetCharIdByCitizenId(citizenid, done)),
41
47
  /** The characters of an account id or of every account with a license (`license:abc` or `abc`). */
42
48
  ofUser: (user: number | string): Promise<StoredCharacter[]> =>
43
49
  ask((done) => core.GetCharactersOfUser(user, done)),
@@ -50,8 +56,11 @@ export const characters = {
50
56
  ask((done) => core.GetJobMembers(job, done, after, limit)),
51
57
  /** Whether anyone holds a job, loaded or not (one row is read). */
52
58
  hasJobMember: async (job: string): Promise<boolean> =>
53
- (await ask<MembersPage>((done) => core.GetJobMembers(job, done, undefined, 1)))
54
- .members.length > 0,
59
+ (
60
+ await ask<MembersPage>((done) =>
61
+ core.GetJobMembers(job, done, undefined, 1),
62
+ )
63
+ ).members.length > 0,
55
64
  gangMembers: (
56
65
  gang: string,
57
66
  after?: number,
@@ -107,7 +116,7 @@ export const characters = {
107
116
  value: unknown,
108
117
  ): Promise<CharacterResult> =>
109
118
  ask((done) => core.SetOfflineMeta(charId, key, value, done)),
110
- /** Name, birth date, nationality, sex (sex only while not loaded), each checked like the creation form. */
119
+ /** Name, birth date, nationality, sex / gender (sex only while not loaded), height (cm), each checked like the creation form. */
111
120
  setInfo: (
112
121
  charId: number,
113
122
  patch: CharacterInfoPatch,
@@ -0,0 +1,21 @@
1
+ import {
2
+ applyVehicleDamage,
3
+ readVehicleDamage,
4
+ repairVehicle,
5
+ restoreVehicleDamage,
6
+ setVehicleEngineHealth,
7
+ } from "./vehicle";
8
+
9
+ /**
10
+ * Server features only FiveM for GTAV Enhanced has (patch notes and native docs, `aicore-fivem` skill
11
+ * `references/enhanced.md`). Each feature is probed; without it every helper answers null / false and the caller
12
+ * keeps its own path. Scripts never call these natives by hash themselves. (Colshapes are on Legacy too:
13
+ * `createColshape` in the fivem layer.)
14
+ */
15
+ export const enhanced = {
16
+ readVehicleDamage,
17
+ applyVehicleDamage,
18
+ restoreVehicleDamage,
19
+ repairVehicle,
20
+ setVehicleEngineHealth,
21
+ };
@@ -0,0 +1,80 @@
1
+ import { createLogger, VEHICLE_DAMAGE_MAX } from "../../shared";
2
+
3
+ export const log = createLogger(GetCurrentResourceName());
4
+
5
+ /**
6
+ * Hashes of the FiveM for GTAV Enhanced server natives that are in neither @citizenfx/server nor Legacy's wrappers
7
+ * (joaat of the upper-case name, from the native docs; `aicore-fivem` skill `references/enhanced.md`).
8
+ */
9
+ export const HASH = {
10
+ isWrecked: "0xA067F5AD", // IS_VEHICLE_WRECKED(Vehicle) -> BOOL
11
+ wheels: "0xEDF4B0FC", // GET_VEHICLE_NUMBER_OF_WHEELS(Vehicle) -> int (owner reported)
12
+ wheelOff: "0xCF1BC668", // IS_VEHICLE_WHEEL_BROKEN_OFF(Vehicle, int wheel) -> BOOL
13
+ breakWheel: "0xA274CADB", // BREAK_OFF_VEHICLE_WHEEL(Vehicle, int wheel, BOOL, BOOL, BOOL, BOOL)
14
+ allWindows: "0xBB619744", // ARE_ALL_VEHICLE_WINDOWS_INTACT(Vehicle) -> BOOL
15
+ smashWindow: "0xDDD9A8C2", // SMASH_VEHICLE_WINDOW(Vehicle, int window)
16
+ lightBroken: "0x7AFC9DF5", // IS_VEHICLE_LIGHT_BROKEN(Vehicle, int light) -> BOOL
17
+ breakLight: "0x611A3234", // SET_VEHICLE_LIGHT_BROKEN(Vehicle, int light, BOOL broken)
18
+ bumper: "0x67C9FAA3", // GET_VEHICLE_BUMPER_STATE(Vehicle, BOOL front) -> int
19
+ setBumper: "0x4716182C", // SET_VEHICLE_BUMPER_STATE(Vehicle, BOOL front, int state)
20
+ burstTyre: "0x89D28068", // SET_VEHICLE_TYRE_BURST(Vehicle, int wheel, BOOL onRim, float damage)
21
+ fixTyre: "0xA42EFA6B", // SET_VEHICLE_TYRE_FIXED(Vehicle, int wheel)
22
+ tank: "0x660A3692", // SET_VEHICLE_PETROL_TANK_HEALTH(Vehicle, float)
23
+ engine: "0x1B760FB5", // SET_VEHICLE_ENGINE_HEALTH(Vehicle, float)
24
+ fixed: "0x17469AA1", // SET_VEHICLE_FIXED(Vehicle): RPC to the owner client
25
+ deformationFixed: "0xDD2920C8", // SET_VEHICLE_DEFORMATION_FIXED(Vehicle): RPC to the owner client
26
+ } as const;
27
+
28
+ type Arg = number | boolean;
29
+
30
+ /** FiveM's own wrappers pass floats like this: an integral number would arrive as an int. */
31
+ export const float = (v: number): number => (v === 0 ? v : v + 0.0000001);
32
+ /** A native answering BOOL, read as truthy: JS gets `1` / `0`, never `true` (`aicore-fivem` `engine.md`). */
33
+ export const bool = (hash: string, ...args: Arg[]): boolean =>
34
+ Boolean(Citizen.invokeNative(hash, ...args, Citizen.returnResultAnyway()));
35
+ /** A native answering int. */
36
+ export const int = (hash: string, ...args: Arg[]): unknown =>
37
+ Citizen.invokeNative(
38
+ hash,
39
+ ...args,
40
+ Citizen.returnResultAnyway(),
41
+ Citizen.resultAsInteger(),
42
+ );
43
+ /** A native answering nothing. */
44
+ export const call = (hash: string, ...args: Arg[]): void =>
45
+ Citizen.invokeNative(hash, ...args);
46
+
47
+ /** Runs one setter; a failure is logged and the next setter still runs. */
48
+ export function attempt(name: string, fn: () => void): void {
49
+ try {
50
+ fn();
51
+ } catch (error) {
52
+ log.error(`enhanced native ${name} failed`, error);
53
+ }
54
+ }
55
+
56
+ let vehicleNatives: boolean | undefined;
57
+ /**
58
+ * The b177 server vehicle natives: a server without them throws on the unknown hash (ai-voice's probe works the same
59
+ * way). A "no" is kept only when probed on a vehicle a client owns, so a fresh entity without data cannot switch the
60
+ * feature off for good.
61
+ */
62
+ export function hasVehicleNatives(vehicle: number): boolean {
63
+ if (vehicleNatives === undefined && DoesEntityExist(vehicle)) {
64
+ try {
65
+ bool(HASH.isWrecked, vehicle);
66
+ vehicleNatives = true;
67
+ } catch {
68
+ if (NetworkGetEntityOwner(vehicle) > 0) vehicleNatives = false;
69
+ }
70
+ }
71
+ return vehicleNatives === true;
72
+ }
73
+
74
+ /** Synced wheel count, 0 while unknown (no owner client has sent the vehicle's data yet). */
75
+ export function wheelCount(vehicle: number): number {
76
+ const n = int(HASH.wheels, vehicle);
77
+ return typeof n === "number" && Number.isInteger(n)
78
+ ? Math.min(VEHICLE_DAMAGE_MAX.wheel + 1, Math.max(0, n))
79
+ : 0;
80
+ }
@@ -0,0 +1,177 @@
1
+ import {
2
+ readBumperState,
3
+ VEHICLE_DAMAGE_MAX,
4
+ waitFor,
5
+ type VehicleDamage,
6
+ } from "../../shared";
7
+ import {
8
+ attempt,
9
+ bool,
10
+ call,
11
+ float,
12
+ HASH,
13
+ hasVehicleNatives,
14
+ int,
15
+ log,
16
+ wheelCount,
17
+ } from "./natives";
18
+
19
+ /** Lowest petrol tank health restored: a tank at or below 0 can burn the car at a garage spot. */
20
+ const TANK_FLOOR = 100;
21
+
22
+ let readFailed = false;
23
+
24
+ /**
25
+ * A per-wheel native that may refuse an index. Tyre and wheel indexes are GTA's (0 LF, 1 RF, 2 LM, 3 RM, 4 LR, 5 RR,
26
+ * ...: a car's rear tyres are 4 and 5) or the synced wheel order; the docs do not say which, so every index up to
27
+ * `VEHICLE_DAMAGE_MAX.wheel` is walked and a refused one counts as intact.
28
+ */
29
+ function wheelSafe(fn: () => unknown): boolean {
30
+ try {
31
+ return Boolean(fn());
32
+ } catch {
33
+ return false;
34
+ }
35
+ }
36
+
37
+ /**
38
+ * The damage of a vehicle a client owns and has synced (windows, tyres, wheels, lights, bumpers, petrol tank), read on
39
+ * the server. Null on Legacy, before the owner's first sync (the server's vehicle data is empty then) or when a native
40
+ * fails (logged once): the caller keeps what it had.
41
+ */
42
+ export function readVehicleDamage(vehicle: number): VehicleDamage | null {
43
+ if (
44
+ !DoesEntityExist(vehicle) ||
45
+ NetworkGetEntityOwner(vehicle) <= 0 ||
46
+ !hasVehicleNatives(vehicle)
47
+ )
48
+ return null;
49
+ try {
50
+ // 0 until the owner's first sync: nothing to read yet.
51
+ if (wheelCount(vehicle) === 0) return null;
52
+ const windows: number[] = [];
53
+ if (!bool(HASH.allWindows, vehicle))
54
+ for (let i = 0; i <= VEHICLE_DAMAGE_MAX.window; i++)
55
+ if (!IsVehicleWindowIntact(vehicle, i)) windows.push(i);
56
+ const tyres: Array<[number, boolean]> = [];
57
+ const wheelsOff: number[] = [];
58
+ for (let i = 0; i <= VEHICLE_DAMAGE_MAX.wheel; i++) {
59
+ if (wheelSafe(() => bool(HASH.wheelOff, vehicle, i))) wheelsOff.push(i);
60
+ else if (wheelSafe(() => IsVehicleTyreBurst(vehicle, i, false)))
61
+ tyres.push([i, wheelSafe(() => IsVehicleTyreBurst(vehicle, i, true))]);
62
+ }
63
+ const lights: number[] = [];
64
+ for (let i = 0; i <= VEHICLE_DAMAGE_MAX.light; i++)
65
+ if (bool(HASH.lightBroken, vehicle, i)) lights.push(i);
66
+ const tank = GetVehiclePetrolTankHealth(vehicle);
67
+ return {
68
+ v: 1,
69
+ windows,
70
+ tyres,
71
+ wheelsOff,
72
+ lights,
73
+ bumpers: [
74
+ readBumperState(int(HASH.bumper, vehicle, true)) ?? 0,
75
+ readBumperState(int(HASH.bumper, vehicle, false)) ?? 0,
76
+ ],
77
+ tank: Number.isFinite(tank) ? tank : 1000,
78
+ };
79
+ } catch (error) {
80
+ if (!readFailed) log.error("enhanced vehicle damage read failed", error);
81
+ readFailed = true;
82
+ return null;
83
+ }
84
+ }
85
+
86
+ /** Writes stored damage to the synced vehicle data; false on Legacy. */
87
+ export function applyVehicleDamage(
88
+ vehicle: number,
89
+ damage: VehicleDamage,
90
+ ): boolean {
91
+ if (!DoesEntityExist(vehicle) || !hasVehicleNatives(vehicle)) return false;
92
+ for (const i of damage.windows)
93
+ attempt("SMASH_VEHICLE_WINDOW", () => call(HASH.smashWindow, vehicle, i));
94
+ for (const i of damage.wheelsOff)
95
+ attempt("BREAK_OFF_VEHICLE_WHEEL", () =>
96
+ call(HASH.breakWheel, vehicle, i, false, true, false, false),
97
+ );
98
+ for (const [i, onRim] of damage.tyres)
99
+ attempt("SET_VEHICLE_TYRE_BURST", () =>
100
+ call(HASH.burstTyre, vehicle, i, onRim, float(1000)),
101
+ );
102
+ for (const i of damage.lights)
103
+ attempt("SET_VEHICLE_LIGHT_BROKEN", () =>
104
+ call(HASH.breakLight, vehicle, i, true),
105
+ );
106
+ damage.bumpers.forEach((state, i) => {
107
+ if (state > 0)
108
+ attempt("SET_VEHICLE_BUMPER_STATE", () =>
109
+ call(HASH.setBumper, vehicle, i === 0, state),
110
+ );
111
+ });
112
+ if (damage.tank < 1000)
113
+ attempt("SET_VEHICLE_PETROL_TANK_HEALTH", () =>
114
+ call(HASH.tank, vehicle, float(Math.max(TANK_FLOOR, damage.tank))),
115
+ );
116
+ return true;
117
+ }
118
+
119
+ /**
120
+ * Restores stored damage on a new entity once its owner client has synced it (a write before that is overwritten
121
+ * by the client's first sync); gives up after 10 s, when the entity is gone or when `same()` says the handle is no
122
+ * longer that vehicle. Resolves whether it was applied (false on Legacy).
123
+ */
124
+ export async function restoreVehicleDamage(
125
+ vehicle: number,
126
+ damage: VehicleDamage,
127
+ same: () => boolean = () => true,
128
+ ): Promise<boolean> {
129
+ const until = (ready: () => boolean): Promise<boolean> =>
130
+ waitFor(
131
+ () =>
132
+ !DoesEntityExist(vehicle) || !same() ? false : ready() || undefined,
133
+ 10_000,
134
+ 250,
135
+ ).catch(() => false);
136
+ // The probe runs on an owned vehicle, like every read.
137
+ if (!(await until(() => NetworkGetEntityOwner(vehicle) > 0))) return false;
138
+ if (!hasVehicleNatives(vehicle)) return false;
139
+ if (!(await until(() => wheelCount(vehicle) > 0))) return false;
140
+ return applyVehicleDamage(vehicle, damage);
141
+ }
142
+
143
+ /**
144
+ * A full repair from the server: deformation, windows, lights, bumpers, tyres, engine, body and petrol tank. The
145
+ * health values are written to the synced data (no owner client needed); `SET_VEHICLE_FIXED` and the deformation go
146
+ * to the owner client. False on Legacy.
147
+ */
148
+ export function repairVehicle(vehicle: number): boolean {
149
+ if (!DoesEntityExist(vehicle) || !hasVehicleNatives(vehicle)) return false;
150
+ attempt("SET_VEHICLE_FIXED", () => call(HASH.fixed, vehicle));
151
+ attempt("SET_VEHICLE_DEFORMATION_FIXED", () =>
152
+ call(HASH.deformationFixed, vehicle),
153
+ );
154
+ attempt("SET_VEHICLE_ENGINE_HEALTH", () =>
155
+ call(HASH.engine, vehicle, float(1000)),
156
+ );
157
+ attempt("SET_VEHICLE_PETROL_TANK_HEALTH", () =>
158
+ call(HASH.tank, vehicle, float(1000)),
159
+ );
160
+ attempt("SET_VEHICLE_BODY_HEALTH", () => SetVehicleBodyHealth(vehicle, 1000));
161
+ // Every index (see `wheelSafe`); SET_VEHICLE_FIXED repairs them on the owner client too.
162
+ for (let i = 0; i <= VEHICLE_DAMAGE_MAX.wheel; i++)
163
+ wheelSafe(() => call(HASH.fixTyre, vehicle, i));
164
+ return true;
165
+ }
166
+
167
+ /** Engine health written to the synced data from the server (no owner client needed); false on Legacy. */
168
+ export function setVehicleEngineHealth(
169
+ vehicle: number,
170
+ health: number,
171
+ ): boolean {
172
+ if (!DoesEntityExist(vehicle) || !hasVehicleNatives(vehicle)) return false;
173
+ attempt("SET_VEHICLE_ENGINE_HEALTH", () =>
174
+ call(HASH.engine, vehicle, float(health)),
175
+ );
176
+ return true;
177
+ }
@@ -0,0 +1,26 @@
1
+ import {
2
+ CORE,
3
+ type CharacterResult,
4
+ type CharacterTarget,
5
+ } from "@aifivem/shared";
6
+ import { resourceExport } from "../fivem/exports";
7
+
8
+ const core = resourceExport(CORE.resource);
9
+
10
+ /**
11
+ * A character's legal / illegal status through ai-core (metadata `illegal`), for scripts that gate illegal content.
12
+ * Always legal while ai-core's panel switch `illegal.enabled` is off.
13
+ */
14
+ export const illegal = {
15
+ /** Whether a loaded player's character is illegal (a memory read; false when not loaded). */
16
+ is: (source: number): boolean => core.IsIllegal(source) === true,
17
+ /** Any character by citizenid or `{ charId }`, loaded or not; null when unknown. */
18
+ of: (target: CharacterTarget): Promise<boolean | null> =>
19
+ new Promise((resolve) => {
20
+ const now = core.IsIllegal(target, resolve);
21
+ if (now !== null) resolve(now);
22
+ }),
23
+ /** Marks a character illegal or legal, loaded or not (`{ ok }` or an ai-core lang key). */
24
+ set: (target: CharacterTarget, state: boolean): Promise<CharacterResult> =>
25
+ new Promise((resolve) => core.SetIllegal(target, state, resolve)),
26
+ };
@@ -154,6 +154,7 @@ export { medical } from "./medical";
154
154
  export { billing } from "./billing";
155
155
  export { banking } from "./banking";
156
156
  export { mdt } from "./mdt";
157
+ export { warrants } from "./warrants";
157
158
  export { ems } from "./ems";
158
159
  export { appearance } from "./appearance";
159
160
  export { needs, stress } from "./stress";
@@ -161,5 +162,14 @@ export { fuel } from "./fuel";
161
162
  export { doors } from "./doors";
162
163
  export { garages } from "./garages";
163
164
  export { characters } from "./characters";
165
+ export { illegal } from "./illegal";
164
166
  export { bans } from "./bans";
165
167
  export { isPrimeTime } from "./primeTime";
168
+ export { enhanced } from "./enhanced/enhanced";
169
+ export {
170
+ createColshape,
171
+ deleteColshape,
172
+ hasColshapes,
173
+ onColshape,
174
+ } from "../fivem/colshape";
175
+ export { vehicleCondition, type VehicleCondition } from "./vehicle/condition";
package/src/server/mdt.ts CHANGED
@@ -7,6 +7,19 @@ const core = resourceExport(CORE.resource);
7
7
  export const mdt = {
8
8
  /** Writes a record; false when no MDT runs or it takes no such record. */
9
9
  record: (record: MdtRecord): boolean => core.AddMdtRecord(record),
10
+ /**
11
+ * Whether a character (a loaded player's server id or a citizenid) has an active warrant: the active MDT's and / or
12
+ * ai-core's own (`warrants`), by ai-core's panel setting `warrants` (`docs/compat/mdt.md`). False when not or when
13
+ * ai-core is stopped. ai-core keeps a stored character's answer 30 s.
14
+ */
15
+ hasWarrant: (target: number | string): Promise<boolean> =>
16
+ new Promise((resolve) => {
17
+ try {
18
+ core.HasMdtWarrant(target, (wanted) => resolve(wanted === true));
19
+ } catch {
20
+ resolve(false);
21
+ }
22
+ }),
10
23
  /** The MDT records go to, or null. */
11
24
  provider: (): string | null => core.GetMdtSystem(),
12
25
  };
@@ -1,8 +1,4 @@
1
- import {
2
- CORE,
3
- type PhoneMail,
4
- type PhoneNotification,
5
- } from "@aifivem/shared";
1
+ import { CORE, type PhoneMail, type PhoneNotification } from "@aifivem/shared";
6
2
  import { resourceExport } from "../fivem/exports";
7
3
 
8
4
  const core = resourceExport(CORE.resource);
@@ -19,4 +15,14 @@ export const phone = {
19
15
  core.SendPhoneMessage(from, to, text),
20
16
  notify: (source: number, notification: PhoneNotification): boolean =>
21
17
  core.PhoneNotify(source, notification),
18
+ /**
19
+ * `fn(source, phone)` when a player with a loaded character opens the phone (`phone`: the phone's resource name):
20
+ * once per opening, at most once per 10 s per player; nothing for a phone without an open signal.
21
+ */
22
+ onUsed(fn: (source: number, phone: string) => void): void {
23
+ on(CORE.phoneUsedEvent, (source: unknown, phone: unknown) => {
24
+ if (typeof source === "number" && typeof phone === "string")
25
+ fn(source, phone);
26
+ });
27
+ },
22
28
  };
@@ -15,11 +15,14 @@ export const stress = {
15
15
  provider: (): string | null => core.GetStressSystem(),
16
16
  };
17
17
 
18
- /** Players' hunger and thirst through the same layer (the HUD that keeps them, ai-core's metadata without one). */
18
+ /** Players' hunger and thirst, kept by ai-core (character metadata, 0-100); any HUD only draws them. */
19
19
  export const needs = {
20
20
  /** Hunger and thirst to full (admin revive, hospital); false when the player has no character. */
21
21
  refill: (source: number): boolean => core.RefillNeeds(source),
22
22
  /** Adds hunger or thirst (0-100 scale; a negative amount takes it away), a food or drink's value. */
23
23
  add: (source: number, need: "hunger" | "thirst", amount: number): boolean =>
24
24
  core.AddNeed(source, need, amount),
25
+ /** Sets hunger or thirst to a value (0-100, clamped); false when the player has no character. */
26
+ set: (source: number, need: "hunger" | "thirst", value: number): boolean =>
27
+ core.SetNeed(source, need, value),
25
28
  };
@@ -0,0 +1,25 @@
1
+ import type { VehicleDamage } from "../../shared";
2
+ import { readVehicleDamage } from "../enhanced/vehicle";
3
+ import { fuel } from "../fuel";
4
+
5
+ /** A vehicle's condition read on the server, in ai-vehicles' `SaveVehicle` shape. */
6
+ export interface VehicleCondition {
7
+ engine: number;
8
+ body: number;
9
+ /** Through ai-core's fuel layer (any fuel script); left out when unknown. */
10
+ fuel?: number;
11
+ /** Windows, tyres, lights, bumpers, tank: FiveM for GTAV Enhanced only, and only while a client owns the vehicle. */
12
+ damage?: VehicleDamage;
13
+ }
14
+
15
+ /** The condition to store with an owned vehicle that leaves the world (parked, impounded, listed, cleaned up). */
16
+ export function vehicleCondition(vehicle: number): VehicleCondition {
17
+ const level = fuel.get(vehicle);
18
+ const damage = readVehicleDamage(vehicle);
19
+ return {
20
+ engine: GetVehicleEngineHealth(vehicle),
21
+ body: GetVehicleBodyHealth(vehicle),
22
+ ...(level !== null ? { fuel: level } : {}),
23
+ ...(damage ? { damage } : {}),
24
+ };
25
+ }
@@ -1,5 +1,11 @@
1
1
  import { VEHICLE_BAGS, type KeyPurpose } from "@aifivem/shared";
2
- import { waitFor, type VehicleProps, type VehicleSetup } from "../../shared";
2
+ import {
3
+ waitFor,
4
+ type VehicleDamage,
5
+ type VehicleProps,
6
+ type VehicleSetup,
7
+ } from "../../shared";
8
+ import { restoreVehicleDamage } from "../enhanced/vehicle";
3
9
  import { fuel } from "../fuel";
4
10
  import { vehicleKeys } from "../vehicleKeys";
5
11
  import { randomPlate } from "./plate";
@@ -28,6 +34,8 @@ export interface SpawnVehicleOptions {
28
34
  props?: VehicleProps;
29
35
  /** Fresh-vehicle extras: full tuning, colours, livery, tint, dirt, engine running. */
30
36
  setup?: VehicleSetup;
37
+ /** Stored damage (windows, tyres, lights...), restored once a client owns the vehicle; FiveM for GTAV Enhanced only. */
38
+ damage?: VehicleDamage;
31
39
  /** Doors locked for everyone (keys unlock them). */
32
40
  locked?: boolean;
33
41
  /** Routing bucket the vehicle lives in (players put in it should be in the same one). */
@@ -60,7 +68,7 @@ async function seatPlayer(
60
68
 
61
69
  /**
62
70
  * Creates a networked vehicle on the server (strict entity lockdown) and sets it up in one step: plate, fuel, state
63
- * bags, look (props / setup), lock, bucket, keys for its purpose, a driver and passengers. Resolves the entity, or null when the model does not exist or creation failed.
71
+ * bags, look (props / setup), damage (Enhanced), lock, bucket, keys for its purpose, a driver and passengers. Resolves the entity, or null when the model does not exist or creation failed.
64
72
  */
65
73
  export async function spawnVehicle(
66
74
  options: SpawnVehicleOptions,
@@ -100,6 +108,16 @@ export async function spawnVehicle(
100
108
  if (options.setup) state.set(VEHICLE_BAGS.setup, options.setup, true);
101
109
  for (const [key, value] of Object.entries(options.bags ?? {}))
102
110
  state.set(key, value, true);
111
+ // Not awaited: it waits for the first owner client (nothing happens on Legacy).
112
+ if (options.damage) {
113
+ const model = GetEntityModel(vehicle);
114
+ // A handle freed and reused within the wait must not get this damage.
115
+ void restoreVehicleDamage(
116
+ vehicle,
117
+ options.damage,
118
+ () => GetEntityModel(vehicle) === model,
119
+ );
120
+ }
103
121
  if (options.keysTo !== undefined) {
104
122
  const synced = await waitFor(
105
123
  () =>
@@ -0,0 +1,37 @@
1
+ import {
2
+ CORE,
3
+ type Warrant,
4
+ type WarrantAdd,
5
+ type WarrantPage,
6
+ type WarrantResult,
7
+ type WarrantTarget,
8
+ } from "@aifivem/shared";
9
+ import { resourceExport } from "../fivem/exports";
10
+
11
+ const core = resourceExport(CORE.resource);
12
+
13
+ /** A callback export as a promise (no promise crosses a resource boundary). */
14
+ const ask = <T>(call: (done: (value: T) => void) => void): Promise<T> =>
15
+ new Promise((resolve) => call(resolve));
16
+
17
+ /**
18
+ * ai-core's own warrants (by character, loaded or not; logged on ai-core's `warrants` channel). Whether they count in
19
+ * `mdt.hasWarrant` is ai-core's panel setting `warrants` (`docs/compat/mdt.md`).
20
+ */
21
+ export const warrants = {
22
+ /** Issues a warrant (`minutes` null or left out = until cleared): `{ ok, id }` or `{ ok: false, error }` (ai-core lang key). */
23
+ add: (warrant: WarrantAdd): Promise<WarrantResult> =>
24
+ ask((done) => core.AddWarrant(warrant, done)),
25
+ /** Clears one active warrant; false when no active warrant has that id. */
26
+ clear: (id: number, by?: number | string): Promise<boolean> =>
27
+ ask((done) => core.ClearWarrant(id, by, done)),
28
+ /** Clears every active warrant of a character; resolves how many. */
29
+ clearAll: (target: WarrantTarget, by?: number | string): Promise<number> =>
30
+ ask((done) => core.ClearWarrants(target, by, done)),
31
+ /** A character's active warrants, newest first; null when the target names no character. */
32
+ of: (target: WarrantTarget): Promise<Warrant[] | null> =>
33
+ ask((done) => core.GetWarrants(target, done)),
34
+ /** Every active warrant, newest first, 25 a page (`cursor` = the last page's `next`). */
35
+ page: (cursor?: number | null): Promise<WarrantPage> =>
36
+ ask((done) => core.ListWarrants(cursor, done)),
37
+ };
@@ -1,5 +1,7 @@
1
1
  /** Helpers usable on client and server. No FiveM natives here. */
2
2
 
3
+ import { isRecord } from "./record";
4
+
3
5
  export { sleep, waitFor } from "./wait";
4
6
  export { bool, int, num, record, str, vec4, type Vec4 } from "./read";
5
7
  export {
@@ -12,13 +14,7 @@ export {
12
14
  readVec4,
13
15
  } from "./strict";
14
16
  export { fail, isActionOk, replyError, type ActionResult } from "./action";
15
- export {
16
- distance,
17
- flatDistance,
18
- headingTo,
19
- nearestOf,
20
- type Vec3,
21
- } from "./vec";
17
+ export { distance, flatDistance, headingTo, nearestOf, type Vec3 } from "./vec";
22
18
  export { pickRandom, randomInt, rollChance } from "./random";
23
19
  export { ServerClock } from "./clock";
24
20
  export {
@@ -36,11 +32,7 @@ export {
36
32
  readAccess,
37
33
  type AccessRule,
38
34
  } from "./access";
39
- export {
40
- BLIP_STYLE_FIELDS,
41
- readBlipStyle,
42
- type BlipStyle,
43
- } from "./blipStyle";
35
+ export { BLIP_STYLE_FIELDS, readBlipStyle, type BlipStyle } from "./blipStyle";
44
36
  export {
45
37
  polyFromCorners,
46
38
  readZoneShape,
@@ -63,10 +55,14 @@ export {
63
55
  type VehicleProps,
64
56
  type VehicleSetup,
65
57
  } from "./vehicleProps";
58
+ export {
59
+ readBumperState,
60
+ toVehicleDamage,
61
+ VEHICLE_DAMAGE_MAX,
62
+ type VehicleDamage,
63
+ } from "./vehicleDamage";
66
64
 
67
- export function isRecord(value: unknown): value is Record<string, unknown> {
68
- return typeof value === "object" && value !== null && !Array.isArray(value);
69
- }
65
+ export { isRecord };
70
66
 
71
67
  /** Client text made safe for the server console: one line, no control characters, no `^n` colour codes. */
72
68
  export function logSafe(text: string, max: number): string {
@@ -1,7 +1,6 @@
1
1
  import type { DataSpec, WidgetSpec } from "@aifivem/shared";
2
2
 
3
- const isRecord = (v: unknown): v is Record<string, unknown> =>
4
- typeof v === "object" && v !== null && !Array.isArray(v);
3
+ import { isRecord } from "./record";
5
4
 
6
5
  /** An NPC standing at a place (a shopkeeper, a clerk): its model, an optional idle scenario and where it stands. */
7
6
  export interface PlacePed {
@@ -0,0 +1,4 @@
1
+ /** A plain object (not null, not an array). */
2
+ export function isRecord(value: unknown): value is Record<string, unknown> {
3
+ return typeof value === "object" && value !== null && !Array.isArray(value);
4
+ }