@vespura/vmenu-plugin 0.0.0-stage → 0.0.1

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

@@ -0,0 +1,142 @@
+import { type Unsubscribe } from '../signal';
+import { type TextLike } from '../text';
+import { PluginItem, type ItemOptions } from './item';
+import { PluginButton, PluginCheckbox, PluginConfirmButton, PluginConfirmList, PluginDynamicList, PluginList, PluginSeparator, PluginSlider, PluginSubmenu } from './items';
+import { PluginKey } from './key';
+/** Extra properties for a confirm button or confirm list. */
+export interface ConfirmOptions extends ItemOptions {
+    /** What the row asks before its second press. */
+    confirmationDescription?: TextLike;
+}
+/** Extra properties for a checkbox. */
+export interface CheckboxOptions extends ItemOptions {
+    /** Whether the box starts ticked. */
+    checked?: boolean;
+    /**
+     * Saves the player's choice in this resource's key value store and restores it on the next start.
+     * Pass a stable `id` along with it: generated ids follow creation order, so reordering your code
+     * would hand a saved value to the wrong box.
+     */
+    persist?: boolean;
+}
+/** Extra properties for a list. */
+export interface ListOptions extends ItemOptions {
+    /** The option selected at the start, counted from 0. */
+    selectedIndex?: number;
+}
+/** Extra properties for a slider. */
+export interface SliderOptions extends ItemOptions {
+    /** Draws a mark in the middle of the bar. */
+    showDivider?: boolean;
+}
+/** Extra properties for a submenu row. */
+export interface SubmenuOptions extends ItemOptions {
+    /** The new menu's title. Falls back to the row's text. */
+    title?: TextLike;
+    /** The bar under the new menu's banner. */
+    subtitle?: TextLike;
+}
+/** Extra properties for a key. */
+export interface KeyOptions {
+    /** A controller button, for example "RUP_INDEX". Without one the key shows no button while the player uses a controller. */
+    defaultButton?: string;
+    /** What the game's key settings list it as. Falls back to the text. */
+    description?: TextLike;
+    /** A game control index to suppress while the menu is open, for a default key the game already uses. */
+    shadowedControl?: number;
+}
+/**
+ * One of your plugin's menus: the root under your row in vMenu's Plugins menu, or a submenu. Rows
+ * added before connecting ride along with the registration, rows added later appear live.
+ */
+export declare class PluginMenu {
+    private readonly plugin;
+    private readonly itemList;
+    private readonly keyList;
+    private titleValue?;
+    private subtitleValue?;
+    private readonly opened;
+    private readonly closed;
+    private readonly indexChanged;
+    private insertIndex?;
+    private filterFn?;
+    /** The menu's id, how vMenu refers to it. */
+    get id(): string;
+    /** Every row, in order. */
+    get items(): readonly PluginItem[];
+    /** Every key of this menu. */
+    get keys(): readonly PluginKey[];
+    /** Whether `filter` is hiding rows right now. */
+    get isFiltered(): boolean;
+    /** The title in the menu's banner. */
+    get title(): TextLike | undefined;
+    set title(value: TextLike | undefined);
+    /** The bar under the banner. */
+    get subtitle(): TextLike | undefined;
+    set subtitle(value: TextLike | undefined);
+    /** Called when the player opens this menu. */
+    onOpened(handler: () => void): Unsubscribe;
+    /** Called when the player leaves this menu, including into a submenu. */
+    onClosed(handler: () => void): Unsubscribe;
+    /** Called when the cursor moves, with the old and new row index counted from 0. Chatty. */
+    onIndexChanged(handler: (oldIndex: number, newIndex: number) => void): Unsubscribe;
+    /** Adds a row the player presses. */
+    addButton(text: TextLike, options?: ItemOptions): PluginButton;
+    /** Adds a row that asks for a second press before it does anything. */
+    addConfirmButton(text: TextLike, options?: ConfirmOptions): PluginConfirmButton;
+    /** Adds a row with a tick box. */
+    addCheckbox(text: TextLike, options?: CheckboxOptions): PluginCheckbox;
+    /** Adds a row the player scrolls through a set of options on. */
+    addList(text: TextLike, values: readonly TextLike[], options?: ListOptions): PluginList;
+    /** Adds a list that asks for a second press before it does anything. */
+    addConfirmList(text: TextLike, values: readonly TextLike[], options?: ListOptions & ConfirmOptions): PluginConfirmList;
+    /** Adds a row with a bar the player drags between `min` and `max`. */
+    addSlider(text: TextLike, min: number, max: number, position: number, options?: SliderOptions): PluginSlider;
+    /** Adds a row whose value your code works out each time the player scrolls it, through `changeRequested`. */
+    addDynamicList(text: TextLike, initialValue: string, options?: ItemOptions): PluginDynamicList;
+    /** Adds a row that only shows text, used to split a menu into sections. */
+    addSeparator(text: TextLike, options?: ItemOptions): PluginSeparator;
+    /** Adds a row that opens a new menu, reached through the returned row's `menu`. */
+    addSubmenu(text: TextLike, options?: SubmenuOptions): PluginSubmenu;
+    /**
+     * Adds a key that works while this menu is open, with an instructional button at the bottom of the
+     * screen. Keep the id stable: it names the binding in the player's key settings, so changing it
+     * loses a key they picked themselves.
+     * @param id Letters, digits and underscores, unique within your plugin.
+     * @param text The instructional button's label.
+     * @param defaultKey A keyboard key name as the game knows it, for example "X" or "F5".
+     */
+    addKey(id: string, text: TextLike, defaultKey: string, options?: KeyOptions): PluginKey;
+    /**
+     * Rows added inside `add` go in at `index`, counted from 0, one after another, instead of at the
+     * bottom. Adding goes back to the bottom once `add` returns.
+     */
+    insertAt(index: number, add: () => void): void;
+    /** Moves a row of this menu to `index`, counted from 0. A submenu row keeps its menu, and the highlighted row stays highlighted. */
+    move(item: PluginItem, index: number): void;
+    /**
+     * Shows only the rows `keep` answers true for. Rows added later are checked too: inside a batch
+     * when the batch ends, so properties set right after adding count, otherwise as they come in. Call
+     * it again after changing what it looks at.
+     */
+    filter(keep: (item: PluginItem) => boolean): void;
+    /** Shows every row again after `filter`. */
+    clearFilter(): void;
+    /** Removes one row. For a submenu row, everything beneath it goes too. */
+    remove(item: PluginItem): void;
+    /** Removes every row. */
+    clear(): void;
+    /** Opens this menu on screen, closing whatever vMenu menu was open. */
+    open(): void;
+    /** Closes this plugin's menu if one is open. */
+    close(): void;
+    /**
+     * Moves the cursor to a row of this menu, as if the player had moved there. Does nothing for a
+     * hidden row or one from another menu.
+     */
+    select(item: PluginItem): void;
+    private newNode;
+    private attach;
+    private removeLocal;
+    private subscribeMenuEvent;
+}

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

@@ -0,0 +1,68 @@
+import type { Unsubscribe } from '../signal';
+import { type TextLike } from '../text';
+import { PluginItem, type ItemOptions } from './item';
+import { PluginSeparator } from './items';
+/**
+ * The player a player action was used on, read from vMenu's Online Players snapshot. The snapshot
+ * can be stale and the player may have left, so your server side must check the target still exists
+ * before acting on it.
+ */
+export interface PlayerTarget {
+    /** The player's server id. */
+    readonly serverId: number;
+    /** The player's name as vMenu showed it. */
+    readonly name: string;
+}
+/** A player action the player presses. */
+export declare class PluginPlayerButton extends PluginItem {
+    private readonly selected;
+    /** Called when the action is used on a player, with that player as the target. */
+    onSelected(handler: (target: PlayerTarget) => void): Unsubscribe;
+}
+/** A player action that asks for a second press before it does anything. */
+export declare class PluginPlayerConfirmButton 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, with the targeted player. */
+    onConfirmed(handler: (target: PlayerTarget) => void): Unsubscribe;
+}
+/** A player action with a set of options. */
+export declare class PluginPlayerList extends PluginItem {
+    private readonly selected;
+    /** The current selection, counted from 0. Shared across every player the menu shows, since the same rows serve them all. */
+    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 action is used on a player, with the target and the chosen index. */
+    onSelected(handler: (target: PlayerTarget, index: number) => void): Unsubscribe;
+}
+/**
+ * Actions vMenu adds to the "Plugin Actions" submenu of every player's entry in its Online Players
+ * menu. The same rows serve every player, and the target is handed to your handler when one fires.
+ */
+export declare class PluginPlayerActions {
+    private readonly plugin;
+    private readonly itemList;
+    /** Every action, in order. */
+    get items(): readonly PluginItem[];
+    /** Adds an action the player presses. */
+    addButton(text: TextLike, options?: ItemOptions): PluginPlayerButton;
+    /** Adds an action that asks for a second press. */
+    addConfirmButton(text: TextLike, options?: ItemOptions & {
+        confirmationDescription?: TextLike;
+    }): PluginPlayerConfirmButton;
+    /** Adds an action with a set of options. */
+    addList(text: TextLike, values: readonly TextLike[], options?: ItemOptions & {
+        selectedIndex?: number;
+    }): PluginPlayerList;
+    /** Adds a row that only shows text. */
+    addSeparator(text: TextLike, options?: ItemOptions): PluginSeparator;
+    /** Removes one action from every player's entry. */
+    remove(item: PluginItem): void;
+    private newNode;
+    private attach;
+}

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

@@ -0,0 +1,113 @@
+import { type RegisterResult } from '../protocol';
+import { type Unsubscribe } from '../signal';
+import { type TextLike } from '../text';
+import type { PluginHost } from './host';
+import { PluginMenu } from './menu';
+import { PluginPlayerActions } from './playerActions';
+import { PluginSettings } from './settings';
+import { PluginThemes } from './themes';
+import { PluginTranslations } from './translations';
+/** How a notification is coloured in vMenu's notification area. */
+export type NotifyStyle = 'info' | 'success' | 'warning' | 'error';
+/** One suggestion row the input box offers while the player types. */
+export interface PromptSuggestion {
+    /** What lands in the box when the suggestion is picked. */
+    value: string;
+    /** What the player reads in the list. The value is shown when left out. */
+    description?: string;
+}
+/** One question for vMenu's input box. */
+export interface PluginPrompt {
+    title: TextLike;
+    /** The longest answer allowed, 60 when left out. vMenu caps it at 500. */
+    maxLength?: number;
+    /** What the box starts with. */
+    initialValue?: string;
+    suggestions?: readonly PromptSuggestion[];
+}
+/**
+ * Your plugin's client side entry point. Create it once, declare your menus, translations and
+ * settings, then call `connect`. It registers again by itself whenever vMenu restarts, so everything
+ * you declared and changed since is restored.
+ */
+export declare class VMenuPlugin implements PluginHost {
+    private readonly displayName;
+    private readonly itemsById;
+    private readonly menusById;
+    private readonly keysById;
+    private readonly pendingPrompts;
+    private readonly pendingItems;
+    private readonly pendingMenus;
+    private readonly dirtyFilters;
+    private readonly registrationAnswered;
+    private readonly disconnected;
+    private firstResult?;
+    private resolveFirst?;
+    private batchOps?;
+    private batchDepth;
+    private nextItem;
+    private nextMenu;
+    private nextPrompt;
+    private handlersRegistered;
+    private connected;
+    /** The resource this plugin runs in, its identity towards vMenu. */
+    readonly resource: string;
+    /** The sanitized identity used inside permission and convar names. */
+    readonly id: string;
+    /** Extra line under the resource name in your row's description, as a translation key. */
+    descriptionKey?: string;
+    /** Your plugin's convar settings. */
+    readonly settings: PluginSettings;
+    /** Your plugin's translation tables. */
+    readonly translations: PluginTranslations;
+    /** The look of vMenu's menus for this player. */
+    readonly themes: PluginThemes;
+    /** The menu behind your row in vMenu's Plugins menu. */
+    readonly rootMenu: PluginMenu;
+    /** Actions added to every player's entry of vMenu's Online Players menu. */
+    readonly playerActions: PluginPlayerActions;
+    private constructor();
+    /** Creates the plugin. One per resource: a second call returns the first instance. */
+    static create(displayName: TextLike): VMenuPlugin;
+    /** Whether vMenu currently has this plugin registered. */
+    get isConnected(): boolean;
+    /** Called on every registration answer, including automatic re-registrations. */
+    onRegistrationAnswered(handler: (result: RegisterResult) => void): Unsubscribe;
+    /** Called when vMenu stops, after which the plugin waits to register again. */
+    onDisconnected(handler: () => void): Unsubscribe;
+    /**
+     * Registers with vMenu. The promise resolves on vMenu's first answer, which can be a while when
+     * vMenu starts later than your resource. It never rejects: a refusal arrives as a result with
+     * `accepted` false.
+     */
+    connect(): Promise<RegisterResult>;
+    /** Shows a message through vMenu's notification area, credited to your resource. */
+    notify(style: NotifyStyle, text: TextLike, durationMs?: number): void;
+    /** Asks the player for text through vMenu's input box. Resolves to null if they cancelled or the box was unavailable. */
+    getText(title: TextLike, options?: {
+        maxLength?: number;
+        initialValue?: string;
+        suggestions?: readonly PromptSuggestion[];
+    }): Promise<string | null>;
+    /** Asks several questions one after another. Resolves to null if the player cancelled any of them. */
+    getTexts(prompts: readonly PluginPrompt[]): Promise<string[] | null>;
+    /**
+     * Groups every change made inside `changes` into one update, so many small changes cost vMenu a
+     * single repaint. Nesting is fine: only the outermost batch sends. The batch ends when `changes`
+     * returns, so changes made after an `await` inside it are sent on their own.
+     */
+    batch<T>(changes: () => T): T;
+    private endBatch;
+    private markFilterDirty;
+    private carriedByPendingAdd;
+    private send;
+    private ensureHandlers;
+    private sendRegistration;
+    private buildRequest;
+    private onRegisterResult;
+    private onCallback;
+    private itemOrUndefined;
+    private onPromptResult;
+    private cancelPendingPrompts;
+    private onResourceStop;
+}

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

@@ -0,0 +1,2 @@
+export declare function readBool(itemId: string): boolean | undefined;
+export declare function writeBool(itemId: string, value: boolean): void;

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

@@ -0,0 +1,49 @@
+/**
+ * One of your plugin's convar settings. The full convar name is
+ * `vMenu.Enhanced.Plugins.<Id>.<Name>`, set by the server owner with `setr`, and readable here
+ * because replicated convars reach every resource.
+ */
+export declare abstract class PluginSetting<T> {
+    /** The short name you declared. */
+    readonly name: string;
+    /** The composed convar name a server owner sets. */
+    readonly fullName: string;
+    /** The value used while the server owner has not set the convar. */
+    readonly defaultValue: T;
+    /** The current value, read from the convar every time. */
+    abstract get value(): T;
+    protected raw(fallback: string): string;
+}
+/** A setting that is on or off. Gates can use it through `Gate.setting`. */
+export declare class PluginBoolSetting extends PluginSetting<boolean> {
+    get value(): boolean;
+}
+/** A whole number setting. */
+export declare class PluginIntSetting extends PluginSetting<number> {
+    get value(): number;
+}
+/** A decimal number setting. */
+export declare class PluginFloatSetting extends PluginSetting<number> {
+    get value(): number;
+}
+/** A text setting. An empty convar falls back to the default. */
+export declare class PluginStringSetting extends PluginSetting<string> {
+    get value(): string;
+}
+/**
+ * Your plugin's settings. Declaring one here lets your menu gate on it and lets vMenu track it for
+ * live refresh. Declare the same settings in your server script too, so they appear in the template
+ * vMenu writes for the server owner.
+ */
+export declare class PluginSettings {
+    private readonly prefix;
+    /** Declares an on or off setting. */
+    bool(name: string, defaultValue: boolean, description: string): PluginBoolSetting;
+    /** Declares a whole number setting. */
+    int(name: string, defaultValue: number, description: string): PluginIntSetting;
+    /** Declares a decimal number setting. */
+    float(name: string, defaultValue: number, description: string): PluginFloatSetting;
+    /** Declares a text setting. */
+    string(name: string, defaultValue: string, description: string): PluginStringSetting;
+    private declare;
+}

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

@@ -0,0 +1,36 @@
+import { type Unsubscribe } from '../signal';
+/** One of vMenu's looks. Hand the `id` to `themes.set` to put the menus in it, and show the `name` to the player. */
+export interface PluginTheme {
+    readonly id: string;
+    readonly name: string;
+    /** Whether this is the theme on screen right now. */
+    readonly isCurrent: boolean;
+}
+/**
+ * The look of vMenu's menus, as seen by this player only. vMenu hands the list over right after the
+ * plugin registers and again on every change, so read `available` from `onChanged` rather than
+ * straight after connecting. A theme set here lasts as long as the client runs.
+ */
+export declare class PluginThemes {
+    private readonly plugin;
+    private availableValue;
+    private currentIdValue?;
+    private configuredIdValue?;
+    private overriddenValue;
+    private readonly changed;
+    /** Every theme vMenu offers, in the order it lists them. Empty until vMenu has sent them. */
+    get available(): readonly PluginTheme[];
+    /** The id of the theme on screen, undefined until vMenu has said what it is. */
+    get currentId(): string | undefined;
+    /** The id the server's own setting asks for, which is where `reset` goes. */
+    get configuredId(): string | undefined;
+    /** Whether a plugin is overriding the server's setting for this player right now. */
+    get isOverridden(): boolean;
+    /** Called whenever the list or the theme on screen changed, including when somebody else changed it. */
+    onChanged(handler: () => void): Unsubscribe;
+    /** Puts vMenu's menus in a theme for this player. An id vMenu does not know is ignored. */
+    set(themeId: string): void;
+    /** Drops the override and goes back to the theme the server's setting asks for. */
+    reset(): void;
+    private send;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Your plugin's translation tables: language code to key to text. An English table under "en" is
+ * required as soon as any of your texts use keys, and it is the fallback whenever the selected
+ * language has no entry. vMenu follows its selected language live.
+ */
+export declare class PluginTranslations {
+    private readonly plugin;
+    /** Adds or extends one language's table. Later entries win over earlier ones. */
+    add(languageCode: string, entries: Readonly<Record<string, string>>): void;
+}

package/dist/types/fivem.d.ts

@@ -0,0 +1,14 @@
+export declare const currentResource: () => string;
+export declare const emitLocal: (eventName: string, ...args: unknown[]) => void;
+export declare const onLocal: (eventName: string, handler: (...args: any[]) => void) => void;
+export declare const getConvar: (name: string, fallback: string) => string;
+export declare const getKvp: (key: string) => string | undefined;
+export declare const setKvp: (key: string, value: string) => void;
+export declare const isAceAllowed: (playerSource: string, object: string) => boolean;
+export declare const log: {
+    info: (resource: string, message: string) => void;
+    warn: (resource: string, message: string) => void;
+    error: (resource: string, message: string) => void;
+};
+export declare function parseJson<T>(json: unknown): T | undefined;
+export declare function sanitizeId(resource: string): string;

package/dist/types/format.d.ts

@@ -0,0 +1 @@
+export declare function formatFloat(value: number): string;

package/dist/types/iife.d.ts

@@ -0,0 +1,2 @@
+export * from './client/index';
+export { ServerPluginDeclaration, VMenuServer } from './server/index';