@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,54 @@
1
+ import type { Vec3 } from "../shared/vec";
2
+ import { cache } from "./cache";
3
+
4
+ export interface LocationName {
5
+ street: string;
6
+ /** The crossing street, when there is one. */
7
+ crossing?: string;
8
+ /** The area's label (`Vinewood Hills`), "" where the game has none. */
9
+ zone: string;
10
+ }
11
+
12
+ /** The street, crossing and zone names at a point (default the local ped). */
13
+ export function locationName(coords?: Vec3): LocationName {
14
+ const at = coords ?? coordsOfPed();
15
+ const [streetHash, crossingHash] = GetStreetNameAtCoord(at.x, at.y, at.z);
16
+ const crossing =
17
+ crossingHash !== 0 ? GetStreetNameFromHashKey(crossingHash) : "";
18
+ const zone = GetLabelText(GetNameOfZone(at.x, at.y, at.z));
19
+ return {
20
+ street: streetHash !== 0 ? GetStreetNameFromHashKey(streetHash) : "",
21
+ crossing: crossing || undefined,
22
+ zone: zone !== "NULL" ? zone : "",
23
+ };
24
+ }
25
+
26
+ function coordsOfPed(): Vec3 {
27
+ const [x = 0, y = 0, z = 0] = GetEntityCoords(cache.ped, false);
28
+ return { x, y, z };
29
+ }
30
+
31
+ /**
32
+ * A vehicle's display name (`Sultan RS`) from a model name, hash or vehicle entity; the model name when the game has
33
+ * no label for it (add-on models without a text entry).
34
+ */
35
+ export function vehicleLabel(vehicle: string | number): string {
36
+ const model =
37
+ typeof vehicle === "number" &&
38
+ DoesEntityExist(vehicle) &&
39
+ IsEntityAVehicle(vehicle)
40
+ ? GetEntityModel(vehicle)
41
+ : vehicle;
42
+ const hash = typeof model === "number" ? model : GetHashKey(model);
43
+ const name = GetDisplayNameFromVehicleModel(hash);
44
+ const label = GetLabelText(name);
45
+ if (label !== "NULL" && label !== "") return label;
46
+ if (name !== "" && name !== "CARNOTFOUND") return name;
47
+ return typeof model === "string" ? model : String(hash);
48
+ }
49
+
50
+ /** The ground height under x / y, probing down from `z` (default 1000): null while the collision there is not loaded. */
51
+ export function groundZ(x: number, y: number, z = 1000): number | null {
52
+ const [found, ground] = GetGroundZFor_3dCoord(x, y, z, false);
53
+ return found ? ground : null;
54
+ }
@@ -0,0 +1,10 @@
1
+ import { CORE } from "@aifivem/shared";
2
+ import { resourceExport } from "../fivem/exports";
3
+
4
+ const core = resourceExport(CORE.resource);
5
+
6
+ /** The police MDT through ai-core's client MDT layer. */
7
+ export const mdt = {
8
+ /** Opens the active MDT for the local player (the MDT checks the job); false when none runs or it cannot be opened from outside. */
9
+ open: (): boolean => core.OpenMdt(),
10
+ };
@@ -0,0 +1,28 @@
1
+ import { CORE } from "@aifivem/shared";
2
+ import { optionalExport } from "../fivem/exports";
3
+ import { cache } from "./cache";
4
+
5
+ /** ai-core's answer, kept from its local event; null until first asked or after ai-core stops. */
6
+ let down: boolean | null = null;
7
+ on(CORE.clientDeadEvent, (value: unknown) => {
8
+ down = value === true;
9
+ });
10
+ on("onClientResourceStop", (resource: string) => {
11
+ if (resource === "ai-core") down = null;
12
+ });
13
+
14
+ /**
15
+ * The local player's down state through ai-core's medical layer, whatever death script runs (`docs/compat/medical.md`):
16
+ * death scripts keep a downed ped alive to animate it, so `IsEntityDead` alone misses them. A memory read after the
17
+ * first call.
18
+ */
19
+ export const medical = {
20
+ isDead(): boolean {
21
+ down ??= optionalExport("ai-core")?.IsDead() ?? null;
22
+ return down === true || IsEntityDead(cache.ped);
23
+ },
24
+ /** `fn(dead)` when the local player goes down or gets up. */
25
+ onChange(fn: (dead: boolean) => void): void {
26
+ on(CORE.clientDeadEvent, (value: unknown) => fn(value === true));
27
+ },
28
+ };
@@ -0,0 +1,41 @@
1
+ import { decideAccess, type AccessRule } from "../shared/access";
2
+ import type { GangMembership, JobMembership } from "@aifivem/shared";
3
+ import { getPlayerData, onPlayerData } from "./playerData";
4
+
5
+ /** Whether the player holds one of `jobs` at `minGrade` or above (on duty or not). Empty list: everyone. */
6
+ export function hasJob(jobs: readonly string[], minGrade = 0): boolean {
7
+ if (jobs.length === 0) return true;
8
+ const list: readonly JobMembership[] = getPlayerData("jobs") ?? [];
9
+ return list.some((m) => jobs.includes(m.job) && m.grade >= minGrade);
10
+ }
11
+
12
+ /** Whether the player is in one of `gangs` at `minGrade` or above. Empty list: everyone. */
13
+ export function inGang(gangs: readonly string[], minGrade = 0): boolean {
14
+ if (gangs.length === 0) return true;
15
+ const list: readonly GangMembership[] = getPlayerData("gangs") ?? [];
16
+ return list.some((m) => gangs.includes(m.gang) && m.grade >= minGrade);
17
+ }
18
+
19
+ /** Whether the player is on duty in one of `jobs`. */
20
+ export function onDutyIn(jobs: readonly string[]): boolean {
21
+ const duty = getPlayerData("duty");
22
+ return typeof duty === "string" && jobs.includes(duty);
23
+ }
24
+
25
+ /** Calls `fn` when the player's jobs, duty or gangs change (refresh points whose `canShow` reads them). */
26
+ export function onMembershipChange(fn: () => void): void {
27
+ onPlayerData("jobs", fn);
28
+ onPlayerData("duty", fn);
29
+ onPlayerData("gangs", fn);
30
+ }
31
+
32
+ /** Whether the local player may use a place with this access rule (the server's `online.allows` decides the same). */
33
+ export function allows(rule: AccessRule): boolean {
34
+ const duty = getPlayerData("duty");
35
+ return decideAccess(
36
+ rule,
37
+ getPlayerData("jobs") ?? [],
38
+ getPlayerData("gangs") ?? [],
39
+ typeof duty === "string" ? duty : null,
40
+ );
41
+ }
@@ -0,0 +1,77 @@
1
+ import type {
2
+ InputRequest,
3
+ ItemPickerRequest,
4
+ MenuRequest,
5
+ PickedItem,
6
+ } from "@aifivem/shared";
7
+ import { core, requests, ui, type MenuListeners } from "./requests";
8
+
9
+ /**
10
+ * Shows ai-lib's menu and resolves with the picked item id, or null when the player closed it. The second argument is
11
+ * `onHover` (the item under the pointer or focus, for live previews) or `{ onHover, onToggle }`: items with `checked`
12
+ * are switch rows that flip in place without closing the menu. Arrows move, Enter picks; in a sub menu (`back: true`)
13
+ * a short Escape resolves `MENU_BACK` and holding Escape closes (null).
14
+ */
15
+ export function menu(
16
+ request: MenuRequest,
17
+ listeners?: ((item: string) => void) | MenuListeners,
18
+ ): Promise<string | null> {
19
+ return new Promise((resolve) =>
20
+ requests.ask(
21
+ (id) => ui.OpenMenu(id, request),
22
+ (value) => resolve(typeof value === "string" ? value : null),
23
+ typeof listeners === "function" ? { onHover: listeners } : listeners,
24
+ ),
25
+ );
26
+ }
27
+
28
+ /** Shows ai-lib's input dialog and resolves with the entered values by field name, or null when closed. */
29
+ export function input(
30
+ request: InputRequest,
31
+ ): Promise<Record<string, string | number> | null> {
32
+ return new Promise((resolve) =>
33
+ requests.ask(
34
+ (id) => ui.OpenInput(id, request),
35
+ (value) => {
36
+ if (typeof value !== "object" || value === null) return resolve(null);
37
+ const out: Record<string, string | number> = {};
38
+ for (const [k, v] of Object.entries(value))
39
+ if (typeof v === "string" || typeof v === "number") out[k] = v;
40
+ resolve(out);
41
+ },
42
+ ),
43
+ );
44
+ }
45
+
46
+ /**
47
+ * Shows ai-core's item picker (admin tools; the item list is only sent to admins): every item of the active inventory
48
+ * with its picture and a search; clicks fill a list on the right (1, Ctrl 10, Shift 100) that stops at `target`'s
49
+ * weight limit. Resolves with the list when the player takes it, null when closed. The caller's server gives the
50
+ * items and checks every one.
51
+ */
52
+ export function itemPicker(
53
+ request: ItemPickerRequest,
54
+ ): Promise<PickedItem[] | null> {
55
+ return new Promise((resolve) =>
56
+ requests.ask(
57
+ (id) => core.OpenItemPicker(id, request),
58
+ (value) => {
59
+ if (!Array.isArray(value)) return resolve(null);
60
+ resolve(
61
+ value.flatMap((v: unknown) =>
62
+ typeof v === "object" &&
63
+ v !== null &&
64
+ "name" in v &&
65
+ "count" in v &&
66
+ typeof v.name === "string" &&
67
+ typeof v.count === "number" &&
68
+ Number.isInteger(v.count) &&
69
+ v.count > 0
70
+ ? [{ name: v.name, count: v.count }]
71
+ : [],
72
+ ),
73
+ );
74
+ },
75
+ ),
76
+ );
77
+ }
@@ -0,0 +1,79 @@
1
+ import {
2
+ LOCKPICK_AREAS,
3
+ SKILL_STAGES,
4
+ type LockpickResult,
5
+ type SkillDifficulty,
6
+ type SkillStage,
7
+ } from "@aifivem/shared";
8
+ import { requests, ui } from "./requests";
9
+
10
+ const stageOf = (d: SkillDifficulty): SkillStage =>
11
+ typeof d === "string"
12
+ ? (SKILL_STAGES[d] ?? SKILL_STAGES.easy)
13
+ : {
14
+ area: Math.min(180, Math.max(5, d.areaSize)),
15
+ speed:
16
+ SKILL_STAGES.easy.speed *
17
+ Math.min(5, Math.max(0.2, d.speedMultiplier)),
18
+ };
19
+
20
+ /**
21
+ * ai-lib's skill check: a needle runs around a ring once per stage, the player presses the shown key while it is
22
+ * on the green arc. Resolves true when every stage was hit, false on a miss, a wrong key or Escape. Stages are
23
+ * `"easy" | "medium" | "hard"` or ox_lib's `{ areaSize, speedMultiplier }`; each stage shows one of `keys` (default E).
24
+ * A result decides a client-side step only: the server keeps checking what it allows.
25
+ */
26
+ export function skillCheck(
27
+ difficulty: SkillDifficulty | SkillDifficulty[],
28
+ keys: string[] = ["e"],
29
+ ): Promise<boolean> {
30
+ const stages = (Array.isArray(difficulty) ? difficulty : [difficulty])
31
+ .slice(0, 20)
32
+ .map(stageOf);
33
+ const keyList = keys
34
+ .filter((k) => typeof k === "string" && /^[a-z0-9]$/i.test(k))
35
+ .map((k) => k.toLowerCase());
36
+ return new Promise((resolve) =>
37
+ requests.ask(
38
+ (id) =>
39
+ ui.OpenMinigame(id, {
40
+ kind: "skillCheck",
41
+ stages,
42
+ keys: keyList.length ? keyList : ["e"],
43
+ }),
44
+ (value) => resolve(value === true),
45
+ ),
46
+ );
47
+ }
48
+
49
+ export interface LockpickOptions {
50
+ /** Width of each pin's sweet spot (default "medium"). */
51
+ difficulty?: "easy" | "medium" | "hard";
52
+ /** Pins to turn one after another (default 1). */
53
+ pins?: number;
54
+ /** Picks the player may break before it fails as "broken" (default 1). */
55
+ picks?: number;
56
+ }
57
+
58
+ /**
59
+ * ai-lib's lockpick: the player moves the pick with A / D (or the arrows), holds W to turn the lock; the lock turns
60
+ * further the closer the pick is to the hidden sweet spot, forcing it wears the pick down. Resolves "opened" when
61
+ * every pin turned, "broken" when the last pick broke (take the item), "cancelled" on Escape.
62
+ */
63
+ export function lockpick(
64
+ options: LockpickOptions = {},
65
+ ): Promise<LockpickResult> {
66
+ return new Promise((resolve) =>
67
+ requests.ask(
68
+ (id) =>
69
+ ui.OpenMinigame(id, {
70
+ kind: "lockpick",
71
+ pins: Math.min(6, Math.max(1, Math.floor(options.pins ?? 1))),
72
+ area: LOCKPICK_AREAS[options.difficulty ?? "medium"],
73
+ picks: Math.min(10, Math.max(1, Math.floor(options.picks ?? 1))),
74
+ }),
75
+ (value) =>
76
+ resolve(value === "opened" || value === "broken" ? value : "cancelled"),
77
+ ),
78
+ );
79
+ }
@@ -0,0 +1,65 @@
1
+ import { CORE, LIB_UI, MENU_EVENTS } from "@aifivem/shared";
2
+ import { resourceExport } from "../../fivem/exports";
3
+
4
+ export const ui = resourceExport(LIB_UI.resource);
5
+ /** The item picker is an admin tool of ai-core (it needs ai-core's inventory layer). */
6
+ export const core = resourceExport(CORE.resource);
7
+
8
+ export interface MenuListeners {
9
+ /** The item under the pointer or focus (live previews). */
10
+ onHover?: (item: string) => void;
11
+ /** A switch row (`checked` item) was flipped; the menu stays open. */
12
+ onToggle?: (item: string, checked: boolean) => void;
13
+ }
14
+
15
+ /** Menus, input dialogs and minigames this resource asked ai-lib (the item picker: ai-core) for, waiting for the player's answer. */
16
+ class Requests {
17
+ private readonly resource = GetCurrentResourceName();
18
+ private readonly waiting = new Map<number, (value: unknown) => void>();
19
+ private readonly hovers = new Map<number, MenuListeners>();
20
+ private nextId = 0;
21
+
22
+ constructor() {
23
+ const answer = (owner: unknown, id: unknown, value: unknown) => {
24
+ if (owner !== this.resource || typeof id !== "number") return;
25
+ this.waiting.get(id)?.(value);
26
+ this.waiting.delete(id);
27
+ this.hovers.delete(id);
28
+ };
29
+ on(MENU_EVENTS.menuHover, (owner: unknown, id: unknown, item: unknown) => {
30
+ if (
31
+ owner === this.resource &&
32
+ typeof id === "number" &&
33
+ typeof item === "string"
34
+ )
35
+ this.hovers.get(id)?.onHover?.(item);
36
+ });
37
+ on(
38
+ MENU_EVENTS.menuToggle,
39
+ (owner: unknown, id: unknown, item: unknown, checked: unknown) => {
40
+ if (
41
+ owner === this.resource &&
42
+ typeof id === "number" &&
43
+ typeof item === "string" &&
44
+ typeof checked === "boolean"
45
+ )
46
+ this.hovers.get(id)?.onToggle?.(item, checked);
47
+ },
48
+ );
49
+ on(MENU_EVENTS.menuResult, answer);
50
+ on(MENU_EVENTS.inputResult, answer);
51
+ }
52
+
53
+ ask(
54
+ open: (id: number) => void,
55
+ read: (value: unknown) => void,
56
+ listeners?: MenuListeners,
57
+ ): void {
58
+ const id = ++this.nextId;
59
+ this.waiting.set(id, read);
60
+ if (listeners) this.hovers.set(id, listeners);
61
+ open(id);
62
+ }
63
+ }
64
+
65
+ export const requests = new Requests();
@@ -0,0 +1,29 @@
1
+ import { isRecord } from "../../shared";
2
+ import { readFinite } from "../../shared/strict";
3
+ import { CELL, MOVE_MARGIN } from "./objectIndex";
4
+
5
+ /** What the scan needs of a model point (its label, `canShow` and action stay with the owner). */
6
+ export interface ModelScanDef {
7
+ /** Model hashes; none with `vehicles` = every networked vehicle. */
8
+ models: number[];
9
+ /** The models are vehicles: the vehicle pool is walked instead of objects. */
10
+ vehicles: boolean;
11
+ radius: number;
12
+ /** Object points are skipped while the player sits in a vehicle unless this is true. */
13
+ inVehicle: boolean;
14
+ }
15
+
16
+ /** A definition from another resource (ai-lib's export); null when malformed. */
17
+ export function readModelScanDef(value: unknown): ModelScanDef | null {
18
+ if (!isRecord(value) || !Array.isArray(value.models)) return null;
19
+ const models = value.models.filter((m): m is number => Number.isInteger(m));
20
+ const radius = readFinite(value.radius);
21
+ if (radius === null || radius <= 0 || radius > CELL - MOVE_MARGIN)
22
+ return null;
23
+ return {
24
+ models,
25
+ vehicles: value.vehicles === true,
26
+ radius,
27
+ inVehicle: value.inVehicle === true,
28
+ };
29
+ }
@@ -0,0 +1,41 @@
1
+ import { cellKey } from "../../shared";
2
+
3
+ /** Pool entries the object index reads per scan, so a big pool is spread over several scans. */
4
+ const INDEX_CHUNK = 300;
5
+ /** Indexed objects are filtered by where they stood when found; this margin covers ones moved since. */
6
+ export const MOVE_MARGIN = 2;
7
+ /** Grid cell of the object index, in metres: at least the largest radius plus the margin, so 3 x 3 cells cover it. */
8
+ export const CELL = 64;
9
+
10
+ /**
11
+ * The objects whose model a many-model point wants (364 chair models, say): one closest-object query per model and
12
+ * scan costs milliseconds, so the object pool is walked instead, a chunk per scan, and only matching objects are kept
13
+ * with the place they stood.
14
+ */
15
+ export class ObjectIndex {
16
+ /** Matching objects found by the last complete walk, by grid cell: entity, then x, y, z. */
17
+ cells = new Map<number, number[]>();
18
+ private pool: number[] = [];
19
+ private next = 0;
20
+ private found = new Map<number, number[]>();
21
+
22
+ advance(wanted: Set<number>): void {
23
+ if (this.next >= this.pool.length) {
24
+ this.cells = this.found;
25
+ this.found = new Map();
26
+ this.pool = GetGamePool("CObject") as number[];
27
+ this.next = 0;
28
+ }
29
+ const end = Math.min(this.pool.length, this.next + INDEX_CHUNK);
30
+ for (let i = this.next; i < end; i++) {
31
+ const entity = this.pool[i] ?? 0;
32
+ if (!entity || !wanted.has(GetEntityModel(entity))) continue;
33
+ const [x = 0, y = 0, z = 0] = GetEntityCoords(entity, false);
34
+ const key = cellKey(Math.floor(x / CELL), Math.floor(y / CELL));
35
+ const cell = this.found.get(key);
36
+ if (cell) cell.push(entity, x, y, z);
37
+ else this.found.set(key, [entity, x, y, z]);
38
+ }
39
+ this.next = end;
40
+ }
41
+ }
@@ -0,0 +1,69 @@
1
+ import type { ModelScanDef } from "./def";
2
+
3
+ /** Up to this many models a point asks GTA for the closest object of each; more models use the object index. */
4
+ const DIRECT_MODELS = 6;
5
+
6
+ export class Scan {
7
+ readonly hashSet: Set<number>;
8
+ /** Every networked vehicle, whatever its model (`Points.addVehicle`). */
9
+ readonly global: boolean;
10
+ readonly indexed: boolean;
11
+
12
+ constructor(
13
+ readonly def: ModelScanDef,
14
+ readonly onNearest: (entity: number) => void,
15
+ public entity: number,
16
+ ) {
17
+ this.hashSet = new Set(def.models);
18
+ this.global = def.vehicles && def.models.length === 0;
19
+ this.indexed = !def.vehicles && def.models.length > DIRECT_MODELS;
20
+ }
21
+
22
+ /** Object points rest while the player sits in a vehicle (unless `inVehicle`). */
23
+ skipped(inVehicle: boolean): boolean {
24
+ return inVehicle && !this.def.vehicles && !this.def.inVehicle;
25
+ }
26
+ }
27
+
28
+ /** Something near the player this scan: entity, model, distance. */
29
+ export interface Near {
30
+ entity: number;
31
+ model: number;
32
+ dist: number;
33
+ }
34
+
35
+ /** The nearest of `near` that this point takes (its models, or any networked vehicle for a global one) within its radius. */
36
+ export function nearestOf(near: Near[], scan: Scan): number {
37
+ let found = 0;
38
+ let best = scan.def.radius;
39
+ for (const item of near) {
40
+ if (item.dist >= best) continue;
41
+ if (
42
+ scan.global
43
+ ? !NetworkGetEntityIsNetworked(item.entity)
44
+ : !scan.hashSet.has(item.model)
45
+ )
46
+ continue;
47
+ found = item.entity;
48
+ best = item.dist;
49
+ }
50
+ return found;
51
+ }
52
+
53
+ /** A point with few models asks GTA for the closest object of each. */
54
+ export function closestObject(x: number, y: number, z: number, scan: Scan): number {
55
+ for (const hash of scan.def.models) {
56
+ const found = GetClosestObjectOfType(
57
+ x,
58
+ y,
59
+ z,
60
+ scan.def.radius,
61
+ hash,
62
+ false,
63
+ false,
64
+ false,
65
+ );
66
+ if (found) return found;
67
+ }
68
+ return 0;
69
+ }
@@ -0,0 +1,164 @@
1
+ import { every } from "../../fivem/scheduler/every";
2
+ import { cellKey, createLogger } from "../../shared";
3
+ import { cache } from "../cache";
4
+ import type { ModelScanDef } from "./def";
5
+ import { CELL, MOVE_MARGIN, ObjectIndex } from "./objectIndex";
6
+ import { closestObject, nearestOf, Scan, type Near } from "./scan";
7
+
8
+ /**
9
+ * The model point scan: for each point, the nearest world object (or vehicle) of its models within its radius, two
10
+ * times a second, told only when it changes. ai-lib runs one for every resource's prompt-mode model points
11
+ * (`modelHost.ts`); a resource runs its own only while ai-lib does not.
12
+ */
13
+
14
+ const log = createLogger(GetCurrentResourceName());
15
+
16
+ const SCAN_MS = 500;
17
+ /** While the player stands still (and stays in or out of a vehicle) a scan is skipped, but not more than this many in a row. */
18
+ const IDLE_SCANS = 6;
19
+
20
+ /**
21
+ * A set of model points scanned by one scheduler job (500 ms, only while it holds points). Scans are skipped while
22
+ * the player stands still, refreshed every 3 s; the vehicle pool is walked once per scan for every vehicle point and
23
+ * the object index once for every many-model point.
24
+ */
25
+ export class ModelScanner {
26
+ private readonly scans = new Map<string, Scan>();
27
+ private readonly index = new ObjectIndex();
28
+ /** Models of every many-model point, rebuilt when the points change. */
29
+ private wanted: Set<number> | null = null;
30
+ private readonly last = {
31
+ x: 0,
32
+ y: 0,
33
+ z: 0,
34
+ inVehicle: false,
35
+ idle: IDLE_SCANS,
36
+ };
37
+ private readonly job = every(SCAN_MS, () => this.scan(), {
38
+ active: false,
39
+ name: "modelPoints",
40
+ });
41
+
42
+ /** Adds (or replaces) a point; `entity` seeds the nearest one already known (a hand-over), so only a change is told. */
43
+ add(
44
+ key: string,
45
+ def: ModelScanDef,
46
+ onNearest: (entity: number) => void,
47
+ entity = 0,
48
+ ): void {
49
+ this.scans.set(key, new Scan(def, onNearest, entity));
50
+ this.wanted = null;
51
+ // The next scan runs even if the player stands still.
52
+ this.last.idle = IDLE_SCANS;
53
+ this.job.set(true);
54
+ }
55
+
56
+ remove(key: string): void {
57
+ if (!this.scans.delete(key)) return;
58
+ this.wanted = null;
59
+ this.job.set(this.scans.size > 0);
60
+ }
61
+
62
+ get size(): number {
63
+ return this.scans.size;
64
+ }
65
+
66
+ private scan(): void {
67
+ const [x = 0, y = 0, z = 0] = GetEntityCoords(cache.ped, false);
68
+ const inVehicle = cache.vehicle !== false;
69
+ const last = this.last;
70
+ const still =
71
+ inVehicle === last.inVehicle &&
72
+ Math.hypot(x - last.x, y - last.y, z - last.z) < 1;
73
+ if (still && ++last.idle < IDLE_SCANS) return;
74
+ Object.assign(last, { x, y, z, inVehicle, idle: 0 });
75
+
76
+ let vehicleRadius = 0;
77
+ let indexRadius = 0;
78
+ for (const scan of this.scans.values()) {
79
+ if (scan.skipped(inVehicle)) continue;
80
+ if (scan.def.vehicles)
81
+ vehicleRadius = Math.max(vehicleRadius, scan.def.radius);
82
+ else if (scan.indexed)
83
+ indexRadius = Math.max(indexRadius, scan.def.radius);
84
+ }
85
+ const vehicles = vehicleRadius
86
+ ? this.nearVehicles(x, y, z, vehicleRadius)
87
+ : [];
88
+ const objects = indexRadius ? this.nearIndexed(x, y, z, indexRadius) : [];
89
+
90
+ for (const scan of this.scans.values()) {
91
+ const found = scan.skipped(inVehicle)
92
+ ? 0
93
+ : scan.def.vehicles
94
+ ? nearestOf(vehicles, scan)
95
+ : scan.indexed
96
+ ? nearestOf(objects, scan)
97
+ : closestObject(x, y, z, scan);
98
+ if (found === scan.entity) continue;
99
+ scan.entity = found;
100
+ try {
101
+ scan.onNearest(found);
102
+ } catch (error) {
103
+ log.error("model point handler failed", error);
104
+ }
105
+ }
106
+ }
107
+
108
+ /** Vehicles within `radius`: one pool walk for every vehicle point. */
109
+ private nearVehicles(x: number, y: number, z: number, radius: number) {
110
+ const near: Near[] = [];
111
+ for (const entity of GetGamePool("CVehicle") as number[]) {
112
+ const [vx = 0, vy = 0, vz = 0] = GetEntityCoords(entity, false);
113
+ const dist = Math.hypot(vx - x, vy - y, vz - z);
114
+ if (dist < radius)
115
+ near.push({ entity, model: GetEntityModel(entity), dist });
116
+ }
117
+ return near;
118
+ }
119
+
120
+ /** Indexed objects within `radius`: filtered by where they stood when found, then checked where they are now. */
121
+ private nearIndexed(x: number, y: number, z: number, radius: number) {
122
+ if (!this.wanted) {
123
+ this.wanted = new Set();
124
+ for (const scan of this.scans.values())
125
+ if (scan.indexed)
126
+ for (const hash of scan.def.models) this.wanted.add(hash);
127
+ }
128
+ this.index.advance(this.wanted);
129
+ const near: Near[] = [];
130
+ const reach = (radius + MOVE_MARGIN) ** 2;
131
+ const cx = Math.floor(x / CELL);
132
+ const cy = Math.floor(y / CELL);
133
+ for (let ox = -1; ox <= 1; ox++)
134
+ for (let oy = -1; oy <= 1; oy++) {
135
+ const list = this.index.cells.get(cellKey(cx + ox, cy + oy));
136
+ if (list) this.nearIn(list, x, y, z, radius, reach, near);
137
+ }
138
+ return near;
139
+ }
140
+
141
+ /** The objects of one index cell within `radius` (filtered by `reach` on their found place first). */
142
+ private nearIn(
143
+ list: number[],
144
+ x: number,
145
+ y: number,
146
+ z: number,
147
+ radius: number,
148
+ reach: number,
149
+ near: Near[],
150
+ ): void {
151
+ for (let i = 0; i < list.length; i += 4) {
152
+ const dx = (list[i + 1] ?? 0) - x;
153
+ const dy = (list[i + 2] ?? 0) - y;
154
+ const dz = (list[i + 3] ?? 0) - z;
155
+ if (dx * dx + dy * dy + dz * dz > reach) continue;
156
+ const entity = list[i] ?? 0;
157
+ if (!DoesEntityExist(entity)) continue;
158
+ const [ox = 0, oy = 0, oz = 0] = GetEntityCoords(entity, false);
159
+ const dist = Math.hypot(ox - x, oy - y, oz - z);
160
+ if (dist < radius)
161
+ near.push({ entity, model: GetEntityModel(entity), dist });
162
+ }
163
+ }
164
+ }