> ## Documentation Index
> Fetch the complete documentation index at: https://hyperscape-ai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
// 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

<Info>
  Banks are safe storage—items cannot be lost from banks.
</Info>

## 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:

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
// 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;
}
```

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

## Economy Flow

```mermaid theme={"theme":{"light":"github-light","dark":"css-variables"}}
flowchart LR
    A[Kill Mobs] --> B[Coins Drop]
    B --> C[Buy Tools]
    C --> D[Gather Resources]
    D --> E[Process Items]
    E --> F[Use/Sell]
    F --> A
```

## 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

<Tip>
  Trade requests appear as pink clickable messages in chat. Click to accept instantly.
</Tip>

## Future Features

<Info>
  A Grand Exchange (automated marketplace) is planned for future updates.
</Info>