@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,20 @@
1
+ import type { DataSpec } from "@aifivem/shared";
2
+
3
+ /** Panel data spec builders for a script's `schema.ts` (the panel's own value types stay in `@aifivem/shared`). */
4
+ export const spec = {
5
+ /** A whole number from `min` to `max`. */
6
+ int: (min: number, max: number, optional = false): DataSpec => ({
7
+ type: "number",
8
+ min,
9
+ max,
10
+ integer: true,
11
+ ...(optional ? { optional } : {}),
12
+ }),
13
+ /** A number from `min` to `max`. */
14
+ num: (min: number, max: number, optional = false): DataSpec => ({
15
+ type: "number",
16
+ min,
17
+ max,
18
+ ...(optional ? { optional } : {}),
19
+ }),
20
+ };
@@ -0,0 +1,70 @@
1
+ /**
2
+ * Strict readers for client input (callback and event arguments): a wrong value is refused with null, never replaced
3
+ * by a fallback (that is what the panel readers `num` / `int` do).
4
+ */
5
+
6
+ /** A finite number, else null (NaN and Infinity refused). */
7
+ export function readFinite(value: unknown): number | null {
8
+ return typeof value === "number" && Number.isFinite(value) ? value : null;
9
+ }
10
+
11
+ /** A whole number in `[min, max]`, else null (fractions, NaN, Infinity and out-of-range values refused). */
12
+ export function readInt(
13
+ value: unknown,
14
+ min: number,
15
+ max: number,
16
+ ): number | null {
17
+ return Number.isInteger(value) &&
18
+ (value as number) >= min &&
19
+ (value as number) <= max
20
+ ? (value as number)
21
+ : null;
22
+ }
23
+
24
+ /** A token or network id: a positive 32-bit integer, else null. */
25
+ export const readId = (value: unknown): number | null =>
26
+ readInt(value, 1, 2_147_483_647);
27
+
28
+ /** A non-empty trimmed string cut to `max`, else null. */
29
+ export function readText(value: unknown, max: number): string | null {
30
+ if (typeof value !== "string") return null;
31
+ const text = value.trim();
32
+ return text ? text.slice(0, max) : null;
33
+ }
34
+
35
+ /** An `args` parser for inputs that take one value: `onClientCallback(name, { args: oneArg(readId) }, (source, token) => ...)`. */
36
+ export const oneArg =
37
+ <T>(read: (value: unknown) => T | null) =>
38
+ ([value]: unknown[]): [T] | null => {
39
+ const parsed = read(value);
40
+ return parsed === null ? null : [parsed];
41
+ };
42
+
43
+ /** The x, y, z (and w) of `{ x, y, z }` or a Lua vector that arrived as `[x, y, z, w?]`. */
44
+ function parts(value: unknown): unknown[] | null {
45
+ if (Array.isArray(value)) return value;
46
+ if (typeof value !== "object" || value === null) return null;
47
+ const v = value as Record<string, unknown>;
48
+ return [v.x, v.y, v.z, v.heading ?? v.w];
49
+ }
50
+
51
+ /** A point from client or export input: `{ x, y, z }` or a Lua vector `[x, y, z]`, every value finite; else null. */
52
+ export function readVec3(
53
+ value: unknown,
54
+ ): { x: number; y: number; z: number } | null {
55
+ const p = parts(value);
56
+ if (!p) return null;
57
+ const [x, y, z] = [readFinite(p[0]), readFinite(p[1]), readFinite(p[2])];
58
+ return x !== null && y !== null && z !== null ? { x, y, z } : null;
59
+ }
60
+
61
+ /** A point with a heading: `{ x, y, z, heading | w }` or a Lua vector4; a missing heading reads 0; else null. */
62
+ export function readVec4(
63
+ value: unknown,
64
+ ): { x: number; y: number; z: number; heading: number } | null {
65
+ const point = readVec3(value);
66
+ if (!point) return null;
67
+ const raw = parts(value)?.[3];
68
+ const heading = raw === undefined || raw === null ? 0 : readFinite(raw);
69
+ return heading === null ? null : { ...point, heading };
70
+ }
@@ -0,0 +1,48 @@
1
+ /** A point in the world. */
2
+ export interface Vec3 {
3
+ x: number;
4
+ y: number;
5
+ z: number;
6
+ }
7
+
8
+ /** Straight distance between two points, in metres. */
9
+ export const distance = (a: Vec3, b: Vec3): number =>
10
+ Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z);
11
+
12
+ /** Distance on the ground plane (x / y only), in metres. */
13
+ export const flatDistance = (
14
+ a: Pick<Vec3, "x" | "y">,
15
+ b: Pick<Vec3, "x" | "y">,
16
+ ): number => Math.hypot(a.x - b.x, a.y - b.y);
17
+
18
+ /** The heading (0-360, GTA's: 0 = north, counter-clockwise) that faces from `from` towards `to`. */
19
+ export function headingTo(
20
+ from: Pick<Vec3, "x" | "y">,
21
+ to: Pick<Vec3, "x" | "y">,
22
+ ): number {
23
+ const deg = (Math.atan2(to.x - from.x, to.y - from.y) * 180) / Math.PI;
24
+ return (-deg + 360) % 360;
25
+ }
26
+
27
+ /** The item nearest to `point` (3D, `pos` reads an item's position), within `max` metres; undefined when none. */
28
+ export function nearestOf<T>(
29
+ items: Iterable<T>,
30
+ point: Vec3,
31
+ pos: (item: T) => Vec3,
32
+ max = Infinity,
33
+ ): T | undefined {
34
+ let best: T | undefined;
35
+ let bestSq = max * max;
36
+ for (const item of items) {
37
+ const p = pos(item);
38
+ const dx = p.x - point.x;
39
+ const dy = p.y - point.y;
40
+ const dz = p.z - point.z;
41
+ const sq = dx * dx + dy * dy + dz * dz;
42
+ if (sq <= bestSq) {
43
+ bestSq = sq;
44
+ best = item;
45
+ }
46
+ }
47
+ return best;
48
+ }
@@ -0,0 +1,138 @@
1
+ /**
2
+ * A vehicle's look and tuning as plain data (colours, mods, extras, livery, wheels, neon, tint, plate), read from and
3
+ * written to an entity. Stored JSON carries `v: 1`.
4
+ */
5
+ export interface VehicleProps {
6
+ v: 1;
7
+ model: number;
8
+ plate: string;
9
+ plateIndex: number;
10
+ colors: [number, number];
11
+ extraColors: [number, number];
12
+ customPrimary: [number, number, number] | null;
13
+ customSecondary: [number, number, number] | null;
14
+ wheelType: number;
15
+ windowTint: number;
16
+ livery: number;
17
+ /** Mod type -> index (-1 = stock); toggle mods (turbo 18, xenon 22, ...) as 0 / 1. */
18
+ mods: Record<number, number>;
19
+ xenonColor: number;
20
+ neon: [boolean, boolean, boolean, boolean];
21
+ neonColor: [number, number, number];
22
+ tyreSmoke: [number, number, number];
23
+ extras: Record<number, boolean>;
24
+ dirt: number;
25
+ engineHealth: number;
26
+ bodyHealth: number;
27
+ }
28
+
29
+ const isObj = (v: unknown): v is Record<string, unknown> =>
30
+ typeof v === "object" && v !== null && !Array.isArray(v);
31
+ const nums = (v: unknown, n: number): number[] | null =>
32
+ Array.isArray(v) && v.length === n && v.every((x) => typeof x === "number")
33
+ ? v
34
+ : null;
35
+
36
+ /** Stored or received props, checked; null when the shape is not ours. */
37
+ export function toVehicleProps(v: unknown): VehicleProps | null {
38
+ if (
39
+ !isObj(v) ||
40
+ v.v !== 1 ||
41
+ typeof v.model !== "number" ||
42
+ typeof v.plate !== "string"
43
+ )
44
+ return null;
45
+ const colors = nums(v.colors, 2);
46
+ const extraColors = nums(v.extraColors, 2);
47
+ const neonColor = nums(v.neonColor, 3);
48
+ const tyreSmoke = nums(v.tyreSmoke, 3);
49
+ if (
50
+ !colors ||
51
+ !extraColors ||
52
+ !neonColor ||
53
+ !tyreSmoke ||
54
+ !isObj(v.mods) ||
55
+ !isObj(v.extras) ||
56
+ !Array.isArray(v.neon)
57
+ )
58
+ return null;
59
+ const mods: Record<number, number> = {};
60
+ for (const [k, x] of Object.entries(v.mods))
61
+ if (typeof x === "number") mods[Number(k)] = x;
62
+ const extras: Record<number, boolean> = {};
63
+ for (const [k, x] of Object.entries(v.extras))
64
+ if (typeof x === "boolean") extras[Number(k)] = x;
65
+ const n = (x: unknown, d: number) => (typeof x === "number" ? x : d);
66
+ const rgb = (x: unknown) => nums(x, 3) as [number, number, number] | null;
67
+ return {
68
+ v: 1,
69
+ model: v.model,
70
+ plate: v.plate.slice(0, 8),
71
+ plateIndex: n(v.plateIndex, 0),
72
+ colors: [colors[0] ?? 0, colors[1] ?? 0],
73
+ extraColors: [extraColors[0] ?? 0, extraColors[1] ?? 0],
74
+ customPrimary: rgb(v.customPrimary),
75
+ customSecondary: rgb(v.customSecondary),
76
+ wheelType: n(v.wheelType, 0),
77
+ windowTint: n(v.windowTint, -1),
78
+ livery: n(v.livery, -1),
79
+ mods,
80
+ xenonColor: n(v.xenonColor, 255),
81
+ neon: [0, 1, 2, 3].map(
82
+ (i) => v.neon instanceof Array && v.neon[i] === true,
83
+ ) as VehicleProps["neon"],
84
+ neonColor: [neonColor[0] ?? 255, neonColor[1] ?? 0, neonColor[2] ?? 255],
85
+ tyreSmoke: [tyreSmoke[0] ?? 255, tyreSmoke[1] ?? 255, tyreSmoke[2] ?? 255],
86
+ extras,
87
+ dirt: n(v.dirt, 0),
88
+ engineHealth: n(v.engineHealth, 1000),
89
+ bodyHealth: n(v.bodyHealth, 1000),
90
+ };
91
+ }
92
+
93
+ /** What a freshly spawned vehicle gets on top of the model's defaults (lib `spawnVehicle`'s `setup`). */
94
+ export interface VehicleSetup {
95
+ /** Every performance mod at its top level, turbo and xenons on. */
96
+ maxed?: boolean;
97
+ /** GTA colour indexes (primary, secondary), as `VehicleProps.colors`. */
98
+ colors?: [number, number];
99
+ primary?: [number, number, number];
100
+ secondary?: [number, number, number];
101
+ livery?: number;
102
+ windowTint?: number;
103
+ /** 0 (clean) - 15. */
104
+ dirt?: number;
105
+ engineOn?: boolean;
106
+ }
107
+
108
+ const rgbOf = (v: unknown): [number, number, number] | undefined =>
109
+ Array.isArray(v) &&
110
+ v.length === 3 &&
111
+ v.every((x) => typeof x === "number" && x >= 0 && x <= 255)
112
+ ? [v[0], v[1], v[2]]
113
+ : undefined;
114
+ const intOf = (v: unknown, min: number, max: number): number | undefined =>
115
+ typeof v === "number" && Number.isInteger(v) && v >= min && v <= max
116
+ ? v
117
+ : undefined;
118
+
119
+ const colorsOf = (v: unknown): [number, number] | undefined => {
120
+ if (!Array.isArray(v) || v.length !== 2) return undefined;
121
+ const [a, b] = [intOf(v[0], 0, 255), intOf(v[1], 0, 255)];
122
+ return a === undefined || b === undefined ? undefined : [a, b];
123
+ };
124
+
125
+ /** A received setup, checked field by field (wrong fields drop); null when it is not an object. */
126
+ export function toVehicleSetup(v: unknown): VehicleSetup | null {
127
+ if (!isObj(v)) return null;
128
+ return {
129
+ maxed: v.maxed === true || undefined,
130
+ colors: colorsOf(v.colors),
131
+ primary: rgbOf(v.primary),
132
+ secondary: rgbOf(v.secondary),
133
+ livery: intOf(v.livery, 0, 100),
134
+ windowTint: intOf(v.windowTint, 0, 6),
135
+ dirt: intOf(v.dirt, 0, 15),
136
+ engineOn: v.engineOn === true || undefined,
137
+ };
138
+ }
@@ -0,0 +1,27 @@
1
+ /** Resolves after `ms` milliseconds. */
2
+ export function sleep(ms: number): Promise<void> {
3
+ return new Promise((resolve) => setTimeout(resolve, ms));
4
+ }
5
+
6
+ /**
7
+ * Resolves with the first value `check` returns that is not undefined, checking once per tick (or every `intervalMs`).
8
+ * Rejects after `timeoutMs` (default 10 s); pass `false` to wait forever.
9
+ * Return `cond || undefined` from `check` to wait for a truthy condition.
10
+ */
11
+ export function waitFor<T>(
12
+ check: () => T | undefined,
13
+ timeoutMs: number | false = 10_000,
14
+ intervalMs = 0,
15
+ ): Promise<T> {
16
+ return new Promise((resolve, reject) => {
17
+ const started = Date.now();
18
+ const poll = (): void => {
19
+ const value = check();
20
+ if (value !== undefined) return resolve(value);
21
+ if (timeoutMs !== false && Date.now() - started > timeoutMs)
22
+ return reject(new Error(`waitFor timed out after ${timeoutMs} ms`));
23
+ setTimeout(poll, intervalMs);
24
+ };
25
+ poll();
26
+ });
27
+ }
@@ -0,0 +1,144 @@
1
+ import type { Vec3 } from "./vec";
2
+
3
+ /** Zone geometry (client `Zones`, server-side area checks). No natives. */
4
+ export type ZoneShape =
5
+ /** A ball around a point. */
6
+ | { type: "sphere"; center: Vec3; radius: number }
7
+ /** A circle on the ground plane, `height` metres up and down from the centre. */
8
+ | { type: "cylinder"; center: Vec3; radius: number; height: number }
9
+ /** A ground polygon (x, y points in order) between two heights. */
10
+ | {
11
+ type: "poly";
12
+ points: Array<{ x: number; y: number }>;
13
+ minZ: number;
14
+ maxZ: number;
15
+ };
16
+
17
+ /** A zone shape from another resource (ai-lib's zone checker), null when it is not one. */
18
+ export function readZoneShape(v: unknown): ZoneShape | null {
19
+ if (typeof v !== "object" || v === null) return null;
20
+ const s = v as Record<string, unknown>;
21
+ const num = (x: unknown): x is number =>
22
+ typeof x === "number" && Number.isFinite(x);
23
+ const vec = (x: unknown): Vec3 | null => {
24
+ if (typeof x !== "object" || x === null) return null;
25
+ const p = x as Record<string, unknown>;
26
+ return num(p.x) && num(p.y) && num(p.z) ? { x: p.x, y: p.y, z: p.z } : null;
27
+ };
28
+ if (s.type === "sphere" || s.type === "cylinder") {
29
+ const center = vec(s.center);
30
+ if (!center || !num(s.radius)) return null;
31
+ if (s.type === "sphere")
32
+ return { type: "sphere", center, radius: s.radius };
33
+ return num(s.height)
34
+ ? { type: "cylinder", center, radius: s.radius, height: s.height }
35
+ : null;
36
+ }
37
+ if (
38
+ s.type !== "poly" ||
39
+ !Array.isArray(s.points) ||
40
+ !num(s.minZ) ||
41
+ !num(s.maxZ)
42
+ )
43
+ return null;
44
+ const points: Array<{ x: number; y: number }> = [];
45
+ for (const p of s.points) {
46
+ if (typeof p !== "object" || p === null) return null;
47
+ const q = p as Record<string, unknown>;
48
+ if (!num(q.x) || !num(q.y)) return null;
49
+ points.push({ x: q.x, y: q.y });
50
+ }
51
+ return points.length >= 3
52
+ ? { type: "poly", points, minZ: s.minZ, maxZ: s.maxZ }
53
+ : null;
54
+ }
55
+
56
+ /** Whether a point lies inside a zone shape. */
57
+ export function zoneContains(
58
+ shape: ZoneShape,
59
+ x: number,
60
+ y: number,
61
+ z: number,
62
+ ): boolean {
63
+ switch (shape.type) {
64
+ case "sphere": {
65
+ const dx = x - shape.center.x;
66
+ const dy = y - shape.center.y;
67
+ const dz = z - shape.center.z;
68
+ return dx * dx + dy * dy + dz * dz <= shape.radius * shape.radius;
69
+ }
70
+ case "cylinder": {
71
+ const dx = x - shape.center.x;
72
+ const dy = y - shape.center.y;
73
+ return (
74
+ dx * dx + dy * dy <= shape.radius * shape.radius &&
75
+ Math.abs(z - shape.center.z) <= shape.height
76
+ );
77
+ }
78
+ case "poly": {
79
+ if (z < shape.minZ || z > shape.maxZ) return false;
80
+ // Ray casting: count the edges a ray to +x crosses.
81
+ let inside = false;
82
+ const p = shape.points;
83
+ for (let i = 0, j = p.length - 1; i < p.length; j = i++) {
84
+ const a = p[i]!;
85
+ const b = p[j]!;
86
+ if (
87
+ a.y > y !== b.y > y &&
88
+ x < ((b.x - a.x) * (y - a.y)) / (b.y - a.y) + a.x
89
+ )
90
+ inside = !inside;
91
+ }
92
+ return inside;
93
+ }
94
+ default: {
95
+ const _exhaustive: never = shape;
96
+ return _exhaustive;
97
+ }
98
+ }
99
+ }
100
+
101
+ /** Ground bounding box of a shape: [minX, minY, maxX, maxY]. */
102
+ export function zoneBounds(shape: ZoneShape): [number, number, number, number] {
103
+ if (shape.type !== "poly")
104
+ return [
105
+ shape.center.x - shape.radius,
106
+ shape.center.y - shape.radius,
107
+ shape.center.x + shape.radius,
108
+ shape.center.y + shape.radius,
109
+ ];
110
+ let minX = Infinity;
111
+ let minY = Infinity;
112
+ let maxX = -Infinity;
113
+ let maxY = -Infinity;
114
+ for (const p of shape.points) {
115
+ minX = Math.min(minX, p.x);
116
+ minY = Math.min(minY, p.y);
117
+ maxX = Math.max(maxX, p.x);
118
+ maxY = Math.max(maxY, p.y);
119
+ }
120
+ return [minX, minY, maxX, maxY];
121
+ }
122
+
123
+ /**
124
+ * A panel `zone` widget's corners as a poly shape: the z range is the corners' lowest and highest z widened by
125
+ * `height` metres; null with fewer than three corners.
126
+ */
127
+ export function polyFromCorners(
128
+ corners: readonly Vec3[],
129
+ height: number,
130
+ ): Extract<ZoneShape, { type: "poly" }> | null {
131
+ if (corners.length < 3) return null;
132
+ let minZ = Infinity;
133
+ let maxZ = -Infinity;
134
+ for (const c of corners) {
135
+ minZ = Math.min(minZ, c.z);
136
+ maxZ = Math.max(maxZ, c.z);
137
+ }
138
+ return {
139
+ type: "poly",
140
+ points: corners.map(({ x, y }) => ({ x, y })),
141
+ minZ: minZ - height,
142
+ maxZ: maxZ + height,
143
+ };
144
+ }
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.