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

# Skills System

> Skill progression, XP formulas, and resource gathering

## Overview

Hyperscape features a RuneScape-inspired skill system with leveling, XP gain, and level requirements for equipment and activities.

## Available Skills

Hyperscape has **14 skills** total:

### Combat Skills

| Skill            | Purpose                              |
| ---------------- | ------------------------------------ |
| **Attack**       | Melee accuracy, weapon requirements  |
| **Strength**     | Melee damage                         |
| **Defense**      | Damage reduction, armor requirements |
| **Constitution** | Health points                        |
| **Ranged**       | Ranged combat accuracy and damage    |
| **Prayer**       | Prayer points and combat bonuses     |

### Gathering Skills

| Skill           | Activity                                 |
| --------------- | ---------------------------------------- |
| **Woodcutting** | Chop trees for logs                      |
| **Mining**      | Mine rocks for ores                      |
| **Fishing**     | Catch fish at water spots                |
| **Agility**     | Traverse the world, stamina regeneration |

### Artisan Skills

| Skill            | Activity                                    |
| ---------------- | ------------------------------------------- |
| **Firemaking**   | Create fires from logs                      |
| **Cooking**      | Prepare food from raw fish                  |
| **Smithing**     | Smelt ores into bars and smith equipment    |
| **Fletching**    | Craft bows and arrows from logs             |
| **Crafting**     | Create leather armor, jewelry, and cut gems |
| **Runecrafting** | Craft elemental and combat runes at altars  |

### Support Skills

| Skill       | Activity                                           |
| ----------- | -------------------------------------------------- |
| **Agility** | Traverse the world to improve stamina regeneration |

## XP and Leveling

### XP Sources

Players gain XP through:

* **Combat** — Damage dealt grants Attack/Strength/Defense/Constitution XP
* **Gathering** — Woodcutting, Mining, Fishing grant XP per resource
* **Artisan** — Firemaking, Cooking, Smithing grant XP per action
* **Quest Rewards** — Quests award XP to specific skills
* **XP Lamps** — Quest rewards that grant XP to chosen skill

### XP Formula

Hyperscape uses RuneScape's XP curve:

```
XP for Level N = floor(sum(floor(L + 300 * 2^(L/7))) / 4) for L = 1 to N-1
```

### Level Milestones

| Level | Total XP   |
| ----- | ---------- |
| 10    | 1,154      |
| 20    | 4,470      |
| 30    | 13,363     |
| 50    | 101,333    |
| 70    | 737,627    |
| 99    | 13,034,431 |

## Resource Gathering

### Woodcutting

Requirements:

* Hatchet in inventory or equipped
* Click tree to chop

Success rate improves with level. Higher-level trees require higher Woodcutting levels.

| Tree   | Level | XP   |
| ------ | ----- | ---- |
| Normal | 1     | 25   |
| Oak    | 15    | 37.5 |
| Willow | 30    | 67.5 |
| Yew    | 60    | 175  |
| Magic  | 75    | 250  |

### Mining

Requirements:

* Pickaxe in inventory or equipped
* Click ore rock to mine

**OSRS-Accurate Mechanics:**

* Pickaxe tier affects **roll frequency** (not success rate)
* Success rate is **level-only** (pickaxe doesn't affect it)
* Rocks have **100% depletion** on successful mine (1/8 chance)
* Dragon/Crystal pickaxes have **bonus speed rolls**

| Ore        | Level | XP   | Depletion  |
| ---------- | ----- | ---- | ---------- |
| Copper/Tin | 1     | 17.5 | 1/8 chance |
| Iron       | 15    | 35   | 1/8 chance |
| Coal       | 30    | 50   | 1/8 chance |
| Mithril    | 55    | 80   | 1/8 chance |
| Adamantite | 70    | 95   | 1/8 chance |
| Runite     | 85    | 125  | 1/8 chance |

**Pickaxe Tiers:**

| Pickaxe | Level | Roll Ticks | Bonus Speed            |
| ------- | ----- | ---------- | ---------------------- |
| Bronze  | 1     | 8 ticks    | None                   |
| Iron    | 1     | 7 ticks    | None                   |
| Steel   | 6     | 6 ticks    | None                   |
| Mithril | 21    | 5 ticks    | None                   |
| Adamant | 31    | 4 ticks    | None                   |
| Rune    | 41    | 3 ticks    | None                   |
| Dragon  | 61    | 3 ticks    | 1/6 chance for 2 ticks |
| Crystal | 71    | 3 ticks    | 1/4 chance for 2 ticks |

<Info>
  Dragon and Crystal pickaxes have a chance to mine faster: Dragon has a 1/6 chance for 2-tick rolls (avg 2.83 ticks), Crystal has a 1/4 chance (avg 2.75 ticks).
</Info>

### Fishing

Requirements:

* Fishing rod in inventory
* Click fishing spot

| Fish      | Level | XP  |
| --------- | ----- | --- |
| Shrimp    | 1     | 10  |
| Trout     | 20    | 50  |
| Lobster   | 40    | 90  |
| Swordfish | 50    | 100 |
| Shark     | 76    | 110 |

### Agility

Agility is trained passively by moving through the world. Unlike traditional RuneScape agility courses, Hyperscape's Agility system rewards exploration and travel.

**Training Method:**

* Gain 1 XP per 2 tiles traveled (walking or running)
* XP is batched at 100 tiles (50 XP) to prevent visual spam
* XP drops appear every \~15 seconds while running, \~30 seconds while walking

**Benefits:**

* **Stamina Regeneration**: +1% stamina regen per Agility level
  * Level 1: 1% bonus (4.04/sec idle, 2.02/sec walking)
  * Level 50: 50% bonus (6.0/sec idle, 3.0/sec walking)
  * Level 99: 99% bonus (7.96/sec idle, 3.98/sec walking)

**Death Penalty:**

* Accumulated tiles toward next XP grant are lost on death
* Earned XP is never lost

<Info>
  Agility does not affect combat level, matching OSRS design.
</Info>

## Artisan Skills

### Firemaking

Use tinderbox on logs in inventory to create a fire.

| Log    | Level | XP    |
| ------ | ----- | ----- |
| Normal | 1     | 40    |
| Oak    | 15    | 60    |
| Willow | 30    | 90    |
| Yew    | 60    | 202.5 |
| Magic  | 75    | 303.8 |

### Cooking

Use raw fish on a fire or range to cook.

| Food      | Level | XP  | Heals |
| --------- | ----- | --- | ----- |
| Shrimp    | 1     | 30  | 3 HP  |
| Trout     | 15    | 70  | 7 HP  |
| Lobster   | 40    | 120 | 12 HP |
| Swordfish | 45    | 140 | 14 HP |
| Shark     | 80    | 210 | 20 HP |

**Cooking Sources:**

* **Fires**: Created via Firemaking skill (temporary)
* **Ranges**: Permanent cooking stations found in towns

<Warning>
  Cooking can fail at low levels, burning the food. Ranges reduce burn chance compared to fires.
</Warning>

### Fletching

Craft bows and arrows from logs using a knife.

**Arrow Shafts** (Knife + Logs):

| Logs   | Level | Shafts | XP |
| ------ | ----- | ------ | -- |
| Normal | 1     | 15     | 5  |
| Oak    | 15    | 30     | 10 |
| Willow | 30    | 45     | 15 |
| Maple  | 45    | 60     | 20 |
| Yew    | 60    | 75     | 25 |
| Magic  | 75    | 90     | 30 |

**Bows** (Knife + Logs, then String):

| Bow             | Level | XP (Cut) | XP (String) |
| --------------- | ----- | -------- | ----------- |
| Shortbow        | 5     | 5        | 5           |
| Longbow         | 10    | 10       | 10          |
| Oak Shortbow    | 20    | 16.5     | 16.5        |
| Oak Longbow     | 25    | 25       | 25          |
| Willow Shortbow | 35    | 33.3     | 33.3        |
| Willow Longbow  | 40    | 41.5     | 41.5        |
| Maple Shortbow  | 50    | 50       | 50          |
| Maple Longbow   | 55    | 58.3     | 58.3        |
| Yew Shortbow    | 65    | 67.5     | 67.5        |
| Yew Longbow     | 70    | 75       | 75          |
| Magic Shortbow  | 80    | 83.3     | 83.3        |
| Magic Longbow   | 85    | 91.5     | 91.5        |

**Arrows** (Arrowtips + Headless Arrows):

| Arrow   | Level | XP (per 15) |
| ------- | ----- | ----------- |
| Bronze  | 1     | 19.5        |
| Iron    | 15    | 37.5        |
| Steel   | 30    | 75          |
| Mithril | 45    | 112.5       |
| Adamant | 60    | 150         |
| Rune    | 75    | 187.5       |

### Crafting

Create leather armor, jewelry, and cut gems.

**Leather Armor** (Needle + Thread + Leather):

| Item              | Level | XP   |
| ----------------- | ----- | ---- |
| Leather Gloves    | 1     | 13.8 |
| Leather Boots     | 7     | 16.3 |
| Leather Cowl      | 9     | 18.5 |
| Leather Vambraces | 11    | 22   |
| Leather Body      | 14    | 25   |
| Leather Chaps     | 18    | 27   |
| Coif              | 38    | 37   |

**Dragonhide Armor** (Needle + Thread + Dragon Leather):

| Item                   | Level | Leather | XP  |
| ---------------------- | ----- | ------- | --- |
| Green D'hide Vambraces | 57    | 1       | 62  |
| Green D'hide Chaps     | 60    | 2       | 124 |
| Green D'hide Body      | 63    | 3       | 186 |

**Jewelry** (Gold Bar + Gem at Furnace):

| Item               | Level | XP  |
| ------------------ | ----- | --- |
| Gold Ring          | 5     | 15  |
| Amulet of Accuracy | 8     | 30  |
| Amulet of Strength | 50    | 85  |
| Amulet of Power    | 70    | 100 |
| Amulet of Glory    | 80    | 150 |
| Amulet of Fury     | 90    | 165 |

**Gem Cutting** (Chisel + Uncut Gem):

| Gem         | Level | XP    |
| ----------- | ----- | ----- |
| Sapphire    | 20    | 50    |
| Emerald     | 27    | 67.5  |
| Ruby        | 34    | 85    |
| Diamond     | 43    | 107.5 |
| Dragonstone | 55    | 137.5 |
| Onyx        | 67    | 167.5 |

### Runecrafting

Craft elemental and combat runes at runecrafting altars using essence.

| Rune  | Level | XP per Essence | Multi-Rune Levels                  |
| ----- | ----- | -------------- | ---------------------------------- |
| Air   | 1     | 5.0            | 11, 22, 33, 44, 55, 66, 77, 88, 99 |
| Mind  | 2     | 5.5            | 14, 28, 42, 56, 70, 84, 98         |
| Water | 5     | 6.0            | 19, 38, 57, 76, 95                 |
| Earth | 9     | 6.5            | 26, 52, 78                         |
| Fire  | 14    | 7.0            | 35, 70, 95                         |
| Chaos | 35    | 8.5            | 74                                 |

<Info>
  Multi-rune levels allow you to craft multiple runes per essence. For example, at level 11 Runecrafting, you craft 2 air runes per essence instead of 1.
</Info>

### Smithing

Smelt ores into bars at furnaces, then smith bars into equipment at anvils.

#### Smelting (at Furnace)

| Bar     | Level | Ores Required             | XP   | Success Rate |
| ------- | ----- | ------------------------- | ---- | ------------ |
| Bronze  | 1     | 1 Copper + 1 Tin          | 6.25 | 100%         |
| Iron    | 15    | 1 Iron Ore                | 12.5 | 50%          |
| Steel   | 30    | 1 Iron Ore + 2 Coal       | 17.5 | 100%         |
| Mithril | 50    | 1 Mithril Ore + 4 Coal    | 30   | 100%         |
| Adamant | 70    | 1 Adamantite Ore + 6 Coal | 37.5 | 100%         |
| Rune    | 85    | 1 Runite Ore + 8 Coal     | 50   | 100%         |

<Info>
  Iron ore has a 50% failure rate when smelting, matching OSRS mechanics.
</Info>

### Agility

Agility is a unique skill that rewards players for traversing the game world. Unlike traditional RuneScape agility courses, Hyperscape's agility system is integrated with movement and stamina mechanics.

#### Training Agility

**XP Gain**: Earn 1 XP per 2 tiles traveled (walking or running)

**XP Batching**: To prevent visual spam, XP is granted in batches:

* Every 100 tiles traveled = 50 XP granted
* Partial progress is preserved between batches
* Death resets accumulated tiles (not earned XP)

**XP Rates**:

| Movement Type | Tiles/Second | XP/Minute |
| ------------- | ------------ | --------- |
| Walking       | 3.33         | \~100 XP  |
| Running       | 6.67         | \~200 XP  |

#### Agility Benefits

**Stamina Regeneration Bonus**: +1% stamina regen per agility level

| Agility Level | Regen Multiplier | Idle Regen/Sec | Walk Regen/Sec |
| ------------- | ---------------- | -------------- | -------------- |
| 1             | 1.01x            | 4.04           | 2.02           |
| 25            | 1.25x            | 5.00           | 2.50           |
| 50            | 1.50x            | 6.00           | 3.00           |
| 75            | 1.75x            | 7.00           | 3.50           |
| 99            | 1.99x            | 7.96           | 3.98           |

<Info>
  High agility levels significantly improve stamina sustainability, allowing longer running sessions and faster recovery.
</Info>

#### Weight and Stamina

Inventory weight affects stamina drain while running:

**Weight Penalty**: +0.5% stamina drain per kg carried

| Weight (kg) | Drain Multiplier | Drain/Second |
| ----------- | ---------------- | ------------ |
| 0           | 1.0x             | 2.0          |
| 20          | 1.1x             | 2.2          |
| 50          | 1.25x            | 2.5          |
| 100         | 1.5x             | 3.0          |

<Warning>
  Heavy loads significantly increase stamina drain. Manage your inventory weight for optimal running efficiency.
</Warning>

#### Smithing (at Anvil)

Click an anvil to open the smithing interface. **Requires a hammer in your inventory** (not consumed). Select the item to smith and quantity.

**Weapons:**

| Item            | Level | Bars Required | XP   | Ticks |
| --------------- | ----- | ------------- | ---- | ----- |
| Bronze Sword    | 4     | 1 Bronze      | 12.5 | 4     |
| Bronze Scimitar | 5     | 2 Bronze      | 25   | 4     |
| Iron Sword      | 19    | 1 Iron        | 25   | 4     |
| Steel Sword     | 34    | 1 Steel       | 37.5 | 4     |
| Mithril Sword   | 54    | 1 Mithril     | 50   | 4     |

**Armor:**

| Item              | Level | Bars Required | XP    | Ticks |
| ----------------- | ----- | ------------- | ----- | ----- |
| Bronze Platebody  | 18    | 5 Bronze      | 62.5  | 4     |
| Iron Platebody    | 33    | 5 Iron        | 125   | 4     |
| Steel Platebody   | 48    | 5 Steel       | 187.5 | 4     |
| Mithril Platebody | 68    | 5 Mithril     | 250   | 4     |

**Tools:**

| Item           | Level | Bars Required | XP   | Ticks |
| -------------- | ----- | ------------- | ---- | ----- |
| Bronze Hatchet | 1     | 1 Bronze      | 12.5 | 4     |
| Bronze Pickaxe | 1     | 1 Bronze      | 12.5 | 4     |
| Iron Hatchet   | 16    | 1 Iron        | 25   | 4     |
| Steel Hatchet  | 31    | 1 Steel       | 37.5 | 4     |

<Warning>
  You must have a hammer in your inventory to smith items at an anvil. The hammer is not consumed.
</Warning>

<Info>
  Smithing supports "Make X" functionality - you can smith multiple items in one session. The system auto-smiths until you run out of bars or reach the target quantity.
</Info>

## Equipment Level Requirements

Equipment and activities have level gates:

| Tier    | Attack/Defense | Ranged |
| ------- | -------------- | ------ |
| Bronze  | 1              | 1      |
| Iron    | 5              | -      |
| Steel   | 10             | 10     |
| Mithril | 20             | 20     |
| Adamant | 30             | -      |
| Rune    | 40             | -      |
| Dragon  | 60             | -      |

## Skill Data Files

Skill configuration is in `packages/shared/src/data/`:

| File                          | Purpose                          |
| ----------------------------- | -------------------------------- |
| `equipment-requirements.json` | Level requirements for equipment |
| `equipment-stats.json`        | Stat bonuses for equipment       |

## Skill Guide Panel

Click any skill in the Skills panel to open its Skill Guide, which shows all unlocks available at each level.

**Features**:

* Visual distinction between unlocked (green) and locked (gray) items
* Next unlock highlighted with progress indicator
* Scrollable list for skills with many unlocks
* Type indicators (item vs ability)
* Shows levels needed to reach next unlock

<Info>
  The Skill Guide Panel helps players plan their progression by showing what they'll unlock at future levels.
</Info>

## Default Skill Values

Skills start at level 1 with 0 XP, except Constitution which starts at level 10:

```typescript theme={null}
// From packages/shared/src/entities/player/PlayerEntity.ts
playerData.skills = {
  attack: { level: 1, xp: 0 },
  strength: { level: 1, xp: 0 },
  defense: { level: 1, xp: 0 },
  constitution: { level: 10, xp: 1154 },  // Starts at level 10
  ranged: { level: 1, xp: 0 },
  prayer: { level: 1, xp: 0 },
  woodcutting: { level: 1, xp: 0 },
  mining: { level: 1, xp: 0 },
  fishing: { level: 1, xp: 0 },
  firemaking: { level: 1, xp: 0 },
  cooking: { level: 1, xp: 0 },
  smithing: { level: 1, xp: 0 },
  agility: { level: 1, xp: 0 },
  fletching: { level: 1, xp: 0 },
  runecrafting: { level: 1, xp: 0 },
};
```

<Info>
  Constitution starts at level 10 (1,154 XP) like RuneScape's Hitpoints.
  Player health equals their Constitution level.
</Info>

## XP Lamps

XP lamps are quest rewards that let you choose which skill receives XP:

### Using XP Lamps

1. Receive XP lamp as quest reward
2. Right-click lamp in inventory
3. Select "Rub" action
4. Choose skill from modal
5. XP granted immediately

### Item Definition

```json theme={null}
{
  "id": "xp_lamp_1000",
  "name": "XP Lamp (1000 XP)",
  "inventoryActions": ["rub", "examine"],
  "useEffect": {
    "type": "xp_lamp",
    "xpAmount": 1000
  }
}
```

**Available Skills:**

* Attack, Strength, Defense, Constitution
* Ranged, Prayer
* Mining, Smithing, Fishing, Cooking, Firemaking, Woodcutting
* Agility, Fletching, Runecrafting

<Info>
  XP lamps are commonly awarded as quest rewards, allowing you to boost the skill of your choice.
</Info>