@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,190 @@
1
+ import type { CharacterInfo } from "@aifivem/shared";
2
+ import { isPublic, type AccessRule } from "../../shared/access";
3
+ import { OnlineMirror, type JobStateChange } from "./mirror";
4
+
5
+ export type { JobStateChange } from "./mirror";
6
+
7
+ /**
8
+ * This resource's mirror of ai-core's loaded players: characters, job and gang memberships (with grades), member sets
9
+ * per job and gang, and duty, read once from ai-core's exports on first use and then kept by its local events. Hot
10
+ * paths (every chat message, every alert, every stash open) read it instead of copying ai-core's player data through
11
+ * an export (10k players = 10k export calls per message).
12
+ */
13
+ class OnlinePlayers extends OnlineMirror {
14
+ /** Server ids of every player with a loaded character. */
15
+ sources(): IterableIterator<number> {
16
+ this.start();
17
+ return this.players.keys();
18
+ }
19
+
20
+ /** How many players have a loaded character. */
21
+ get size(): number {
22
+ this.start();
23
+ return this.players.size;
24
+ }
25
+
26
+ /** The loaded character of a player, or null. */
27
+ character(source: number): CharacterInfo | null {
28
+ this.start();
29
+ return this.players.get(source)?.character ?? null;
30
+ }
31
+
32
+ /** The server id of a loaded character by its citizenid, or null. */
33
+ sourceOf(citizenid: string): number | null {
34
+ this.start();
35
+ return this.byCitizenid.get(citizenid) ?? null;
36
+ }
37
+
38
+ /** Every loaded character by server id (a copy). */
39
+ characters(): Map<number, CharacterInfo> {
40
+ this.start();
41
+ const out = new Map<number, CharacterInfo>();
42
+ for (const [source, player] of this.players)
43
+ out.set(source, player.character);
44
+ return out;
45
+ }
46
+
47
+ /** The id of the player's loaded character, undefined when none. */
48
+ charId(source: number): number | undefined {
49
+ this.start();
50
+ return this.players.get(source)?.character.id;
51
+ }
52
+
53
+ /** The character's "Firstname Lastname", else the FiveM player name ("" with `fallback: false`). */
54
+ name(source: number, options: { fallback?: boolean } = {}): string {
55
+ const c = this.character(source);
56
+ if (c) return `${c.firstname} ${c.lastname}`;
57
+ return options.fallback === false ? "" : GetPlayerName(String(source));
58
+ }
59
+
60
+ /** Job names of a player (every membership, on duty or not). */
61
+ jobs(source: number): readonly string[] {
62
+ this.start();
63
+ return this.players.get(source)?.jobNames ?? [];
64
+ }
65
+
66
+ /** Gang names of a player. */
67
+ gangs(source: number): readonly string[] {
68
+ this.start();
69
+ return this.players.get(source)?.gangNames ?? [];
70
+ }
71
+
72
+ /** The player's grade in a job, or null when not a member. */
73
+ jobGrade(source: number, job: string): number | null {
74
+ this.start();
75
+ return (
76
+ this.players.get(source)?.jobs.find((m) => m.job === job)?.grade ?? null
77
+ );
78
+ }
79
+
80
+ /** The player's grade in a gang, or null when not a member. */
81
+ gangGrade(source: number, gang: string): number | null {
82
+ this.start();
83
+ return (
84
+ this.players.get(source)?.gangs.find((m) => m.gang === gang)?.grade ??
85
+ null
86
+ );
87
+ }
88
+
89
+ /** Players with a membership in the job, on duty or not (a live set: copy before awaiting). */
90
+ jobMembers(job: string): ReadonlySet<number> {
91
+ this.start();
92
+ return this.jobIndex.get(job) ?? EMPTY;
93
+ }
94
+
95
+ /** Players in the gang (a live set: copy before awaiting). */
96
+ gangMembers(gang: string): ReadonlySet<number> {
97
+ this.start();
98
+ return this.gangIndex.get(gang) ?? EMPTY;
99
+ }
100
+
101
+ /** The job a player is on duty for, or null. */
102
+ dutyJob(source: number): string | null {
103
+ this.start();
104
+ return this.players.get(source)?.duty ?? null;
105
+ }
106
+
107
+ /** Whether the player is on duty for one of `jobs` (police jobs, EMS jobs). */
108
+ onDutyIn(source: number, jobs: readonly string[]): boolean {
109
+ const duty = this.dutyJob(source);
110
+ return duty !== null && jobs.includes(duty);
111
+ }
112
+
113
+ /** Whether the player may use a place with this access rule (lib `AccessRule`; the client's `allows` decides the same). */
114
+ allows(source: number, rule: AccessRule): boolean {
115
+ if (isPublic(rule)) return true;
116
+ const min = (name: string) => rule.grades[name] ?? 0;
117
+ for (const gang of rule.gangs) {
118
+ const grade = this.gangGrade(source, gang);
119
+ if (grade !== null && grade >= min(gang)) return true;
120
+ }
121
+ const duty = rule.onDuty ? this.dutyJob(source) : null;
122
+ for (const job of rule.jobs) {
123
+ const grade = this.jobGrade(source, job);
124
+ if (grade !== null && grade >= min(job) && (!rule.onDuty || duty === job))
125
+ return true;
126
+ }
127
+ return false;
128
+ }
129
+
130
+ /** How many players are on duty over several jobs (O(jobs)). */
131
+ countOnDuty(jobs: readonly string[]): number {
132
+ this.start();
133
+ let count = 0;
134
+ for (const job of jobs) count += this.onDuty.get(job)?.size ?? 0;
135
+ return count;
136
+ }
137
+
138
+ /** How many players hold one of the jobs (a player in two of them counts once), or with `onlyOnDuty` are on duty in one. */
139
+ countMembers(jobs: readonly string[], onlyOnDuty = false): number {
140
+ if (onlyOnDuty) return this.countOnDuty(jobs);
141
+ this.start();
142
+ // a player in several of the jobs is counted at the first one (no set allocated)
143
+ let count = 0;
144
+ for (let i = 0; i < jobs.length; i++) {
145
+ const set = this.jobIndex.get(jobs[i]!);
146
+ if (!set) continue;
147
+ count += set.size;
148
+ if (i === 0) continue;
149
+ for (const source of set)
150
+ for (let k = 0; k < i; k++)
151
+ if (this.jobIndex.get(jobs[k]!)?.has(source)) {
152
+ count--;
153
+ break;
154
+ }
155
+ }
156
+ return count;
157
+ }
158
+
159
+ /** Server ids of the players holding one of the jobs (or with `onlyOnDuty` on duty in one), each once. */
160
+ membersOf(jobs: readonly string[], onlyOnDuty = false): number[] {
161
+ this.start();
162
+ const index = onlyOnDuty ? this.onDuty : this.jobIndex;
163
+ if (jobs.length === 1) return [...(index.get(jobs[0]!) ?? EMPTY)];
164
+ const seen = new Set<number>();
165
+ for (const job of jobs)
166
+ for (const source of index.get(job) ?? EMPTY) seen.add(source);
167
+ return [...seen];
168
+ }
169
+
170
+ /**
171
+ * Calls `listener` when a loaded player's jobs or duty change, once at each load (`previous` empty) and at each
172
+ * unload (`online` false); the players already loaded when it subscribes are not replayed (read `sources()`).
173
+ * Returns the unsubscribe.
174
+ */
175
+ onJobState(listener: (change: JobStateChange) => void): () => void {
176
+ this.start();
177
+ this.jobListeners.add(listener);
178
+ return () => this.jobListeners.delete(listener);
179
+ }
180
+
181
+ /** Players on duty for a job (a live set: copy before awaiting). */
182
+ onDutyFor(job: string): ReadonlySet<number> {
183
+ this.start();
184
+ return this.onDuty.get(job) ?? EMPTY;
185
+ }
186
+ }
187
+
188
+ const EMPTY: ReadonlySet<number> = new Set();
189
+
190
+ export const online = new OnlinePlayers();
@@ -0,0 +1,70 @@
1
+ import { CORE } from "@aifivem/shared";
2
+ import { PlayerMap } from "./players";
3
+
4
+ interface Pending<T> {
5
+ token: number;
6
+ data: T;
7
+ startedAt: number;
8
+ durationMs: number;
9
+ }
10
+
11
+ /**
12
+ * Actions waiting for a player's client (progress bar, dialog), one per player: `start` hands out a token the client
13
+ * sends back, `take` ends the action when the token matches and enough of the time passed. Freed when the player
14
+ * drops or lets the character go (a switch never pays an action of the old character to the new one). Create once at
15
+ * module level.
16
+ */
17
+ export class PendingActions<T> {
18
+ private readonly actions = new PlayerMap<Pending<T>>();
19
+ private readonly minRatio: number;
20
+ private next = 0;
21
+
22
+ /** `take` refuses an answer that comes before `minRatio` (default 0.8) of the action's duration. */
23
+ constructor(options: { minRatio?: number } = {}) {
24
+ this.minRatio = options.minRatio ?? 0.8;
25
+ on(CORE.playerUnloadedEvent, (source: number) =>
26
+ this.actions.delete(source),
27
+ );
28
+ }
29
+
30
+ /** Starts the player's action (replacing a running one) and answers its token (1 to 2^31-1, `readId` parses it). */
31
+ start(source: number, data: T, durationMs: number): number {
32
+ this.next = this.next >= 2_147_483_647 ? 1 : this.next + 1;
33
+ this.actions.set(source, {
34
+ token: this.next,
35
+ data,
36
+ startedAt: GetGameTimer(),
37
+ durationMs,
38
+ });
39
+ return this.next;
40
+ }
41
+
42
+ /**
43
+ * The action's data when `token` is the running one and enough time passed; null otherwise. A wrong token leaves the
44
+ * running action alone (a stale or forged token never cancels it); a matching one ends it, too fast or not.
45
+ */
46
+ take(source: number, token: number): T | null {
47
+ const action = this.actions.get(source);
48
+ if (!action || action.token !== token) return null;
49
+ this.actions.delete(source);
50
+ return GetGameTimer() - action.startedAt >=
51
+ action.durationMs * this.minRatio
52
+ ? action.data
53
+ : null;
54
+ }
55
+
56
+ /** The running action's data without ending it, or null. */
57
+ peek(source: number): T | null {
58
+ return this.actions.get(source)?.data ?? null;
59
+ }
60
+
61
+ /** Ends the player's action without a result. */
62
+ cancel(source: number): void {
63
+ this.actions.delete(source);
64
+ }
65
+
66
+ /** How many actions run now. */
67
+ get size(): number {
68
+ return this.actions.size;
69
+ }
70
+ }
@@ -0,0 +1,22 @@
1
+ import {
2
+ CORE,
3
+ type PhoneMail,
4
+ type PhoneNotification,
5
+ } from "@aifivem/shared";
6
+ import { resourceExport } from "../fivem/exports";
7
+
8
+ const core = resourceExport(CORE.resource);
9
+
10
+ /** Phones through ai-core (tgiann-phone, lb-phone...): numbers, mails, texts, notifications; null / false without one. */
11
+ export const phone = {
12
+ number: (source: number): string | null => core.GetPhoneNumber(source),
13
+ sourceOf: (number: string): number | null => core.GetSourceByPhone(number),
14
+ hasPhone: (source: number): boolean => core.HasPhone(source),
15
+ /** `to`: a player's server id or a phone number. */
16
+ mail: (to: number | string, mail: PhoneMail): boolean =>
17
+ core.SendPhoneMail(to, mail),
18
+ message: (from: string, to: number | string, text: string): boolean =>
19
+ core.SendPhoneMessage(from, to, text),
20
+ notify: (source: number, notification: PhoneNotification): boolean =>
21
+ core.PhoneNotify(source, notification),
22
+ };
@@ -0,0 +1,197 @@
1
+ import { CORE, type CharacterInfo } from "@aifivem/shared";
2
+ import { createLogger } from "../shared";
3
+ import { online } from "./online/online";
4
+
5
+ const log = createLogger(GetCurrentResourceName());
6
+
7
+ /** Every per-player store of this resource; one playerDropped listener frees them all (one listener each trips Node's limit). */
8
+ const dropped = new Set<(source: number) => void>();
9
+ let listening = false;
10
+
11
+ function onDropped(fn: (source: number) => void): void {
12
+ if (!listening) {
13
+ listening = true;
14
+ on("playerDropped", () => {
15
+ const source = Number(globalThis.source);
16
+ for (const handler of dropped) handler(source);
17
+ });
18
+ }
19
+ dropped.add(fn);
20
+ }
21
+
22
+ /**
23
+ * A Map keyed by player source that empties itself when the player drops (one shared playerDropped listener).
24
+ * Create it once at module level: every instance stays registered for the resource's life.
25
+ */
26
+ export class PlayerMap<V> extends Map<number, V> {
27
+ constructor(options: { onDrop?: (source: number, value: V) => void } = {}) {
28
+ super();
29
+ onDropped((source) => {
30
+ if (!this.has(source)) return;
31
+ const value = this.get(source) as V;
32
+ this.delete(source);
33
+ options.onDrop?.(source, value);
34
+ });
35
+ }
36
+ }
37
+
38
+ /** Per-player cooldowns on the game clock, freed when the player drops. Create once at module level. */
39
+ export class Cooldowns {
40
+ private readonly until = new PlayerMap<number>();
41
+
42
+ /** No cooldown runs for the player. */
43
+ ready(source: number): boolean {
44
+ return this.left(source) === 0;
45
+ }
46
+
47
+ /** Starts (or restarts) the player's cooldown for `ms`. */
48
+ start(source: number, ms: number): void {
49
+ this.until.set(source, GetGameTimer() + ms);
50
+ }
51
+
52
+ /** Starts the cooldown when it is ready and answers true; false while one still runs. */
53
+ take(source: number, ms: number): boolean {
54
+ if (!this.ready(source)) return false;
55
+ this.start(source, ms);
56
+ return true;
57
+ }
58
+
59
+ /** Milliseconds left, 0 when ready. */
60
+ left(source: number): number {
61
+ const until = this.until.get(source);
62
+ if (until === undefined) return 0;
63
+ const left = until - GetGameTimer();
64
+ if (left > 0) return left;
65
+ this.until.delete(source);
66
+ return 0;
67
+ }
68
+
69
+ /** Ends the player's cooldown. */
70
+ clear(source: number): void {
71
+ this.until.delete(source);
72
+ }
73
+ }
74
+
75
+ /**
76
+ * Cooldowns by a key that outlives the connection, on the game clock: a character id (a reconnect keeps the
77
+ * cooldown) or an entity. Expired entries are swept when the map has doubled since the last sweep (amortized O(1)
78
+ * per `start`). Create once at module level.
79
+ */
80
+ export class KeyedCooldowns<K = number> {
81
+ private readonly until = new Map<K, number>();
82
+ private sweepAt = 64;
83
+
84
+ /** No cooldown runs for the key. */
85
+ ready(key: K): boolean {
86
+ return this.left(key) === 0;
87
+ }
88
+
89
+ /** Starts (or restarts) the key's cooldown for `ms`; 0 or less ends it. */
90
+ start(key: K, ms: number): void {
91
+ if (ms <= 0) {
92
+ this.until.delete(key);
93
+ return;
94
+ }
95
+ if (this.until.size >= this.sweepAt) this.sweep();
96
+ this.until.set(key, GetGameTimer() + ms);
97
+ }
98
+
99
+ /** Starts the cooldown when it is ready and answers true; false while one still runs. */
100
+ take(key: K, ms: number): boolean {
101
+ if (!this.ready(key)) return false;
102
+ this.start(key, ms);
103
+ return true;
104
+ }
105
+
106
+ /** Milliseconds left, 0 when ready. */
107
+ left(key: K): number {
108
+ const until = this.until.get(key);
109
+ if (until === undefined) return 0;
110
+ const left = until - GetGameTimer();
111
+ if (left > 0) return left;
112
+ this.until.delete(key);
113
+ return 0;
114
+ }
115
+
116
+ /** Ends the key's cooldown. */
117
+ clear(key: K): void {
118
+ this.until.delete(key);
119
+ }
120
+
121
+ private sweep(): void {
122
+ const now = GetGameTimer();
123
+ for (const [key, until] of this.until)
124
+ if (until <= now) this.until.delete(key);
125
+ this.sweepAt = Math.max(64, this.until.size * 2);
126
+ }
127
+ }
128
+
129
+ export interface CharacterHandlers {
130
+ /** A character entered the world; also once at start for every character loaded before this resource (re)started. */
131
+ loaded?: (source: number, character: CharacterInfo) => void | Promise<void>;
132
+ /** The character left: logout or character switch (`"switch"`) or a drop (`"dropped"`); each `loaded` gets exactly one. */
133
+ unloaded?: (
134
+ source: number,
135
+ charId: number,
136
+ reason: "dropped" | "switch",
137
+ ) => void;
138
+ }
139
+
140
+ /**
141
+ * A loaded character's lifecycle from ai-core's events. `loaded` replays the characters already in the world after
142
+ * a restart (from lib `online`, on the next tick so the caller's module has finished loading); no extra
143
+ * playerDropped handler is needed next to it.
144
+ */
145
+ export function onCharacter(handlers: CharacterHandlers): void {
146
+ // source -> charId of each `loaded` delivered, so every one gets its `unloaded` and the replay skips repeats.
147
+ const live = new Map<number, number>();
148
+ const deliver = (source: number, character: CharacterInfo): void => {
149
+ live.set(source, character.id);
150
+ if (!handlers.loaded) return;
151
+ try {
152
+ const result = handlers.loaded(source, character);
153
+ if (result instanceof Promise)
154
+ result.catch((error: unknown) =>
155
+ log.error(`character loaded handler failed for ${source}`, error),
156
+ );
157
+ } catch (error) {
158
+ log.error(`character loaded handler failed for ${source}`, error);
159
+ }
160
+ };
161
+ const end = (
162
+ source: number,
163
+ charId: number,
164
+ reason: "dropped" | "switch",
165
+ ): void => {
166
+ if (!live.delete(source)) return;
167
+ try {
168
+ handlers.unloaded?.(source, charId, reason);
169
+ } catch (error) {
170
+ log.error(`character unloaded handler failed for ${source}`, error);
171
+ }
172
+ };
173
+ on(CORE.playerLoadedEvent, (source: number, character: CharacterInfo) => {
174
+ const previous = live.get(source);
175
+ if (previous !== undefined) end(source, previous, "switch");
176
+ deliver(source, character);
177
+ });
178
+ on(
179
+ CORE.playerUnloadedEvent,
180
+ (source: number, charId: number, reason: unknown) =>
181
+ end(source, charId, reason === "dropped" ? "dropped" : "switch"),
182
+ );
183
+ // ai-core unloads on drop itself; this only catches a drop whose unload never came (ai-core stopping).
184
+ onDropped((source) =>
185
+ setImmediate(() => {
186
+ const charId = live.get(source);
187
+ if (charId !== undefined) end(source, charId, "dropped");
188
+ }),
189
+ );
190
+ setImmediate(() => {
191
+ for (const source of online.sources()) {
192
+ if (live.has(source)) continue;
193
+ const character = online.character(source);
194
+ if (character) deliver(source, character);
195
+ }
196
+ });
197
+ }
@@ -0,0 +1,31 @@
1
+ import type { Vec3 } from "../shared/vec";
2
+
3
+ /** An entity's position (server copy of the owner's sync). */
4
+ export function entityCoords(entity: number): Vec3 {
5
+ const [x = 0, y = 0, z = 0] = GetEntityCoords(entity);
6
+ return { x, y, z };
7
+ }
8
+
9
+ /** A player's ped position. */
10
+ export const coordsOf = (source: number): Vec3 =>
11
+ entityCoords(GetPlayerPed(String(source)));
12
+
13
+ /** The vehicle the player sits in (with `driver: true` only when in its driver seat), 0 on foot. */
14
+ export function vehicleOf(
15
+ source: number,
16
+ options: { driver?: boolean } = {},
17
+ ): number {
18
+ const ped = GetPlayerPed(String(source));
19
+ const vehicle = GetVehiclePedIsIn(ped, false);
20
+ if (!vehicle || !options.driver) return vehicle;
21
+ return GetPedInVehicleSeat(vehicle, -1) === ped ? vehicle : 0;
22
+ }
23
+
24
+ /** The player's ped is within `metres` of a point. */
25
+ export function isNear(source: number, point: Vec3, metres: number): boolean {
26
+ const [x = 0, y = 0, z = 0] = GetEntityCoords(GetPlayerPed(String(source)));
27
+ const dx = x - point.x;
28
+ const dy = y - point.y;
29
+ const dz = z - point.z;
30
+ return dx * dx + dy * dy + dz * dz <= metres * metres;
31
+ }
@@ -0,0 +1,7 @@
1
+ import { CORE } from "@aifivem/shared";
2
+ import { resourceExport } from "../fivem/exports";
3
+
4
+ const core = resourceExport(CORE.resource);
5
+
6
+ /** Whether it is prime time for `job` (the default hours without one), from ai-core's prime time setting (tgiann-policealert's hours while it runs, else ai-core's panel hours). */
7
+ export const isPrimeTime = (job?: string): boolean => core.IsPrimeTime(job);
@@ -0,0 +1,15 @@
1
+ import { CORE } from "@aifivem/shared";
2
+ import { resourceExport } from "../fivem/exports";
3
+
4
+ const core = resourceExport(CORE.resource);
5
+
6
+ /** Jail sentences through ai-core, whatever prison script runs (`docs/compat/prison.md`). */
7
+ export const prison = {
8
+ /** Sends a loaded player to prison for `minutes` (`by`: who sent them, for the log); false while no prison runs. */
9
+ jail: (source: number, minutes: number, by = 0): boolean =>
10
+ core.JailPlayer(source, minutes, by),
11
+ /** Lets a jailed player out; false when not jailed or no prison runs. */
12
+ release: (source: number): boolean => core.ReleasePlayer(source),
13
+ /** Minutes of sentence left, 0 when free. */
14
+ timeLeft: (source: number): number => core.GetJailTime(source),
15
+ };
@@ -0,0 +1,62 @@
1
+ import { CORE, LIB_UI, type ServerProgress } from "@aifivem/shared";
2
+ import { triggerClientCallback } from "./callback";
3
+ import { PlayerMap } from "./players";
4
+
5
+ export interface ProgressForOptions extends ServerProgress {
6
+ /** The answer counts only after this share of `duration` passed on the server (default 0.8). */
7
+ minRatio?: number;
8
+ }
9
+
10
+ /** Slack on top of the duration for turning, loading the animation and the round trip. */
11
+ const TIMEOUT_SLACK_MS = 15_000;
12
+
13
+ /** The running server progress of each player: settling it with false ends the waiting flow. */
14
+ const running = new PlayerMap<(ok: boolean) => void>({
15
+ onDrop: (_source, settle) => settle(false),
16
+ });
17
+ on(CORE.playerUnloadedEvent, (source: number) => {
18
+ const settle = running.get(source);
19
+ if (settle) settle(false);
20
+ });
21
+
22
+ /**
23
+ * Runs ai-lib's progress bar (animation or scenario, `face`, blocked controls) on the player's client and resolves
24
+ * true only when it ran out there and at least `minRatio` of `duration` passed on the server; false on cancel, drop,
25
+ * character switch, timeout or a too-early answer. One per player: a second call ends the first with false. Check the
26
+ * flow's conditions again after it resolves (the player may have walked away). The label is a translated text.
27
+ */
28
+ export function progressFor(
29
+ source: number,
30
+ options: ProgressForOptions,
31
+ ): Promise<boolean> {
32
+ const previous = running.get(source);
33
+ if (previous) {
34
+ previous(false);
35
+ emitNet(LIB_UI.progressForCancelEvent, source);
36
+ }
37
+ const { minRatio = 0.8, ...bar } = options;
38
+ const startedAt = GetGameTimer();
39
+ return new Promise((resolve) => {
40
+ let done = false;
41
+ const settle = (ok: boolean) => {
42
+ if (done) return;
43
+ done = true;
44
+ if (running.get(source) === settle) running.delete(source);
45
+ resolve(ok);
46
+ };
47
+ running.set(source, settle);
48
+ triggerClientCallback(
49
+ LIB_UI.progressForCallback,
50
+ source,
51
+ [bar],
52
+ bar.duration + TIMEOUT_SLACK_MS,
53
+ ).then(
54
+ (answer) =>
55
+ settle(
56
+ answer === true &&
57
+ GetGameTimer() - startedAt >= bar.duration * minRatio,
58
+ ),
59
+ () => settle(false),
60
+ );
61
+ });
62
+ }