@vespura/vmenu-plugin 0.0.0-stage → 0.0.1

package/dist/server.js

@@ -0,0 +1,267 @@
+// src/version.ts
+var version = true ? "0.0.1" : "0.0.0-local";
+
+// src/format.ts
+function formatFloat(value) {
+  const text = value.toFixed(4).replace(/0+$/, "");
+  return text.endsWith(".") ? `${text}0` : text;
+}
+
+// src/protocol.ts
+var SERVER_PROTOCOL_VERSION = 1;
+var PluginEvents = {
+  Probe: "vMenu.Enhanced:Plugins:Probe",
+  Register: "vMenu.Enhanced:Plugins:Register",
+  Unregister: "vMenu.Enhanced:Plugins:Unregister",
+  Update: "vMenu.Enhanced:Plugins:Update",
+  Notify: "vMenu.Enhanced:Plugins:Notify",
+  Prompt: "vMenu.Enhanced:Plugins:Prompt",
+  SetTheme: "vMenu.Enhanced:Plugins:SetTheme",
+  RegisterThemes: "vMenu.Enhanced:Plugins:RegisterThemes",
+  Ready: "vMenu.Enhanced:Plugins:Ready",
+  ServerProbe: "vMenu.Enhanced:Plugins:Server:Probe",
+  ServerRegister: "vMenu.Enhanced:Plugins:Server:Register",
+  ServerDenied: "vMenu.Enhanced:Plugins:Server:Denied",
+  ServerReady: "vMenu.Enhanced:Plugins:Server:Ready",
+  readyFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:Ready`,
+  registerResultFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:RegisterResult`,
+  eventFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:Event`,
+  promptResultFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:PromptResult`,
+  themesFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:Themes`,
+  themesRegisteredFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:ThemesRegistered`,
+  serverReadyFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:Server:Ready`,
+  serverRegisterResultFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:Server:RegisterResult`
+};
+var RefreshPermissionsEvent = "vMenu.Enhanced:Permissions:Refresh";
+var SettingTypes = {
+  Bool: "bool",
+  Int: "int",
+  Float: "float",
+  String: "string"
+};
+function normalizeResult(raw) {
+  if (!raw || typeof raw !== "object") {
+    return void 0;
+  }
+  return {
+    accepted: raw.accepted === true,
+    protocolVersion: typeof raw.protocolVersion === "number" ? raw.protocolVersion : 0,
+    errors: Array.isArray(raw.errors) ? raw.errors : [],
+    warnings: Array.isArray(raw.warnings) ? raw.warnings : []
+  };
+}
+
+// src/server/declaration.ts
+var ServerPluginDeclaration = class {
+  /** @param displayName Used in the generated example files, so owners see which plugin a section belongs to. */
+  constructor(displayName) {
+    this.displayName = displayName;
+    this.permissions = [];
+    this.settings = [];
+    this.loggedItems = [];
+  }
+  /** Declares a permission. `staffOnly` marks it as staff only in the generated permissions example. */
+  addPermission(name, description, staffOnly = false) {
+    this.permissions.push({ name, description, staffOnly });
+    return this;
+  }
+  /**
+   * Lets the server owner see a line in their webhook whenever somebody uses this row. The client
+   * half still has to set `log` on it. `description` is a noun phrase dropped into vMenu's own
+   * wording, as in "turned the anti-grief shield on".
+   */
+  addLoggedItem(itemId, description) {
+    this.loggedItems.push({ itemId, description });
+    return this;
+  }
+  /** Declares an on or off setting. */
+  addBoolSetting(name, defaultValue, description) {
+    return this.add(name, SettingTypes.Bool, defaultValue ? "true" : "false", description);
+  }
+  /** Declares a whole number setting. */
+  addIntSetting(name, defaultValue, description) {
+    return this.add(name, SettingTypes.Int, String(Math.trunc(defaultValue)), description);
+  }
+  /** Declares a decimal number setting. */
+  addFloatSetting(name, defaultValue, description) {
+    return this.add(name, SettingTypes.Float, formatFloat(defaultValue), description);
+  }
+  /** Declares a text setting. */
+  addStringSetting(name, defaultValue, description) {
+    return this.add(name, SettingTypes.String, defaultValue, description);
+  }
+  /** @internal */
+  toRequest() {
+    return {
+      protocolVersion: SERVER_PROTOCOL_VERSION,
+      displayName: this.displayName,
+      permissions: [...this.permissions],
+      settings: [...this.settings],
+      loggedItems: [...this.loggedItems]
+    };
+  }
+  add(name, type, defaultText, description) {
+    this.settings.push({ name, type, default: defaultText, description });
+    return this;
+  }
+};
+
+// src/fivem.ts
+var natives = globalThis;
+var currentResource = () => natives.GetCurrentResourceName();
+var emitLocal = (eventName, ...args) => natives.emit(eventName, ...args);
+var onLocal = (eventName, handler) => natives.on(eventName, handler);
+var isAceAllowed = (playerSource, object) => natives.IsPlayerAceAllowed(playerSource, object) === true;
+var log = {
+  info: (resource, message) => console.log(`[${resource}] ${message}`),
+  warn: (resource, message) => console.warn(`[${resource}] ${message}`),
+  error: (resource, message) => console.error(`[${resource}] ${message}`)
+};
+function parseJson(json) {
+  if (typeof json !== "string") {
+    return void 0;
+  }
+  try {
+    return JSON.parse(json);
+  } catch {
+    return void 0;
+  }
+}
+function sanitizeId(resource) {
+  return resource.replace(/[^A-Za-z0-9]/g, "_");
+}
+
+// src/signal.ts
+var Signal = class {
+  constructor(resource, name) {
+    this.resource = resource;
+    this.name = name;
+    this.handlers = [];
+  }
+  get hasHandlers() {
+    return this.handlers.length > 0;
+  }
+  add(handler) {
+    this.handlers.push(handler);
+    return () => {
+      this.handlers = this.handlers.filter((existing) => existing !== handler);
+    };
+  }
+  fire(...args) {
+    for (const handler of [...this.handlers]) {
+      try {
+        handler(...args);
+      } catch (error) {
+        log.error(this.resource(), `A ${this.name} handler threw: ${describe(error)}`);
+      }
+    }
+  }
+};
+function describe(error) {
+  return error instanceof Error ? error.stack ?? error.message : String(error);
+}
+
+// src/server/server.ts
+var PermissionPrefix = "vMenu.Enhanced.Plugins";
+var Everything = "vMenu.Enhanced.Everything";
+var declaration;
+var firstResult;
+var resolveFirst;
+var handlersRegistered = false;
+var resourceName = "";
+var pluginId = "";
+var registrationAnswered = new Signal(() => resourceName, "registration answered");
+function ensureIdentity() {
+  if (resourceName.length === 0) {
+    resourceName = currentResource();
+    pluginId = sanitizeId(resourceName);
+  }
+}
+function sendRegistration() {
+  if (declaration) {
+    emitLocal(PluginEvents.ServerRegister, JSON.stringify(declaration.toRequest()));
+  }
+}
+function onResult(json) {
+  const result = normalizeResult(parseJson(json));
+  if (!result) {
+    log.warn(resourceName, "vMenu sent a registration answer that did not parse.");
+    return;
+  }
+  for (const error of result.errors) {
+    log.error(resourceName, `vMenu refused the plugin registration: ${error}`);
+  }
+  for (const warning of result.warnings) {
+    log.warn(resourceName, `vMenu accepted the plugin registration with a note: ${warning}`);
+  }
+  resolveFirst?.(result);
+  resolveFirst = void 0;
+  registrationAnswered.fire(result);
+}
+function ensureHandlers() {
+  if (handlersRegistered) {
+    return;
+  }
+  handlersRegistered = true;
+  ensureIdentity();
+  onLocal(PluginEvents.ServerReady, () => sendRegistration());
+  onLocal(PluginEvents.serverReadyFor(resourceName), () => sendRegistration());
+  onLocal(PluginEvents.serverRegisterResultFor(resourceName), (json) => onResult(json));
+}
+var VMenuServer = {
+  /**
+   * Declares the plugin with vMenu. The promise resolves on vMenu's first answer, which can be a
+   * while when vMenu starts later than the plugin. It never rejects: a refusal arrives as a result
+   * with `accepted` false.
+   */
+  register(pluginDeclaration) {
+    declaration = pluginDeclaration;
+    firstResult ?? (firstResult = new Promise((resolve) => {
+      resolveFirst = resolve;
+    }));
+    ensureHandlers();
+    emitLocal(PluginEvents.ServerProbe);
+    return firstResult;
+  },
+  /**
+   * Whether a player holds one of the plugin's own permissions, by its short name. Also honours the
+   * container grants a server owner may have used instead of the exact name.
+   */
+  isPlayerAllowed(playerSource, permissionName) {
+    const source = String(playerSource ?? "");
+    if (source.length === 0) {
+      return false;
+    }
+    ensureIdentity();
+    const scope = `${PermissionPrefix}.${pluginId}`;
+    return isAceAllowed(source, `${scope}.${permissionName}`) || isAceAllowed(source, `${scope}.All`) || isAceAllowed(source, `${PermissionPrefix}.All`) || isAceAllowed(source, Everything);
+  },
+  /**
+   * The same check as `isPlayerAllowed`, but a refusal is also reported to vMenu's security webhook.
+   * Use it where a legitimate client could only ever have sent the thing you are handling while
+   * allowed, and keep `isPlayerAllowed` for ordinary branching.
+   */
+  requirePermission(playerSource, permissionName) {
+    if (VMenuServer.isPlayerAllowed(playerSource, permissionName)) {
+      return true;
+    }
+    const source = String(playerSource ?? "");
+    if (source.length > 0) {
+      emitLocal(PluginEvents.ServerDenied, source, permissionName);
+    }
+    return false;
+  },
+  /** Refreshes permissions for one or more players. Passing no ids refreshes every connected player. */
+  refreshPermissions(...serverIds) {
+    emitLocal(RefreshPermissionsEvent, serverIds.map((id) => Math.trunc(Number(id))));
+  },
+  /** Called on every registration answer, including automatic re-registrations. */
+  onRegistrationAnswered(handler) {
+    return registrationAnswered.add(handler);
+  }
+};
+export {
+  ServerPluginDeclaration,
+  VMenuServer,
+  version
+};

package/dist/types/client/diff.d.ts

@@ -0,0 +1,4 @@
+import type { GateNode, TextRef } from '../protocol';
+export declare function sameText(left: TextRef | undefined, right: TextRef | undefined): boolean;
+export declare function sameTexts(left: TextRef[] | undefined, right: TextRef[] | undefined): boolean;
+export declare function sameGate(left: GateNode | undefined, right: GateNode | undefined): boolean;

package/dist/types/client/gate.d.ts

@@ -0,0 +1,24 @@
+import type { PluginBoolSetting } from './settings';
+/** A gate, or a permission's short name as a shortcut for `Gate.permission(name)`. */
+export type GateLike = Gate | string;
+/**
+ * Decides whether a menu item is available to the player, evaluated live by vMenu. Combine gates
+ * with `and`, `or`, `Gate.all` and `Gate.any`. Names are short: vMenu scopes them to your plugin, so
+ * you can never gate on another plugin's permissions or settings.
+ */
+export declare class Gate {
+    private readonly node;
+    private constructor();
+    /** One of the permissions your server side declared, by its short name. */
+    static permission(shortName: string): Gate;
+    /** One of your bool settings: the item is available while the convar reads true. */
+    static setting(setting: PluginBoolSetting | string): Gate;
+    /** Passes when every gate passes. */
+    static all(...gates: GateLike[]): Gate;
+    /** Passes when at least one gate passes. */
+    static any(...gates: GateLike[]): Gate;
+    /** Passes when this gate and the other one both pass. */
+    and(other: GateLike): Gate;
+    /** Passes when this gate or the other one passes. */
+    or(other: GateLike): Gate;
+}

package/dist/types/client/host.d.ts

@@ -0,0 +1,18 @@
+import type { UpdateOp } from '../protocol';
+import type { PluginItem } from './item';
+import type { PluginKey } from './key';
+import type { PluginMenu } from './menu';
+export interface PluginHost {
+    readonly resource: string;
+    readonly isConnected: boolean;
+    nextItemId(): string;
+    nextMenuId(): string;
+    registerMenu(menu: PluginMenu): void;
+    registerItem(item: PluginItem): void;
+    registerKey(key: PluginKey): void;
+    unregisterItem(item: PluginItem): void;
+    emitOp(op: UpdateOp): void;
+    emitAdd(menu: PluginMenu, item: PluginItem, add: UpdateOp): void;
+    filterChanged(menu: PluginMenu): void;
+    mergeTranslations(code: string, entries: Record<string, string>): void;
+}

package/dist/types/client/index.d.ts

@@ -0,0 +1,14 @@
+export { version } from '../version';
+export { Text, type TextLike } from '../text';
+export type { Unsubscribe } from '../signal';
+export type { RegisterResult } from '../protocol';
+export { Gate, type GateLike } from './gate';
+export { PluginSetting, PluginBoolSetting, PluginIntSetting, PluginFloatSetting, PluginStringSetting, PluginSettings, } from './settings';
+export { PluginItem, type ItemOptions } from './item';
+export { PluginButton, PluginConfirmButton, PluginCheckbox, PluginList, PluginConfirmList, PluginSlider, PluginDynamicList, PluginSeparator, PluginSubmenu, } from './items';
+export { PluginKey, type PluginKeyPress } from './key';
+export { PluginMenu, type CheckboxOptions, type ConfirmOptions, type KeyOptions, type ListOptions, type SliderOptions, type SubmenuOptions, } from './menu';
+export { PluginPlayerActions, PluginPlayerButton, PluginPlayerConfirmButton, PluginPlayerList, type PlayerTarget, } from './playerActions';
+export { PluginThemes, type PluginTheme } from './themes';
+export { PluginTranslations } from './translations';
+export { VMenuPlugin, type NotifyStyle, type PluginPrompt, type PromptSuggestion } from './plugin';

package/dist/types/client/item.d.ts

@@ -0,0 +1,71 @@
+import { type UpdateOp } from '../protocol';
+import { Signal, type Unsubscribe } from '../signal';
+import { type TextLike } from '../text';
+import { type GateLike } from './gate';
+/** Properties every row accepts when you add it. Setting them here sends them along with the row itself. */
+export interface ItemOptions {
+    /** A stable id of your own. Generated when left out. Unique within your plugin. */
+    id?: string;
+    description?: TextLike;
+    label?: TextLike;
+    lockedDescription?: TextLike;
+    gate?: GateLike;
+    hideWhenLocked?: boolean;
+    visible?: boolean;
+    enabled?: boolean;
+    log?: boolean;
+    leftIcon?: string;
+    rightIcon?: string;
+}
+/**
+ * One row in your plugin's menus. Setting a property updates the row live once the plugin is
+ * connected, and everything set before connecting rides along with the registration.
+ */
+export declare abstract class PluginItem {
+    private textValue?;
+    private descriptionValue?;
+    private labelValue?;
+    private lockedDescriptionValue?;
+    private gateValue?;
+    private readonly highlighted;
+    /** The row's id, how vMenu refers to it. */
+    get id(): string;
+    /** The row's text. */
+    get text(): TextLike | undefined;
+    set text(value: TextLike | undefined);
+    /** The line shown under the menu while the row is highlighted. */
+    get description(): TextLike | undefined;
+    set description(value: TextLike | undefined);
+    /** Right aligned text. Ignored by rows whose label the menu draws itself. */
+    get label(): TextLike | undefined;
+    set label(value: TextLike | undefined);
+    /** What the row says while its gate locks it. Empty uses vMenu's own wording. */
+    get lockedDescription(): TextLike | undefined;
+    set lockedDescription(value: TextLike | undefined);
+    /** Decides whether the row is available, evaluated live by vMenu. */
+    get gate(): GateLike | undefined;
+    set gate(value: GateLike | undefined);
+    /** What a failing gate does to the row: greyed out with a lock, or gone entirely. */
+    get hideWhenLocked(): boolean;
+    set hideWhenLocked(value: boolean);
+    /** Whether the row is shown at all. */
+    get visible(): boolean;
+    set visible(value: boolean);
+    /** A disabled row is greyed out but still visible. Independent of the gate. */
+    get enabled(): boolean;
+    set enabled(value: boolean);
+    /**
+     * Ask vMenu to log use of this row to the server owner's webhook. Does nothing on its own: the
+     * plugin's server half has to declare the same id with `addLoggedItem`.
+     */
+    get log(): boolean;
+    set log(value: boolean);
+    /** Icon names from the vMenu icon set, for example "LOCK" or "STAR". */
+    setIcons(leftIcon?: string, rightIcon?: string): void;
+    /** Called while the player's cursor sits on this row. Chatty, subscribe deliberately. */
+    onHighlighted(handler: () => void): Unsubscribe;
+    protected signal<T extends unknown[]>(name: string): Signal<T>;
+    protected subscribeNodeEvent(name: string): void;
+    protected emit(op: UpdateOp): void;
+    protected setTextField(field: 'text' | 'description' | 'label' | 'lockedDescription' | 'confirmationDescription', value: TextLike | undefined, opName: string): void;
+}

package/dist/types/client/items.d.ts

@@ -0,0 +1,96 @@
+import type { Unsubscribe } from '../signal';
+import { type TextLike } from '../text';
+import { PluginItem } from './item';
+import type { PluginMenu } from './menu';
+/** A row the player presses. */
+export declare class PluginButton extends PluginItem {
+    private readonly selected;
+    /** Called when the player presses the row. */
+    onSelected(handler: () => void): Unsubscribe;
+}
+/** A row that asks for a second press before it does anything. */
+export declare class PluginConfirmButton extends PluginItem {
+    private confirmationDescriptionValue?;
+    private readonly confirmed;
+    /** What the row asks before its second press. Empty uses vMenu's own wording. */
+    get confirmationDescription(): TextLike | undefined;
+    set confirmationDescription(value: TextLike | undefined);
+    /** Called on the confirming second press, never on the first. */
+    onConfirmed(handler: () => void): Unsubscribe;
+}
+/** A row with a tick box. */
+export declare class PluginCheckbox extends PluginItem {
+    private readonly changed;
+    /** Whether the state is saved in this resource's key value store and restored on start. */
+    get persisted(): boolean;
+    /** Whether the box is ticked. */
+    get checked(): boolean;
+    set checked(value: boolean);
+    /** Called when the player toggles the box. The new state is already in `checked`. */
+    onChanged(handler: (checked: boolean) => void): Unsubscribe;
+    private remember;
+}
+/** A row the player scrolls through a set of options on. */
+export declare class PluginList extends PluginItem {
+    private readonly indexChanged;
+    private readonly selected;
+    /** The selected option, counted from 0. */
+    get selectedIndex(): number;
+    set selectedIndex(value: number);
+    /** Replaces the options, optionally moving the selection at the same time. */
+    setOptions(options: readonly TextLike[], selectedIndex?: number): void;
+    /** Called when the player scrolls the value. The new index is already in `selectedIndex`. */
+    onIndexChanged(handler: (oldIndex: number, newIndex: number) => void): Unsubscribe;
+    /** Called when the player presses the row, with the index they had selected. */
+    onSelected(handler: (index: number) => void): Unsubscribe;
+    protected raiseConfirmed(_index: number): void;
+}
+/** A list that asks for a second press before it does anything. */
+export declare class PluginConfirmList extends PluginList {
+    private confirmationDescriptionValue?;
+    private readonly confirmed;
+    /** What the row asks before its second press. Empty uses vMenu's own wording. */
+    get confirmationDescription(): TextLike | undefined;
+    set confirmationDescription(value: TextLike | undefined);
+    /** Called on the confirming second press, with the index that was confirmed. */
+    onConfirmed(handler: (index: number) => void): Unsubscribe;
+    protected raiseConfirmed(index: number): void;
+}
+/** A row with a bar the player drags between a minimum and a maximum. */
+export declare class PluginSlider extends PluginItem {
+    private readonly moved;
+    private readonly selected;
+    /** The lowest position. */
+    get min(): number;
+    /** The highest position. */
+    get max(): number;
+    /** Where the bar sits. */
+    get position(): number;
+    set position(value: number);
+    /** Called while the player drags the bar. The new position is already in `position`. */
+    onMoved(handler: (oldPosition: number, newPosition: number) => void): Unsubscribe;
+    /** Called when the player presses the row, with the position it sat at. */
+    onSelected(handler: (position: number) => void): Unsubscribe;
+}
+/** A row whose value your code works out each time the player scrolls it. */
+export declare class PluginDynamicList extends PluginItem {
+    private readonly selected;
+    /**
+     * Produces the next value when the player scrolls: the current value and whether they went left.
+     * The answer crosses back to vMenu as an update, so it lands one beat after the press.
+     */
+    changeRequested?: (currentValue: string, left: boolean) => string | null | undefined;
+    /** The value the row shows. */
+    get value(): string;
+    set value(value: string);
+    /** Called when the player presses the row, with the value it showed. */
+    onSelected(handler: (value: string) => void): Unsubscribe;
+}
+/** A row that only shows text, used to split a menu into sections. */
+export declare class PluginSeparator extends PluginItem {
+}
+/** A row that opens another menu. */
+export declare class PluginSubmenu extends PluginItem {
+    /** The menu this row opens. Add its rows through this. */
+    readonly menu: PluginMenu;
+}

package/dist/types/client/key.d.ts

@@ -0,0 +1,38 @@
+import { type Unsubscribe } from '../signal';
+import { type TextLike } from '../text';
+import { type GateLike } from './gate';
+import type { PluginItem } from './item';
+/**
+ * Which row the cursor was on when a key was pressed. At most one of the two is set, and neither
+ * when the menu is empty or the row is not one of yours.
+ */
+export interface PluginKeyPress {
+    /** The row under the cursor, when the player may use it. */
+    readonly item?: PluginItem;
+    /** The row under the cursor, when it is locked by its gate or disabled. Acting on it anyway is your call. */
+    readonly disabledItem?: PluginItem;
+}
+/**
+ * A key that works while its menu is open, shown as an instructional button at the bottom of the
+ * screen. The player can rebind it in the game's key settings, where it is listed under vMenu with
+ * your plugin's name in front.
+ */
+export declare class PluginKey {
+    private readonly plugin;
+    private textValue?;
+    private gateValue?;
+    private readonly pressed;
+    /** The key's id, which also names the binding in the player's key settings. */
+    get id(): string;
+    /** The instructional button's label. Empty hides the button, the key still works. */
+    get text(): TextLike | undefined;
+    set text(value: TextLike | undefined);
+    /** A disabled key does nothing and shows no button. */
+    get enabled(): boolean;
+    set enabled(value: boolean);
+    /** While the gate fails the key does nothing and shows no button. */
+    get gate(): GateLike | undefined;
+    set gate(value: GateLike | undefined);
+    /** Called when the player presses the key, with the row the cursor was on. */
+    onPressed(handler: (press: PluginKeyPress) => void): Unsubscribe;
+}