Economy

Banking, shops, currency, and item management

Overview

Hyperscape features a player-driven economy with banking, shops, loot drops, and item trading.

Currency

Coins are the universal currency:

• Dropped by all mobs
• Used to purchase from shops
• Stackable in inventory

Inventory

Configuration

// From packages/shared/src/constants/GameConstants.ts
export const INVENTORY_CONSTANTS = {
  MAX_INVENTORY_SLOTS: 28,
  MAX_BANK_SLOTS: 100,
  MAX_STACK_SIZE: 1000,
  DEFAULT_ITEM_VALUE: 1,
} as const;

Capacity

• 28 slots in active inventory (RuneScape-style)
• 100 slots in bank storage
• 1000 max stack for stackable items
• Items must be managed carefully
• Stackable items (coins, arrows) share a slot

Item Properties

Property	Description
Stackable	Multiple units per slot (up to 1000)
Tradeable	Can be exchanged
Weight	Affects run energy
Requirements	Level gates for use

Banking

Features

• Unlimited storage slots
• Accessible at bank locations in starter towns
• Each bank is independent (no shared storage)

Operations

• Deposit: Move items from inventory to bank
• Withdraw: Move items from bank to inventory
• Organize: Drag to rearrange

Banks are safe storage—items cannot be lost from banks.

Shops

General Store

Available in all starter towns:

Item	Price
Bronze Hatchet	50 coins
Fishing Rod	25 coins
Tinderbox	15 coins
Arrows (10)	20 coins

Shop Mechanics

• Stock replenishes over time
• Prices are fixed
• Sell items back for reduced value

Loot Drops

Mob Drops

All mobs drop loot on death:

Mob Tier	Typical Drops
Level 1	Coins, bronze equipment (rare)
Level 2	More coins, steel equipment (uncommon)
Level 3	Substantial coins, mithril equipment (uncommon)

Drop Tables

Drop tables are defined in NPC manifests and calculated at runtime:

// From packages/shared/src/data/npcs.ts (lines 107-149)
export function calculateNPCDrops(
  npcId: string,
): Array<{ itemId: string; quantity: number }> {
  const npc = getNPCById(npcId);
  if (!npc) return [];

  const drops: Array<{ itemId: string; quantity: number }> = [];

  // Add default drop if enabled
  if (npc.drops.defaultDrop.enabled) {
    drops.push({
      itemId: npc.drops.defaultDrop.itemId,
      quantity: npc.drops.defaultDrop.quantity,
    });
  }

  // Roll for drop tiers: always, common, uncommon, rare, veryRare
  npc.drops.always.forEach(processDrop);
  npc.drops.common.forEach(processDrop);
  npc.drops.uncommon.forEach(processDrop);
  npc.drops.rare.forEach(processDrop);
  npc.drops.veryRare.forEach(processDrop);

  return drops;
}

Drop tables are defined in world/assets/manifests/npcs.json and loaded by DataManager.

Economy Flow

Item Tiers

Weapons

Tier	Attack Req	Examples
Bronze	1	Bronze Sword
Steel	10	Steel Sword
Mithril	20	Mithril Sword

Armor

Tier	Defense Req	Slots
Leather	1	Helmet, Body, Legs
Steel	10	Helmet, Body, Legs
Mithril	20	Helmet, Body, Legs

Bows

Tier	Range Req	Type
Wood	1	Shortbow
Oak	10	Oak Bow
Willow	20	Willow Bow

Player Trading

Trade System

Players can trade items directly with each other using an OSRS-style two-screen confirmation flow:

Initiating a Trade

1. Right-click another player
2. Select “Trade with [Player Name]”
3. If not adjacent, your character walks to them automatically
4. Trade request appears as pink clickable chat message

Trade Flow

Offer Screen:

• Add items by left-clicking inventory items (adds 1)
• Right-click for context menu: Offer-1, Offer-5, Offer-10, Offer-X, Offer-All
• Remove items by clicking them in your trade offer
• Both players must accept to proceed

Confirmation Screen:

• Final review of both offers
• Wealth transfer indicator shows value difference
• Both players must accept again to complete
• Trade executes atomically (no item duplication possible)

Anti-Scam Features

Feature	Description
Two-Screen Flow	Must accept twice (offer + confirm)
Removal Warning	Red flashing exclamation when items removed
Wealth Indicator	Shows if you’re gaining/losing value (green/red)
Free Slots	Displays partner’s available inventory space
Value Warning	⚠️ if wealth difference >50% of offer

Security

• Server-authoritative state management
• Atomic database transactions
• Inventory locks during swap
• Proximity validation (must be adjacent)
• Rate limiting on requests
• Tradeable flag enforcement

Trade requests appear as pink clickable messages in chat. Click to accept instantly.

Future Features

A Grand Exchange (automated marketplace) is planned for future updates.