Context Menu API

The context menu system provides OSRS-accurate right-click menus with colored entity names, manifest-driven actions, and centralized dispatching.

InventoryActionDispatcher

Centralized inventory action dispatching. Location: packages/client/src/game/systems/InventoryActionDispatcher.ts

dispatchInventoryAction()

Dispatch an inventory action to the appropriate handler.

dispatchInventoryAction(
  action: string,
  ctx: InventoryActionContext
): ActionResult

Parameters:

action - The action ID (e.g., “eat”, “wield”, “drop”)
ctx - Context containing world, itemId, slot, and optional quantity

Returns: ActionResult indicating success/failure Example:

import { dispatchInventoryAction } from '../systems/InventoryActionDispatcher';

// Eat food
const result = dispatchInventoryAction("eat", {
  world,
  itemId: "shrimp",
  slot: 5,
});

// Wield weapon
const result = dispatchInventoryAction("wield", {
  world,
  itemId: "bronze_sword",
  slot: 10,
});

// Drop item
const result = dispatchInventoryAction("drop", {
  world,
  itemId: "logs",
  slot: 3,
  quantity: 10,
});

Supported Actions

Action	Handler	Description
`eat`	`useItem` network message	Consumes food, heals HP
`drink`	`ITEM_ACTION_SELECTED` event	Consumes potion, applies effects
`bury`	`buryBones` network message	Buries bones for Prayer XP
`wield`	`equipItem` network message	Equips weapons/shields
`wear`	`equipItem` network message	Equips armor
`drop`	`dropItem` network message	Drops item on ground
`examine`	`UI_TOAST` + chat message	Shows examine text
`use`	`ITEM_ACTION_SELECTED` event	Enters targeting mode
`cancel`	No-op	Closes menu

Item Helpers

Type detection utilities for inventory actions. Location: packages/shared/src/utils/item-helpers.ts

Type Detection Functions

isFood()

Check if item is food (can be eaten).

isFood(item: Item | null): boolean

Detection: type === "consumable" + healAmount > 0 + not a potion Example:

import { isFood } from '@hyperscape/shared';

const item = getItem("shrimp");
if (isFood(item)) {
  // Show "Eat" action
}

isPotion()

Check if item is a potion (can be drunk).

isPotion(item: Item | null): boolean

Detection: type === "consumable" + id.includes("potion")

isBone()

Check if item is bones (can be buried).

isBone(item: Item | null): boolean

Detection: id === "bones" or id.endsWith("_bones")

isWeapon()

Check if item is a weapon.

isWeapon(item: Item | null): boolean

Detection: equipSlot === "weapon" or equipSlot === "2h" or is2h === true or weaponType != null

isShield()

Check if item is a shield.

isShield(item: Item | null): boolean

Detection: equipSlot === "shield"

usesWield()

Check if item uses “Wield” action (weapons + shields).

usesWield(item: Item | null): boolean

Returns: isWeapon(item) || isShield(item)

usesWear()

Check if item uses “Wear” action (armor, not weapons/shields).

usesWear(item: Item | null): boolean

Detection: equipable === true and not a weapon/shield

isNotedItem()

Check if item is a bank note.

isNotedItem(item: Item | null): boolean

Detection: isNoted === true or id.endsWith("_noted")

Primary Action Detection

getPrimaryAction()

Get primary action using manifest-first approach with heuristic fallback.

getPrimaryAction(
  item: Item | null,
  isNoted: boolean
): PrimaryActionType

Parameters:

item - Item to check
isNoted - Whether item is a bank note

If noted → return “use”
Check item.inventoryActions[0] if defined
Heuristic fallback based on item properties
Final fallback → “use”

Example:

import { getPrimaryAction, isNotedItem } from '@hyperscape/shared';

const item = getItem("shrimp");
const isNoted = isNotedItem(item);
const action = getPrimaryAction(item, isNoted);
// Returns: "eat"

// On left-click
dispatchInventoryAction(action, { world, itemId: item.id, slot });

getPrimaryActionFromManifest()

Get primary action from manifest’s inventoryActions only.

getPrimaryActionFromManifest(item: Item | null): PrimaryActionType | null

Returns: First action from inventoryActions array, or null if not defined Example:

const item = getItem("bronze_sword");
// item.inventoryActions = ["Wield", "Use", "Drop", "Examine"]

const action = getPrimaryActionFromManifest(item);
// Returns: "wield"

Location: packages/shared/src/constants/GameConstants.ts

CONTEXT_MENU_COLORS

OSRS-accurate color constants for context menu entity names.

export const CONTEXT_MENU_COLORS = {
  ITEM: "#ff9040",      // Orange - for items
  NPC: "#ffff00",       // Yellow - for NPCs and mobs
  OBJECT: "#00ffff",    // Cyan - for scenery/objects
  PLAYER: "#ffffff",    // White - for players
};

Usage:

import { CONTEXT_MENU_COLORS } from '@hyperscape/shared';

// Styled label for context menu
const styledLabel = [
  { text: "Take " },
  { text: "Bones", color: CONTEXT_MENU_COLORS.ITEM }
];

ContextMenuAction Interface

interface ContextMenuAction {
  id: string;                    // Unique action ID
  label: string;                 // Plain text label
  styledLabel?: LabelSegment[];  // Colored segments
  enabled: boolean;              // Can be executed
  priority: number;              // Sort order (lower = higher)
  handler?: () => void;          // Action callback
}

interface LabelSegment {
  text: string;
  color?: string;  // Hex color code
}

Example:

const action: ContextMenuAction = {
  id: "attack",
  label: "Attack Goblin (Level: 5)",
  styledLabel: [
    { text: "Attack " },
    { text: "Goblin", color: CONTEXT_MENU_COLORS.NPC },
    { text: " (Level: " },
    { text: "5", color: "#ff0000" },  // Red for dangerous
    { text: ")" }
  ],
  enabled: true,
  priority: 1,
  handler: () => attackMob(target)
};

Interaction Handlers

Base class for all interaction handlers. Location: packages/shared/src/systems/client/interaction/handlers/BaseInteractionHandler.ts

BaseInteractionHandler

All handlers extend this base class:

abstract class BaseInteractionHandler {
  abstract handleLeftClick(target: RaycastTarget): void;
  abstract getContextMenuActions(target: RaycastTarget): ContextMenuAction[];
  
  // Helper methods
  protected createWalkHereAction(target: RaycastTarget): ContextMenuAction;
  protected showExamineMessage(text: string): void;
  protected queueInteraction(params: InteractionParams): void;
}

Handler Registry

Handler	Entity Types	Primary Action
`ItemInteractionHandler`	Ground items	Take
`NPCInteractionHandler`	NPCs (bankers, shopkeepers)	Talk-to
`MobInteractionHandler`	Hostile mobs	Attack
`PlayerInteractionHandler`	Other players	Trade
`ResourceInteractionHandler`	Trees, rocks, fishing spots	Chop/Mine/Fish
`BankInteractionHandler`	Bank booths/chests	Bank
`CookingSourceInteractionHandler`	Fires, ranges	Cook
`SmeltingSourceInteractionHandler`	Furnaces	Smelt
`SmithingSourceInteractionHandler`	Anvils	Smith
`CorpseInteractionHandler`	Gravestones, corpses	Loot

Manifest Integration

Item Manifest

Items can define explicit inventoryActions:

{
  "id": "shrimp",
  "name": "Shrimp",
  "type": "consumable",
  "healAmount": 3,
  "inventoryActions": ["Eat", "Use", "Drop", "Examine"]
}

Rules:

First action becomes left-click default
Actions are case-insensitive when dispatched
If not specified, system uses heuristic detection
Noted items always use [“Use”, “Drop”, “Examine”]

Supported Manifest Actions

export const HANDLED_INVENTORY_ACTIONS = new Set<string>([
  "eat",
  "drink",
  "bury",
  "wield",
  "wear",
  "drop",
  "examine",
  "use",
]);

Testing

InventoryActionDispatcher Tests

File: packages/client/src/game/systems/__tests__/InventoryActionDispatcher.test.ts Coverage: 333 lines, 100% of all actions Example:

it("emits ITEM_ACTION_SELECTED event for eat action", () => {
  const result = dispatchInventoryAction("eat", {
    world: mockWorld,
    itemId: "shrimp",
    slot: 0,
  });

  expect(result.success).toBe(true);
  expect(mockWorld.emit).toHaveBeenCalledWith(
    EventType.ITEM_ACTION_SELECTED,
    {
      playerId: "player1",
      actionId: "eat",
      itemId: "shrimp",
      slot: 0,
    }
  );
});

Item Helpers Tests

File: packages/shared/src/utils/__tests__/item-helpers.test.ts Coverage: 510 lines, all edge cases Example:

it("returns eat for food without manifest", () => {
  const food = createItem({
    id: "shrimp",
    type: "consumable",
    healAmount: 10,
  });
  
  expect(getPrimaryAction(food, false)).toBe("eat");
});

it("uses manifest action when available", () => {
  const item = createItem({
    inventoryActions: ["Wield", "Use", "Drop"],
  });
  
  expect(getPrimaryAction(item, false)).toBe("wield");
});

REST API

Context Menu API

InventoryActionDispatcher

dispatchInventoryAction()

Supported Actions

Item Helpers

Type Detection Functions

isFood()

isPotion()

isBone()

isWeapon()

isShield()

usesWield()

usesWear()

isNotedItem()

Primary Action Detection

getPrimaryAction()

getPrimaryActionFromManifest()

Context Menu Colors

CONTEXT_MENU_COLORS

Context Menu Action Structure

ContextMenuAction Interface

Interaction Handlers

BaseInteractionHandler

Handler Registry

Manifest Integration

Item Manifest

Supported Manifest Actions

Testing

InventoryActionDispatcher Tests

Item Helpers Tests

​Context Menu API

​InventoryActionDispatcher

​dispatchInventoryAction()

​Supported Actions

​Item Helpers

​Type Detection Functions

​isFood()

​isPotion()

​isBone()

​isWeapon()

​isShield()

​usesWield()

​usesWear()

​isNotedItem()

​Primary Action Detection

​getPrimaryAction()

​getPrimaryActionFromManifest()

​Context Menu Colors

​CONTEXT_MENU_COLORS

​Context Menu Action Structure

​ContextMenuAction Interface

​Interaction Handlers

​BaseInteractionHandler

​Handler Registry

​Manifest Integration

​Item Manifest

​Supported Manifest Actions

​Testing

​InventoryActionDispatcher Tests

​Item Helpers Tests

​Related Documentation

Context Menu API

InventoryActionDispatcher

dispatchInventoryAction()

Supported Actions

Item Helpers

Type Detection Functions

isFood()

isPotion()

isBone()

isWeapon()

isShield()

usesWield()

usesWear()

isNotedItem()

Primary Action Detection

getPrimaryAction()

getPrimaryActionFromManifest()

Context Menu Colors

CONTEXT_MENU_COLORS

Context Menu Action Structure

ContextMenuAction Interface

Interaction Handlers

BaseInteractionHandler

Handler Registry

Manifest Integration

Item Manifest

Supported Manifest Actions

Testing

InventoryActionDispatcher Tests

Item Helpers Tests

Related Documentation