@vespura/vmenu-plugin 1.0.14 → 1.0.15

package/README.md

@@ -4,7 +4,7 @@ The TypeScript and JavaScript plugin API for vMenu Enhanced, the version of vMen
 
 A plugin is a normal FiveM resource of your own. With this package, your resource can add menus to vMenu, under a Plugins entry on its main menu. You describe the menu in code and the package talks to vMenu over events for you. vMenu never needs to know about your resource ahead of time.
 
-Everything the C# plugin API can do is here too. That covers buttons, checkboxes, lists, sliders, dynamic lists, submenus, confirm rows, separators, keys, player actions, translations, permission and setting gates, notifications, text prompts and themes.
+Everything the C# plugin API can do is here too. That covers buttons, checkboxes, lists, sliders, dynamic lists, submenus, confirm rows, separators, keys, player actions, translations, permission and setting gates, notifications, text prompts, themes and standalone menus.
 
 ```ts
 import { Gate, NotifyStyle, Text, VMenuPlugin } from '@vespura/vmenu-plugin/client';

package/dist/client.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var version = true ? "1.0.14" : "0.0.0-local";
+var version = true ? "1.0.15" : "0.0.0-local";
 
 // src/text.ts
 var Text = class _Text {
@@ -133,7 +133,9 @@ function int(value) {
 }
 
 // src/protocol.ts
-var PROTOCOL_VERSION = 2;
+var PROTOCOL_VERSION = 3;
+var BASE_PROTOCOL_VERSION = 2;
+var MAX_STANDALONE_MENUS = 50;
 var VMENU_RESOURCE = "vMenu.Enhanced";
 var PluginEvents = {
   Probe: "vMenu.Enhanced:Plugins:Probe",
@@ -153,6 +155,7 @@ var PluginEvents = {
   registerResultFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:RegisterResult`,
   eventFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:Event`,
   promptResultFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:PromptResult`,
+  openResultFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:OpenResult`,
   themesFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:Themes`,
   themesRegisteredFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:ThemesRegistered`,
   serverReadyFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:Server:Ready`,
@@ -173,6 +176,8 @@ var NodeEvents = {
   Opened: "opened",
   Closed: "closed",
   IndexChanged: "indexChanged",
+  Replaced: "replaced",
+  ForceClosed: "forceClosed",
   Highlighted: "highlighted"
 };
 var SettingTypes = {
@@ -195,6 +200,8 @@ var CallbackTypes = {
   MenuOpened: "menuOpened",
   MenuClosed: "menuClosed",
   MenuIndexChanged: "menuIndexChanged",
+  MenuReplaced: "menuReplaced",
+  MenuForceClosed: "menuForceClosed",
   PlayerActionSelected: "playerActionSelected",
   PlayerActionConfirmed: "playerActionConfirmed",
   PlayerActionListSelected: "playerActionListSelected",
@@ -231,6 +238,7 @@ var UpdateOps = {
   SetMenuEvents: "setMenuEvents",
   SetFilter: "setFilter",
   ClearFilter: "clearFilter",
+  AddStandaloneMenu: "addStandaloneMenu",
   AddKeys: "addKeys",
   SetKeyText: "setKeyText",
   SetKeyEnabled: "setKeyEnabled",
@@ -913,6 +921,37 @@ var PluginKey = class {
 };
 
 // src/client/menu.ts
+var MenuPriority = {
+  /** Only opens when no vMenu or plugin menu is open. */
+  None: "none",
+  /** Replaces vMenu's menus and other menus at low priority. */
+  Low: "low",
+  /** Replaces anything at low or medium priority. */
+  Medium: "medium",
+  /**
+   * Replaces anything that is not locked. Only use this in extreme situations, prevents vMenu or other plugins with a
+   * lower priority from opening any menus while yours is open. Use responsibly!
+   */
+  High: "high"
+};
+var OpenMenuResult = {
+  /** The menu is on screen. */
+  Opened: "opened",
+  /** A menu with a higher priority is open, or any menu is open for a request at `None`. */
+  BlockedByPriority: "blockedByPriority",
+  /** Another menu asked not to be closed. */
+  BlockedByLock: "blockedByLock",
+  /** vMenu does not know this menu, for example an empty root menu, which has no row yet. */
+  UnknownMenu: "unknownMenu",
+  /** The player is not allowed into this menu, for example because a gate on the row leading to it fails. */
+  NotAllowed: "notAllowed",
+  /** A later open or close in the same batch took its place. */
+  Superseded: "superseded",
+  /** The plugin is not connected to vMenu, or vMenu stopped before it answered. */
+  NotConnected: "notConnected",
+  /** The vMenu this plugin talks to predates open priorities. Nothing was opened, use `open()` there instead. */
+  NotSupported: "notSupported"
+};
 var PluginMenu = class _PluginMenu {
   /** @internal */
   constructor(plugin, node, title, subtitle) {
@@ -925,6 +964,8 @@ var PluginMenu = class _PluginMenu {
     this.opened = new Signal(() => plugin.resource, "opened");
     this.closed = new Signal(() => plugin.resource, "closed");
     this.indexChanged = new Signal(() => plugin.resource, "indexChanged");
+    this.replaced = new Signal(() => plugin.resource, "replaced");
+    this.forceClosed = new Signal(() => plugin.resource, "forceClosed");
   }
   /** The menu's id, how vMenu refers to it. */
   get id() {
@@ -1152,10 +1193,53 @@ var PluginMenu = class _PluginMenu {
     this.node.items.length = 0;
     this.plugin.emitOp({ op: UpdateOps.ClearMenu, menuId: this.id });
   }
-  /** Opens this menu on screen, closing whatever vMenu menu was open. */
+  /** Opens this menu on screen at low priority, closing whatever vMenu menu was open. Use `requestOpen` to learn whether it worked. */
   open() {
     this.plugin.emitOp({ op: UpdateOps.OpenMenu, menuId: this.id });
   }
+  /**
+   * Opens this menu only when no vMenu or plugin menu is open, so it never interrupts the player. Switching between your
+   * own menus always works.
+   */
+  requestOpen() {
+    return this.requestOpenWithPriority(MenuPriority.None);
+  }
+  /**
+   * Opens this menu, closing an open menu of equal or lower priority. A menu with a higher priority, or one that asked
+   * not to be closed, keeps the screen and the request is refused.
+   *
+   * @param priority `High`: only use this in extreme situations, prevents vMenu or other plugins with a lower priority
+   * from opening any menus while yours is open. Use responsibly!
+   * @param doNotClose Only with `High`. Only use this in extreme situations. It blocks the player from using anything
+   * else, so always close the menu as soon as possible. The lock ends when you close the menu or open its parent, and
+   * the player can still force it shut by holding back.
+   * @throws When `doNotClose` is set below `High`.
+   */
+  requestOpenWithPriority(priority, doNotClose = false) {
+    if (!Object.values(MenuPriority).includes(priority)) {
+      throw new Error(`'${String(priority)}' is not a menu priority.`);
+    }
+    if (doNotClose && priority !== MenuPriority.High) {
+      throw new Error("doNotClose only works with MenuPriority.High.");
+    }
+    return this.plugin.requestOpen(this, priority, doNotClose);
+  }
+  /** Called when another plugin's menu took the screen while the player was in this one. `onClosed` fires as well. */
+  onReplaced(handler) {
+    const unsubscribe = this.replaced.add(handler);
+    this.subscribeMenuEvent(NodeEvents.Replaced);
+    return unsubscribe;
+  }
+  /**
+   * Called when this menu was opened with `doNotClose` and closed by anything other than your own code: the player
+   * holding back to force it shut, or vMenu having to close it. Whatever the player was in the middle of was left
+   * unfinished.
+   */
+  onForceClosed(handler) {
+    const unsubscribe = this.forceClosed.add(handler);
+    this.subscribeMenuEvent(NodeEvents.ForceClosed);
+    return unsubscribe;
+  }
   /** Closes this plugin's menu if one is open. */
   close() {
     this.plugin.emitOp({ op: UpdateOps.CloseMenu, menuId: this.id });
@@ -1199,6 +1283,12 @@ var PluginMenu = class _PluginMenu {
           this.indexChanged.fire(callback.oldIndex ?? 0, callback.newIndex);
         }
         break;
+      case CallbackTypes.MenuReplaced:
+        this.replaced.fire();
+        break;
+      case CallbackTypes.MenuForceClosed:
+        this.forceClosed.fire();
+        break;
     }
   }
   /** @internal */
@@ -1206,8 +1296,12 @@ var PluginMenu = class _PluginMenu {
     if (!node.menu) {
       return node;
     }
-    const { items: _items, ...menu } = node.menu;
-    return { ...node, menu: { ...menu, items: [] } };
+    return { ...node, menu: _PluginMenu.withoutItems(node.menu) };
+  }
+  /** @internal */
+  static withoutItems(node) {
+    const { items: _items, ...menu } = node;
+    return { ...menu, items: [] };
   }
   newNode(type, text, options) {
     return { id: options?.id ?? this.plugin.nextItemId(), type, text: Text.toRef(text) };
@@ -1537,6 +1631,8 @@ var VMenuPlugin = class _VMenuPlugin {
     this.menusById = /* @__PURE__ */ new Map();
     this.keysById = /* @__PURE__ */ new Map();
     this.pendingPrompts = /* @__PURE__ */ new Map();
+    this.pendingOpens = /* @__PURE__ */ new Map();
+    this.standalone = [];
     this.pendingItems = /* @__PURE__ */ new Set();
     this.pendingMenus = /* @__PURE__ */ new Set();
     this.dirtyFilters = [];
@@ -1544,6 +1640,8 @@ var VMenuPlugin = class _VMenuPlugin {
     this.nextItem = 0;
     this.nextMenu = 0;
     this.nextPrompt = 0;
+    this.nextOpen = 0;
+    this.vMenuProtocol = 0;
     this.handlersRegistered = false;
     this.connected = false;
     this.resource = currentResource();
@@ -1557,6 +1655,10 @@ var VMenuPlugin = class _VMenuPlugin {
     this.disconnected = new Signal(() => this.resource, "disconnected");
     this.registerMenu(this.rootMenu);
   }
+  /** Menus added with `addStandaloneMenu`. */
+  get standaloneMenus() {
+    return this.standalone;
+  }
   /** Creates the plugin. One per resource: a second call returns the first instance. */
   static create(displayName) {
     if (instance) {
@@ -1591,6 +1693,38 @@ var VMenuPlugin = class _VMenuPlugin {
     emitLocal(PluginEvents.Probe);
     return this.firstResult;
   }
+  /**
+   * Adds a top level menu of your own, outside vMenu's Plugins menu. It has no row anywhere and no toggle key: only your
+   * code opens it, through `menu.requestOpen()`. Needs a vMenu that knows standalone menus, an older one refuses the
+   * registration. Adding one after connecting appears live.
+   *
+   * @param id Letters, digits and underscores, unique within your plugin. "root" and "m" followed by digits are taken
+   * by the menus the API names itself.
+   * @throws When the id is malformed, reserved or already used, when the plugin already has 50 standalone menus, or when
+   * it is connected to a vMenu that predates standalone menus.
+   */
+  addStandaloneMenu(id, title, subtitle) {
+    if (!/^[A-Za-z0-9_]+$/.test(id)) {
+      throw new Error("A standalone menu id may only contain letters, digits and underscores.");
+    }
+    if (id === "root" || /^m\d+$/.test(id)) {
+      throw new Error(`'${id}' is reserved for the menus the API names itself.`);
+    }
+    if (this.menusById.has(id)) {
+      throw new Error(`A menu with id '${id}' already exists.`);
+    }
+    if (this.standalone.length >= MAX_STANDALONE_MENUS) {
+      throw new Error(`A plugin may have at most ${MAX_STANDALONE_MENUS} standalone menus.`);
+    }
+    if (this.connected && this.vMenuProtocol < PROTOCOL_VERSION) {
+      throw new Error("The vMenu this plugin is connected to predates standalone menus. Update vMenu.");
+    }
+    const menu = new PluginMenu(this, { id, title: Text.toRef(title), subtitle: Text.toRef(subtitle), items: [] }, title, subtitle);
+    this.registerMenu(menu);
+    this.standalone.push(menu);
+    this.emitOp({ op: UpdateOps.AddStandaloneMenu, menu: menu.node });
+    return menu;
+  }
   /** Shows a message through vMenu's notification area, credited to your resource. */
   notify(style, text, durationMs) {
     if (!this.connected) {
@@ -1687,6 +1821,9 @@ var VMenuPlugin = class _VMenuPlugin {
     if (this.carriedByPendingAdd(op)) {
       return;
     }
+    if (op.op === UpdateOps.AddStandaloneMenu && op.menu) {
+      this.pendingMenus.add(op.menu.id);
+    }
     if (op.op === UpdateOps.AddItems) {
       for (const node of op.items ?? []) {
         this.pendingItems.add(node.id);
@@ -1698,6 +1835,19 @@ var VMenuPlugin = class _VMenuPlugin {
     batch.push(op);
   }
   /** @internal */
+  requestOpen(menu, priority, doNotClose) {
+    if (!this.connected) {
+      return Promise.resolve(OpenMenuResult.NotConnected);
+    }
+    if (this.vMenuProtocol < PROTOCOL_VERSION) {
+      return Promise.resolve(OpenMenuResult.NotSupported);
+    }
+    const requestId = ++this.nextOpen;
+    const pending = new Promise((resolve) => this.pendingOpens.set(requestId, resolve));
+    this.emitOp({ op: UpdateOps.OpenMenu, menuId: menu.id, priority, doNotClose: doNotClose || void 0, requestId });
+    return pending;
+  }
+  /** @internal */
   filterChanged(menu) {
     if (!this.connected) {
       return;
@@ -1767,9 +1917,15 @@ var VMenuPlugin = class _VMenuPlugin {
     return false;
   }
   send(ops) {
-    const payload = ops.map(
-      (op) => op.op === UpdateOps.AddItems && op.items ? { ...op, items: op.items.map(PluginMenu.asAdded) } : op
-    );
+    const payload = ops.map((op) => {
+      if (op.op === UpdateOps.AddItems && op.items) {
+        return { ...op, items: op.items.map(PluginMenu.asAdded) };
+      }
+      if (op.op === UpdateOps.AddStandaloneMenu && op.menu) {
+        return { ...op, menu: PluginMenu.withoutItems(op.menu) };
+      }
+      return op;
+    });
     emitLocal(PluginEvents.Update, JSON.stringify({ ops: payload }));
   }
   ensureHandlers() {
@@ -1777,23 +1933,30 @@ var VMenuPlugin = class _VMenuPlugin {
       return;
     }
     this.handlersRegistered = true;
-    onLocal(PluginEvents.Ready, () => this.sendRegistration());
-    onLocal(PluginEvents.readyFor(this.resource), () => this.sendRegistration());
+    onLocal(PluginEvents.Ready, (protocolVersion) => this.onReady(protocolVersion));
+    onLocal(PluginEvents.readyFor(this.resource), (protocolVersion) => this.onReady(protocolVersion));
     onLocal(PluginEvents.registerResultFor(this.resource), (json) => this.onRegisterResult(json));
     onLocal(PluginEvents.eventFor(this.resource), (json) => this.onCallback(json));
     onLocal(PluginEvents.promptResultFor(this.resource), (json) => this.onPromptResult(json));
+    onLocal(PluginEvents.openResultFor(this.resource), (json) => this.onOpenResult(json));
     onLocal(PluginEvents.themesFor(this.resource), (json) => this.themes.handle(json));
     onLocal("onResourceStop", (stopped) => this.onResourceStop(stopped));
   }
+  onReady(protocolVersion) {
+    this.vMenuProtocol = typeof protocolVersion === "number" ? protocolVersion : 0;
+    this.sendRegistration();
+  }
   sendRegistration() {
     emitLocal(PluginEvents.Register, JSON.stringify(this.buildRequest()));
   }
   buildRequest() {
     const request = {
-      protocolVersion: PROTOCOL_VERSION,
+      // Only a plugin that needs a newer vMenu says so, so everything else still registers with an older one.
+      protocolVersion: this.standalone.length > 0 ? PROTOCOL_VERSION : BASE_PROTOCOL_VERSION,
       displayName: Text.toRef(this.displayName),
       descriptionKey: this.descriptionKey,
       menu: this.rootMenu.node,
+      standaloneMenus: this.standalone.length > 0 ? this.standalone.map((menu) => menu.node) : void 0,
       playerActions: this.playerActions.nodes.length > 0 ? this.playerActions.nodes : void 0
     };
     if (Object.keys(this.translations.tables).length > 0) {
@@ -1819,6 +1982,7 @@ var VMenuPlugin = class _VMenuPlugin {
     this.connected = result.accepted;
     if (!this.connected) {
       this.cancelPendingPrompts();
+      this.cancelPendingOpens();
     } else {
       this.batch(() => {
         for (const menu of this.menusById.values()) {
@@ -1841,7 +2005,9 @@ var VMenuPlugin = class _VMenuPlugin {
       switch (callback.type) {
         case CallbackTypes.MenuOpened:
         case CallbackTypes.MenuClosed:
-        case CallbackTypes.MenuIndexChanged: {
+        case CallbackTypes.MenuIndexChanged:
+        case CallbackTypes.MenuReplaced:
+        case CallbackTypes.MenuForceClosed: {
           const menu = callback.menuId === void 0 ? void 0 : this.menusById.get(callback.menuId);
           menu?.handleMenu(callback);
           break;
@@ -1875,6 +2041,25 @@ var VMenuPlugin = class _VMenuPlugin {
       pending(result);
     }
   }
+  onOpenResult(json) {
+    const result = parseJson(json);
+    if (!result) {
+      return;
+    }
+    const pending = this.pendingOpens.get(result.requestId);
+    if (!pending) {
+      return;
+    }
+    this.pendingOpens.delete(result.requestId);
+    const known = Object.values(OpenMenuResult);
+    pending(known.includes(result.reason) ? result.reason : OpenMenuResult.BlockedByPriority);
+  }
+  cancelPendingOpens() {
+    for (const pending of this.pendingOpens.values()) {
+      pending(OpenMenuResult.NotConnected);
+    }
+    this.pendingOpens.clear();
+  }
   cancelPendingPrompts() {
     for (const pending of this.pendingPrompts.values()) {
       pending({ requestId: 0, cancelled: true, busy: false });
@@ -1887,12 +2072,15 @@ var VMenuPlugin = class _VMenuPlugin {
     }
     this.connected = false;
     this.cancelPendingPrompts();
+    this.cancelPendingOpens();
     this.disconnected.fire();
   }
 };
 export {
   Gate,
+  MenuPriority,
   NotifyStyle,
+  OpenMenuResult,
   PluginBoolSetting,
   PluginButton,
   PluginCheckbox,

package/dist/server.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var version = true ? "1.0.14" : "0.0.0-local";
+var version = true ? "1.0.15" : "0.0.0-local";
 
 // src/format.ts
 function formatFloat(value) {
@@ -27,6 +27,7 @@ var PluginEvents = {
   registerResultFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:RegisterResult`,
   eventFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:Event`,
   promptResultFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:PromptResult`,
+  openResultFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:OpenResult`,
   themesFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:Themes`,
   themesRegisteredFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:ThemesRegistered`,
   serverReadyFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:Server:Ready`,

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

@@ -1,7 +1,7 @@
 import type { UpdateOp } from '../protocol.js';
 import type { PluginItem } from './item.js';
 import type { PluginKey } from './key.js';
-import type { PluginMenu } from './menu.js';
+import type { MenuPriority, OpenMenuResult, PluginMenu } from './menu.js';
 export interface PluginHost {
     readonly resource: string;
     readonly isConnected: boolean;
@@ -12,6 +12,7 @@ export interface PluginHost {
     registerKey(key: PluginKey): void;
     unregisterItem(item: PluginItem): void;
     emitOp(op: UpdateOp): void;
+    requestOpen(menu: PluginMenu, priority: MenuPriority, doNotClose: boolean): Promise<OpenMenuResult>;
     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

@@ -7,7 +7,7 @@ export { PluginSetting, PluginBoolSetting, PluginIntSetting, PluginFloatSetting,
 export { PluginItem, type ItemOptions } from './item.js';
 export { PluginButton, PluginConfirmButton, PluginCheckbox, PluginList, PluginConfirmList, PluginSlider, PluginDynamicList, PluginSeparator, PluginSubmenu, } from './items.js';
 export { PluginKey, type PluginKeyPress } from './key.js';
-export { PluginMenu, type CheckboxOptions, type ConfirmOptions, type KeyOptions, type ListOptions, type SliderOptions, type SubmenuOptions, } from './menu.js';
+export { MenuPriority, OpenMenuResult, PluginMenu, type CheckboxOptions, type ConfirmOptions, type KeyOptions, type ListOptions, type SliderOptions, type SubmenuOptions, } from './menu.js';
 export { PluginPlayerActions, PluginPlayerButton, PluginPlayerConfirmButton, PluginPlayerList, type PlayerTarget, } from './playerActions.js';
 export { PluginThemes, type PluginTheme } from './themes.js';
 export { PluginTranslations } from './translations.js';

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

@@ -45,8 +45,45 @@ export interface KeyOptions {
     /** A game control index to suppress while the menu is open, for a default key the game already uses. */
     shadowedControl?: number;
 }
+/** How hard `requestOpenWithPriority` may push. vMenu's own menus always count as `None`. The plain strings work too. */
+export declare const MenuPriority: {
+    /** Only opens when no vMenu or plugin menu is open. */
+    readonly None: 'none';
+    /** Replaces vMenu's menus and other menus at low priority. */
+    readonly Low: 'low';
+    /** Replaces anything at low or medium priority. */
+    readonly Medium: 'medium';
+    /**
+     * Replaces anything that is not locked. Only use this in extreme situations, prevents vMenu or other plugins with a
+     * lower priority from opening any menus while yours is open. Use responsibly!
+     */
+    readonly High: 'high';
+};
+/** How hard `requestOpenWithPriority` may push. */
+export type MenuPriority = (typeof MenuPriority)[keyof typeof MenuPriority];
+/** What happened to a request to open a menu. The plain strings work too. */
+export declare const OpenMenuResult: {
+    /** The menu is on screen. */
+    readonly Opened: 'opened';
+    /** A menu with a higher priority is open, or any menu is open for a request at `None`. */
+    readonly BlockedByPriority: 'blockedByPriority';
+    /** Another menu asked not to be closed. */
+    readonly BlockedByLock: 'blockedByLock';
+    /** vMenu does not know this menu, for example an empty root menu, which has no row yet. */
+    readonly UnknownMenu: 'unknownMenu';
+    /** The player is not allowed into this menu, for example because a gate on the row leading to it fails. */
+    readonly NotAllowed: 'notAllowed';
+    /** A later open or close in the same batch took its place. */
+    readonly Superseded: 'superseded';
+    /** The plugin is not connected to vMenu, or vMenu stopped before it answered. */
+    readonly NotConnected: 'notConnected';
+    /** The vMenu this plugin talks to predates open priorities. Nothing was opened, use `open()` there instead. */
+    readonly NotSupported: 'notSupported';
+};
+/** What happened to a request to open a menu. */
+export type OpenMenuResult = (typeof OpenMenuResult)[keyof typeof OpenMenuResult];
 /**
- * One of your plugin's menus: the root under your row in vMenu's Plugins menu, or a submenu. Rows
+ * One of your plugin's menus: the root under your row in vMenu's Plugins menu, a standalone menu, or a submenu. Rows
  * added before connecting ride along with the registration, rows added later appear live.
  */
 export declare class PluginMenu {
@@ -58,6 +95,8 @@ export declare class PluginMenu {
     private readonly opened;
     private readonly closed;
     private readonly indexChanged;
+    private readonly replaced;
+    private readonly forceClosed;
     private insertIndex?;
     private filterFn?;
     /** The menu's id, how vMenu refers to it. */
@@ -126,8 +165,33 @@ export declare class PluginMenu {
     remove(item: PluginItem): void;
     /** Removes every row. */
     clear(): void;
-    /** Opens this menu on screen, closing whatever vMenu menu was open. */
+    /** Opens this menu on screen at low priority, closing whatever vMenu menu was open. Use `requestOpen` to learn whether it worked. */
     open(): void;
+    /**
+     * Opens this menu only when no vMenu or plugin menu is open, so it never interrupts the player. Switching between your
+     * own menus always works.
+     */
+    requestOpen(): Promise<OpenMenuResult>;
+    /**
+     * Opens this menu, closing an open menu of equal or lower priority. A menu with a higher priority, or one that asked
+     * not to be closed, keeps the screen and the request is refused.
+     *
+     * @param priority `High`: only use this in extreme situations, prevents vMenu or other plugins with a lower priority
+     * from opening any menus while yours is open. Use responsibly!
+     * @param doNotClose Only with `High`. Only use this in extreme situations. It blocks the player from using anything
+     * else, so always close the menu as soon as possible. The lock ends when you close the menu or open its parent, and
+     * the player can still force it shut by holding back.
+     * @throws When `doNotClose` is set below `High`.
+     */
+    requestOpenWithPriority(priority: MenuPriority, doNotClose?: boolean): Promise<OpenMenuResult>;
+    /** Called when another plugin's menu took the screen while the player was in this one. `onClosed` fires as well. */
+    onReplaced(handler: () => void): Unsubscribe;
+    /**
+     * Called when this menu was opened with `doNotClose` and closed by anything other than your own code: the player
+     * holding back to force it shut, or vMenu having to close it. Whatever the player was in the middle of was left
+     * unfinished.
+     */
+    onForceClosed(handler: () => void): Unsubscribe;
     /** Closes this plugin's menu if one is open. */
     close(): void;
     /**

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

@@ -42,6 +42,8 @@ export declare class VMenuPlugin {
     private readonly menusById;
     private readonly keysById;
     private readonly pendingPrompts;
+    private readonly pendingOpens;
+    private readonly standalone;
     private readonly pendingItems;
     private readonly pendingMenus;
     private readonly dirtyFilters;
@@ -54,6 +56,8 @@ export declare class VMenuPlugin {
     private nextItem;
     private nextMenu;
     private nextPrompt;
+    private nextOpen;
+    private vMenuProtocol;
     private handlersRegistered;
     private connected;
     /** The resource this plugin runs in, its identity towards vMenu. */
@@ -70,6 +74,8 @@ export declare class VMenuPlugin {
     readonly themes: PluginThemes;
     /** The menu behind your row in vMenu's Plugins menu. */
     readonly rootMenu: PluginMenu;
+    /** Menus added with `addStandaloneMenu`. */
+    get standaloneMenus(): readonly PluginMenu[];
     /** Actions added to every player's entry of vMenu's Online Players menu. */
     readonly playerActions: PluginPlayerActions;
     private constructor();
@@ -87,6 +93,17 @@ export declare class VMenuPlugin {
      * `accepted` false.
      */
     connect(): Promise<RegisterResult>;
+    /**
+     * Adds a top level menu of your own, outside vMenu's Plugins menu. It has no row anywhere and no toggle key: only your
+     * code opens it, through `menu.requestOpen()`. Needs a vMenu that knows standalone menus, an older one refuses the
+     * registration. Adding one after connecting appears live.
+     *
+     * @param id Letters, digits and underscores, unique within your plugin. "root" and "m" followed by digits are taken
+     * by the menus the API names itself.
+     * @throws When the id is malformed, reserved or already used, when the plugin already has 50 standalone menus, or when
+     * it is connected to a vMenu that predates standalone menus.
+     */
+    addStandaloneMenu(id: string, title: TextLike, subtitle?: TextLike): PluginMenu;
     /** 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. */
@@ -108,12 +125,15 @@ export declare class VMenuPlugin {
     private carriedByPendingAdd;
     private send;
     private ensureHandlers;
+    private onReady;
     private sendRegistration;
     private buildRequest;
     private onRegisterResult;
     private onCallback;
     private itemOrUndefined;
     private onPromptResult;
+    private onOpenResult;
+    private cancelPendingOpens;
     private cancelPendingPrompts;
     private onResourceStop;
 }

package/dist/types/protocol.d.ts

@@ -1,4 +1,7 @@
-export declare const PROTOCOL_VERSION = 2;
+export declare const PROTOCOL_VERSION = 3;
+/** What a plugin without standalone menus announces, so it still registers with a vMenu that predates them. */
+export declare const BASE_PROTOCOL_VERSION = 2;
+export declare const MAX_STANDALONE_MENUS = 50;
 export declare const SERVER_PROTOCOL_VERSION = 1;
 export declare const VMENU_RESOURCE = "vMenu.Enhanced";
 export declare const PluginEvents: {
@@ -19,6 +22,7 @@ export declare const PluginEvents: {
     readonly registerResultFor: (resource: string) => string;
     readonly eventFor: (resource: string) => string;
     readonly promptResultFor: (resource: string) => string;
+    readonly openResultFor: (resource: string) => string;
     readonly themesFor: (resource: string) => string;
     readonly themesRegisteredFor: (resource: string) => string;
     readonly serverReadyFor: (resource: string) => string;
@@ -40,6 +44,8 @@ export declare const NodeEvents: {
     readonly Opened: 'opened';
     readonly Closed: 'closed';
     readonly IndexChanged: 'indexChanged';
+    readonly Replaced: 'replaced';
+    readonly ForceClosed: 'forceClosed';
     readonly Highlighted: 'highlighted';
 };
 export declare const SettingTypes: {
@@ -62,11 +68,27 @@ export declare const CallbackTypes: {
     readonly MenuOpened: 'menuOpened';
     readonly MenuClosed: 'menuClosed';
     readonly MenuIndexChanged: 'menuIndexChanged';
+    readonly MenuReplaced: 'menuReplaced';
+    readonly MenuForceClosed: 'menuForceClosed';
     readonly PlayerActionSelected: 'playerActionSelected';
     readonly PlayerActionConfirmed: 'playerActionConfirmed';
     readonly PlayerActionListSelected: 'playerActionListSelected';
     readonly KeyPressed: 'keyPressed';
 };
+export declare const MenuPriorities: {
+    readonly None: 'none';
+    readonly Low: 'low';
+    readonly Medium: 'medium';
+    readonly High: 'high';
+};
+export declare const OpenMenuReasons: {
+    readonly Opened: 'opened';
+    readonly BlockedByPriority: 'blockedByPriority';
+    readonly BlockedByLock: 'blockedByLock';
+    readonly UnknownMenu: 'unknownMenu';
+    readonly NotAllowed: 'notAllowed';
+    readonly Superseded: 'superseded';
+};
 export declare const UpdateOps: {
     readonly SetText: 'setText';
     readonly SetDescription: 'setDescription';
@@ -98,6 +120,7 @@ export declare const UpdateOps: {
     readonly SetMenuEvents: 'setMenuEvents';
     readonly SetFilter: 'setFilter';
     readonly ClearFilter: 'clearFilter';
+    readonly AddStandaloneMenu: 'addStandaloneMenu';
     readonly AddKeys: 'addKeys';
     readonly SetKeyText: 'setKeyText';
     readonly SetKeyEnabled: 'setKeyEnabled';
@@ -180,12 +203,16 @@ export interface UpdateOp {
     options?: TextRef[];
     gate?: GateNode;
     items?: ItemNode[];
+    menu?: MenuNode;
     itemIds?: string[];
     beforeItemId?: string;
     events?: string[];
     keys?: KeyNode[];
     language?: string;
     entries?: Record<string, string>;
+    priority?: string;
+    doNotClose?: boolean;
+    requestId?: number;
 }
 export interface PluginCallback {
     type: string;
@@ -213,6 +240,7 @@ export interface RegisterRequest {
     translations?: Record<string, Record<string, string>>;
     settings?: SettingNode[];
     menu?: MenuNode;
+    standaloneMenus?: MenuNode[];
     playerActions?: ItemNode[];
 }
 /** vMenu's answer to a registration. Errors mean it was refused, warnings mean it was accepted with parts skipped. */
@@ -238,6 +266,11 @@ export interface PromptRequest {
         }[];
     }[];
 }
+export interface OpenMenuResultPayload {
+    requestId: number;
+    opened: boolean;
+    reason: string;
+}
 export interface PromptResult {
     requestId: number;
     cancelled: boolean;

package/dist/vmenu.js

@@ -1,4 +1,4 @@
-// vMenu Enhanced plugin API for JavaScript, built for vMenu Enhanced v1.0.14.
+// vMenu Enhanced plugin API for JavaScript, built for vMenu Enhanced v1.0.15.
 // Copy this file into your resource and load it before your own scripts, see https://docs.vespura.com/vmenu/enhanced/plugins/javascript/
 "use strict";
 var vMenu = (() => {
@@ -24,7 +24,9 @@ var vMenu = (() => {
   var iife_exports = {};
   __export(iife_exports, {
     Gate: () => Gate,
+    MenuPriority: () => MenuPriority,
     NotifyStyle: () => NotifyStyle,
+    OpenMenuResult: () => OpenMenuResult,
     PluginBoolSetting: () => PluginBoolSetting,
     PluginButton: () => PluginButton,
     PluginCheckbox: () => PluginCheckbox,
@@ -57,7 +59,7 @@ var vMenu = (() => {
   });
 
   // src/version.ts
-  var version = true ? "1.0.14" : "0.0.0-local";
+  var version = true ? "1.0.15" : "0.0.0-local";
 
   // src/text.ts
   var Text = class _Text {
@@ -192,7 +194,9 @@ var vMenu = (() => {
   }
 
   // src/protocol.ts
-  var PROTOCOL_VERSION = 2;
+  var PROTOCOL_VERSION = 3;
+  var BASE_PROTOCOL_VERSION = 2;
+  var MAX_STANDALONE_MENUS = 50;
   var SERVER_PROTOCOL_VERSION = 1;
   var VMENU_RESOURCE = "vMenu.Enhanced";
   var PluginEvents = {
@@ -213,6 +217,7 @@ var vMenu = (() => {
     registerResultFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:RegisterResult`,
     eventFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:Event`,
     promptResultFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:PromptResult`,
+    openResultFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:OpenResult`,
     themesFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:Themes`,
     themesRegisteredFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:ThemesRegistered`,
     serverReadyFor: (resource) => `vMenu.Enhanced:Plugins:${resource}:Server:Ready`,
@@ -234,6 +239,8 @@ var vMenu = (() => {
     Opened: "opened",
     Closed: "closed",
     IndexChanged: "indexChanged",
+    Replaced: "replaced",
+    ForceClosed: "forceClosed",
     Highlighted: "highlighted"
   };
   var SettingTypes = {
@@ -256,6 +263,8 @@ var vMenu = (() => {
     MenuOpened: "menuOpened",
     MenuClosed: "menuClosed",
     MenuIndexChanged: "menuIndexChanged",
+    MenuReplaced: "menuReplaced",
+    MenuForceClosed: "menuForceClosed",
     PlayerActionSelected: "playerActionSelected",
     PlayerActionConfirmed: "playerActionConfirmed",
     PlayerActionListSelected: "playerActionListSelected",
@@ -292,6 +301,7 @@ var vMenu = (() => {
     SetMenuEvents: "setMenuEvents",
     SetFilter: "setFilter",
     ClearFilter: "clearFilter",
+    AddStandaloneMenu: "addStandaloneMenu",
     AddKeys: "addKeys",
     SetKeyText: "setKeyText",
     SetKeyEnabled: "setKeyEnabled",
@@ -974,6 +984,37 @@ var vMenu = (() => {
   };
 
   // src/client/menu.ts
+  var MenuPriority = {
+    /** Only opens when no vMenu or plugin menu is open. */
+    None: "none",
+    /** Replaces vMenu's menus and other menus at low priority. */
+    Low: "low",
+    /** Replaces anything at low or medium priority. */
+    Medium: "medium",
+    /**
+     * Replaces anything that is not locked. Only use this in extreme situations, prevents vMenu or other plugins with a
+     * lower priority from opening any menus while yours is open. Use responsibly!
+     */
+    High: "high"
+  };
+  var OpenMenuResult = {
+    /** The menu is on screen. */
+    Opened: "opened",
+    /** A menu with a higher priority is open, or any menu is open for a request at `None`. */
+    BlockedByPriority: "blockedByPriority",
+    /** Another menu asked not to be closed. */
+    BlockedByLock: "blockedByLock",
+    /** vMenu does not know this menu, for example an empty root menu, which has no row yet. */
+    UnknownMenu: "unknownMenu",
+    /** The player is not allowed into this menu, for example because a gate on the row leading to it fails. */
+    NotAllowed: "notAllowed",
+    /** A later open or close in the same batch took its place. */
+    Superseded: "superseded",
+    /** The plugin is not connected to vMenu, or vMenu stopped before it answered. */
+    NotConnected: "notConnected",
+    /** The vMenu this plugin talks to predates open priorities. Nothing was opened, use `open()` there instead. */
+    NotSupported: "notSupported"
+  };
   var PluginMenu = class _PluginMenu {
     /** @internal */
     constructor(plugin, node, title, subtitle) {
@@ -986,6 +1027,8 @@ var vMenu = (() => {
       this.opened = new Signal(() => plugin.resource, "opened");
       this.closed = new Signal(() => plugin.resource, "closed");
       this.indexChanged = new Signal(() => plugin.resource, "indexChanged");
+      this.replaced = new Signal(() => plugin.resource, "replaced");
+      this.forceClosed = new Signal(() => plugin.resource, "forceClosed");
     }
     /** The menu's id, how vMenu refers to it. */
     get id() {
@@ -1213,10 +1256,53 @@ var vMenu = (() => {
       this.node.items.length = 0;
       this.plugin.emitOp({ op: UpdateOps.ClearMenu, menuId: this.id });
     }
-    /** Opens this menu on screen, closing whatever vMenu menu was open. */
+    /** Opens this menu on screen at low priority, closing whatever vMenu menu was open. Use `requestOpen` to learn whether it worked. */
     open() {
       this.plugin.emitOp({ op: UpdateOps.OpenMenu, menuId: this.id });
     }
+    /**
+     * Opens this menu only when no vMenu or plugin menu is open, so it never interrupts the player. Switching between your
+     * own menus always works.
+     */
+    requestOpen() {
+      return this.requestOpenWithPriority(MenuPriority.None);
+    }
+    /**
+     * Opens this menu, closing an open menu of equal or lower priority. A menu with a higher priority, or one that asked
+     * not to be closed, keeps the screen and the request is refused.
+     *
+     * @param priority `High`: only use this in extreme situations, prevents vMenu or other plugins with a lower priority
+     * from opening any menus while yours is open. Use responsibly!
+     * @param doNotClose Only with `High`. Only use this in extreme situations. It blocks the player from using anything
+     * else, so always close the menu as soon as possible. The lock ends when you close the menu or open its parent, and
+     * the player can still force it shut by holding back.
+     * @throws When `doNotClose` is set below `High`.
+     */
+    requestOpenWithPriority(priority, doNotClose = false) {
+      if (!Object.values(MenuPriority).includes(priority)) {
+        throw new Error(`'${String(priority)}' is not a menu priority.`);
+      }
+      if (doNotClose && priority !== MenuPriority.High) {
+        throw new Error("doNotClose only works with MenuPriority.High.");
+      }
+      return this.plugin.requestOpen(this, priority, doNotClose);
+    }
+    /** Called when another plugin's menu took the screen while the player was in this one. `onClosed` fires as well. */
+    onReplaced(handler) {
+      const unsubscribe = this.replaced.add(handler);
+      this.subscribeMenuEvent(NodeEvents.Replaced);
+      return unsubscribe;
+    }
+    /**
+     * Called when this menu was opened with `doNotClose` and closed by anything other than your own code: the player
+     * holding back to force it shut, or vMenu having to close it. Whatever the player was in the middle of was left
+     * unfinished.
+     */
+    onForceClosed(handler) {
+      const unsubscribe = this.forceClosed.add(handler);
+      this.subscribeMenuEvent(NodeEvents.ForceClosed);
+      return unsubscribe;
+    }
     /** Closes this plugin's menu if one is open. */
     close() {
       this.plugin.emitOp({ op: UpdateOps.CloseMenu, menuId: this.id });
@@ -1260,6 +1346,12 @@ var vMenu = (() => {
             this.indexChanged.fire(callback.oldIndex ?? 0, callback.newIndex);
           }
           break;
+        case CallbackTypes.MenuReplaced:
+          this.replaced.fire();
+          break;
+        case CallbackTypes.MenuForceClosed:
+          this.forceClosed.fire();
+          break;
       }
     }
     /** @internal */
@@ -1267,8 +1359,12 @@ var vMenu = (() => {
       if (!node.menu) {
         return node;
       }
-      const { items: _items, ...menu } = node.menu;
-      return { ...node, menu: { ...menu, items: [] } };
+      return { ...node, menu: _PluginMenu.withoutItems(node.menu) };
+    }
+    /** @internal */
+    static withoutItems(node) {
+      const { items: _items, ...menu } = node;
+      return { ...menu, items: [] };
     }
     newNode(type, text, options) {
       return { id: options?.id ?? this.plugin.nextItemId(), type, text: Text.toRef(text) };
@@ -1598,6 +1694,8 @@ var vMenu = (() => {
       this.menusById = /* @__PURE__ */ new Map();
       this.keysById = /* @__PURE__ */ new Map();
       this.pendingPrompts = /* @__PURE__ */ new Map();
+      this.pendingOpens = /* @__PURE__ */ new Map();
+      this.standalone = [];
       this.pendingItems = /* @__PURE__ */ new Set();
       this.pendingMenus = /* @__PURE__ */ new Set();
       this.dirtyFilters = [];
@@ -1605,6 +1703,8 @@ var vMenu = (() => {
       this.nextItem = 0;
       this.nextMenu = 0;
       this.nextPrompt = 0;
+      this.nextOpen = 0;
+      this.vMenuProtocol = 0;
       this.handlersRegistered = false;
       this.connected = false;
       this.resource = currentResource();
@@ -1618,6 +1718,10 @@ var vMenu = (() => {
       this.disconnected = new Signal(() => this.resource, "disconnected");
       this.registerMenu(this.rootMenu);
     }
+    /** Menus added with `addStandaloneMenu`. */
+    get standaloneMenus() {
+      return this.standalone;
+    }
     /** Creates the plugin. One per resource: a second call returns the first instance. */
     static create(displayName) {
       if (instance) {
@@ -1652,6 +1756,38 @@ var vMenu = (() => {
       emitLocal(PluginEvents.Probe);
       return this.firstResult;
     }
+    /**
+     * Adds a top level menu of your own, outside vMenu's Plugins menu. It has no row anywhere and no toggle key: only your
+     * code opens it, through `menu.requestOpen()`. Needs a vMenu that knows standalone menus, an older one refuses the
+     * registration. Adding one after connecting appears live.
+     *
+     * @param id Letters, digits and underscores, unique within your plugin. "root" and "m" followed by digits are taken
+     * by the menus the API names itself.
+     * @throws When the id is malformed, reserved or already used, when the plugin already has 50 standalone menus, or when
+     * it is connected to a vMenu that predates standalone menus.
+     */
+    addStandaloneMenu(id, title, subtitle) {
+      if (!/^[A-Za-z0-9_]+$/.test(id)) {
+        throw new Error("A standalone menu id may only contain letters, digits and underscores.");
+      }
+      if (id === "root" || /^m\d+$/.test(id)) {
+        throw new Error(`'${id}' is reserved for the menus the API names itself.`);
+      }
+      if (this.menusById.has(id)) {
+        throw new Error(`A menu with id '${id}' already exists.`);
+      }
+      if (this.standalone.length >= MAX_STANDALONE_MENUS) {
+        throw new Error(`A plugin may have at most ${MAX_STANDALONE_MENUS} standalone menus.`);
+      }
+      if (this.connected && this.vMenuProtocol < PROTOCOL_VERSION) {
+        throw new Error("The vMenu this plugin is connected to predates standalone menus. Update vMenu.");
+      }
+      const menu = new PluginMenu(this, { id, title: Text.toRef(title), subtitle: Text.toRef(subtitle), items: [] }, title, subtitle);
+      this.registerMenu(menu);
+      this.standalone.push(menu);
+      this.emitOp({ op: UpdateOps.AddStandaloneMenu, menu: menu.node });
+      return menu;
+    }
     /** Shows a message through vMenu's notification area, credited to your resource. */
     notify(style, text, durationMs) {
       if (!this.connected) {
@@ -1748,6 +1884,9 @@ var vMenu = (() => {
       if (this.carriedByPendingAdd(op)) {
         return;
       }
+      if (op.op === UpdateOps.AddStandaloneMenu && op.menu) {
+        this.pendingMenus.add(op.menu.id);
+      }
       if (op.op === UpdateOps.AddItems) {
         for (const node of op.items ?? []) {
           this.pendingItems.add(node.id);
@@ -1759,6 +1898,19 @@ var vMenu = (() => {
       batch.push(op);
     }
     /** @internal */
+    requestOpen(menu, priority, doNotClose) {
+      if (!this.connected) {
+        return Promise.resolve(OpenMenuResult.NotConnected);
+      }
+      if (this.vMenuProtocol < PROTOCOL_VERSION) {
+        return Promise.resolve(OpenMenuResult.NotSupported);
+      }
+      const requestId = ++this.nextOpen;
+      const pending = new Promise((resolve) => this.pendingOpens.set(requestId, resolve));
+      this.emitOp({ op: UpdateOps.OpenMenu, menuId: menu.id, priority, doNotClose: doNotClose || void 0, requestId });
+      return pending;
+    }
+    /** @internal */
     filterChanged(menu) {
       if (!this.connected) {
         return;
@@ -1828,9 +1980,15 @@ var vMenu = (() => {
       return false;
     }
     send(ops) {
-      const payload = ops.map(
-        (op) => op.op === UpdateOps.AddItems && op.items ? { ...op, items: op.items.map(PluginMenu.asAdded) } : op
-      );
+      const payload = ops.map((op) => {
+        if (op.op === UpdateOps.AddItems && op.items) {
+          return { ...op, items: op.items.map(PluginMenu.asAdded) };
+        }
+        if (op.op === UpdateOps.AddStandaloneMenu && op.menu) {
+          return { ...op, menu: PluginMenu.withoutItems(op.menu) };
+        }
+        return op;
+      });
       emitLocal(PluginEvents.Update, JSON.stringify({ ops: payload }));
     }
     ensureHandlers() {
@@ -1838,23 +1996,30 @@ var vMenu = (() => {
         return;
       }
       this.handlersRegistered = true;
-      onLocal(PluginEvents.Ready, () => this.sendRegistration());
-      onLocal(PluginEvents.readyFor(this.resource), () => this.sendRegistration());
+      onLocal(PluginEvents.Ready, (protocolVersion) => this.onReady(protocolVersion));
+      onLocal(PluginEvents.readyFor(this.resource), (protocolVersion) => this.onReady(protocolVersion));
       onLocal(PluginEvents.registerResultFor(this.resource), (json) => this.onRegisterResult(json));
       onLocal(PluginEvents.eventFor(this.resource), (json) => this.onCallback(json));
       onLocal(PluginEvents.promptResultFor(this.resource), (json) => this.onPromptResult(json));
+      onLocal(PluginEvents.openResultFor(this.resource), (json) => this.onOpenResult(json));
       onLocal(PluginEvents.themesFor(this.resource), (json) => this.themes.handle(json));
       onLocal("onResourceStop", (stopped) => this.onResourceStop(stopped));
     }
+    onReady(protocolVersion) {
+      this.vMenuProtocol = typeof protocolVersion === "number" ? protocolVersion : 0;
+      this.sendRegistration();
+    }
     sendRegistration() {
       emitLocal(PluginEvents.Register, JSON.stringify(this.buildRequest()));
     }
     buildRequest() {
       const request = {
-        protocolVersion: PROTOCOL_VERSION,
+        // Only a plugin that needs a newer vMenu says so, so everything else still registers with an older one.
+        protocolVersion: this.standalone.length > 0 ? PROTOCOL_VERSION : BASE_PROTOCOL_VERSION,
         displayName: Text.toRef(this.displayName),
         descriptionKey: this.descriptionKey,
         menu: this.rootMenu.node,
+        standaloneMenus: this.standalone.length > 0 ? this.standalone.map((menu) => menu.node) : void 0,
         playerActions: this.playerActions.nodes.length > 0 ? this.playerActions.nodes : void 0
       };
       if (Object.keys(this.translations.tables).length > 0) {
@@ -1880,6 +2045,7 @@ var vMenu = (() => {
       this.connected = result.accepted;
       if (!this.connected) {
         this.cancelPendingPrompts();
+        this.cancelPendingOpens();
       } else {
         this.batch(() => {
           for (const menu of this.menusById.values()) {
@@ -1902,7 +2068,9 @@ var vMenu = (() => {
         switch (callback.type) {
           case CallbackTypes.MenuOpened:
           case CallbackTypes.MenuClosed:
-          case CallbackTypes.MenuIndexChanged: {
+          case CallbackTypes.MenuIndexChanged:
+          case CallbackTypes.MenuReplaced:
+          case CallbackTypes.MenuForceClosed: {
             const menu = callback.menuId === void 0 ? void 0 : this.menusById.get(callback.menuId);
             menu?.handleMenu(callback);
             break;
@@ -1936,6 +2104,25 @@ var vMenu = (() => {
         pending(result);
       }
     }
+    onOpenResult(json) {
+      const result = parseJson(json);
+      if (!result) {
+        return;
+      }
+      const pending = this.pendingOpens.get(result.requestId);
+      if (!pending) {
+        return;
+      }
+      this.pendingOpens.delete(result.requestId);
+      const known = Object.values(OpenMenuResult);
+      pending(known.includes(result.reason) ? result.reason : OpenMenuResult.BlockedByPriority);
+    }
+    cancelPendingOpens() {
+      for (const pending of this.pendingOpens.values()) {
+        pending(OpenMenuResult.NotConnected);
+      }
+      this.pendingOpens.clear();
+    }
     cancelPendingPrompts() {
       for (const pending of this.pendingPrompts.values()) {
         pending({ requestId: 0, cancelled: true, busy: false });
@@ -1948,6 +2135,7 @@ var vMenu = (() => {
       }
       this.connected = false;
       this.cancelPendingPrompts();
+      this.cancelPendingOpens();
       this.disconnected.fire();
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vespura/vmenu-plugin",
-  "version": "1.0.14",
+  "version": "1.0.15",
   "description": "Build vMenu Enhanced plugins in TypeScript or JavaScript.",
   "license": "GPL-3.0-or-later",
   "author": "Tom Grobbe",