@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.
- package/package.json +34 -4
- package/src/client/action.ts +38 -0
- package/src/client/adminWorld.ts +95 -0
- package/src/client/appearance.ts +29 -0
- package/src/client/areaFollower.ts +41 -0
- package/src/client/blip.ts +79 -0
- package/src/client/cache.ts +66 -0
- package/src/client/callback.ts +70 -0
- package/src/client/controls.ts +73 -0
- package/src/client/entities.ts +83 -0
- package/src/client/entity.ts +26 -0
- package/src/client/fuel.ts +18 -0
- package/src/client/gestures.ts +18 -0
- package/src/client/headshot.ts +26 -0
- package/src/client/hud.ts +24 -0
- package/src/client/index.ts +131 -0
- package/src/client/inventory.ts +117 -0
- package/src/client/keyHints.ts +13 -0
- package/src/client/keybind.ts +163 -0
- package/src/client/localPed.ts +169 -0
- package/src/client/location.ts +54 -0
- package/src/client/mdt.ts +10 -0
- package/src/client/medical.ts +28 -0
- package/src/client/membership.ts +41 -0
- package/src/client/menu/dialogs.ts +77 -0
- package/src/client/menu/minigames.ts +79 -0
- package/src/client/menu/requests.ts +65 -0
- package/src/client/modelScan/def.ts +29 -0
- package/src/client/modelScan/objectIndex.ts +41 -0
- package/src/client/modelScan/scan.ts +69 -0
- package/src/client/modelScan/scanner.ts +164 -0
- package/src/client/netEvent.ts +40 -0
- package/src/client/notify.ts +14 -0
- package/src/client/nuiScreen.ts +87 -0
- package/src/client/player/anim.ts +98 -0
- package/src/client/player/fade.ts +17 -0
- package/src/client/player/player.ts +80 -0
- package/src/client/player/teleport.ts +87 -0
- package/src/client/playerData.ts +83 -0
- package/src/client/players.ts +44 -0
- package/src/client/points/interact.ts +144 -0
- package/src/client/points/modelHost.ts +117 -0
- package/src/client/points/modelPoint.ts +181 -0
- package/src/client/points/point.ts +159 -0
- package/src/client/points/points.ts +170 -0
- package/src/client/points/targets/adapter.ts +40 -0
- package/src/client/points/targets/interactTarget.ts +45 -0
- package/src/client/points/targets/optionShape.ts +22 -0
- package/src/client/points/targets/oxTarget.ts +42 -0
- package/src/client/points/targets/qbTarget.ts +71 -0
- package/src/client/points/targets/targets.ts +20 -0
- package/src/client/preview.ts +51 -0
- package/src/client/progress.ts +132 -0
- package/src/client/prompt.ts +26 -0
- package/src/client/prop.ts +79 -0
- package/src/client/radial.ts +16 -0
- package/src/client/raycast.ts +48 -0
- package/src/client/scriptCamera.ts +167 -0
- package/src/client/seatbelt.ts +18 -0
- package/src/client/shot.ts +29 -0
- package/src/client/streaming.ts +91 -0
- package/src/client/tickLoop.ts +18 -0
- package/src/client/vehicleKeys.ts +14 -0
- package/src/client/vehicleProps.ts +107 -0
- package/src/client/vehicles.ts +46 -0
- package/src/client/waypoint.ts +10 -0
- package/src/client/world.ts +10 -0
- package/src/client/zoneEngine.ts +174 -0
- package/src/client/zones.ts +161 -0
- package/src/fivem/byResource.ts +146 -0
- package/src/fivem/callbackNames.ts +12 -0
- package/src/fivem/exports.ts +70 -0
- package/src/fivem/index.ts +13 -0
- package/src/fivem/locale.ts +57 -0
- package/src/fivem/playerData.ts +13 -0
- package/src/fivem/scheduler/every.ts +101 -0
- package/src/fivem/scheduler/group.ts +97 -0
- package/src/fivem/scheduler/scheduler.ts +77 -0
- package/src/fivem/state/entityState.ts +75 -0
- package/src/fivem/state/globalState.ts +80 -0
- package/src/fivem/state/mirror.ts +47 -0
- package/src/fivem/state/playerState.ts +60 -0
- package/src/server/admin/descriptions.ts +57 -0
- package/src/server/admin/edit.ts +127 -0
- package/src/server/admin/jsonSchema.ts +156 -0
- package/src/server/admin/panel.ts +167 -0
- package/src/server/admin/panelFiles.ts +128 -0
- package/src/server/admin/patch.ts +46 -0
- package/src/server/admin/validate.ts +147 -0
- package/src/server/appearance.ts +28 -0
- package/src/server/areaStream/areaStream.ts +141 -0
- package/src/server/areaStream/followers.ts +154 -0
- package/src/server/areaStream/grid.ts +74 -0
- package/src/server/areaStream/options.ts +16 -0
- package/src/server/banking.ts +15 -0
- package/src/server/bans.ts +47 -0
- package/src/server/billing.ts +20 -0
- package/src/server/buckets.ts +12 -0
- package/src/server/callback.ts +112 -0
- package/src/server/characters.ts +129 -0
- package/src/server/command/addCommand.ts +83 -0
- package/src/server/command/command.ts +116 -0
- package/src/server/command/commandSet.ts +74 -0
- package/src/server/dataFile.ts +81 -0
- package/src/server/database.ts +117 -0
- package/src/server/definitions.ts +65 -0
- package/src/server/dispatch.ts +13 -0
- package/src/server/doors.ts +15 -0
- package/src/server/ems.ts +15 -0
- package/src/server/fuel.ts +15 -0
- package/src/server/garages.ts +34 -0
- package/src/server/gate.ts +148 -0
- package/src/server/index.ts +165 -0
- package/src/server/inventory.ts +106 -0
- package/src/server/jobs.ts +42 -0
- package/src/server/log.ts +21 -0
- package/src/server/mdt.ts +12 -0
- package/src/server/medical.ts +16 -0
- package/src/server/minigameFor.ts +65 -0
- package/src/server/money.ts +70 -0
- package/src/server/netEntity.ts +19 -0
- package/src/server/netEvent.ts +58 -0
- package/src/server/notify.ts +17 -0
- package/src/server/online/mirror.ts +176 -0
- package/src/server/online/online.ts +190 -0
- package/src/server/pending.ts +70 -0
- package/src/server/phone.ts +22 -0
- package/src/server/players.ts +197 -0
- package/src/server/position.ts +31 -0
- package/src/server/primeTime.ts +7 -0
- package/src/server/prison.ts +15 -0
- package/src/server/progressFor.ts +62 -0
- package/src/server/proximity.ts +98 -0
- package/src/server/rateLimit.ts +53 -0
- package/src/server/state.ts +45 -0
- package/src/server/stress.ts +25 -0
- package/src/server/vehicle/nearby.ts +66 -0
- package/src/server/vehicle/plate.ts +14 -0
- package/src/server/vehicle/spawn.ts +125 -0
- package/src/server/vehicle/vehicleType.ts +50 -0
- package/src/server/vehicleKeys.ts +23 -0
- package/src/server/watchers.ts +46 -0
- package/src/server/world.ts +16 -0
- package/src/shared/access.ts +94 -0
- package/src/shared/action.ts +28 -0
- package/src/shared/blipStyle.ts +26 -0
- package/src/shared/clock.ts +22 -0
- package/src/shared/format.ts +36 -0
- package/src/shared/grid.ts +20 -0
- package/src/shared/index.ts +179 -0
- package/src/shared/lang.ts +39 -0
- package/src/shared/placePed.ts +96 -0
- package/src/shared/random.ts +11 -0
- package/src/shared/read.ts +60 -0
- package/src/shared/records.ts +148 -0
- package/src/shared/spec.ts +20 -0
- package/src/shared/strict.ts +70 -0
- package/src/shared/vec.ts +48 -0
- package/src/shared/vehicleProps.ts +138 -0
- package/src/shared/wait.ts +27 -0
- package/src/shared/zone.ts +144 -0
- package/README.md +0 -3
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import type { ActionResult } from "@aifivem/shared";
|
|
2
|
+
|
|
3
|
+
/** A refused action: `{ ok: false, error }` with a lang key the client shows. */
|
|
4
|
+
export const fail = (error: string): { ok: false; error: string } => ({
|
|
5
|
+
ok: false,
|
|
6
|
+
error,
|
|
7
|
+
});
|
|
8
|
+
|
|
9
|
+
/** The reply is an ok `ActionResult` (any extra fields unchecked: parse the ones you read). */
|
|
10
|
+
export const isActionOk = (
|
|
11
|
+
reply: unknown,
|
|
12
|
+
): reply is { ok: true } & Record<string, unknown> =>
|
|
13
|
+
typeof reply === "object" &&
|
|
14
|
+
reply !== null &&
|
|
15
|
+
!Array.isArray(reply) &&
|
|
16
|
+
(reply as { ok?: unknown }).ok === true;
|
|
17
|
+
|
|
18
|
+
/** The lang key of a refused reply: its `error`, or `fallback` when the reply is missing or malformed; null when ok. */
|
|
19
|
+
export function replyError(reply: unknown, fallback: string): string | null {
|
|
20
|
+
if (isActionOk(reply)) return null;
|
|
21
|
+
const error =
|
|
22
|
+
typeof reply === "object" && reply !== null
|
|
23
|
+
? (reply as { error?: unknown }).error
|
|
24
|
+
: undefined;
|
|
25
|
+
return typeof error === "string" && error !== "" ? error : fallback;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export type { ActionResult };
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import type { DataSpec } from "@aifivem/shared";
|
|
2
|
+
import { int, num, record } from "./read";
|
|
3
|
+
|
|
4
|
+
/** A blip's style as the panel's `blip` widget stores it. */
|
|
5
|
+
export interface BlipStyle {
|
|
6
|
+
sprite: number;
|
|
7
|
+
color: number;
|
|
8
|
+
scale: number;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
/** The panel data spec of a blip style's fields (`{ type: "object", fields: BLIP_STYLE_FIELDS }`). */
|
|
12
|
+
export const BLIP_STYLE_FIELDS: Record<string, DataSpec> = {
|
|
13
|
+
sprite: { type: "number", min: 0, max: 1000, integer: true },
|
|
14
|
+
color: { type: "number", min: 0, max: 100, integer: true },
|
|
15
|
+
scale: { type: "number", min: 0.3, max: 2 },
|
|
16
|
+
};
|
|
17
|
+
|
|
18
|
+
/** A blip style from panel data; each missing or bad part from `fallback` (sprite 0-1000, colour 0-100, scale 0.3-2). */
|
|
19
|
+
export function readBlipStyle(value: unknown, fallback: BlipStyle): BlipStyle {
|
|
20
|
+
const v = record(value);
|
|
21
|
+
return {
|
|
22
|
+
sprite: int(v.sprite, fallback.sprite, 0, 1000),
|
|
23
|
+
color: int(v.color, fallback.color, 0, 100),
|
|
24
|
+
scale: num(v.scale, fallback.scale, 0.3, 2),
|
|
25
|
+
};
|
|
26
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The server's epoch clock on a client: `sync(serverNow)` takes the offset from a server's `Date.now()` (a snapshot,
|
|
3
|
+
* a start message), `now()` is the server time now, `toLocal(serverTime)` the same moment on the local clock.
|
|
4
|
+
*/
|
|
5
|
+
export class ServerClock {
|
|
6
|
+
private offset = 0;
|
|
7
|
+
|
|
8
|
+
/** Takes the offset from the server's `Date.now()` just received. */
|
|
9
|
+
sync(serverNow: number): void {
|
|
10
|
+
this.offset = serverNow - Date.now();
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
/** The server's `Date.now()` right now. */
|
|
14
|
+
now(): number {
|
|
15
|
+
return Date.now() + this.offset;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
/** A server time as a local `Date.now()` time (for countdowns on the local clock). */
|
|
19
|
+
toLocal(serverTime: number): number {
|
|
20
|
+
return serverTime - this.offset;
|
|
21
|
+
}
|
|
22
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/** Rounds to `decimals` places (default 0). */
|
|
2
|
+
export function round(value: number, decimals = 0): number {
|
|
3
|
+
const power = 10 ** decimals;
|
|
4
|
+
return Math.round(value * power) / power;
|
|
5
|
+
}
|
|
6
|
+
|
|
7
|
+
/** `1234567` as `1,234,567` (`separator` default `,`); keeps a sign and decimals. */
|
|
8
|
+
export function groupDigits(value: number | string, separator = ","): string {
|
|
9
|
+
const [whole = "", fraction] = String(value).split(".");
|
|
10
|
+
const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/g, separator);
|
|
11
|
+
return fraction === undefined ? grouped : `${grouped}.${fraction}`;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Text from another script made plain: HTML tags, GTA colour and input codes (`~r~`, `~INPUT_PICKUP~`) and ` `
|
|
16
|
+
* removed, runs of spaces folded.
|
|
17
|
+
*/
|
|
18
|
+
export function stripGameText(text: unknown): string {
|
|
19
|
+
if (text === null || text === undefined) return "";
|
|
20
|
+
return String(text)
|
|
21
|
+
.replace(/<[^>]*>/g, "")
|
|
22
|
+
.replace(/~[\w]+~/g, "")
|
|
23
|
+
.replace(/ /g, " ")
|
|
24
|
+
.replace(/\s\s+/g, " ")
|
|
25
|
+
.trim();
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** A weight in grams for players: "750 g", "1.5 kg", "1,250 kg" (one decimal under 100 kg). */
|
|
29
|
+
export function formatWeight(grams: number): string {
|
|
30
|
+
if (Math.abs(grams) < 1000) return `${Math.round(grams)} g`;
|
|
31
|
+
const kg = grams / 1000;
|
|
32
|
+
return `${groupDigits(Math.abs(kg) < 100 ? round(kg, 1) : Math.round(kg))} kg`;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** A plate as the game compares it: GTA pads plates to 8 characters with spaces; keys use the trimmed upper case. */
|
|
36
|
+
export const normalizePlate = (plate: string): string => plate.trim().toUpperCase();
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/** Grid cells for world streaming (lib `AreaStream` / `AreaFollower`): the same math on server and client. */
|
|
2
|
+
|
|
3
|
+
/** Cells are clamped to +-16,000 so `cellKey` stays a small integer (a fast Map key). */
|
|
4
|
+
const LIMIT = 16_000;
|
|
5
|
+
const OFFSET = 16_384;
|
|
6
|
+
const clampCell = (v: number): number => Math.max(-LIMIT, Math.min(LIMIT, v));
|
|
7
|
+
|
|
8
|
+
/** The integer cell of a point on a grid of `size` metres. */
|
|
9
|
+
export const gridCell = (
|
|
10
|
+
x: number,
|
|
11
|
+
y: number,
|
|
12
|
+
size: number,
|
|
13
|
+
): { cx: number; cy: number } => ({
|
|
14
|
+
cx: clampCell(Math.floor(x / size)),
|
|
15
|
+
cy: clampCell(Math.floor(y / size)),
|
|
16
|
+
});
|
|
17
|
+
|
|
18
|
+
/** One number for a cell (below 2^30). */
|
|
19
|
+
export const cellKey = (cx: number, cy: number): number =>
|
|
20
|
+
(clampCell(cx) + OFFSET) * 32_768 + (clampCell(cy) + OFFSET);
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
/** Helpers usable on client and server. No FiveM natives here. */
|
|
2
|
+
|
|
3
|
+
export { sleep, waitFor } from "./wait";
|
|
4
|
+
export { bool, int, num, record, str, vec4, type Vec4 } from "./read";
|
|
5
|
+
export {
|
|
6
|
+
oneArg,
|
|
7
|
+
readFinite,
|
|
8
|
+
readId,
|
|
9
|
+
readInt,
|
|
10
|
+
readText,
|
|
11
|
+
readVec3,
|
|
12
|
+
readVec4,
|
|
13
|
+
} from "./strict";
|
|
14
|
+
export { fail, isActionOk, replyError, type ActionResult } from "./action";
|
|
15
|
+
export {
|
|
16
|
+
distance,
|
|
17
|
+
flatDistance,
|
|
18
|
+
headingTo,
|
|
19
|
+
nearestOf,
|
|
20
|
+
type Vec3,
|
|
21
|
+
} from "./vec";
|
|
22
|
+
export { pickRandom, randomInt, rollChance } from "./random";
|
|
23
|
+
export { ServerClock } from "./clock";
|
|
24
|
+
export {
|
|
25
|
+
formatWeight,
|
|
26
|
+
groupDigits,
|
|
27
|
+
normalizePlate,
|
|
28
|
+
round,
|
|
29
|
+
stripGameText,
|
|
30
|
+
} from "./format";
|
|
31
|
+
export {
|
|
32
|
+
ACCESS_FIELDS,
|
|
33
|
+
accessFields,
|
|
34
|
+
decideAccess,
|
|
35
|
+
isPublic,
|
|
36
|
+
readAccess,
|
|
37
|
+
type AccessRule,
|
|
38
|
+
} from "./access";
|
|
39
|
+
export {
|
|
40
|
+
BLIP_STYLE_FIELDS,
|
|
41
|
+
readBlipStyle,
|
|
42
|
+
type BlipStyle,
|
|
43
|
+
} from "./blipStyle";
|
|
44
|
+
export {
|
|
45
|
+
polyFromCorners,
|
|
46
|
+
readZoneShape,
|
|
47
|
+
zoneBounds,
|
|
48
|
+
zoneContains,
|
|
49
|
+
type ZoneShape,
|
|
50
|
+
} from "./zone";
|
|
51
|
+
export {
|
|
52
|
+
LiveRecords,
|
|
53
|
+
readRecords,
|
|
54
|
+
RecordObjects,
|
|
55
|
+
type RecordReader,
|
|
56
|
+
type RecordSource,
|
|
57
|
+
} from "./records";
|
|
58
|
+
export { formatText, LangTexts } from "./lang";
|
|
59
|
+
export { spec } from "./spec";
|
|
60
|
+
export {
|
|
61
|
+
toVehicleProps,
|
|
62
|
+
toVehicleSetup,
|
|
63
|
+
type VehicleProps,
|
|
64
|
+
type VehicleSetup,
|
|
65
|
+
} from "./vehicleProps";
|
|
66
|
+
|
|
67
|
+
export function isRecord(value: unknown): value is Record<string, unknown> {
|
|
68
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** Client text made safe for the server console: one line, no control characters, no `^n` colour codes. */
|
|
72
|
+
export function logSafe(text: string, max: number): string {
|
|
73
|
+
// oxlint-disable-next-line no-control-regex
|
|
74
|
+
return text
|
|
75
|
+
.replace(/\r?\n/g, " | ")
|
|
76
|
+
.replace(/[\u0000-\u001f\u007f]/g, "")
|
|
77
|
+
.replace(/\^\d/g, "")
|
|
78
|
+
.slice(0, max);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* JSON-like text of an untrusted value cut at `max` characters, built without serializing the rest (a hostile
|
|
83
|
+
* payload can be megabytes): for log lines. Deeper than 4 levels shows as `[...]` / `{...}`.
|
|
84
|
+
*/
|
|
85
|
+
export function previewJson(value: unknown, max: number): string {
|
|
86
|
+
let out = "";
|
|
87
|
+
const walk = (v: unknown, depth: number): void => {
|
|
88
|
+
if (out.length >= max) return;
|
|
89
|
+
if (typeof v === "string") {
|
|
90
|
+
out += JSON.stringify(v.length > max ? v.slice(0, max) : v);
|
|
91
|
+
return;
|
|
92
|
+
}
|
|
93
|
+
if (v === null || typeof v !== "object") {
|
|
94
|
+
out += String(v);
|
|
95
|
+
return;
|
|
96
|
+
}
|
|
97
|
+
if (depth > 4) {
|
|
98
|
+
out += Array.isArray(v) ? "[...]" : "{...}";
|
|
99
|
+
return;
|
|
100
|
+
}
|
|
101
|
+
if (Array.isArray(v)) {
|
|
102
|
+
out += "[";
|
|
103
|
+
for (let i = 0; i < v.length && out.length < max; i++) {
|
|
104
|
+
if (i > 0) out += ",";
|
|
105
|
+
walk(v[i], depth + 1);
|
|
106
|
+
}
|
|
107
|
+
out += "]";
|
|
108
|
+
return;
|
|
109
|
+
}
|
|
110
|
+
out += "{";
|
|
111
|
+
let first = true;
|
|
112
|
+
for (const key in v) {
|
|
113
|
+
if (out.length >= max) break;
|
|
114
|
+
if (!first) out += ",";
|
|
115
|
+
first = false;
|
|
116
|
+
out += `${JSON.stringify(key.slice(0, 50))}:`;
|
|
117
|
+
walk((v as Record<string, unknown>)[key], depth + 1);
|
|
118
|
+
}
|
|
119
|
+
out += "}";
|
|
120
|
+
};
|
|
121
|
+
walk(value, 0);
|
|
122
|
+
return out.slice(0, max);
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/** GTA vehicle class (`GetVehicleClassFromName`) -> the type `CreateVehicleServerSetter` wants. */
|
|
126
|
+
export function vehicleTypeOfClass(vehicleClass: number): string {
|
|
127
|
+
switch (vehicleClass) {
|
|
128
|
+
case 8:
|
|
129
|
+
case 13:
|
|
130
|
+
return "bike";
|
|
131
|
+
case 14:
|
|
132
|
+
return "boat";
|
|
133
|
+
case 15:
|
|
134
|
+
return "heli";
|
|
135
|
+
case 16:
|
|
136
|
+
return "plane";
|
|
137
|
+
case 21:
|
|
138
|
+
return "train";
|
|
139
|
+
default:
|
|
140
|
+
return "automobile";
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/** One parsed value as an `args` result: `[value]`, or null to refuse the call. */
|
|
145
|
+
export const asArgs = <T>(value: T | null): [T] | null =>
|
|
146
|
+
value === null ? null : [value];
|
|
147
|
+
|
|
148
|
+
export interface Logger {
|
|
149
|
+
info(message: string, ...details: unknown[]): void;
|
|
150
|
+
warn(message: string, ...details: unknown[]): void;
|
|
151
|
+
error(message: string, ...details: unknown[]): void;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/** Console output prefixed with the resource name, so server logs show where a line came from. */
|
|
155
|
+
export function createLogger(resource: string): Logger {
|
|
156
|
+
const prefix = `[${resource}]`;
|
|
157
|
+
return {
|
|
158
|
+
info: (message, ...details) =>
|
|
159
|
+
console.log(`${prefix} ${message}`, ...details),
|
|
160
|
+
warn: (message, ...details) =>
|
|
161
|
+
console.warn(`${prefix} ^3${message}^7`, ...details),
|
|
162
|
+
error: (message, ...details) =>
|
|
163
|
+
console.error(`${prefix} ^1${message}^7`, ...details),
|
|
164
|
+
};
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/** A data file's `"$schema"` key is for editors only: readers of panel files never see it. */
|
|
168
|
+
export function withoutSchemaKey(value: unknown): unknown {
|
|
169
|
+
if (!isRecord(value) || !("$schema" in value)) return value;
|
|
170
|
+
const { $schema: _schema, ...rest } = value;
|
|
171
|
+
return rest;
|
|
172
|
+
}
|
|
173
|
+
export {
|
|
174
|
+
PLACE_PED_SPEC,
|
|
175
|
+
placePedFields,
|
|
176
|
+
readPlacePed,
|
|
177
|
+
type PlacePed,
|
|
178
|
+
} from "./placePed";
|
|
179
|
+
export { cellKey, gridCell } from "./grid";
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/** Fills `{0}`, `{1}`... with the arguments by position (a translation may reorder or repeat them). */
|
|
2
|
+
export function formatText(
|
|
3
|
+
template: string,
|
|
4
|
+
args: ReadonlyArray<string | number>,
|
|
5
|
+
): string {
|
|
6
|
+
return template.replace(/\{(\d+)\}/g, (match, index: string) => {
|
|
7
|
+
const value = args[Number(index)];
|
|
8
|
+
return value === undefined ? match : String(value);
|
|
9
|
+
});
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* A NUI page's lang texts (its client sends them with the screen): `translate` fills `{0}` placeholders and answers
|
|
14
|
+
* the key itself when a text is missing; `subscribe` / `snapshot` fit React's `useSyncExternalStore`. Methods are
|
|
15
|
+
* bound, so they can be passed around as plain functions.
|
|
16
|
+
*/
|
|
17
|
+
export class LangTexts {
|
|
18
|
+
private texts: Record<string, string> = {};
|
|
19
|
+
private readonly listeners = new Set<() => void>();
|
|
20
|
+
|
|
21
|
+
/** Replaces every text and tells the subscribers. */
|
|
22
|
+
readonly set = (next: Record<string, string>): void => {
|
|
23
|
+
this.texts = next;
|
|
24
|
+
for (const listener of this.listeners) listener();
|
|
25
|
+
};
|
|
26
|
+
|
|
27
|
+
/** The text of `key` with `{0}`, `{1}`... filled in; the key itself when it is missing. */
|
|
28
|
+
readonly translate = (key: string, ...args: Array<string | number>): string =>
|
|
29
|
+
formatText(this.texts[key] ?? key, args);
|
|
30
|
+
|
|
31
|
+
/** Calls `listener` after each `set`; answers the unsubscribe function. */
|
|
32
|
+
readonly subscribe = (listener: () => void): (() => void) => {
|
|
33
|
+
this.listeners.add(listener);
|
|
34
|
+
return () => this.listeners.delete(listener);
|
|
35
|
+
};
|
|
36
|
+
|
|
37
|
+
/** The current texts (a new object after each `set`). */
|
|
38
|
+
readonly snapshot = (): Record<string, string> => this.texts;
|
|
39
|
+
}
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import type { DataSpec, WidgetSpec } from "@aifivem/shared";
|
|
2
|
+
|
|
3
|
+
const isRecord = (v: unknown): v is Record<string, unknown> =>
|
|
4
|
+
typeof v === "object" && v !== null && !Array.isArray(v);
|
|
5
|
+
|
|
6
|
+
/** An NPC standing at a place (a shopkeeper, a clerk): its model, an optional idle scenario and where it stands. */
|
|
7
|
+
export interface PlacePed {
|
|
8
|
+
model: string;
|
|
9
|
+
scenario?: string;
|
|
10
|
+
coords?: { x: number; y: number; z: number; heading: number };
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
/** Idle scenarios offered in the panel ("" = stands still). */
|
|
14
|
+
const SCENARIOS = [
|
|
15
|
+
"",
|
|
16
|
+
"WORLD_HUMAN_STAND_IMPATIENT",
|
|
17
|
+
"WORLD_HUMAN_CLIPBOARD",
|
|
18
|
+
"WORLD_HUMAN_STAND_MOBILE",
|
|
19
|
+
"WORLD_HUMAN_AA_COFFEE",
|
|
20
|
+
"WORLD_HUMAN_SMOKING",
|
|
21
|
+
"WORLD_HUMAN_GUARD_STAND",
|
|
22
|
+
"WORLD_HUMAN_COP_IDLES",
|
|
23
|
+
"WORLD_HUMAN_HANG_OUT_STREET",
|
|
24
|
+
] as const;
|
|
25
|
+
|
|
26
|
+
/** The data spec of a place's `ped` section (optional: a place without one has no NPC). */
|
|
27
|
+
export const PLACE_PED_SPEC: DataSpec = {
|
|
28
|
+
type: "object",
|
|
29
|
+
optional: true,
|
|
30
|
+
fields: {
|
|
31
|
+
model: { type: "text", max: 64, optional: true },
|
|
32
|
+
scenario: { type: "enum", values: [...SCENARIOS], optional: true },
|
|
33
|
+
coords: { type: "vec4", optional: true },
|
|
34
|
+
},
|
|
35
|
+
};
|
|
36
|
+
|
|
37
|
+
/** The panel fields of a place's NPC (labels and hints are ai-core's generic panel texts). */
|
|
38
|
+
export function placePedFields(path = "ped"): WidgetSpec[] {
|
|
39
|
+
return [
|
|
40
|
+
{
|
|
41
|
+
widget: "model",
|
|
42
|
+
kind: "ped",
|
|
43
|
+
path: `${path}.model`,
|
|
44
|
+
label: "ADMIN_F_PED_MODEL",
|
|
45
|
+
hint: "ADMIN_H_PED_MODEL",
|
|
46
|
+
placeholder: "ADMIN_PH_PED_MODEL",
|
|
47
|
+
},
|
|
48
|
+
{
|
|
49
|
+
widget: "select",
|
|
50
|
+
path: `${path}.scenario`,
|
|
51
|
+
label: "ADMIN_F_PED_SCENARIO",
|
|
52
|
+
hint: "ADMIN_H_PED_SCENARIO",
|
|
53
|
+
options: SCENARIOS.map((value) => ({
|
|
54
|
+
value,
|
|
55
|
+
label: value ? `ADMIN_O_SCENARIO_${value}` : "ADMIN_O_SCENARIO_NONE",
|
|
56
|
+
})),
|
|
57
|
+
},
|
|
58
|
+
{
|
|
59
|
+
widget: "point",
|
|
60
|
+
path: `${path}.coords`,
|
|
61
|
+
heading: true,
|
|
62
|
+
ground: true,
|
|
63
|
+
label: "ADMIN_F_PED_POSITION",
|
|
64
|
+
hint: "ADMIN_H_PED_POSITION",
|
|
65
|
+
},
|
|
66
|
+
];
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** A place's NPC from panel data; null when it has no model (no NPC). */
|
|
70
|
+
export function readPlacePed(value: unknown): PlacePed | null {
|
|
71
|
+
if (
|
|
72
|
+
!isRecord(value) ||
|
|
73
|
+
typeof value.model !== "string" ||
|
|
74
|
+
!value.model.trim()
|
|
75
|
+
)
|
|
76
|
+
return null;
|
|
77
|
+
const c = value.coords;
|
|
78
|
+
const coords =
|
|
79
|
+
isRecord(c) &&
|
|
80
|
+
[c.x, c.y, c.z, c.heading].every((n) => typeof n === "number")
|
|
81
|
+
? {
|
|
82
|
+
x: Number(c.x),
|
|
83
|
+
y: Number(c.y),
|
|
84
|
+
z: Number(c.z),
|
|
85
|
+
heading: Number(c.heading),
|
|
86
|
+
}
|
|
87
|
+
: undefined;
|
|
88
|
+
return {
|
|
89
|
+
model: value.model.trim(),
|
|
90
|
+
scenario:
|
|
91
|
+
typeof value.scenario === "string" && value.scenario
|
|
92
|
+
? value.scenario
|
|
93
|
+
: undefined,
|
|
94
|
+
coords,
|
|
95
|
+
};
|
|
96
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/** A whole number from `min` to `max`, both included. */
|
|
2
|
+
export const randomInt = (min: number, max: number): number =>
|
|
3
|
+
min + Math.floor(Math.random() * (max - min + 1));
|
|
4
|
+
|
|
5
|
+
/** One random item of a list, undefined when it is empty. */
|
|
6
|
+
export const pickRandom = <T>(list: readonly T[]): T | undefined =>
|
|
7
|
+
list[Math.floor(Math.random() * list.length)];
|
|
8
|
+
|
|
9
|
+
/** True with a chance of `percent` (0-100). */
|
|
10
|
+
export const rollChance = (percent: number): boolean =>
|
|
11
|
+
Math.random() * 100 < percent;
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
/** Small readers for panel content (`data/*.json`): every one returns the fallback when the value is missing or wrong. */
|
|
2
|
+
|
|
3
|
+
/** A finite number clamped to `[min, max]`, else the fallback. */
|
|
4
|
+
export function num(
|
|
5
|
+
value: unknown,
|
|
6
|
+
fallback: number,
|
|
7
|
+
min = -Infinity,
|
|
8
|
+
max = Infinity,
|
|
9
|
+
): number {
|
|
10
|
+
return typeof value === "number" && Number.isFinite(value)
|
|
11
|
+
? Math.min(max, Math.max(min, value))
|
|
12
|
+
: fallback;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/** `num` rounded to an integer. */
|
|
16
|
+
export function int(
|
|
17
|
+
value: unknown,
|
|
18
|
+
fallback: number,
|
|
19
|
+
min = -Infinity,
|
|
20
|
+
max = Infinity,
|
|
21
|
+
): number {
|
|
22
|
+
return Math.round(num(value, fallback, min, max));
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** A boolean, else the fallback. */
|
|
26
|
+
export function bool(value: unknown, fallback: boolean): boolean {
|
|
27
|
+
return typeof value === "boolean" ? value : fallback;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** A trimmed non-empty string cut to `max`, else the fallback. */
|
|
31
|
+
export function str(value: unknown, fallback: string, max = 64): string {
|
|
32
|
+
return typeof value === "string" && value.trim()
|
|
33
|
+
? value.trim().slice(0, max)
|
|
34
|
+
: fallback;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** The value as a plain object, or an empty one. */
|
|
38
|
+
export function record(value: unknown): Record<string, unknown> {
|
|
39
|
+
return typeof value === "object" && value !== null && !Array.isArray(value)
|
|
40
|
+
? (value as Record<string, unknown>)
|
|
41
|
+
: {};
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
export interface Vec4 {
|
|
45
|
+
x: number;
|
|
46
|
+
y: number;
|
|
47
|
+
z: number;
|
|
48
|
+
heading: number;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** A position with heading; each missing field comes from the fallback. */
|
|
52
|
+
export function vec4(value: unknown, fallback: Vec4): Vec4 {
|
|
53
|
+
const v = record(value);
|
|
54
|
+
return {
|
|
55
|
+
x: num(v.x, fallback.x),
|
|
56
|
+
y: num(v.y, fallback.y),
|
|
57
|
+
z: num(v.z, fallback.z),
|
|
58
|
+
heading: num(v.heading, fallback.heading),
|
|
59
|
+
};
|
|
60
|
+
}
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
/** A reader of one panel record: the parsed value, or null to leave the record out. */
|
|
2
|
+
export type RecordReader<T> = (
|
|
3
|
+
key: string,
|
|
4
|
+
raw: Record<string, unknown>,
|
|
5
|
+
) => T | null;
|
|
6
|
+
|
|
7
|
+
const isObject = (value: unknown): value is Record<string, unknown> =>
|
|
8
|
+
typeof value === "object" && value !== null && !Array.isArray(value);
|
|
9
|
+
|
|
10
|
+
/** `{ key: record }` -> Map through a per-record reader (null or a non-object drops the record). */
|
|
11
|
+
export function readRecords<T>(
|
|
12
|
+
raw: unknown,
|
|
13
|
+
readOne: RecordReader<T>,
|
|
14
|
+
): Map<string, T> {
|
|
15
|
+
const out = new Map<string, T>();
|
|
16
|
+
if (!isObject(raw)) return out;
|
|
17
|
+
for (const key in raw) {
|
|
18
|
+
const value = raw[key];
|
|
19
|
+
if (!isObject(value)) continue;
|
|
20
|
+
const parsed = readOne(key, value);
|
|
21
|
+
if (parsed !== null) out.set(key, parsed);
|
|
22
|
+
}
|
|
23
|
+
return out;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Parsed views of panel files (`AdminPanel` and `AdminWorld` use it): each view is updated on a change before the
|
|
28
|
+
* file's `onChange` handlers run, so a handler reads the new parsed value.
|
|
29
|
+
*/
|
|
30
|
+
export class FileViews {
|
|
31
|
+
private readonly updaters = new Map<
|
|
32
|
+
string,
|
|
33
|
+
Array<(key: string | undefined, value: unknown) => void>
|
|
34
|
+
>();
|
|
35
|
+
|
|
36
|
+
/** `read(file)`: the file's current raw content. */
|
|
37
|
+
constructor(private readonly read: (file: string) => unknown) {}
|
|
38
|
+
|
|
39
|
+
/** A file parsed by `parse`, parsed again on every change (settings files). */
|
|
40
|
+
view<T>(file: string, parse: (raw: unknown) => T): { readonly value: T } {
|
|
41
|
+
const box = { value: parse(this.read(file)) };
|
|
42
|
+
this.on(file, () => (box.value = parse(this.read(file))));
|
|
43
|
+
return box;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** A records file parsed per record; a change parses only the changed record. */
|
|
47
|
+
records<T>(file: string, readOne: RecordReader<T>): ReadonlyMap<string, T> {
|
|
48
|
+
const live = new LiveRecords(readOne);
|
|
49
|
+
live.reset(this.read(file));
|
|
50
|
+
this.on(file, (key, value) => live.update(key, value, this.read(file)));
|
|
51
|
+
return live.map;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** A record of `file` changed (records: its key, `null` = deleted; settings: no key). */
|
|
55
|
+
changed(file: string, key: string | undefined, value: unknown): void {
|
|
56
|
+
for (const update of this.updaters.get(file) ?? []) update(key, value);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
private on(
|
|
60
|
+
file: string,
|
|
61
|
+
update: (key: string | undefined, value: unknown) => void,
|
|
62
|
+
): void {
|
|
63
|
+
const list = this.updaters.get(file);
|
|
64
|
+
if (list) list.push(update);
|
|
65
|
+
else this.updaters.set(file, [update]);
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* A records file parsed record by record and kept current one key at a time (`AdminPanel.records`,
|
|
71
|
+
* `AdminWorld.records`): a full read at start, O(1) per changed record afterwards.
|
|
72
|
+
*/
|
|
73
|
+
export class LiveRecords<T> {
|
|
74
|
+
readonly map = new Map<string, T>();
|
|
75
|
+
|
|
76
|
+
constructor(private readonly readOne: RecordReader<T>) {}
|
|
77
|
+
|
|
78
|
+
/** Reads the whole file again. */
|
|
79
|
+
reset(raw: unknown): void {
|
|
80
|
+
this.map.clear();
|
|
81
|
+
for (const [key, value] of readRecords(raw, this.readOne))
|
|
82
|
+
this.map.set(key, value);
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** One record changed (`null` = deleted); `key` undefined means the whole file was replaced by `whole`. */
|
|
86
|
+
update(key: string | undefined, value: unknown, whole: unknown): void {
|
|
87
|
+
if (key === undefined) return this.reset(whole);
|
|
88
|
+
const parsed = isObject(value) ? this.readOne(key, value) : null;
|
|
89
|
+
if (parsed === null) this.map.delete(key);
|
|
90
|
+
else this.map.set(key, parsed);
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** What `RecordObjects` needs of a panel store: `AdminWorld` (client) and `AdminPanel` (server) both fit. */
|
|
95
|
+
export interface RecordSource {
|
|
96
|
+
records<T>(file: string, readOne: RecordReader<T>): ReadonlyMap<string, T>;
|
|
97
|
+
onChange(
|
|
98
|
+
file: string,
|
|
99
|
+
handler: (key: string | undefined, value: unknown) => void,
|
|
100
|
+
): void;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* The world objects of a records file (points, blips, peds, zones) kept in step one record at a time: `build(key,
|
|
105
|
+
* record)` makes one record's objects and returns how to remove them; an edited record removes and rebuilds only its
|
|
106
|
+
* own objects, a deleted one only removes them. A setting every record reads (a blip style) calls `rebuildAll()`.
|
|
107
|
+
* Never `clear()` + add everything on a change: with 10k records one edit would rebuild 10k objects on every client.
|
|
108
|
+
* `records` is a reader, or a view the script already keeps of the same file (`source.records(file, readOne)`), so
|
|
109
|
+
* each edit is parsed once.
|
|
110
|
+
*/
|
|
111
|
+
export class RecordObjects<T> {
|
|
112
|
+
readonly records: ReadonlyMap<string, T>;
|
|
113
|
+
private readonly built = new Map<string, () => void>();
|
|
114
|
+
|
|
115
|
+
constructor(
|
|
116
|
+
source: RecordSource,
|
|
117
|
+
file: string,
|
|
118
|
+
records: RecordReader<T> | ReadonlyMap<string, T>,
|
|
119
|
+
private readonly build: (key: string, record: T) => (() => void) | void,
|
|
120
|
+
) {
|
|
121
|
+
this.records =
|
|
122
|
+
typeof records === "function" ? source.records(file, records) : records;
|
|
123
|
+
source.onChange(file, (key) =>
|
|
124
|
+
key === undefined ? this.rebuildAll() : this.rebuild(key),
|
|
125
|
+
);
|
|
126
|
+
this.rebuildAll();
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/** Removes and builds again one record's objects (its current value; gone when the record is). */
|
|
130
|
+
rebuild(key: string): void {
|
|
131
|
+
this.built.get(key)?.();
|
|
132
|
+
this.built.delete(key);
|
|
133
|
+
const record = this.records.get(key);
|
|
134
|
+
if (record === undefined) return;
|
|
135
|
+
const remove = this.build(key, record);
|
|
136
|
+
if (remove) this.built.set(key, remove);
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/** Every record again (a shared setting changed, or the whole file was replaced). */
|
|
140
|
+
rebuildAll(): void {
|
|
141
|
+
for (const remove of this.built.values()) remove();
|
|
142
|
+
this.built.clear();
|
|
143
|
+
for (const [key, record] of this.records) {
|
|
144
|
+
const remove = this.build(key, record);
|
|
145
|
+
if (remove) this.built.set(key, remove);
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
}
|