@aifivem/lib 0.0.0-stage → 0.7.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,174 @@
1
+ import { every, type Job } from "../fivem/scheduler/every";
2
+ import { createLogger } from "../shared";
3
+ import { zoneBounds, zoneContains, type ZoneShape } from "../shared/zone";
4
+ import { cache } from "./cache";
5
+
6
+ /**
7
+ * The zone checker: inside / outside checks at each zone's own interval, never per frame. Built for any count
8
+ * (measured with 1,000,000 zones): zones sit in a grid of 64 m cells and a check looks only at the player's cell and
9
+ * the zones the player is in. ai-lib runs one for every resource's zones (`zones.ts`); a resource runs its own only
10
+ * while ai-lib does not.
11
+ */
12
+
13
+ const log = createLogger(GetCurrentResourceName());
14
+
15
+ export interface ZoneOptions {
16
+ shape: ZoneShape;
17
+ /** How often to check, in ms (default 500, at least 50). A shop needs ~500, a fast trigger ~100; per-frame work belongs elsewhere. */
18
+ interval?: number;
19
+ onEnter?: () => void;
20
+ onExit?: () => void;
21
+ }
22
+
23
+ const CELL = 64;
24
+ /** A zone wider than this many cells is kept in one list checked every time instead of in the grid. */
25
+ const MAX_CELLS = 64;
26
+ const cellKey = (cx: number, cy: number): number =>
27
+ ((cx + 32768) << 16) | (cy + 32768);
28
+
29
+ class Zone {
30
+ inside = false;
31
+ nextCheck = 0;
32
+ readonly interval: number;
33
+ /** Grid cells the zone is filed under; empty when it is in the large list. */
34
+ readonly cells: number[] = [];
35
+
36
+ constructor(
37
+ readonly options: ZoneOptions,
38
+ inside: boolean,
39
+ ) {
40
+ this.interval = Math.max(50, options.interval ?? 500);
41
+ this.inside = inside;
42
+ }
43
+ }
44
+
45
+ /**
46
+ * A set of zones. One scheduler job serves them all at the shortest interval any zone asks for; each zone is checked
47
+ * only when its own interval has passed. With no zones the job stops.
48
+ */
49
+ export class ZoneEngine {
50
+ private readonly zones = new Map<string, Zone>();
51
+ private readonly grid = new Map<number, Set<Zone>>();
52
+ private readonly large = new Set<Zone>();
53
+ private readonly insideNow = new Set<Zone>();
54
+ /** How many zones use each interval, so the shortest one is found without walking every zone. */
55
+ private readonly intervals = new Map<number, number>();
56
+ private job: Job | null = null;
57
+ private period = 0;
58
+
59
+ /**
60
+ * Adds (or replaces) a zone. A replaced zone the player was in fires its onExit first. `inside` seeds the state of a
61
+ * zone handed over from another checker, so leaving it is noticed and staying in it fires nothing.
62
+ */
63
+ add(id: string, options: ZoneOptions, inside = false): void {
64
+ this.remove(id);
65
+ const zone = new Zone(options, inside);
66
+ this.zones.set(id, zone);
67
+ if (inside) this.insideNow.add(zone);
68
+ const [minX, minY, maxX, maxY] = zoneBounds(options.shape);
69
+ const x0 = Math.floor(minX / CELL);
70
+ const y0 = Math.floor(minY / CELL);
71
+ const x1 = Math.floor(maxX / CELL);
72
+ const y1 = Math.floor(maxY / CELL);
73
+ if ((x1 - x0 + 1) * (y1 - y0 + 1) > MAX_CELLS) this.large.add(zone);
74
+ else {
75
+ for (let cx = x0; cx <= x1; cx++) {
76
+ for (let cy = y0; cy <= y1; cy++) {
77
+ const key = cellKey(cx, cy);
78
+ let cell = this.grid.get(key);
79
+ if (!cell) this.grid.set(key, (cell = new Set()));
80
+ cell.add(zone);
81
+ zone.cells.push(key);
82
+ }
83
+ }
84
+ }
85
+ this.intervals.set(
86
+ zone.interval,
87
+ (this.intervals.get(zone.interval) ?? 0) + 1,
88
+ );
89
+ this.schedule();
90
+ }
91
+
92
+ /** Removes a zone; it fires onExit when the player was in it, unless `quiet` (a hand-over). */
93
+ remove(id: string, quiet = false): void {
94
+ const zone = this.zones.get(id);
95
+ if (!zone) return;
96
+ this.zones.delete(id);
97
+ this.large.delete(zone);
98
+ for (const key of zone.cells) {
99
+ const cell = this.grid.get(key);
100
+ cell?.delete(zone);
101
+ if (cell?.size === 0) this.grid.delete(key);
102
+ }
103
+ const left = (this.intervals.get(zone.interval) ?? 1) - 1;
104
+ if (left > 0) this.intervals.set(zone.interval, left);
105
+ else this.intervals.delete(zone.interval);
106
+ if (this.insideNow.delete(zone) && !quiet) this.fire(zone, false);
107
+ this.schedule();
108
+ }
109
+
110
+ /** Removes every zone (exits fire for the ones the player is in). */
111
+ clear(): void {
112
+ const inside = [...this.insideNow];
113
+ this.zones.clear();
114
+ this.grid.clear();
115
+ this.large.clear();
116
+ this.insideNow.clear();
117
+ this.intervals.clear();
118
+ for (const zone of inside) this.fire(zone, false);
119
+ this.schedule();
120
+ }
121
+
122
+ isInside(id: string): boolean {
123
+ return this.zones.get(id)?.inside ?? false;
124
+ }
125
+
126
+ get size(): number {
127
+ return this.zones.size;
128
+ }
129
+
130
+ private schedule(): void {
131
+ let period = 0;
132
+ for (const interval of this.intervals.keys())
133
+ period = period === 0 ? interval : Math.min(period, interval);
134
+ if (period === this.period) return;
135
+ this.job?.stop();
136
+ this.job = period
137
+ ? every(period, () => this.check(), { name: "zones" })
138
+ : null;
139
+ this.period = period;
140
+ }
141
+
142
+ private check(): void {
143
+ const now = GetGameTimer();
144
+ const [x = 0, y = 0, z = 0] = GetEntityCoords(cache.ped, false);
145
+ // The zones the player is in go first, so leaving one is noticed wherever the player went.
146
+ for (const zone of this.insideNow) this.test(zone, now, x, y, z);
147
+ for (const zone of this.large) this.test(zone, now, x, y, z);
148
+ const cell = this.grid.get(
149
+ cellKey(Math.floor(x / CELL), Math.floor(y / CELL)),
150
+ );
151
+ if (cell) for (const zone of cell) this.test(zone, now, x, y, z);
152
+ }
153
+
154
+ private test(zone: Zone, now: number, x: number, y: number, z: number): void {
155
+ if (now < zone.nextCheck) return;
156
+ zone.nextCheck = now + zone.interval;
157
+ const inside = zoneContains(zone.options.shape, x, y, z);
158
+ if (inside === zone.inside) return;
159
+ if (inside) this.insideNow.add(zone);
160
+ else this.insideNow.delete(zone);
161
+ this.fire(zone, inside);
162
+ }
163
+
164
+ private fire(zone: Zone, inside: boolean): void {
165
+ zone.inside = inside;
166
+ // A failing enter / exit handler must not stop the other zones.
167
+ try {
168
+ if (inside) zone.options.onEnter?.();
169
+ else zone.options.onExit?.();
170
+ } catch (error) {
171
+ log.error("zone handler failed", error);
172
+ }
173
+ }
174
+ }
@@ -0,0 +1,161 @@
1
+ import { LIB_UI } from "@aifivem/shared";
2
+ import { callExport, isResourceStarted } from "../fivem/exports";
3
+ import { createLogger } from "../shared";
4
+ import type { ZoneShape } from "../shared/zone";
5
+ import { ZoneEngine, type ZoneOptions } from "./zoneEngine";
6
+
7
+ export type { ZoneShape, ZoneOptions };
8
+
9
+ /**
10
+ * Zones are checked by ai-lib for every resource: FiveM enters a resource's JS every frame while it has any timer, so
11
+ * one checker for all costs one resource's frame time instead of every resource's. A resource checks its own zones
12
+ * only while ai-lib does not run (client still loading, ai-lib restarting) and hands them back when it starts.
13
+ */
14
+ const RESOURCE = GetCurrentResourceName();
15
+ const HOST = LIB_UI.resource;
16
+ const log = createLogger(RESOURCE);
17
+
18
+ class Entry {
19
+ inside = false;
20
+ constructor(
21
+ readonly key: string,
22
+ readonly options: ZoneOptions,
23
+ ) {}
24
+ }
25
+
26
+ /** Every zone of this resource by its key (`<group>:<id>`), so ai-lib's enter / exit events find it. */
27
+ const entries = new Map<string, Entry>();
28
+ const local = new ZoneEngine();
29
+ let hosted = false;
30
+ /** ai-lib reads started but its exports are not there yet (client loading): wait for its start event. */
31
+ let waiting = false;
32
+
33
+ function setInside(entry: Entry, inside: boolean): void {
34
+ if (entry.inside === inside) return;
35
+ entry.inside = inside;
36
+ try {
37
+ if (inside) entry.options.onEnter?.();
38
+ else entry.options.onExit?.();
39
+ } catch (error) {
40
+ log.error("zone handler failed", error);
41
+ }
42
+ }
43
+
44
+ function addLocal(entry: Entry): void {
45
+ local.add(
46
+ entry.key,
47
+ {
48
+ shape: entry.options.shape,
49
+ interval: entry.options.interval,
50
+ onEnter: () => setInside(entry, true),
51
+ onExit: () => setInside(entry, false),
52
+ },
53
+ entry.inside,
54
+ );
55
+ }
56
+
57
+ /** Hands one zone to ai-lib; false while it cannot take it (not started, or its exports not there yet). */
58
+ function addHosted(entry: Entry): boolean {
59
+ try {
60
+ callExport(
61
+ HOST,
62
+ "AddZone",
63
+ entry.key,
64
+ entry.options.shape,
65
+ entry.options.interval ?? 500,
66
+ entry.inside,
67
+ );
68
+ return true;
69
+ } catch (error) {
70
+ if (!String(error).includes("No such export")) throw error;
71
+ waiting = true;
72
+ return false;
73
+ }
74
+ }
75
+
76
+ /** ai-lib takes every zone over; the local checker stops. */
77
+ function handOver(): void {
78
+ if (RESOURCE === HOST || waiting || !isResourceStarted(HOST)) return;
79
+ for (const entry of entries.values())
80
+ if (!addHosted(entry)) return takeBack();
81
+ hosted = true;
82
+ for (const key of entries.keys()) local.remove(key, true);
83
+ }
84
+
85
+ /** ai-lib is gone: this resource checks its zones again, from the state ai-lib last reported. */
86
+ function takeBack(): void {
87
+ hosted = false;
88
+ for (const entry of entries.values()) addLocal(entry);
89
+ }
90
+
91
+ if (RESOURCE !== HOST) {
92
+ on(LIB_UI.zoneEvent, (owner: unknown, key: unknown, inside: unknown) => {
93
+ if (owner !== RESOURCE || typeof key !== "string") return;
94
+ const entry = entries.get(key);
95
+ if (entry && hosted) setInside(entry, inside === true);
96
+ });
97
+ on("onClientResourceStart", (resource: string) => {
98
+ if (resource !== HOST) return;
99
+ waiting = false;
100
+ handOver();
101
+ });
102
+ on("onClientResourceStop", (resource: string) => {
103
+ if (resource === HOST && hosted) takeBack();
104
+ });
105
+ }
106
+
107
+ let nextGroup = 0;
108
+
109
+ /**
110
+ * The zones of one feature (`add` / `remove` by id, `onEnter` / `onExit` per zone). Checked by ai-lib's one checker
111
+ * (each zone at its own interval, never per frame), or by this resource while ai-lib does not run.
112
+ */
113
+ export class Zones {
114
+ private readonly prefix = `${++nextGroup}:`;
115
+ private readonly ids = new Set<string>();
116
+
117
+ /** Adds (or replaces) a zone. A replaced zone the player was in fires its onExit first. */
118
+ add(id: string, options: ZoneOptions): void {
119
+ this.remove(id);
120
+ const entry = new Entry(this.prefix + id, options);
121
+ entries.set(entry.key, entry);
122
+ this.ids.add(id);
123
+ if (!hosted) {
124
+ handOver();
125
+ if (!hosted) return addLocal(entry);
126
+ }
127
+ if (!addHosted(entry)) {
128
+ takeBack();
129
+ return;
130
+ }
131
+ }
132
+
133
+ remove(id: string): void {
134
+ const key = this.prefix + id;
135
+ const entry = entries.get(key);
136
+ if (!entry) return;
137
+ entries.delete(key);
138
+ this.ids.delete(id);
139
+ if (hosted) {
140
+ try {
141
+ callExport(HOST, "RemoveZone", key);
142
+ } catch {
143
+ // ai-lib stopped meanwhile: its zones went with it.
144
+ }
145
+ } else local.remove(key, true);
146
+ setInside(entry, false);
147
+ }
148
+
149
+ /** Removes every zone (exits fire for the ones the player is in). */
150
+ clear(): void {
151
+ for (const id of [...this.ids]) this.remove(id);
152
+ }
153
+
154
+ isInside(id: string): boolean {
155
+ return entries.get(this.prefix + id)?.inside ?? false;
156
+ }
157
+
158
+ get size(): number {
159
+ return this.ids.size;
160
+ }
161
+ }
@@ -0,0 +1,146 @@
1
+ /** The resource that called the current export (this resource when called from its own code). */
2
+ export function caller(): string {
3
+ const invoking = GetInvokingResource();
4
+ return invoking !== null && invoking !== undefined && invoking !== ""
5
+ ? invoking
6
+ : GetCurrentResourceName();
7
+ }
8
+
9
+ /** One resource-stop listener for every owner map and `onStop` of this resource. */
10
+ const stopHandlers: Array<(resource: string) => void> = [];
11
+ let listening = false;
12
+ function onAnyStop(handler: (resource: string) => void): void {
13
+ stopHandlers.push(handler);
14
+ if (listening) return;
15
+ listening = true;
16
+ const event = IsDuplicityVersion() ? "onResourceStop" : "onClientResourceStop";
17
+ on(event, (resource: string) => {
18
+ for (const stop of stopHandlers) stop(resource);
19
+ });
20
+ }
21
+
22
+ /** Runs `fn` when this resource stops (the side's stop event; one listener per resource). */
23
+ export function onStop(fn: () => void): void {
24
+ const self = GetCurrentResourceName();
25
+ onAnyStop((resource) => {
26
+ if (resource === self) fn();
27
+ });
28
+ }
29
+
30
+ /**
31
+ * Entries owned by the resources that registered them (an export provider's prompts, hints, items): a stopping
32
+ * resource's entries go at once. `dropResource` is O(entries of that resource).
33
+ */
34
+ export class ByResource<K, V> {
35
+ private readonly byOwner = new Map<string, Map<K, V>>();
36
+ private readonly owners = new Map<K, string>();
37
+
38
+ constructor(
39
+ private readonly options: {
40
+ onDrop?: (resource: string, key: K, value: V) => void;
41
+ } = {},
42
+ ) {
43
+ onAnyStop((resource) => this.dropResource(resource));
44
+ }
45
+
46
+ /** Sets the entry under `owner` (default: the calling resource), moving it from another owner. */
47
+ set(key: K, value: V, owner = caller()): void {
48
+ const previous = this.owners.get(key);
49
+ if (previous !== undefined && previous !== owner)
50
+ this.byOwner.get(previous)?.delete(key);
51
+ let map = this.byOwner.get(owner);
52
+ if (!map) this.byOwner.set(owner, (map = new Map()));
53
+ map.set(key, value);
54
+ this.owners.set(key, owner);
55
+ }
56
+
57
+ get(key: K): V | undefined {
58
+ const owner = this.owners.get(key);
59
+ return owner === undefined ? undefined : this.byOwner.get(owner)?.get(key);
60
+ }
61
+
62
+ ownerOf(key: K): string | undefined {
63
+ return this.owners.get(key);
64
+ }
65
+
66
+ delete(key: K): boolean {
67
+ const owner = this.owners.get(key);
68
+ if (owner === undefined) return false;
69
+ this.owners.delete(key);
70
+ const map = this.byOwner.get(owner);
71
+ map?.delete(key);
72
+ if (map?.size === 0) this.byOwner.delete(owner);
73
+ return true;
74
+ }
75
+
76
+ *values(): Generator<V> {
77
+ for (const map of this.byOwner.values()) yield* map.values();
78
+ }
79
+
80
+ *entries(): Generator<[K, V]> {
81
+ for (const map of this.byOwner.values()) yield* map.entries();
82
+ }
83
+
84
+ get size(): number {
85
+ return this.owners.size;
86
+ }
87
+
88
+ /** Drops every entry of a resource (`onDrop` per entry). */
89
+ dropResource(resource: string): void {
90
+ const map = this.byOwner.get(resource);
91
+ if (!map) return;
92
+ this.byOwner.delete(resource);
93
+ for (const [key, value] of map) {
94
+ this.owners.delete(key);
95
+ this.options.onDrop?.(resource, key, value);
96
+ }
97
+ }
98
+ }
99
+
100
+ /**
101
+ * Flags set by resources for a reason (`<resource>:<reason>`: HUD hidden, sync paused): `any` is true while one is
102
+ * set; a stopping resource's flags go. `onChange` hears `any` flip.
103
+ */
104
+ export class Reasons {
105
+ private readonly set_ = new Set<string>();
106
+ private readonly listeners: Array<(any: boolean) => void> = [];
107
+
108
+ constructor() {
109
+ onAnyStop((resource) => {
110
+ const before = this.any;
111
+ for (const key of this.set_)
112
+ if (key.startsWith(`${resource}:`)) this.set_.delete(key);
113
+ this.notify(before);
114
+ });
115
+ }
116
+
117
+ get any(): boolean {
118
+ return this.set_.size > 0;
119
+ }
120
+
121
+ /** Whether a reason (of `owner`, default the calling resource) is set. */
122
+ has(reason: string, owner = caller()): boolean {
123
+ return this.set_.has(`${owner}:${reason}`);
124
+ }
125
+
126
+ set(reason: string, on: boolean, owner = caller()): void {
127
+ const before = this.any;
128
+ const key = `${owner}:${reason}`;
129
+ if (on) this.set_.add(key);
130
+ else this.set_.delete(key);
131
+ this.notify(before);
132
+ }
133
+
134
+ onChange(handler: (any: boolean) => void): void {
135
+ this.listeners.push(handler);
136
+ }
137
+
138
+ private notify(before: boolean): void {
139
+ if (before === this.any) return;
140
+ for (const listener of this.listeners) listener(this.any);
141
+ }
142
+ }
143
+
144
+ /** A vehicle's plate as keys use it (trimmed, upper case; GTA pads plates with spaces). */
145
+ export const plateOf = (vehicle: number): string =>
146
+ GetVehicleNumberPlateText(vehicle).trim().toUpperCase();
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Callback wire format, the same on both sides:
3
+ * request `aicore:cb:<name>` (callerResource, id, ...args)
4
+ * response `aicore:cbr:<callerResource>` (id, ok, result)
5
+ * The response goes only to the resource that asked, so two resources never see each other's replies.
6
+ */
7
+ export const requestEvent = (name: string): string => `aicore:cb:${name}`;
8
+ export const responseEvent = (resource: string): string =>
9
+ `aicore:cbr:${resource}`;
10
+
11
+ /** Default time a caller waits for an answer before the promise rejects. */
12
+ export const DEFAULT_CALLBACK_TIMEOUT = 30_000;
@@ -0,0 +1,70 @@
1
+ /**
2
+ * FiveM exports without the bare `exports` identifier. A source file that mentions `exports` is treated as
3
+ * CommonJS by the bundler and wrapped in its own `(exports) =>` scope, which hides the FiveM function.
4
+ * Shared by "@aifivem/lib/client" and "@aifivem/lib/server".
5
+ */
6
+
7
+ // oxlint-disable-next-line typescript/no-explicit-any -- export handlers take whatever their contract declares
8
+ type ExportHandler = (...args: any[]) => unknown;
9
+
10
+ /** Names registered by name (not as the other-case twin): a twin never replaces one of them. */
11
+ const named = new Set<string>();
12
+
13
+ /**
14
+ * Registers an export under `name` and under its twin with the first letter's case swapped (`GetItems` and
15
+ * `getItems`), so scripts written for either style find it. A name registered explicitly always wins over a twin.
16
+ */
17
+ export function registerExport(name: string, handler: ExportHandler): void {
18
+ named.add(name);
19
+ globalThis.exports(name, handler);
20
+ const first = name.charAt(0);
21
+ const swapped =
22
+ first === first.toUpperCase() ? first.toLowerCase() : first.toUpperCase();
23
+ const twin = swapped + name.slice(1);
24
+ if (twin !== name && !named.has(twin)) globalThis.exports(twin, handler);
25
+ }
26
+
27
+ /** Typed access to another resource's exports (types come from CitizenExports in @aifivem/shared). */
28
+ export function resourceExport<K extends keyof CitizenExports & string>(
29
+ resource: K,
30
+ ): CitizenExports[K] {
31
+ return globalThis.exports[resource] as CitizenExports[K];
32
+ }
33
+
34
+ /** Whether a resource is running now. */
35
+ export function isResourceStarted(resource: string): boolean {
36
+ return GetResourceState(resource) === "started";
37
+ }
38
+
39
+ /** Another resource's exports while it runs, null when it does not (an optional dependency). */
40
+ export function optionalExport<K extends keyof CitizenExports & string>(
41
+ resource: K,
42
+ ): CitizenExports[K] | null {
43
+ return isResourceStarted(resource)
44
+ ? (globalThis.exports[resource] as CitizenExports[K])
45
+ : null;
46
+ }
47
+
48
+ /** Calls an export of a resource whose exports have no type here (a third-party script); parse the result. */
49
+ export function callExport(
50
+ resource: string,
51
+ name: string,
52
+ ...args: unknown[]
53
+ ): unknown {
54
+ const fn: unknown = Reflect.get(Object(globalThis.exports[resource]), name);
55
+ if (typeof fn !== "function")
56
+ throw new Error(`${resource} has no export ${name}`);
57
+ return Reflect.apply(fn, undefined, args);
58
+ }
59
+
60
+ /** Answers `exports["<resource>"].<name>` for a resource name this one `provide`s: provide makes the name exist but does not alias its exports, so each export of the stood-in resource is answered through FiveM's export event. */
61
+ export function provideExport(
62
+ resource: string,
63
+ name: string,
64
+ fn: ExportHandler,
65
+ ): void {
66
+ on(
67
+ `__cfx_export_${resource}_${name}`,
68
+ (setCallback: (fn: ExportHandler) => void) => setCallback(fn),
69
+ );
70
+ }
@@ -0,0 +1,13 @@
1
+ /** Helpers that call natives available on both sides; for `resource/common/` code. Import from "@aifivem/lib/fivem". */
2
+
3
+ export {
4
+ callExport,
5
+ isResourceStarted,
6
+ optionalExport,
7
+ provideExport,
8
+ registerExport,
9
+ resourceExport,
10
+ } from "./exports";
11
+ export { createLocale, loadLocaleTexts, LOCALE_CONVAR } from "./locale";
12
+ export { every, type EveryOptions, type Job } from "./scheduler/every";
13
+ export { ByResource, caller, onStop, plateOf, Reasons } from "./byResource";
@@ -0,0 +1,57 @@
1
+ import { formatText, isRecord } from "../shared";
2
+
3
+ /** Convar holding the language (`setr ai:locale "en"` in misc.cfg); replicated so clients read it too. */
4
+ export const LOCALE_CONVAR = "ai:locale";
5
+
6
+ function readLocaleFile(
7
+ resource: string,
8
+ lang: string,
9
+ ): Record<string, string> {
10
+ const raw = LoadResourceFile(resource, `locales/${lang}.json`);
11
+ if (!raw) return {};
12
+ const parsed: unknown = JSON.parse(raw);
13
+ if (!isRecord(parsed)) return {};
14
+ const texts: Record<string, string> = {};
15
+ for (const [key, value] of Object.entries(parsed))
16
+ if (typeof value === "string") texts[key] = value;
17
+ return texts;
18
+ }
19
+
20
+ /**
21
+ * The resource's lang texts: `locales/en.json` (complete base) overlaid with `locales/<ai:locale>.json`.
22
+ * `${OTHER_KEY}` inside a text is replaced by that text once at load. Returns `t(key, ...args)` filling
23
+ * `{0}`, `{1}`...; a missing key returns the key itself so it is visible in game.
24
+ *
25
+ * const t = createLocale<typeof import("../../locales/en.json")>();
26
+ * t("NOTIFY_NO_MONEY", price);
27
+ */
28
+ export function createLocale<T extends Record<string, string>>(): (
29
+ key: keyof T & string,
30
+ ...args: Array<string | number>
31
+ ) => string {
32
+ const texts = loadLocaleTexts();
33
+ return (key, ...args) => formatText(texts[key] ?? key, args);
34
+ }
35
+
36
+ /**
37
+ * The resource's merged lang table (`en.json` overlaid with the `ai:locale` language, `${KEY}` references
38
+ * resolved). A NUI gets this once and fills `{0}` placeholders itself.
39
+ */
40
+ export function loadLocaleTexts(
41
+ resource = GetCurrentResourceName(),
42
+ ): Record<string, string> {
43
+ const lang = GetConvar(LOCALE_CONVAR, "en");
44
+ const texts = {
45
+ ...readLocaleFile(resource, "en"),
46
+ ...(lang === "en" ? {} : readLocaleFile(resource, lang)),
47
+ };
48
+
49
+ for (const key of Object.keys(texts)) {
50
+ texts[key] = (texts[key] ?? "").replace(
51
+ /\$\{([A-Z0-9_]+)\}/g,
52
+ (match, ref: string) => texts[ref] ?? match,
53
+ );
54
+ }
55
+
56
+ return texts;
57
+ }
@@ -0,0 +1,13 @@
1
+ import type { AiPlayerData } from "@aifivem/shared";
2
+
3
+ /**
4
+ * ai-core's per-player channel: the server pushes `(key, value)` of `AiPlayerData` to the owner's client. One net
5
+ * event carries every key, and every resource on that client receives it, so client code subscribes per key
6
+ * instead of wiring its own `onNet` for each value.
7
+ */
8
+ export const PLAYER_DATA_EVENT = "ai-core:client:playerData";
9
+
10
+ /** Same channel for map values (money): only the changed entries travel and the client merges them. */
11
+ export const PLAYER_DATA_PATCH_EVENT = "ai-core:client:playerDataPatch";
12
+
13
+ export type PlayerDataKey = keyof AiPlayerData;