usePlayerData Hook API Reference

File: packages/client/src/hooks/usePlayerData.ts Added: March 2026 (PR #1067)

Overview

Centralized React hook for subscribing to player data events (inventory, equipment, stats, coins). Eliminates duplicate event listeners across components and provides proper equality checks to prevent cascading re-renders.

Usage

Basic Usage with Context Provider

import { PlayerDataProvider, usePlayerDataContext, usePlayerStatsContext } from '@/hooks';

// Wrap your component tree
function App() {
  return (
    <PlayerDataProvider world={world}>
      <GameUI />
    </PlayerDataProvider>
  );
}

// Access player data in child components
function GameUI() {
  const { inventory, equipment, playerStats, coins } = usePlayerDataContext();
  
  return (
    <div>
      <InventoryPanel items={inventory} coins={coins} />
      <EquipmentPanel equipment={equipment} />
      <StatusBars stats={playerStats} />
    </div>
  );
}

// Or access just stats
function HealthBar() {
  const playerStats = usePlayerStatsContext();
  
  return (
    <div>
      HP: {playerStats?.health.current} / {playerStats?.health.max}
    </div>
  );
}

Direct Hook Usage (without context)

import { usePlayerDataState } from '@/hooks';

function MyComponent({ world }: { world: ClientWorld }) {
  const { inventory, equipment, playerStats, coins } = usePlayerDataState(world);
  
  // ... use player data
}

API

PlayerDataProvider

React context provider that wraps usePlayerDataState and provides data to child components. Props:

interface PlayerDataProviderProps {
  world: ClientWorld | null;
  children: React.ReactNode;
}

Example:

<PlayerDataProvider world={world}>
  {children}
</PlayerDataProvider>

usePlayerDataContext

Hook to access player data from context. Must be used within PlayerDataProvider. Returns: PlayerDataState Throws: Error if used outside PlayerDataProvider Example:

const { inventory, equipment, playerStats, coins } = usePlayerDataContext();

usePlayerStatsContext

Hook to access only player stats from context. Must be used within PlayerDataProvider. Returns: PlayerStats | null Example:

const playerStats = usePlayerStatsContext();

usePlayerDataState

Low-level hook that subscribes to player data events. Use usePlayerDataContext instead when possible. Parameters:

function usePlayerDataState(world: ClientWorld | null): PlayerDataState

Returns: PlayerDataState

Types

PlayerDataState

interface PlayerDataState {
  /** Inventory items (28 slots) */
  inventory: InventorySlotViewItem[];
  
  /** Player equipment (weapon, armor, etc.) */
  equipment: PlayerEquipmentItems | null;
  
  /** Player stats (health, prayer, skills, combat level) */
  playerStats: PlayerStats | null;
  
  /** Coin count */
  coins: number;
  
  /** Setter for inventory */
  setInventory: React.Dispatch<React.SetStateAction<InventorySlotViewItem[]>>;
  
  /** Setter for equipment */
  setEquipment: React.Dispatch<React.SetStateAction<PlayerEquipmentItems | null>>;
  
  /** Setter for player stats */
  setPlayerStats: React.Dispatch<React.SetStateAction<PlayerStats | null>>;
  
  /** Setter for coins */
  setCoins: React.Dispatch<React.SetStateAction<number>>;
}

InventorySlotViewItem

interface InventorySlotViewItem {
  slot: number;
  itemId: string;
  quantity: number;
}

PlayerEquipmentItems

interface PlayerEquipmentItems {
  weapon: InventoryItem | null;
  shield: InventoryItem | null;
  helmet: InventoryItem | null;
  body: InventoryItem | null;
  legs: InventoryItem | null;
  boots: InventoryItem | null;
  gloves: InventoryItem | null;
  cape: InventoryItem | null;
  amulet: InventoryItem | null;
  ring: InventoryItem | null;
  arrows: InventoryItem | null;
}

PlayerStats

interface PlayerStats {
  level: number;
  combatLevel: number;
  inCombat: boolean;
  health: {
    current: number;
    max: number;
  };
  prayerPoints: {
    current: number;
    max: number;
  };
  skills: {
    attack: { level: number; xp: number };
    strength: { level: number; xp: number };
    defense: { level: number; xp: number };
    constitution: { level: number; xp: number };
    ranged: { level: number; xp: number };
    woodcutting: { level: number; xp: number };
    fishing: { level: number; xp: number };
    firemaking: { level: number; xp: number };
    cooking: { level: number; xp: number };
  };
  equipment: PlayerEquipmentItems;
}

Event Handling

The hook subscribes to the following events:

Event	Description	Payload
`UI_UPDATE`	Primary source for player stats	`{ component: "player", data: Partial<PlayerStats> }`
`INVENTORY_UPDATED`	Inventory items and coins	`{ playerId, items, coins }`
`INVENTORY_UPDATE_COINS`	Coin count only	`{ playerId, coins }`
`UI_EQUIPMENT_UPDATE`	Equipment changes	`{ equipment: RawEquipmentData }`
`STATS_UPDATE`	Alternative stats event	`Partial<PlayerStats>`
`SKILLS_UPDATED`	Skill XP and levels	`{ playerId, skills }`
`PRAYER_STATE_SYNC`	Full prayer state	`{ playerId, points, maxPoints }`
`PRAYER_POINTS_CHANGED`	Prayer points only	`{ playerId, points, maxPoints }`

Equality Checks

The hook uses custom equality functions to prevent unnecessary re-renders:

areInventoryItemsEqual

Compares two inventory arrays by slot, itemId, and quantity.

function areInventoryItemsEqual(
  left: InventorySlotViewItem[],
  right: InventorySlotViewItem[]
): boolean

Returns: true if inventories are equal, false otherwise

areEquipmentItemsEqual

Compares two equipment objects by item id, quantity, and name for each slot.

function areEquipmentItemsEqual(
  left: PlayerEquipmentItems | null,
  right: PlayerEquipmentItems | null
): boolean

Returns: true if equipment is equal, false otherwise

arePlayerStatsEqual

Compares two player stats objects including health, prayer, skills, and combat level.

function arePlayerStatsEqual(
  left: PlayerStats | null,
  right: PlayerStats | null
): boolean

Returns: true if stats are equal, false otherwise

areSkillsEqual

Compares skill levels and XP for all skills.

function areSkillsEqual(
  left: PlayerStats["skills"],
  right: PlayerStats["skills"]
): boolean

Returns: true if skills are equal, false otherwise

areStatusValuesEqual

Compares status values (health, prayer) by current and max.

function areStatusValuesEqual(
  left?: { current?: number; max?: number },
  right?: { current?: number; max?: number }
): boolean

Returns: true if status values are equal, false otherwise

Initial Data Loading

The hook automatically requests initial data from the network cache on mount:

Check for player ID - Waits for world.entities.player.id to be available
Load from cache - Reads lastInventoryByPlayerId, lastSkillsByPlayerId, lastEquipmentByPlayerId, lastPrayerStateByPlayerId
Request fresh data - Emits INVENTORY_REQUEST event to server
Retry on failure - Retries after 400ms if player not ready

Performance Optimizations

Defensive Cloning

Inventory items are defensively cloned to prevent shared reference bugs:

function cloneInventoryItems(
  items: InventorySlotViewItem[] | undefined | null
): InventorySlotViewItem[] {
  if (!items || items.length === 0) return [];
  return items.map((item) => ({ ...item }));
}

Equality Checks

All state updates use equality checks to prevent unnecessary re-renders:

setInventory((prev) =>
  areInventoryItemsEqual(prev, newItems) ? prev : cloneInventoryItems(newItems)
);

setEquipment((prev) =>
  areEquipmentItemsEqual(prev, newEquipment) ? prev : newEquipment
);

setPlayerStats((prev) => {
  const merged = mergePlayerStats(prev, updates);
  return arePlayerStatsEqual(prev, merged) ? prev : merged;
});

Merge Strategy

Player stats are merged instead of replaced to preserve data from different event sources:

function mergePlayerStats(
  previous: PlayerStats | null,
  updates: Partial<PlayerStats>
): PlayerStats {
  if (!previous) return updates as PlayerStats;
  
  const next = { ...previous, ...updates };
  
  // Preserve nested objects
  if (updates.health) next.health = updates.health;
  if (updates.skills) next.skills = updates.skills;
  if (updates.prayerPoints) next.prayerPoints = updates.prayerPoints;
  
  return next;
}

Type Guards

The hook uses type guards to validate event payloads:

import {
  isInventoryUpdateEvent,
  isCoinUpdateWithPlayerEvent,
  isUIUpdateEvent,
  isPlayerStatsData,
  isSkillsUpdateEvent,
  isPrayerStateSyncEvent,
  isPrayerPointsChangedEvent,
  isObject,
} from "../types/guards";

Example:

const handleInventory = (data: unknown) => {
  if (!isInventoryUpdateEvent(data)) {
    console.warn("[usePlayerData] Invalid inventory update event:", data);
    return;
  }
  // ... safe to use data.items, data.coins, data.playerId
};

Cleanup

The hook properly cleans up all event listeners on unmount:

useEffect(() => {
  // ... register listeners
  
  return () => {
    if (timeoutId !== null) clearTimeout(timeoutId);
    world.off(EventType.UI_UPDATE, handleUIUpdate);
    world.off(EventType.INVENTORY_UPDATED, handleInventory);
    world.off(EventType.INVENTORY_UPDATE_COINS, handleCoins);
    world.off(EventType.UI_EQUIPMENT_UPDATE, handleEquipment);
    world.off(EventType.STATS_UPDATE, handleStats);
    world.off(EventType.SKILLS_UPDATED, handleSkillsUpdate);
    world.off(EventType.PRAYER_STATE_SYNC, handlePrayerStateSync);
    world.off(EventType.PRAYER_POINTS_CHANGED, handlePrayerPointsChanged);
  };
}, [world, playerId]);

Migration from Old Pattern

Before (Duplicate Subscriptions)

// Sidebar.tsx
const [inventory, setInventory] = useState([]);
const [equipment, setEquipment] = useState(null);
const [playerStats, setPlayerStats] = useState(null);

useEffect(() => {
  world.on(EventType.INVENTORY_UPDATED, (data) => setInventory(data.items));
  world.on(EventType.UI_UPDATE, (data) => setPlayerStats(data));
  // ... more listeners
}, [world]);

// CoreUI.tsx (duplicate subscription)
const [playerStats, setPlayerStats] = useState(null);

useEffect(() => {
  world.on(EventType.UI_UPDATE, (data) => setPlayerStats(data));
  // ... duplicate listener
}, [world]);

After (Centralized Subscription)

// App.tsx
<PlayerDataProvider world={world}>
  <InterfaceManager world={world}>
    <CoreUI world={world} />
  </InterfaceManager>
</PlayerDataProvider>

// Any child component
function MyComponent() {
  const { inventory, equipment, playerStats, coins } = usePlayerDataContext();
  // ... use data
}

Benefits

Eliminates Duplicate Listeners: Single subscription per event type across entire app
Prevents Cascading Re-renders: Equality checks ensure components only re-render when data actually changes
Type Safety: Type guards validate all event payloads
Defensive Cloning: Prevents shared reference bugs
Proper Cleanup: All listeners removed on unmount
Cache Integration: Automatically loads from network cache on mount
Player ID Filtering: Only processes events for local player (prevents cross-tab updates)

useModalPanels - Centralized modal panel state (bank, store, dialogue, etc.)
useMinimapTerrainCache - Minimap terrain rendering
useMinimapEntityPips - Minimap entity markers
useMinimapWorldCaches - Minimap road/town caching

Configuration

Operations

Api hooks player data

usePlayerData Hook API Reference

Overview

Usage

Basic Usage with Context Provider

Direct Hook Usage (without context)

API

PlayerDataProvider

usePlayerDataContext

usePlayerStatsContext

usePlayerDataState

Types

PlayerDataState

InventorySlotViewItem

PlayerEquipmentItems

PlayerStats

Event Handling

Equality Checks

areInventoryItemsEqual

areEquipmentItemsEqual

arePlayerStatsEqual

areSkillsEqual

areStatusValuesEqual

Initial Data Loading

Performance Optimizations

Defensive Cloning

Equality Checks

Merge Strategy

Type Guards

Cleanup

Migration from Old Pattern

Before (Duplicate Subscriptions)

After (Centralized Subscription)

Benefits

See Also

​usePlayerData Hook API Reference

​Overview

​Usage

​Basic Usage with Context Provider

​Direct Hook Usage (without context)

​API

​PlayerDataProvider

​usePlayerDataContext

​usePlayerStatsContext

​usePlayerDataState

​Types

​PlayerDataState

​InventorySlotViewItem

​PlayerEquipmentItems

​PlayerStats

​Event Handling

​Equality Checks

​areInventoryItemsEqual

​areEquipmentItemsEqual

​arePlayerStatsEqual

​areSkillsEqual

​areStatusValuesEqual

​Initial Data Loading

​Performance Optimizations

​Defensive Cloning

​Equality Checks

​Merge Strategy

​Type Guards

​Cleanup

​Migration from Old Pattern

​Before (Duplicate Subscriptions)

​After (Centralized Subscription)

​Benefits

​Related Hooks

​See Also

usePlayerData Hook API Reference

Overview

Usage

Basic Usage with Context Provider

Direct Hook Usage (without context)

API

PlayerDataProvider

usePlayerDataContext

usePlayerStatsContext

usePlayerDataState

Types

PlayerDataState

InventorySlotViewItem

PlayerEquipmentItems

PlayerStats

Event Handling

Equality Checks

areInventoryItemsEqual

areEquipmentItemsEqual

arePlayerStatsEqual

areSkillsEqual

areStatusValuesEqual

Initial Data Loading

Performance Optimizations

Defensive Cloning

Equality Checks

Merge Strategy

Type Guards

Cleanup

Migration from Old Pattern

Before (Duplicate Subscriptions)

After (Centralized Subscription)

Benefits

Related Hooks

See Also