@aifivem/shared 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 (52) hide show
  1. package/package.json +23 -4
  2. package/src/action.ts +6 -0
  3. package/src/admin/dataSpec.ts +63 -0
  4. package/src/admin/events.ts +45 -0
  5. package/src/admin/lookups.ts +29 -0
  6. package/src/admin/panel.ts +105 -0
  7. package/src/admin/schema.ts +58 -0
  8. package/src/admin/widgets.ts +123 -0
  9. package/src/appearance.ts +115 -0
  10. package/src/banking.ts +58 -0
  11. package/src/bans.ts +91 -0
  12. package/src/billing.ts +112 -0
  13. package/src/characters.ts +71 -0
  14. package/src/commands.ts +80 -0
  15. package/src/core.ts +125 -0
  16. package/src/deaths.ts +44 -0
  17. package/src/definitions.ts +26 -0
  18. package/src/dispatch.ts +103 -0
  19. package/src/doorlock.ts +29 -0
  20. package/src/ems.ts +50 -0
  21. package/src/exports/aiInventory.ts +96 -0
  22. package/src/exports/citizen.ts +45 -0
  23. package/src/exports/coreCharacters.ts +167 -0
  24. package/src/exports/coreClient.ts +79 -0
  25. package/src/exports/coreGroups.ts +29 -0
  26. package/src/exports/coreLayers.ts +45 -0
  27. package/src/exports/coreMoney.ts +97 -0
  28. package/src/exports/coreServer.ts +91 -0
  29. package/src/exports/coreServices.ts +60 -0
  30. package/src/exports/resources.ts +107 -0
  31. package/src/fuel.ts +48 -0
  32. package/src/garages.ts +101 -0
  33. package/src/index.ts +49 -0
  34. package/src/inventory/adapters.ts +86 -0
  35. package/src/inventory/exports.ts +92 -0
  36. package/src/inventory/items.ts +92 -0
  37. package/src/logs.ts +45 -0
  38. package/src/mdt.ts +78 -0
  39. package/src/medical.ts +18 -0
  40. package/src/menu.ts +94 -0
  41. package/src/minigame.ts +45 -0
  42. package/src/multichar.ts +44 -0
  43. package/src/phone.ts +39 -0
  44. package/src/player.ts +159 -0
  45. package/src/radial.ts +44 -0
  46. package/src/ui.ts +92 -0
  47. package/src/validation.ts +82 -0
  48. package/src/vehicleKeys.ts +78 -0
  49. package/src/vehicles.ts +117 -0
  50. package/src/vrp.ts +51 -0
  51. package/src/world.ts +26 -0
  52. package/README.md +0 -3
package/package.json CHANGED
@@ -1,6 +1,25 @@
1
1
  {
2
2
  "name": "@aifivem/shared",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.6.0",
4
+ "description": "Contracts shared between ai-core resources: event names, payload types, export types.",
5
+ "license": "GPL-3.0-only",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/aifivem/aicore-packages.git",
9
+ "directory": "shared"
10
+ },
11
+ "type": "module",
12
+ "exports": {
13
+ ".": "./src/index.ts"
14
+ },
15
+ "files": [
16
+ "src"
17
+ ],
18
+ "publishConfig": {
19
+ "access": "public"
20
+ },
21
+ "devDependencies": {
22
+ "@citizenfx/client": "latest",
23
+ "@citizenfx/server": "latest"
24
+ }
25
+ }
package/src/action.ts ADDED
@@ -0,0 +1,6 @@
1
+ /**
2
+ * What every client action answers: ok, or a lang key the client shows. Extra fields ride on the ok branch
3
+ * (`ActionResult<{ id: number }>`); the new state itself arrives as a delta, never in the reply.
4
+ */
5
+ export type ActionResult<T extends object = object> =
6
+ ({ ok: true } & T) | { ok: false; error: string };
@@ -0,0 +1,63 @@
1
+ import type { LookupSource } from "./lookups";
2
+
3
+ /** Data model of one value (server validation). Every spec may be `optional` (absent allowed). */
4
+ export type DataSpec =
5
+ | {
6
+ type: "text";
7
+ min?: number;
8
+ max?: number;
9
+ pattern?: string;
10
+ lookup?: LookupSource;
11
+ /** The key of a record in another `records` file of the same panel ("" allowed: none). */
12
+ records?: string;
13
+ optional?: boolean;
14
+ }
15
+ | {
16
+ type: "number";
17
+ min?: number;
18
+ max?: number;
19
+ integer?: boolean;
20
+ optional?: boolean;
21
+ }
22
+ | { type: "bool"; optional?: boolean }
23
+ | { type: "enum"; values: Array<string | number>; optional?: boolean }
24
+ | {
25
+ type: "names";
26
+ max?: number;
27
+ itemMax?: number;
28
+ pattern?: string;
29
+ lookup?: LookupSource;
30
+ optional?: boolean;
31
+ }
32
+ | { type: "vec3"; optional?: boolean }
33
+ | { type: "vec4"; optional?: boolean }
34
+ | { type: "object"; fields: Record<string, DataSpec>; optional?: boolean }
35
+ | {
36
+ type: "list";
37
+ of: DataSpec;
38
+ min?: number;
39
+ max?: number;
40
+ optional?: boolean;
41
+ };
42
+
43
+ /**
44
+ * A data file: `settings` is one object (its top-level keys are the sections), `records` is `{ key: record }`.
45
+ * `sync: "all"` files are in the resource's `files` and every client mirrors them; `"admin"` files stay on the server.
46
+ */
47
+ export interface FileSpec {
48
+ kind: "settings" | "records";
49
+ sync: "all" | "admin";
50
+ sections: Record<string, DataSpec>;
51
+ /** records: allowed keys (default lowercase letters, digits, underscores, 2-32 long). */
52
+ keyPattern?: string;
53
+ /** records: section holding the name shown in lists and dialogs. */
54
+ labelPath?: string;
55
+ /** records: the new record a create starts from (the typed name goes to `labelPath`). */
56
+ newRecord?: Record<string, unknown>;
57
+ /** records: keys that can never be deleted (e.g. the unemployed job). */
58
+ locked?: string[];
59
+ /** settings: sections a file is missing are filled from here at load (a setting added in an update). */
60
+ defaults?: Record<string, unknown>;
61
+ /** Runtime state the script fills with `commit` (a live list the panel shows): never read from or saved to disk, never edited in the panel. */
62
+ memory?: boolean;
63
+ }
@@ -0,0 +1,45 @@
1
+ /** Where `ADMIN.showEvent` opens the panel: the Bans section (with a search) or a character in the Players section. */
2
+ export type AdminShowTarget =
3
+ | { section: "bans"; search?: string }
4
+ | { section: "players"; charId?: number };
5
+
6
+ /** An `AdminShowTarget` from the network; null when it is not one. */
7
+ export function toAdminShowTarget(value: unknown): AdminShowTarget | null {
8
+ if (typeof value !== "object" || value === null) return null;
9
+ const v = value as Record<string, unknown>;
10
+ if (v.section === "bans")
11
+ return typeof v.search === "string" && v.search.length <= 64
12
+ ? { section: "bans", search: v.search }
13
+ : { section: "bans" };
14
+ if (v.section === "players")
15
+ return typeof v.charId === "number" && Number.isInteger(v.charId)
16
+ ? { section: "players", charId: v.charId }
17
+ : { section: "players" };
18
+ return null;
19
+ }
20
+
21
+ /** Event names of the admin panel (owned by ai-core). */
22
+ export const ADMIN = {
23
+ /** ACE every panel action checks: `add_ace group.admin ai.admin allow`. */
24
+ ace: "ai.admin",
25
+ /** Callback: (keybinds: KeybindInfo[] the admin's client knows) -> AdminOpenData (each script's summary). */
26
+ openCallback: "ai-core:admin:open",
27
+ /** Callback: (resource) -> the script's whole panel data, asked when the admin opens that script. */
28
+ panelDataCallback: "ai-core:admin:panelData",
29
+ applyCallback: "ai-core:admin:apply",
30
+ closeEvent: "ai-core:admin:close",
31
+ /**
32
+ * Server -> client: (target?: AdminShowTarget) open the panel (the `aiadmin` command, other admin tools; checked on
33
+ * the server), on a section when `target` is given.
34
+ */
35
+ showEvent: "ai-core:admin:show",
36
+ /** Server -> admins with the panel open: (delta: AdminDelta). */
37
+ deltaEvent: "ai-core:admin:delta",
38
+ /** Server -> admins with the panel open: (delta: RecommendationDelta). */
39
+ recommendationEvent: "ai-core:admin:recommendation",
40
+ /** Server -> client of a world (`sync: "all"`) file: (file, key | null, value). Prefixed with the resource name. */
41
+ worldEvent: (resource: string): string => `${resource}:admin:world`,
42
+ /** Callback: () -> { [file]: { key: value } } world records changed since the resource started. */
43
+ worldChangesCallback: (resource: string): string =>
44
+ `${resource}:admin:worldChanges`,
45
+ } as const;
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Values a field picks from what exists in the game: items of the active inventory, jobs, gangs, money accounts.
3
+ * A `lookup` on a text or names spec makes the server refuse anything else and the panel offer the list.
4
+ */
5
+ /**
6
+ * Lists the panel offers: the server's (items, jobs, gangs, accounts, started resources, online players by citizen id)
7
+ * and the admin game's (`vehicle`: every vehicle model it has, addons included; `ped`: GTA's ped models). The server
8
+ * cannot list game models, so those two never refuse a value.
9
+ */
10
+ export type LookupSource =
11
+ | "item"
12
+ | "job"
13
+ | "gang"
14
+ | "account"
15
+ | "resource"
16
+ | "player"
17
+ | "vehicle"
18
+ | "ped";
19
+
20
+ /** One choice of a lookup list. */
21
+ export interface LookupOption {
22
+ value: string;
23
+ label: string;
24
+ /** Jobs and gangs: the grade names, the grade number is the index (the `grade` widget lists them). */
25
+ grades?: string[];
26
+ }
27
+
28
+ /** Every lookup list, sent with the panel when it opens. */
29
+ export type Lookups = Record<LookupSource, LookupOption[]>;
@@ -0,0 +1,105 @@
1
+ import type { Lookups } from "./lookups";
2
+ import type { PanelSchema } from "./schema";
3
+
4
+ /** One edit, the same shape on every hop. */
5
+ export type AdminPatch =
6
+ | {
7
+ file: string;
8
+ action: "set";
9
+ key?: string;
10
+ section: string;
11
+ value: unknown;
12
+ }
13
+ | { file: string; action: "create"; key: string; label: string }
14
+ | { file: string; action: "delete"; key: string }
15
+ /** Whole records from the panel's JSON import (all or none): added, or put in place of the records with those keys. */
16
+ | {
17
+ file: string;
18
+ action: "import";
19
+ records: Record<string, Record<string, unknown>>;
20
+ }
21
+ /** An `action` widget's button: runs the script's `panel.onAction(id, ...)` handler on the record; stores nothing itself. */
22
+ | { file: string; action: "run"; key?: string; id: string };
23
+
24
+ export type AdminResult = import("../action").ActionResult;
25
+
26
+ /** What the panel gets per script when it opens: the schema, the script's lang texts and its current data. */
27
+ export interface AdminPanelSnapshot {
28
+ resource: string;
29
+ schema: PanelSchema;
30
+ texts: Record<string, string>;
31
+ /** Every file when `loaded`; only the settings files in the open summary. */
32
+ data: Record<string, unknown>;
33
+ /** False in the open summary: the records files come with `ADMIN.panelDataCallback` when the script is opened. */
34
+ loaded?: boolean;
35
+ /** Records files' labels by key (the global search while the records are not loaded). */
36
+ index?: Record<string, Record<string, string>>;
37
+ }
38
+
39
+ /**
40
+ * Another script's own settings screen listed on ai-core's dashboard: opened by its command (`command`, run on the
41
+ * admin's client after ai-core's panel closes) or embedded as a page (`url`, e.g. `https://cfx-nui-<resource>/ui/index.html`).
42
+ */
43
+ export interface ExternalPanel {
44
+ id: string;
45
+ resource: string;
46
+ label: string;
47
+ icon?: string;
48
+ description?: string;
49
+ command?: string;
50
+ url?: string;
51
+ }
52
+
53
+ /** What ai-core answers when an admin opens the panel. */
54
+ /** A script whose GitHub release is newer than the version running (ai-core's update check). */
55
+ export interface UpdateInfo {
56
+ resource: string;
57
+ /** The name people know it by (`monitor` is txAdmin). */
58
+ label: string;
59
+ current: string;
60
+ latest: string;
61
+ url: string;
62
+ }
63
+
64
+ /** A script ai-core recommends on the dashboard while its condition holds and the owner has not dismissed it. */
65
+ export interface Recommendation {
66
+ id: string;
67
+ /** ai-core lang keys: the script's name and one line why. */
68
+ title: string;
69
+ desc: string;
70
+ url: string;
71
+ /** Free to get: the card shows a "Free" chip. */
72
+ free: boolean;
73
+ }
74
+
75
+ /** A recommendation that starts showing (`value`) or stops (`null`). */
76
+ export interface RecommendationDelta {
77
+ id: string;
78
+ value: Recommendation | null;
79
+ }
80
+
81
+ export interface AdminOpenData {
82
+ panels: AdminPanelSnapshot[];
83
+ lookups: Lookups;
84
+ external: ExternalPanel[];
85
+ updates: UpdateInfo[];
86
+ recommendations: Recommendation[];
87
+ }
88
+
89
+ /** A changed record (records: `key`; settings: no key, `value` is the whole object); `null` = deleted. */
90
+ export interface AdminDelta {
91
+ resource: string;
92
+ file: string;
93
+ key?: string;
94
+ value: unknown;
95
+ }
96
+
97
+ /** Exports each panel resource answers for ai-core (registered by the lib's AdminPanel). */
98
+ export type AdminPanelResourceExports = {
99
+ AdminPanelSnapshot(): AdminPanelSnapshot;
100
+ /** Every file's content (`AdminPanelSnapshot().data` without building schema and texts). */
101
+ AdminPanelData(): Record<string, unknown>;
102
+ /** Schema, texts, settings files and the records' label index: what the panel needs at opening. */
103
+ AdminPanelSummary(): AdminPanelSnapshot;
104
+ AdminPanelApply(admin: number, patch: unknown): AdminResult;
105
+ };
@@ -0,0 +1,58 @@
1
+ /**
2
+ * Admin panel contract: every ai-* resource describes its panel content in one JSON-safe schema; ai-core hosts the
3
+ * panel, the resource keeps, validates and saves its own `data/*.json` (the lib's `AdminPanel`).
4
+ */
5
+
6
+ import type { FileSpec } from "./dataSpec";
7
+ import type { ValueLabels, WidgetSpec } from "./widgets";
8
+
9
+ /** A column of a read-only table tab: the value at `path` of each record. */
10
+ export interface TableColumn extends ValueLabels {
11
+ path: string;
12
+ /** Lang key of the header. */
13
+ label: string;
14
+ /** Relative width (default 1). */
15
+ width?: number;
16
+ mono?: boolean;
17
+ }
18
+
19
+ export interface TableSpec {
20
+ columns: TableColumn[];
21
+ /** Path the rows are sorted by (default the record key). */
22
+ sort?: string;
23
+ }
24
+
25
+ export interface CardSpec {
26
+ /** Font Awesome solid icon name without `fa-` (e.g. "briefcase"). */
27
+ icon: string;
28
+ title: string;
29
+ desc?: string;
30
+ fields: WidgetSpec[];
31
+ }
32
+
33
+ export interface TabSpec {
34
+ id: string;
35
+ file: string;
36
+ icon: string;
37
+ label: string;
38
+ /** One sentence: what this tab sets up in the game. */
39
+ desc: string;
40
+ cards: CardSpec[];
41
+ /** records: a second line in list rows (path of a value). */
42
+ listSub?: string;
43
+ /** records: lang keys of the create button and of the delete button (a short verb, also the dialog's action). */
44
+ createLabel?: string;
45
+ deleteLabel?: string;
46
+ /** records: lang key of what deleting a record leaves behind, shown in the delete dialog (default: the generic text). */
47
+ deleteDesc?: string;
48
+ /** records: show the file as one read-only, searchable table (a row per record) instead of list + editor; `cards` stays empty. */
49
+ table?: TableSpec;
50
+ }
51
+
52
+ export interface PanelSchema {
53
+ /** Lang key of the script's name in the panel sidebar. */
54
+ title: string;
55
+ icon: string;
56
+ files: Record<string, FileSpec>;
57
+ tabs: TabSpec[];
58
+ }
@@ -0,0 +1,123 @@
1
+ import type { LookupSource } from "./lookups";
2
+
3
+ /** Controls of the panel; `path` is dotted from the record (or the settings object), a write replaces its section. */
4
+ export type WidgetSpec = WidgetBase &
5
+ (
6
+ | {
7
+ widget: "text";
8
+ placeholder?: string;
9
+ /** Pick from a lookup list (autocomplete; the data spec carries the same lookup). */
10
+ lookup?: LookupSource;
11
+ /** Pick a record of another `records` file of this panel by its label (the data spec carries the same `records`). */
12
+ records?: string;
13
+ /** Name suggestions (a button inside the box lists them): street and zone names at the point at `from` (a path in the same record), else at the admin. */
14
+ suggest?: { from?: string };
15
+ }
16
+ | {
17
+ widget: "number";
18
+ min?: number;
19
+ max?: number;
20
+ step?: number;
21
+ unit?: string;
22
+ }
23
+ | { widget: "switch" }
24
+ | {
25
+ widget: "select";
26
+ options: Array<{ value: string | number; label: string }>;
27
+ }
28
+ | { widget: "tags"; placeholder?: string; lookup?: LookupSource }
29
+ | {
30
+ widget: "point";
31
+ heading?: boolean;
32
+ /** "camera": "Use my position" takes the game camera instead of the ped. */
33
+ from?: "camera";
34
+ /** The point is on the floor (teleported to with SetEntityCoords); without it the ped's own root height. */
35
+ ground?: boolean;
36
+ }
37
+ | {
38
+ widget: "list";
39
+ /** Row controls: `text`, `number`, `switch`, `select`, `grade`, `point`; a row control's `showIf` path is read in its row. */
40
+ rows: WidgetSpec[];
41
+ newRow: Record<string, unknown>;
42
+ addLabel: string;
43
+ rowLabel?: string;
44
+ max?: number;
45
+ /** Fewest rows the remove button leaves (default 1). */
46
+ min?: number;
47
+ /** Long lists: a search box over the rows' values, newest rows first, 50 shown at a time. */
48
+ search?: boolean;
49
+ /** Rows with more controls than fit on one line wrap onto the next. */
50
+ wrap?: boolean;
51
+ }
52
+ /**
53
+ * A job or gang grade (data: the grade number): a select of the grade names of the job or gang named at `of` (a
54
+ * path in the same record, or in the same row inside a `list`), from the `lookup` list.
55
+ */
56
+ | { widget: "grade"; of: string; lookup: "job" | "gang" }
57
+ /**
58
+ * A long read-only names list (data: `names`, thousands of entries): search and 50 shown at a time. With `addTo`,
59
+ * each entry has a button that appends `newRow` with the entry at `field` to the list section at `path`
60
+ * (`label`: lang key of the button, `doneLabel`: shown instead when a row there already has the entry).
61
+ */
62
+ | {
63
+ widget: "browse";
64
+ addTo?: {
65
+ path: string;
66
+ field: string;
67
+ newRow: Record<string, unknown>;
68
+ label: string;
69
+ doneLabel: string;
70
+ };
71
+ }
72
+ /** A map blip `{ sprite, color, scale }` (data: an object of three numbers): picture grid, colour swatches, size. */
73
+ | { widget: "blip" }
74
+ /** A game model name (data: text): a search over the game's models with pictures; a typed addon name is kept. */
75
+ | {
76
+ widget: "model";
77
+ kind: "vehicle" | "ped" | "object";
78
+ placeholder?: string;
79
+ }
80
+ /** A colour (data: text `#rrggbb`): swatch, hex box, preset colours. */
81
+ | { widget: "color" }
82
+ /** A world object picked with the free camera (data at `path`: vec3 of the object; its model name goes to `modelPath`). Doors, props. */
83
+ | { widget: "entity"; modelPath: string }
84
+ /** Read only: shows the value (state the script fills in, e.g. a default it reports). */
85
+ | ({ widget: "info"; mono?: boolean } & ValueLabels)
86
+ /**
87
+ * A button that runs the script's `panel.onAction(path, (admin, record) => error | null)` on this record (or the
88
+ * settings object); nothing is stored at `path`, it names the action. `button`: lang key of the button text;
89
+ * `confirm`: lang key of a question asked first (destructive or costly actions); `danger`: red button.
90
+ */
91
+ | {
92
+ widget: "action";
93
+ button: string;
94
+ icon?: string;
95
+ confirm?: string;
96
+ danger?: boolean;
97
+ }
98
+ /**
99
+ * A ground polygon (data: a list of `{ x, y, z }` corners, data spec `{ type: "list", of: { type: "vec3" }, min: 3 }`):
100
+ * corners added with the free camera or the admin's position, removed one by one; the shape is drawn in the world
101
+ * while the field is on screen. `heightPath`: a number section of the same record drawn as the metres above and
102
+ * below the corners.
103
+ */
104
+ | { widget: "zone"; heightPath?: string; max?: number }
105
+ );
106
+
107
+ /** How a read-only value is shown: stored values with a lang key show that text; an empty value shows `empty`. */
108
+ export interface ValueLabels {
109
+ /** Lang keys of stored values (a value without an entry shows as it is). */
110
+ values?: Record<string, string>;
111
+ /** Lang key shown for an empty value. */
112
+ empty?: string;
113
+ }
114
+
115
+ interface WidgetBase {
116
+ path: string;
117
+ /** Lang key of the label. */
118
+ label: string;
119
+ /** Lang key of a one-sentence hint (unit, rule, what it does in game). */
120
+ hint?: string;
121
+ /** Shown only while the value at `path` (same record or settings section) is one of `values` (a door's second leaf for double doors). */
122
+ showIf?: { path: string; values: Array<string | number | boolean> };
123
+ }
@@ -0,0 +1,115 @@
1
+ /**
2
+ * ai-core's appearance layer: a character's stored look, putting a look on a ped, the clothing menus and job outfits,
3
+ * through whichever clothing script runs (ai-appearance, tgiann-clothing). `docs/compat/appearance.md`.
4
+ */
5
+
6
+ /**
7
+ * A look as the appearance layer hands it out: the ped model (hash) and the clothing script's own data, opaque to
8
+ * everyone else (give it back to `ApplyAppearance` unchanged).
9
+ */
10
+ export interface CharacterAppearance {
11
+ model: number;
12
+ data: unknown;
13
+ }
14
+
15
+ /** GlobalState key: the resource name of the clothing script behind the appearance layer (unset while none runs). */
16
+ export const APPEARANCE_STATE_KEY = "ai:appearance";
17
+
18
+ /** One clothing script on ai-core's server (`resource/server/appearance/`). */
19
+ export interface AppearanceAdapter {
20
+ resource: string;
21
+ version?: string;
22
+ /** The stored look of a character (loaded or not), null when it has none. */
23
+ load(charId: number): Promise<CharacterAppearance | null>;
24
+ }
25
+
26
+ /** The same clothing script on ai-core's client (`resource/client/appearance/`). */
27
+ export interface AppearanceClientAdapter {
28
+ resource: string;
29
+ version?: string;
30
+ /** Puts the script's look data on a ped whose model already matches. */
31
+ apply(ped: number, data: unknown): void;
32
+ /** The look data a ped wears now, null when the script cannot tell. */
33
+ read?(ped: number): unknown;
34
+ /** Opens one of the script's menus for the local player; absent or false when it has no such menu. */
35
+ openMenu?(menu: ClothingMenu): boolean;
36
+ /** Puts a job outfit on the local player until `reloadSkin` (not saved as the player's own look). */
37
+ wearOutfit?(outfit: JobOutfit): void;
38
+ /** Puts the local player's saved look back on (takes a job outfit off). */
39
+ reloadSkin?(): void;
40
+ }
41
+
42
+ /** A clothing script menu other scripts open: the clothing shop, the barber, the player's saved outfits. */
43
+ export type ClothingMenu = "clothing" | "barber" | "outfits";
44
+ export const CLOTHING_MENUS: readonly ClothingMenu[] = [
45
+ "clothing",
46
+ "barber",
47
+ "outfits",
48
+ ];
49
+
50
+ /** One piece of a job outfit: a component or prop id, its collection name (`""` = base game) and local index. */
51
+ export interface OutfitPiece {
52
+ id: number;
53
+ collection: string;
54
+ /** Local drawable index in the collection; -1 takes a prop off. */
55
+ index: number;
56
+ texture: number;
57
+ }
58
+
59
+ /** A job outfit (uniform) for the freemode model the player wears: only the listed pieces change. */
60
+ export interface JobOutfit {
61
+ components: OutfitPiece[];
62
+ props: OutfitPiece[];
63
+ }
64
+
65
+ function toPieces(value: unknown, max: number, prop: boolean): OutfitPiece[] {
66
+ if (!Array.isArray(value)) return [];
67
+ const pieces: OutfitPiece[] = [];
68
+ for (const v of value as unknown[]) {
69
+ if (typeof v !== "object" || v === null) continue;
70
+ const { id, collection, index, texture } = v as Record<string, unknown>;
71
+ if (
72
+ Number.isInteger(id) &&
73
+ (id as number) >= 0 &&
74
+ (id as number) <= max &&
75
+ typeof collection === "string" &&
76
+ collection.length <= 64 &&
77
+ Number.isInteger(index) &&
78
+ (index as number) >= (prop ? -1 : 0) &&
79
+ (index as number) < 1024
80
+ )
81
+ pieces.push({
82
+ id: id as number,
83
+ collection,
84
+ index: index as number,
85
+ texture:
86
+ Number.isInteger(texture) && (texture as number) >= 0
87
+ ? (texture as number)
88
+ : 0,
89
+ });
90
+ }
91
+ return pieces;
92
+ }
93
+
94
+ /** A job outfit from another resource: valid pieces only (components 0-11, props 0-13), null when none is left. */
95
+ export function toJobOutfit(value: unknown): JobOutfit | null {
96
+ if (typeof value !== "object" || value === null) return null;
97
+ const { components, props } = value as Record<string, unknown>;
98
+ const outfit = {
99
+ components: toPieces(components, 11, false),
100
+ props: toPieces(props, 13, true),
101
+ };
102
+ return outfit.components.length || outfit.props.length ? outfit : null;
103
+ }
104
+
105
+ /** A look from another resource or the network: a model hash and some data, else null. */
106
+ export function toCharacterAppearance(
107
+ value: unknown,
108
+ ): CharacterAppearance | null {
109
+ if (typeof value !== "object" || value === null || Array.isArray(value))
110
+ return null;
111
+ const { model, data } = value as { model?: unknown; data?: unknown };
112
+ return Number.isInteger(model) && model !== 0 && data != null
113
+ ? { model: model as number, data }
114
+ : null;
115
+ }
package/src/banking.ts ADDED
@@ -0,0 +1,58 @@
1
+ /** A society account's owner kind: a job's or a gang's account, named by the job / gang. */
2
+ export type SocietyType = "job" | "gang";
3
+
4
+ /**
5
+ * A banking script's own job and gang accounts, reached through its documented exports (ai-core's `bankAccounts`
6
+ * modes). `own`: ai-core's job / gang `bank` account changes go to `add` / `remove` and reads to `balance` for every
7
+ * job / gang the script `has`. `core`: ai-core keeps the money and writes each change with `set`; changes made in the
8
+ * script (its screen) come back through `watch`. A script without `set` only reports ai-core's balance in `core`.
9
+ */
10
+ export interface BankingAccounts {
11
+ /** Whether the script keeps an account for this job / gang. */
12
+ has(type: SocietyType, name: string): boolean;
13
+ /** The script's balance of the account; null when it has none. */
14
+ balance(type: SocietyType, name: string): number | null;
15
+ /** Adds to the script's account; false when it refused (no account). */
16
+ add(type: SocietyType, name: string, amount: number): boolean;
17
+ /** Removes from the script's account; false when it refused (no account, not enough money). */
18
+ remove(type: SocietyType, name: string, amount: number): boolean;
19
+ /** Sets the script's balance (`core` mode: ai-core's balance); false when it refused. */
20
+ set?(type: SocietyType, name: string, amount: number): boolean;
21
+ /**
22
+ * Reports balance changes of the listed accounts made inside the script: `changed(type, name, delta, balance)`.
23
+ * Each call replaces the last; null stops reporting. Changes caused by `set` are reported too (the caller ignores
24
+ * them).
25
+ */
26
+ watch?(
27
+ owners: Readonly<Record<SocietyType, readonly string[]>> | null,
28
+ changed: (
29
+ type: SocietyType,
30
+ name: string,
31
+ delta: number,
32
+ balance: number,
33
+ ) => void,
34
+ ): void;
35
+ }
36
+
37
+ /** One banking script behind ai-core's banking layer (server side). */
38
+ export interface BankingAdapter {
39
+ resource: string;
40
+ /** The version the adapter is written for; ai-core warns when another one runs. Absent for ai-* scripts. */
41
+ version?: string;
42
+ /** The script's own balance of a job's society account; null when it keeps none for the job (or none at all). */
43
+ societyBalance(job: string): number | null;
44
+ /** Opens the script's bank screen for a player; absent when it cannot be opened from outside. */
45
+ open?(source: number): boolean;
46
+ /** Its own job / gang accounts, when its exports reach them; absent when they cannot be linked. */
47
+ accounts?: BankingAccounts;
48
+ }
49
+
50
+ /** ai-core's banking exports: whatever banking script runs (none: null / false). */
51
+ export type BankingServerExports = {
52
+ /** The banking script the layer uses, or null. */
53
+ GetBankingSystem(): string | null;
54
+ /** Opens the banking script's screen for a player; false when it cannot be opened from outside or none runs. */
55
+ OpenBank(source: number): boolean;
56
+ /** A job's society balance: ai-core's job `bank` account in `core` mode, the script's own in `own` mode; null when none runs or it keeps none. */
57
+ GetBankSocietyBalance(job: string): number | null;
58
+ };