@aifivem/lib 0.0.0-stage → 0.6.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.
Files changed (162) hide show
  1. package/package.json +34 -4
  2. package/src/client/action.ts +38 -0
  3. package/src/client/adminWorld.ts +95 -0
  4. package/src/client/appearance.ts +29 -0
  5. package/src/client/areaFollower.ts +41 -0
  6. package/src/client/blip.ts +79 -0
  7. package/src/client/cache.ts +66 -0
  8. package/src/client/callback.ts +70 -0
  9. package/src/client/controls.ts +73 -0
  10. package/src/client/entities.ts +83 -0
  11. package/src/client/entity.ts +26 -0
  12. package/src/client/fuel.ts +18 -0
  13. package/src/client/gestures.ts +18 -0
  14. package/src/client/headshot.ts +26 -0
  15. package/src/client/hud.ts +24 -0
  16. package/src/client/index.ts +131 -0
  17. package/src/client/inventory.ts +117 -0
  18. package/src/client/keyHints.ts +13 -0
  19. package/src/client/keybind.ts +163 -0
  20. package/src/client/localPed.ts +169 -0
  21. package/src/client/location.ts +54 -0
  22. package/src/client/mdt.ts +10 -0
  23. package/src/client/medical.ts +28 -0
  24. package/src/client/membership.ts +41 -0
  25. package/src/client/menu/dialogs.ts +77 -0
  26. package/src/client/menu/minigames.ts +79 -0
  27. package/src/client/menu/requests.ts +65 -0
  28. package/src/client/modelScan/def.ts +29 -0
  29. package/src/client/modelScan/objectIndex.ts +41 -0
  30. package/src/client/modelScan/scan.ts +69 -0
  31. package/src/client/modelScan/scanner.ts +164 -0
  32. package/src/client/netEvent.ts +40 -0
  33. package/src/client/notify.ts +14 -0
  34. package/src/client/nuiScreen.ts +87 -0
  35. package/src/client/player/anim.ts +98 -0
  36. package/src/client/player/fade.ts +17 -0
  37. package/src/client/player/player.ts +80 -0
  38. package/src/client/player/teleport.ts +87 -0
  39. package/src/client/playerData.ts +83 -0
  40. package/src/client/players.ts +44 -0
  41. package/src/client/points/interact.ts +144 -0
  42. package/src/client/points/modelHost.ts +117 -0
  43. package/src/client/points/modelPoint.ts +181 -0
  44. package/src/client/points/point.ts +159 -0
  45. package/src/client/points/points.ts +170 -0
  46. package/src/client/points/targets/adapter.ts +40 -0
  47. package/src/client/points/targets/interactTarget.ts +45 -0
  48. package/src/client/points/targets/optionShape.ts +22 -0
  49. package/src/client/points/targets/oxTarget.ts +42 -0
  50. package/src/client/points/targets/qbTarget.ts +71 -0
  51. package/src/client/points/targets/targets.ts +20 -0
  52. package/src/client/preview.ts +51 -0
  53. package/src/client/progress.ts +132 -0
  54. package/src/client/prompt.ts +26 -0
  55. package/src/client/prop.ts +79 -0
  56. package/src/client/radial.ts +16 -0
  57. package/src/client/raycast.ts +48 -0
  58. package/src/client/scriptCamera.ts +167 -0
  59. package/src/client/seatbelt.ts +18 -0
  60. package/src/client/shot.ts +29 -0
  61. package/src/client/streaming.ts +91 -0
  62. package/src/client/tickLoop.ts +18 -0
  63. package/src/client/vehicleKeys.ts +14 -0
  64. package/src/client/vehicleProps.ts +107 -0
  65. package/src/client/vehicles.ts +46 -0
  66. package/src/client/waypoint.ts +10 -0
  67. package/src/client/world.ts +10 -0
  68. package/src/client/zoneEngine.ts +174 -0
  69. package/src/client/zones.ts +161 -0
  70. package/src/fivem/byResource.ts +146 -0
  71. package/src/fivem/callbackNames.ts +12 -0
  72. package/src/fivem/exports.ts +70 -0
  73. package/src/fivem/index.ts +13 -0
  74. package/src/fivem/locale.ts +57 -0
  75. package/src/fivem/playerData.ts +13 -0
  76. package/src/fivem/scheduler/every.ts +101 -0
  77. package/src/fivem/scheduler/group.ts +97 -0
  78. package/src/fivem/scheduler/scheduler.ts +77 -0
  79. package/src/fivem/state/entityState.ts +75 -0
  80. package/src/fivem/state/globalState.ts +80 -0
  81. package/src/fivem/state/mirror.ts +47 -0
  82. package/src/fivem/state/playerState.ts +60 -0
  83. package/src/server/admin/descriptions.ts +57 -0
  84. package/src/server/admin/edit.ts +127 -0
  85. package/src/server/admin/jsonSchema.ts +156 -0
  86. package/src/server/admin/panel.ts +167 -0
  87. package/src/server/admin/panelFiles.ts +128 -0
  88. package/src/server/admin/patch.ts +46 -0
  89. package/src/server/admin/validate.ts +147 -0
  90. package/src/server/appearance.ts +28 -0
  91. package/src/server/areaStream/areaStream.ts +141 -0
  92. package/src/server/areaStream/followers.ts +154 -0
  93. package/src/server/areaStream/grid.ts +74 -0
  94. package/src/server/areaStream/options.ts +16 -0
  95. package/src/server/banking.ts +15 -0
  96. package/src/server/bans.ts +47 -0
  97. package/src/server/billing.ts +20 -0
  98. package/src/server/buckets.ts +12 -0
  99. package/src/server/callback.ts +112 -0
  100. package/src/server/characters.ts +129 -0
  101. package/src/server/command/addCommand.ts +83 -0
  102. package/src/server/command/command.ts +116 -0
  103. package/src/server/command/commandSet.ts +74 -0
  104. package/src/server/dataFile.ts +81 -0
  105. package/src/server/database.ts +117 -0
  106. package/src/server/definitions.ts +65 -0
  107. package/src/server/dispatch.ts +13 -0
  108. package/src/server/doors.ts +15 -0
  109. package/src/server/ems.ts +15 -0
  110. package/src/server/fuel.ts +15 -0
  111. package/src/server/garages.ts +34 -0
  112. package/src/server/gate.ts +148 -0
  113. package/src/server/index.ts +165 -0
  114. package/src/server/inventory.ts +106 -0
  115. package/src/server/jobs.ts +42 -0
  116. package/src/server/log.ts +21 -0
  117. package/src/server/mdt.ts +12 -0
  118. package/src/server/medical.ts +16 -0
  119. package/src/server/minigameFor.ts +65 -0
  120. package/src/server/money.ts +70 -0
  121. package/src/server/netEntity.ts +19 -0
  122. package/src/server/netEvent.ts +58 -0
  123. package/src/server/notify.ts +17 -0
  124. package/src/server/online/mirror.ts +176 -0
  125. package/src/server/online/online.ts +190 -0
  126. package/src/server/pending.ts +70 -0
  127. package/src/server/phone.ts +22 -0
  128. package/src/server/players.ts +197 -0
  129. package/src/server/position.ts +31 -0
  130. package/src/server/primeTime.ts +7 -0
  131. package/src/server/prison.ts +15 -0
  132. package/src/server/progressFor.ts +62 -0
  133. package/src/server/proximity.ts +98 -0
  134. package/src/server/rateLimit.ts +53 -0
  135. package/src/server/state.ts +45 -0
  136. package/src/server/stress.ts +25 -0
  137. package/src/server/vehicle/nearby.ts +66 -0
  138. package/src/server/vehicle/plate.ts +14 -0
  139. package/src/server/vehicle/spawn.ts +125 -0
  140. package/src/server/vehicle/vehicleType.ts +50 -0
  141. package/src/server/vehicleKeys.ts +23 -0
  142. package/src/server/watchers.ts +46 -0
  143. package/src/server/world.ts +16 -0
  144. package/src/shared/access.ts +94 -0
  145. package/src/shared/action.ts +28 -0
  146. package/src/shared/blipStyle.ts +26 -0
  147. package/src/shared/clock.ts +22 -0
  148. package/src/shared/format.ts +36 -0
  149. package/src/shared/grid.ts +20 -0
  150. package/src/shared/index.ts +179 -0
  151. package/src/shared/lang.ts +39 -0
  152. package/src/shared/placePed.ts +96 -0
  153. package/src/shared/random.ts +11 -0
  154. package/src/shared/read.ts +60 -0
  155. package/src/shared/records.ts +148 -0
  156. package/src/shared/spec.ts +20 -0
  157. package/src/shared/strict.ts +70 -0
  158. package/src/shared/vec.ts +48 -0
  159. package/src/shared/vehicleProps.ts +138 -0
  160. package/src/shared/wait.ts +27 -0
  161. package/src/shared/zone.ts +144 -0
  162. package/README.md +0 -3
@@ -0,0 +1,98 @@
1
+ import { CORE } from "@aifivem/shared";
2
+ import { resourceExport } from "../fivem/exports";
3
+ import type { Vec3 } from "../shared/vec";
4
+ import { online } from "./online/online";
5
+ import { coordsOf, entityCoords } from "./position";
6
+
7
+ /**
8
+ * Who is near whom without scanning every player: ai-core keeps which players are in each other's OneSync scope
9
+ * (~424 m, one set of scope handlers for the whole server); a "near" question measures only those few players.
10
+ */
11
+ const core = resourceExport(CORE.resource);
12
+
13
+ /** Players within `radius` metres of a point, measured only among `candidates`. */
14
+ function within(
15
+ point: Vec3,
16
+ radius: number,
17
+ candidates: Iterable<number>,
18
+ ): number[] {
19
+ const out: number[] = [];
20
+ for (const source of candidates) {
21
+ const p = coordsOf(source);
22
+ if (Math.hypot(p.x - point.x, p.y - point.y, p.z - point.z) <= radius)
23
+ out.push(source);
24
+ }
25
+ return out;
26
+ }
27
+
28
+ /** Players within `radius` (up to ~424 m) of a player, that player included. */
29
+ export function playersNear(source: number, radius: number): number[] {
30
+ return within(coordsOf(source), radius, [
31
+ source,
32
+ ...core.GetPlayersInScope(source),
33
+ ]);
34
+ }
35
+
36
+ /**
37
+ * Players with a loaded character whose ped is within `radius` of a point (in routing bucket `bucket` when given).
38
+ * Walks every loaded player (two natives each, the bucket read only for those in range): for actions and commands,
39
+ * not ticks; around a player or an entity use `playersNear` / `playersNearEntity` (scope candidates only).
40
+ */
41
+ export function playersNearCoords(
42
+ coords: Vec3,
43
+ radius: number,
44
+ bucket?: number,
45
+ ): number[] {
46
+ const out: number[] = [];
47
+ const max = radius * radius;
48
+ for (const source of online.sources()) {
49
+ const id = String(source);
50
+ const ped = GetPlayerPed(id);
51
+ if (!ped) continue;
52
+ const [x = 0, y = 0, z = 0] = GetEntityCoords(ped);
53
+ const dx = x - coords.x;
54
+ const dy = y - coords.y;
55
+ const dz = z - coords.z;
56
+ if (dx * dx + dy * dy + dz * dz > max) continue;
57
+ if (bucket !== undefined && GetPlayerRoutingBucket(id) !== bucket) continue;
58
+ out.push(source);
59
+ }
60
+ return out;
61
+ }
62
+
63
+ /**
64
+ * Players within `radius` (up to ~424 m) of a networked entity: its owner (a player near it) and the players in that
65
+ * owner's scope. An entity nobody owns (the server) has nobody near it.
66
+ */
67
+ export function playersNearEntity(entity: number, radius: number): number[] {
68
+ if (!DoesEntityExist(entity)) return [];
69
+ const owner = NetworkGetEntityOwner(entity);
70
+ if (owner <= 0) return [];
71
+ return within(entityCoords(entity), radius, [
72
+ owner,
73
+ ...core.GetPlayersInScope(owner),
74
+ ]);
75
+ }
76
+
77
+ /**
78
+ * The closest other player within `metres` of `source` (up to ~424 m, OneSync scope candidates only) that passes
79
+ * `filter` (loaded character, on foot, not cuffed...); null when none.
80
+ */
81
+ export function nearestPlayerTo(
82
+ source: number,
83
+ metres: number,
84
+ filter?: (other: number) => boolean,
85
+ ): number | null {
86
+ const from = coordsOf(source);
87
+ let best: number | null = null;
88
+ let bestDistance = metres;
89
+ for (const other of core.GetPlayersInScope(source)) {
90
+ if (other === source) continue;
91
+ const p = coordsOf(other);
92
+ const d = Math.hypot(p.x - from.x, p.y - from.y, p.z - from.z);
93
+ if (d > bestDistance || (filter && !filter(other))) continue;
94
+ best = other;
95
+ bestDistance = d;
96
+ }
97
+ return best;
98
+ }
@@ -0,0 +1,53 @@
1
+ /**
2
+ * One in-flight action per player. `run` returns `busy` instead of starting a second copy.
3
+ * Call `release(source)` from playerDropped.
4
+ */
5
+ export class SourceLock {
6
+ private readonly active = new Set<number>();
7
+
8
+ async run<T, B>(
9
+ source: number,
10
+ busy: B,
11
+ task: () => Promise<T>,
12
+ ): Promise<T | B> {
13
+ if (this.active.has(source)) return busy;
14
+ this.active.add(source);
15
+ try {
16
+ return await task();
17
+ } finally {
18
+ this.active.delete(source);
19
+ }
20
+ }
21
+
22
+ release(source: number): void {
23
+ this.active.delete(source);
24
+ }
25
+ }
26
+
27
+ /** Per-player burst limit: at most `count` actions inside any `windowMs`. Call `release(source)` from playerDropped. */
28
+ export class RateLimit {
29
+ private readonly hits = new Map<number, number[]>();
30
+
31
+ constructor(
32
+ private readonly count: number,
33
+ private readonly windowMs: number,
34
+ ) {}
35
+
36
+ take(source: number): boolean {
37
+ const now = GetGameTimer();
38
+ const recent = (this.hits.get(source) ?? []).filter(
39
+ (at) => now - at < this.windowMs,
40
+ );
41
+ if (recent.length >= this.count) {
42
+ this.hits.set(source, recent);
43
+ return false;
44
+ }
45
+ recent.push(now);
46
+ this.hits.set(source, recent);
47
+ return true;
48
+ }
49
+
50
+ release(source: number): void {
51
+ this.hits.delete(source);
52
+ }
53
+ }
@@ -0,0 +1,45 @@
1
+ import { EntityState as EntityMirror } from "../fivem/state/entityState";
2
+ import {
3
+ GlobalGroup as GlobalGroupMirror,
4
+ GlobalKey as GlobalKeyMirror,
5
+ } from "../fivem/state/globalState";
6
+ import { PlayerState as PlayerMirror } from "../fivem/state/playerState";
7
+
8
+ /**
9
+ * The server side of the state classes: the same memory reads plus `set`, the only way state bags are written
10
+ * (`sv_stateBagStrictMode`: clients ask through a callback, the server sets). A set is readable at once here (the
11
+ * engine applies it later when any change handler exists), and replicates to the clients that need it.
12
+ */
13
+
14
+ /** One key of entity state bags; `set` replicates to players with the entity in scope. */
15
+ export class EntityState<T> extends EntityMirror<T> {
16
+ set(entity: number, value: T | undefined): void {
17
+ if (!DoesEntityExist(entity)) return;
18
+ Entity(entity).state.set(this.key, value ?? null, true);
19
+ this.put(entity, value);
20
+ }
21
+ }
22
+
23
+ /** One key of player state bags; `set` replicates to that player and the players near them. */
24
+ export class PlayerState<T> extends PlayerMirror<T> {
25
+ set(source: number, value: T | undefined): void {
26
+ Player(source).state.set(this.key, value ?? null, true);
27
+ this.put(source, value);
28
+ }
29
+ }
30
+
31
+ /** One GlobalState key; `set` replicates to everyone. Only for state every player needs. */
32
+ export class GlobalKey<T> extends GlobalKeyMirror<T> {
33
+ set(value: T | undefined): void {
34
+ GlobalState.set(this.key, value ?? null, true);
35
+ this.put(value);
36
+ }
37
+ }
38
+
39
+ /** Many GlobalState keys with one prefix; `set(id, value)` replicates `<prefix><id>` to everyone. */
40
+ export class GlobalGroup<T> extends GlobalGroupMirror<T> {
41
+ set(id: string, value: T | undefined): void {
42
+ GlobalState.set(this.prefix + id, value ?? null, true);
43
+ this.put(id, value);
44
+ }
45
+ }
@@ -0,0 +1,25 @@
1
+ import { CORE } from "@aifivem/shared";
2
+ import { resourceExport } from "../fivem/exports";
3
+
4
+ const core = resourceExport(CORE.resource);
5
+
6
+ /** Players' stress through ai-core's stress layer, whatever HUD keeps it (ai-hud, qb-hud, TGIANN HUDs). */
7
+ export const stress = {
8
+ /** Adds stress points (0-100 scale); false when no HUD with stress runs. */
9
+ gain: (source: number, amount: number): boolean =>
10
+ amount > 0 && core.AddStress(source, amount),
11
+ /** Takes stress points away; false when no HUD with stress runs. */
12
+ relieve: (source: number, amount: number): boolean =>
13
+ amount > 0 && core.AddStress(source, -amount),
14
+ /** The HUD that keeps stress, or null. */
15
+ provider: (): string | null => core.GetStressSystem(),
16
+ };
17
+
18
+ /** Players' hunger and thirst through the same layer (the HUD that keeps them, ai-core's metadata without one). */
19
+ export const needs = {
20
+ /** Hunger and thirst to full (admin revive, hospital); false when the player has no character. */
21
+ refill: (source: number): boolean => core.RefillNeeds(source),
22
+ /** Adds hunger or thirst (0-100 scale; a negative amount takes it away), a food or drink's value. */
23
+ add: (source: number, need: "hunger" | "thirst", amount: number): boolean =>
24
+ core.AddNeed(source, need, amount),
25
+ };
@@ -0,0 +1,66 @@
1
+ import { vehicleFromNet } from "../netEntity";
2
+
3
+ /**
4
+ * The closest vehicle within `metres` of a point (a spawn spot is free...) that passes `filter`; 0 when none. Walks
5
+ * every vehicle: for actions, not ticks.
6
+ */
7
+ export function nearestVehicleAt(
8
+ point: { x: number; y: number; z: number },
9
+ metres: number,
10
+ filter?: (vehicle: number) => boolean,
11
+ ): number {
12
+ let best = 0;
13
+ let bestDistance = metres;
14
+ for (const vehicle of GetAllVehicles() as number[]) {
15
+ const [vx = 0, vy = 0, vz = 0] = GetEntityCoords(vehicle);
16
+ const d = Math.hypot(vx - point.x, vy - point.y, vz - point.z);
17
+ if (d < bestDistance && (!filter || filter(vehicle)))
18
+ [best, bestDistance] = [vehicle, d];
19
+ }
20
+ return best;
21
+ }
22
+
23
+ /**
24
+ * The closest vehicle within `metres` of a player (the one the player sits in first) that passes `filter` (locked
25
+ * doors, a model...); 0 when none. Walks every vehicle: for commands and actions, not ticks.
26
+ */
27
+ export function nearestVehicleTo(
28
+ source: number,
29
+ metres: number,
30
+ filter?: (vehicle: number) => boolean,
31
+ ): number {
32
+ const ped = GetPlayerPed(String(source));
33
+ const own = GetVehiclePedIsIn(ped, false);
34
+ if (own && (!filter || filter(own))) return own;
35
+ const [x = 0, y = 0, z = 0] = GetEntityCoords(ped);
36
+ let best = 0;
37
+ let bestDistance = metres;
38
+ for (const vehicle of GetAllVehicles() as number[]) {
39
+ const [vx = 0, vy = 0, vz = 0] = GetEntityCoords(vehicle);
40
+ const d = Math.hypot(vx - x, vy - y, vz - z);
41
+ if (d < bestDistance && (!filter || filter(vehicle)))
42
+ [best, bestDistance] = [vehicle, d];
43
+ }
44
+ return best;
45
+ }
46
+
47
+ /**
48
+ * The vehicle behind a client's network id when the player is near it: within `metres` (default 5) of it, or, with
49
+ * `driver: true`, in its driver seat. 0 otherwise.
50
+ */
51
+ export function vehicleNearPlayer(
52
+ source: number,
53
+ netId: unknown,
54
+ options: { metres?: number; driver?: boolean } = {},
55
+ ): number {
56
+ const vehicle = vehicleFromNet(netId);
57
+ if (!vehicle) return 0;
58
+ const ped = GetPlayerPed(String(source));
59
+ if (options.driver)
60
+ return GetPedInVehicleSeat(vehicle, -1) === ped ? vehicle : 0;
61
+ const [px = 0, py = 0, pz = 0] = GetEntityCoords(ped);
62
+ const [vx = 0, vy = 0, vz = 0] = GetEntityCoords(vehicle);
63
+ return Math.hypot(vx - px, vy - py, vz - pz) <= (options.metres ?? 5)
64
+ ? vehicle
65
+ : 0;
66
+ }
@@ -0,0 +1,14 @@
1
+ const PLATE_LETTERS = "ABCDEFGHJKLMNPRSTUVWXYZ";
2
+
3
+ /** A plate like the game's own (two digits, three letters, three digits), or `prefix` followed by digits (8 in all). */
4
+ export function randomPlate(prefix?: string): string {
5
+ const digit = () => String(Math.floor(Math.random() * 10));
6
+ if (prefix !== undefined) {
7
+ let plate = prefix.slice(0, 8);
8
+ while (plate.length < 8) plate += digit();
9
+ return plate;
10
+ }
11
+ const letter = () =>
12
+ PLATE_LETTERS[Math.floor(Math.random() * PLATE_LETTERS.length)] ?? "A";
13
+ return `${digit()}${digit()}${letter()}${letter()}${letter()}${digit()}${digit()}${digit()}`;
14
+ }
@@ -0,0 +1,125 @@
1
+ import { VEHICLE_BAGS, type KeyPurpose } from "@aifivem/shared";
2
+ import { waitFor, type VehicleProps, type VehicleSetup } from "../../shared";
3
+ import { fuel } from "../fuel";
4
+ import { vehicleKeys } from "../vehicleKeys";
5
+ import { randomPlate } from "./plate";
6
+ import { modelHash, vehicleType } from "./vehicleType";
7
+
8
+ export interface SpawnVehicleOptions {
9
+ /** Model name or hash. */
10
+ model: string | number;
11
+ coords: { x: number; y: number; z: number; heading: number };
12
+ /** A player whose client tells the spawn type (and whether the model exists); without it `type` or "automobile". */
13
+ asker?: number;
14
+ /** `CreateVehicleServerSetter` type when no `asker` is given ("automobile", "bike", "boat", "heli", "plane"...). */
15
+ type?: string;
16
+ /** Up to 8 characters. */
17
+ plate?: string;
18
+ /** 0-100, set through ai-core's fuel layer (lib `fuel`). */
19
+ fuel?: number;
20
+ /** A player who gets the keys through ai-core's key layer, for `purpose` (default `temporary`). */
21
+ keysTo?: number;
22
+ purpose?: KeyPurpose;
23
+ /** A player put into the driver seat. */
24
+ driver?: number;
25
+ /** Players put into other seats (0 front passenger, 1 and 2 the back...). */
26
+ seats?: Array<{ source: number; seat: number }>;
27
+ /** Stored look and tuning (a garage vehicle); the owner client applies them. */
28
+ props?: VehicleProps;
29
+ /** Fresh-vehicle extras: full tuning, colours, livery, tint, dirt, engine running. */
30
+ setup?: VehicleSetup;
31
+ /** Doors locked for everyone (keys unlock them). */
32
+ locked?: boolean;
33
+ /** Routing bucket the vehicle lives in (players put in it should be in the same one). */
34
+ bucket?: number;
35
+ /** Orphan mode 2: the vehicle stays when its owner leaves (default true). */
36
+ persistent?: boolean;
37
+ /** Replicated state bag values set right after creation. */
38
+ bags?: Record<string, unknown>;
39
+ }
40
+
41
+ /** Puts a player into a seat, trying again while the new entity is not ready for it (up to 2 s). */
42
+ async function seatPlayer(
43
+ vehicle: number,
44
+ source: number,
45
+ seat: number,
46
+ ): Promise<boolean> {
47
+ const ped = GetPlayerPed(String(source));
48
+ if (!ped) return false;
49
+ return waitFor(
50
+ () => {
51
+ if (!DoesEntityExist(vehicle)) return false;
52
+ if (GetPedInVehicleSeat(vehicle, seat) === ped) return true;
53
+ SetPedIntoVehicle(ped, vehicle, seat);
54
+ return undefined;
55
+ },
56
+ 2000,
57
+ 150,
58
+ ).catch(() => false);
59
+ }
60
+
61
+ /**
62
+ * 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.
64
+ */
65
+ export async function spawnVehicle(
66
+ options: SpawnVehicleOptions,
67
+ ): Promise<number | null> {
68
+ const type =
69
+ options.asker !== undefined
70
+ ? await vehicleType(options.model, options.asker)
71
+ : (options.type ?? "automobile");
72
+ if (!type) return null;
73
+ const { x, y, z, heading } = options.coords;
74
+ const vehicle = CreateVehicleServerSetter(
75
+ modelHash(options.model),
76
+ type,
77
+ x,
78
+ y,
79
+ z,
80
+ heading,
81
+ );
82
+ if (
83
+ !(await waitFor(() => DoesEntityExist(vehicle) || undefined, 5000).catch(
84
+ () => false,
85
+ ))
86
+ )
87
+ return null;
88
+ if (options.persistent !== false) SetEntityOrphanMode(vehicle, 2);
89
+ // The server reads the plate only after the owner client's first sync: the plate is always set here (a random one
90
+ // when none is given), so keys never go to an empty plate.
91
+ const plate = (options.plate ?? randomPlate()).slice(0, 8);
92
+ SetVehicleNumberPlateText(vehicle, plate);
93
+ if (options.bucket !== undefined)
94
+ SetEntityRoutingBucket(vehicle, options.bucket);
95
+ if (options.locked) SetVehicleDoorsLocked(vehicle, 2);
96
+ const state = Entity(vehicle).state;
97
+ // Through ai-core's fuel layer: a fuel script that keeps fuel on clients gets it from the entity's owner.
98
+ if (options.fuel !== undefined) fuel.set(vehicle, options.fuel);
99
+ if (options.props) state.set(VEHICLE_BAGS.props, options.props, true);
100
+ if (options.setup) state.set(VEHICLE_BAGS.setup, options.setup, true);
101
+ for (const [key, value] of Object.entries(options.bags ?? {}))
102
+ state.set(key, value, true);
103
+ if (options.keysTo !== undefined) {
104
+ const synced = await waitFor(
105
+ () =>
106
+ !DoesEntityExist(vehicle) ||
107
+ GetVehicleNumberPlateText(vehicle).trim() === plate.trim() ||
108
+ undefined,
109
+ 3000,
110
+ ).catch(() => false);
111
+ vehicleKeys.give(
112
+ options.keysTo,
113
+ synced && DoesEntityExist(vehicle) ? vehicle : plate.trim(),
114
+ options.purpose ?? "temporary",
115
+ );
116
+ }
117
+ const riders = [
118
+ ...(options.driver !== undefined
119
+ ? [{ source: options.driver, seat: -1 }]
120
+ : []),
121
+ ...(options.seats ?? []),
122
+ ];
123
+ await Promise.all(riders.map((r) => seatPlayer(vehicle, r.source, r.seat)));
124
+ return vehicle;
125
+ }
@@ -0,0 +1,50 @@
1
+ import { CORE } from "@aifivem/shared";
2
+ import { triggerClientCallback } from "../callback";
3
+
4
+ /** Every type `CreateVehicleServerSetter` takes; a client answering anything else is ignored. */
5
+ const TYPES = new Set([
6
+ "automobile",
7
+ "bike",
8
+ "boat",
9
+ "heli",
10
+ "plane",
11
+ "submarine",
12
+ "trailer",
13
+ "train",
14
+ ]);
15
+ /** Model hash -> spawn type two different players' clients agreed on (the server cannot read a vehicle class). */
16
+ const types = new Map<number, string>();
17
+ /** Model hash -> type -> the first player whose client answered it, until a second player confirms one. */
18
+ const votes = new Map<number, Map<string, number>>();
19
+
20
+ /** A model name or hash as the signed 32-bit hash `GetHashKey` gives (a hash written unsigned is the same model). */
21
+ export const modelHash = (model: string | number): number =>
22
+ typeof model === "number" ? model | 0 : GetHashKey(model) | 0;
23
+
24
+ /**
25
+ * The `CreateVehicleServerSetter` type of a model (name or hash) asked from a player's client (ai-core answers); null:
26
+ * no such vehicle. An answer serves only that player's spawn until a second player's client gives the same one, then
27
+ * it is kept for everyone: one modified client can break only its own spawns, never a model for the server.
28
+ */
29
+ export async function vehicleType(
30
+ model: string | number,
31
+ asker: number,
32
+ ): Promise<string | null> {
33
+ const hash = modelHash(model);
34
+ const known = types.get(hash);
35
+ if (known !== undefined) return known;
36
+ const answer = await triggerClientCallback(CORE.vehicleTypeCallback, asker, [
37
+ model,
38
+ ]).catch(() => null);
39
+ if (typeof answer !== "string" || !TYPES.has(answer)) return null;
40
+ const seen = votes.get(hash) ?? new Map<string, number>();
41
+ const first = seen.get(answer);
42
+ if (first !== undefined && first !== asker) {
43
+ types.set(hash, answer);
44
+ votes.delete(hash);
45
+ } else {
46
+ seen.set(answer, asker);
47
+ votes.set(hash, seen);
48
+ }
49
+ return answer;
50
+ }
@@ -0,0 +1,23 @@
1
+ import { CORE, type KeyPurpose } from "@aifivem/shared";
2
+ import { resourceExport } from "../fivem/exports";
3
+
4
+ const core = resourceExport(CORE.resource);
5
+
6
+ /**
7
+ * Vehicle keys through ai-core's key layer: the active key system (ai-vehiclekeys, or another the panel picks) answers.
8
+ * A vehicle is a server entity handle or a plate; `purpose` tells the key system why the player gets it (`KeyPurpose`).
9
+ */
10
+ export const vehicleKeys = {
11
+ /** Gives a player the keys of a vehicle; `purpose` defaults to `temporary`. */
12
+ give: (
13
+ source: number,
14
+ vehicle: number | string,
15
+ purpose: KeyPurpose = "temporary",
16
+ ): void => core.GiveVehicleKeys(source, vehicle, purpose),
17
+ /** Takes a player's keys of a vehicle. */
18
+ remove: (source: number, vehicle: number | string): void =>
19
+ core.RemoveVehicleKeys(source, vehicle),
20
+ /** Whether a player holds the keys; true when the key system cannot tell or none runs. */
21
+ has: (source: number, vehicle: number | string): boolean =>
22
+ core.HasVehicleKeys(source, vehicle),
23
+ };
@@ -0,0 +1,46 @@
1
+ import { PlayerMap } from "./players";
2
+
3
+ /**
4
+ * Players who receive one key's deltas (a lot's cars, a character's screen): one key per player, `watch` replaces
5
+ * the old one; freed on drop, empty sets deleted. Every operation is O(1). Create once at module level.
6
+ */
7
+ export class KeyWatchers<K> {
8
+ private readonly byKey = new Map<K, Set<number>>();
9
+ private readonly keys = new PlayerMap<K>({
10
+ onDrop: (source, key) => this.leave(source, key),
11
+ });
12
+
13
+ /** The player watches `key` (and stops watching the one before). */
14
+ watch(source: number, key: K): void {
15
+ this.stop(source);
16
+ this.keys.set(source, key);
17
+ let set = this.byKey.get(key);
18
+ if (!set) this.byKey.set(key, (set = new Set()));
19
+ set.add(source);
20
+ }
21
+
22
+ /** The player stops watching. */
23
+ stop(source: number): void {
24
+ const key = this.keys.get(source);
25
+ if (key === undefined) return;
26
+ this.keys.delete(source);
27
+ this.leave(source, key);
28
+ }
29
+
30
+ /** The players watching `key`, undefined when none. */
31
+ of(key: K): ReadonlySet<number> | undefined {
32
+ return this.byKey.get(key);
33
+ }
34
+
35
+ /** The key the player watches. */
36
+ keyOf(source: number): K | undefined {
37
+ return this.keys.get(source);
38
+ }
39
+
40
+ private leave(source: number, key: K): void {
41
+ const set = this.byKey.get(key);
42
+ if (!set) return;
43
+ set.delete(source);
44
+ if (set.size === 0) this.byKey.delete(key);
45
+ }
46
+ }
@@ -0,0 +1,16 @@
1
+ import { CORE, type Weather } from "@aifivem/shared";
2
+ import { resourceExport } from "../fivem/exports";
3
+
4
+ const core = resourceExport(CORE.resource);
5
+
6
+ /** Time and weather through ai-core, whatever weather script runs (admin tools, events, jobs). */
7
+ export const world = {
8
+ /** The current weather type as the weather script reports it, null while none runs. */
9
+ getWeather: (): string | null => core.GetWeather(),
10
+ /** Sets the weather (`isWeather` checks a value from a client or a panel first); false while no weather script runs. */
11
+ setWeather: (type: Weather): boolean => core.SetWeather(type),
12
+ getTime: (): { hour: number; minute: number } | null => core.GetTime(),
13
+ setTime: (hour: number, minute = 0): boolean => core.SetTime(hour, minute),
14
+ setBlackout: (on: boolean): boolean => core.SetBlackout(on),
15
+ freezeTime: (on: boolean): boolean => core.FreezeTime(on),
16
+ };
@@ -0,0 +1,94 @@
1
+ import type { DataSpec, WidgetSpec } from "@aifivem/shared";
2
+ import { bool, record } from "./read";
3
+
4
+ /**
5
+ * Who may use a place: one of `jobs` (each at its `grades` minimum, on duty in it with `onDuty`) or one of `gangs`
6
+ * (at its minimum grade). Both lists empty: everyone. Read from a record's own fields (`jobs`, `gangs`, `grades`,
7
+ * `onDuty`), so the client's check (`allows`) and the server's (`online.allows`) use the same rule.
8
+ */
9
+ export interface AccessRule {
10
+ jobs: string[];
11
+ gangs: string[];
12
+ /** Minimum grade per job or gang name (missing: 0). */
13
+ grades: Record<string, number>;
14
+ onDuty: boolean;
15
+ }
16
+
17
+ const names = (v: unknown): string[] =>
18
+ Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : [];
19
+
20
+ /** A record's access rule (missing fields: everyone). */
21
+ export function readAccess(value: unknown): AccessRule {
22
+ const v = record(value);
23
+ const grades: Record<string, number> = {};
24
+ for (const [name, grade] of Object.entries(record(v.grades)))
25
+ if (typeof grade === "number" && Number.isInteger(grade) && grade >= 0)
26
+ grades[name] = grade;
27
+ return {
28
+ jobs: names(v.jobs),
29
+ gangs: names(v.gangs),
30
+ grades,
31
+ onDuty: bool(v.onDuty, false),
32
+ };
33
+ }
34
+
35
+ /** Whether the rule lets everyone in. */
36
+ export const isPublic = (rule: AccessRule): boolean =>
37
+ rule.jobs.length === 0 && rule.gangs.length === 0;
38
+
39
+ /** The panel data spec of the access fields, spread into a records file's sections. */
40
+ export const ACCESS_FIELDS: Record<string, DataSpec> = {
41
+ jobs: { type: "names", lookup: "job", optional: true },
42
+ gangs: { type: "names", lookup: "gang", optional: true },
43
+ onDuty: { type: "bool", optional: true },
44
+ };
45
+
46
+ /** The panel fields of the access rule (labels and hints are ai-core's generic panel texts). */
47
+ export function accessFields(): WidgetSpec[] {
48
+ return [
49
+ {
50
+ widget: "tags",
51
+ lookup: "job",
52
+ path: "jobs",
53
+ label: "ADMIN_F_ACCESS_JOBS",
54
+ hint: "ADMIN_H_ACCESS_JOBS",
55
+ placeholder: "ADMIN_P_ACCESS_JOBS",
56
+ },
57
+ {
58
+ widget: "tags",
59
+ lookup: "gang",
60
+ path: "gangs",
61
+ label: "ADMIN_F_ACCESS_GANGS",
62
+ hint: "ADMIN_H_ACCESS_GANGS",
63
+ placeholder: "ADMIN_P_ACCESS_GANGS",
64
+ },
65
+ {
66
+ widget: "switch",
67
+ path: "onDuty",
68
+ label: "ADMIN_F_ACCESS_ON_DUTY",
69
+ hint: "ADMIN_H_ACCESS_ON_DUTY",
70
+ },
71
+ ];
72
+ }
73
+
74
+ /**
75
+ * The rule's decision from a player's memberships (the shared core of the client's `allows` and the server's
76
+ * `online.allows`).
77
+ */
78
+ export function decideAccess(
79
+ rule: AccessRule,
80
+ jobs: ReadonlyArray<{ job: string; grade: number }>,
81
+ gangs: ReadonlyArray<{ gang: string; grade: number }>,
82
+ dutyJob: string | null,
83
+ ): boolean {
84
+ if (isPublic(rule)) return true;
85
+ const min = (name: string) => rule.grades[name] ?? 0;
86
+ if (gangs.some((g) => rule.gangs.includes(g.gang) && g.grade >= min(g.gang)))
87
+ return true;
88
+ return jobs.some(
89
+ (j) =>
90
+ rule.jobs.includes(j.job) &&
91
+ j.grade >= min(j.job) &&
92
+ (!rule.onDuty || dutyJob === j.job),
93
+ );
94
+ }