HyperscapeAI · SYMBaiEX · Mar 19, 2026 · Feb 13, 2026 · Feb 13, 2026 · Feb 13, 2026
diff --git a/wiki/data/npcs.mdx b/wiki/data/npcs.mdx
@@ -1,12 +1,12 @@
 ---
 title: "NPC Data Structure"
 description: "How NPCs and mobs are defined in Hyperscape"
 icon: "users"
 ---

 # NPC Data Structure

 NPCs (Non-Player Characters) and mobs are defined in **JSON manifests** and loaded at runtime. This data-driven approach allows content to be modified without code changes.

 <Info>
 NPC data is managed in `packages/shared/src/data/npcs.ts` and loaded from `world/assets/manifests/npcs.json`.
@@ -14,7 +14,7 @@

 ## Data Loading

 NPCs are **NOT hardcoded**. The `ALL_NPCS` map is populated at runtime:

 ```typescript
 // From npcs.ts
@@ -73,7 +73,7 @@

 ## Aggression Types

 NPCs have different aggression behaviors:

 ```typescript
 type AggressionType =
@@ -162,15 +162,34 @@
 
 ## Available 3D Models
 
-NPCs use rigged GLB models from `/assets/world/forge/`:
-
-| Model Path | Used For |
-|------------|----------|
-| `goblin/goblin_rigged.glb` | Goblins |
-| `thug/thug_rigged.glb` | Bandits, thugs |
-| `human/human_rigged.glb` | Guards, knights, shopkeepers |
-| `troll/troll_rigged.glb` | Hobgoblins |
-| `imp/imp_rigged.glb` | Dark warriors |
+### Mobs
+
+Hostile NPCs use models from `models/mobs/`:
+
+| Model Path | Format | Used For |
+|------------|--------|----------|
+| `models/mobs/goblin/goblin.vrm` | VRM | Goblins |
+| `models/mobs/goblin/goblin_rigged.glb` | GLB | Goblins (legacy) |
+| `models/mobs/dark-ranger/dark-ranger.vrm` | VRM | Dark rangers |
+| `models/mobs/dark-wizard/dark-wizard.vrm` | VRM | Dark wizards |
+
+**Goblin Animations**:
+- `models/mobs/goblin/animations/running.glb` - Running animation
+- `models/mobs/goblin/animations/walking.glb` - Walking animation
+
+### NPCs
+
+Service NPCs use models from `models/npcs/`:
+
+| Model Path | NPC |
+|------------|-----|
+| `models/npcs/banker/banker.vrm` | Banker |
+| `models/npcs/captain-rowan/captain-rowan.vrm` | Captain Rowan |
+| `models/npcs/fisherman-pete/fisherman-pete.vrm` | Fisherman Pete |
+| `models/npcs/forester-wilma/forester-wilma.vrm` | Forester Wilma |
+| `models/npcs/shopkeeper/shopkeeper.vrm` | Shopkeeper |
+| `models/npcs/tanner-ellis/tanner-ellis.vrm` | Tanner Ellis |
+| `models/npcs/torvin/torvin.vrm` | Torvin |
 
 ---
 
@@ -184,7 +203,7 @@
 }
 ```

 ### Get NPCs by Category

 ```typescript
 export function getNPCsByCategory(category: NPCCategory): NPCData[] {
@@ -194,17 +213,17 @@
 }
 ```

 ### Get NPCs by Biome

 ```typescript
 export function getNPCsByBiome(biome: string): NPCData[] {
  return Array.from(ALL_NPCS.values()).filter((npc) =>
    npc.spawnBiomes?.includes(biome)
  );
 }
 ```

 ### Get NPCs by Level Range

 ```typescript
 export function getNPCsByLevelRange(minLevel: number, maxLevel: number): NPCData[] {
@@ -292,7 +311,7 @@
    "type": "aggressive"
  },
  "spawnBiomes": ["forest", "plains"],
  "respawnTime": 30,
  "drops": {
    "defaultDrop": {
      "enabled": true,
@@ -307,14 +326,14 @@
      { "itemId": "iron_dagger", "minQuantity": 1, "maxQuantity": 1, "chance": 0.1 }
    ],
    "rare": [],
    "veryRare": []
  }
 }
 ```

 ---

 ## Adding New NPCs

 <Steps>
  <Step title="Add to JSON Manifest">

diff --git a/wiki/data/overview.mdx b/wiki/data/overview.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Data Manifests Overview"
 description: "Manifest-driven content system for NPCs, items, and world areas"
 icon: "database"
 ---

@@ -58,12 +58,12 @@
 │   └── misc.json         # Miscellaneous items
 ├── recipes/              # Crafting recipes by skill
 │   ├── cooking.json      # Cooking recipes
 │   ├── firemaking.json   # Firemaking recipes
 │   ├── smelting.json     # Ore smelting recipes
 │   ├── smithing.json     # Smithing recipes
 │   ├── fletching.json    # Fletching recipes (NEW)
 │   ├── crafting.json     # Crafting recipes (NEW)
 │   ├── runecrafting.json # Runecrafting recipes (NEW)
 │   └── tanning.json      # Leather tanning recipes
 ├── gathering/            # Gathering skill data
 │   ├── woodcutting.json  # Tree data
@@ -100,23 +100,35 @@
 | `category` | `"mob" \| "boss" \| "quest" \| "neutral"` | NPC type |
 | `stats` | `NPCStats` | Combat stats (attack, strength, defense, health, ranged, level) |
 | `drops` | `DropTable` | Loot table with rarity tiers |
 | `spawnBiomes` | `string[]` | Biomes where NPC spawns |
 | `modelPath` | `string` | Path to 3D model |
 | `behavior` | `"passive" \| "aggressive"` | Combat behavior |
 
 ### Available 3D Models
 
-**NPCs**:
+**Mobs** (`models/mobs/`):
 ```
-/assets/models/
-├── goblin/goblin_rigged.glb     → Goblins
-├── thug/thug_rigged.glb         → Bandits
-├── human/human_rigged.glb       → Guards, knights, warriors, rangers
-├── troll/troll_rigged.glb       → Hobgoblins
-├── imp/imp_rigged.glb           → Dark warriors
-├── cow/cow.vrm                  → Cows
-├── dark-wizard/dark-wizard.vrm  → Dark wizards
-└── dark-ranger/dark-ranger.vrm  → Dark rangers
+├── goblin/
+│   ├── goblin.vrm                → Goblin (VRM format)
+│   ├── goblin_rigged.glb         → Goblin (GLB format)
+│   └── animations/
+│       ├── running.glb           → Running animation
+│       └── walking.glb           → Walking animation
+├── dark-ranger/
+│   └── dark-ranger.vrm           → Dark ranger
+└── dark-wizard/
+    └── dark-wizard.vrm           → Dark wizard
+```
+
+**NPCs** (`models/npcs/`):
+```
+├── banker/banker.vrm             → Banker
+├── captain-rowan/captain-rowan.vrm → Captain Rowan
+├── fisherman-pete/fisherman-pete.vrm → Fisherman Pete
+├── forester-wilma/forester-wilma.vrm → Forester Wilma
+├── shopkeeper/shopkeeper.vrm     → Shopkeeper
+├── tanner-ellis/tanner-ellis.vrm → Tanner Ellis
+└── torvin/torvin.vrm             → Torvin
 ```
 
 **Stations**:
@@ -197,6 +209,14 @@
 └── pine_01.glb - pine_03.glb (+ LOD variants)     → Pine trees
 ```
 
+**Miscellaneous Items** (`models/misc/`):
+```
+├── bones/bones.glb               → Bones (mob drop)
+├── coin-pile/coin-pile.glb       → Coin pile
+├── ashes/ashes.glb               → Ashes
+├── firemaking-fire/firemaking-fire.glb → Fire model for firemaking
+└── headstone/headstone.glb       → Headstone
+```
 <Note>
 Tree models include LOD (Level of Detail) variants for performance optimization. Each tree type has multiple variants (e.g., `fir_01.glb`, `fir_01_lod1.glb`, `fir_01_lod2.glb`) for different viewing distances. All tree models have been normalized to consistent root depths to prevent floating or sinking into terrain.
 </Note>
@@ -278,10 +298,10 @@
 ```

 **Supported Tiers:**
 - **Melee**: bronze, iron, steel, black, mithril, adamant, rune, dragon
 - **Tools**: Same as melee (with different skill requirements)
 - **Ranged**: leather, studded, green_dhide, blue_dhide, red_dhide, black_dhide
 - **Magic**: wizard, mystic, infinity, ahrims

 ### Item Helper Functions

@@ -328,7 +348,7 @@

 ### Bank Notes

 The system supports bank notes for stackable versions of items:

 ```typescript
 // From packages/shared/src/data/items.ts
@@ -351,7 +371,7 @@

 ## Drop Tables

 NPCs have tiered drop tables:

 ```typescript
 interface DropTable {
@@ -415,7 +435,7 @@

 ## World Areas

 World areas define zones, biomes, and spawn points:

 ```
 packages/shared/src/data/
@@ -431,7 +451,7 @@
 | `name` | Display name |
 | `biome` | Biome type (forest, plains, etc.) |
 | `difficulty` | 0-3 difficulty level |
 | `mobs` | NPCs that spawn here |
 | `resources` | Trees, fishing spots, etc. |
 | `isSafe` | Whether it's a safe zone |

@@ -452,7 +472,7 @@

 ## Stations

 Crafting stations are interactive objects that enable processing skills like smithing, smelting, and cooking:

 ```typescript
 interface StationData {
@@ -563,7 +583,7 @@

 Stations are defined in `stations.json`:

 - **Anvil** - Used for smithing bars into equipment
 - **Furnace** - Used for smelting ores into bars
 - **Range** - Used for cooking food (reduces burn chance compared to fires)
 - **Bank Booth** - Used for accessing bank storage
@@ -615,7 +635,7 @@

 | Station | Purpose | Model | Scale | Y Offset |
 |---------|---------|-------|-------|----------|
 | **Anvil** | Smithing bars into equipment | `models/anvil/anvil.glb` | 0.5 | 0.2 |
 | **Furnace** | Smelting ores into bars | `models/furnace/furnace.glb` | 1.5 | 1.0 |
 | **Cooking Range** | Cooking food (reduced burn chance) | `models/cooking-range/cooking-range.glb` | 1.0 | 0.5 |
 | **Bank Chest** | Accessing bank storage | `models/bank-chest/bank-chest.glb` | 0.5 | 0.75 |
@@ -651,7 +671,7 @@
 | Dragon | 2 |
 | Rune | 3 |
 | Adamant | 4 |
 | Mithril | 5 |
 | Steel | 6 |
 | Iron | 7 |
 | Bronze | 8 (worst) |
@@ -663,14 +683,14 @@
 | Dragon | 2 | 3 |
 | Rune | 3 | 3 |
 | Adamant | 4 | 4 |
 | Mithril | 5 | 5 |
 | Steel | 6 | 6 |
 | Iron | 7 | 7 |
 | Bronze | 8 | 8 |

 ---

 ## Vegetation & Biomes

 ### Vegetation Assets

@@ -692,13 +712,13 @@
 }
 ```

 **Recent maxSlope Updates** (March 2026):
 - **Tundra**: 0.8 → 1.8 (increased for terraced terrain)
 - **Forest**: 0.8 → 1.5 (increased for landscape features)
 - **Canyon**: 0.6 → 2.5 (increased for steep canyon walls)

 **Vegetation Categories**:
 - `tree` - Large trees (oak, willow, maple, yew, magic, fir, knotwood, dead, wind_pine)
 - `bush` - Small bushes and shrubs
 - `fern` - Ground ferns
 - `flower` - Decorative flowers
@@ -709,10 +729,10 @@

 **Tree Types**:
 - **Oak, Willow, Yew, Magic** - Standard woodcutting trees with multiple model variants
 - **Maple** - Autumn trees with warm vermillion red-orange leaves (#D04838)
 - **Fir** - Coniferous trees for forest biomes
 - **Knotwood** - Trees with warm amber-colored leaves (#C4832A)
 - **Dead** - Barren trees for tundra/canyon biomes
 - **Wind Pine** - Specialized pine tree for tundra biome (single model variant)
 ### Model Bounds System

@@ -746,11 +766,11 @@

 The model bounds system is used by the terrain flattening system to calculate station footprints and by the collision system for efficient spatial queries.

 ### Biomes

 The `biomes.json` manifest defines terrain biomes with vegetation, mobs, and environmental properties:

 **Available Biomes:**
 - **Plains** - Open grasslands with gentle rolling hills (difficulty 0)
 - **Forest** - Dense woodland with abundant trees (difficulty 1)
 - **Valley** - Low-lying areas between hills (difficulty 0)
@@ -763,7 +783,7 @@

 ### Biome Vegetation Layers

 Biomes in `biomes.json` define procedural vegetation layers that reference vegetation assets:

 ```typescript
 interface VegetationLayer {
@@ -782,18 +802,18 @@
 ```

 **Recent Updates**:
 - **165 tree model variants** added across 12 tree types (bamboo, birch, cactus, chinaPine, coconut, dead, fir, knotwood, maple, oak, palm, pine) with 3 LOD levels each
 - **Tree model depth normalization**: All fir variants aligned to fir_03's minY (-59.46), all maple variants aligned to maple_01's minY (-114.76) to prevent floating
 - **Maple tree recoloring**: Leaves changed to warm vermillion red-orange (#D04838)
 - **Knotwood tree recoloring**: Leaves changed from golden-yellow to warm amber (#C4832A)
 - **Terrain biome textures** added for TerrainShader rendering (grass, dirt, cliff, desert, snow variants)
 - **Woodcutting manifest updated**: Replaced 8 generic trees with 12 new tree types using `modelVariants` arrays
 - **Biomes manifest updated**: Removed stale `tree1` vegetation layers (trees now managed via TreeTypes.ts + woodcutting manifest)
 - **Wind Pine tree type** added for tundra biome (split from dead tree variants)
 - Mushroom vegetation added to all biomes with varying densities (2-30)
 - Tree density reduced in plains biome (8 → 5)
 - Mushroom clustering varies by biome (cluster size 3-8)
 - Firemaking fire 3D model added (`models/firemaking-fire/firemaking-fire.glb`)
 - Tree model scales adjusted for better visual proportions (March 2026)
 - Fir and maple model root depths normalized to prevent floating (March 2026)
  - All fir variants aligned to fir_03's minY (-59.46)
@@ -805,7 +825,7 @@

 Recipe manifests define crafting, processing, and production activities for artisan skills. All recipes follow a consistent structure with inputs, outputs, tools, level requirements, and XP rewards.

 ### Fletching Recipes

 The `recipes/fletching.json` manifest defines bow and arrow crafting:

@@ -829,10 +849,10 @@
 **Recipe Categories**:
 - `arrow_shafts` - Knife + logs → arrow shafts (15-90 per log)
 - `headless_arrows` - Arrow shafts + feathers → headless arrows
 - `shortbows` - Knife + logs → unstrung shortbows
 - `longbows` - Knife + logs → unstrung longbows
 - `stringing` - Bowstring + unstrung bow → finished bow
 - `arrows` - Arrowtips + headless arrows → finished arrows

 ### Crafting Recipes

@@ -861,11 +881,11 @@
 **Recipe Categories**:
 - `leather` - Needle + thread + leather → leather armor
 - `studded` - Leather armor + steel studs → studded armor
 - `dragonhide` - Needle + thread + dragon leather → dragonhide armor
 - `jewelry` - Gold bar + gems + mould → jewelry (at furnace)
 - `gem_cutting` - Chisel + uncut gem → cut gem

 ### Runecrafting Recipes

 The `recipes/runecrafting.json` manifest defines rune crafting at altars:

@@ -939,14 +959,14 @@
 | **Goblin Slayer** | Novice | 1 | Help Captain Rowan deal with the goblin threat |
 | **Lumberjack's First Lesson** | Novice | 1 | Help Forester Wilma gather and burn firewood |
 | **Fresh Catch** | Novice | 1 | Help Fisherman Pete catch and cook fish |
 | **Torvin's Tools** | Novice | 1 | Help Torvin forge a set of bronze tools |

 ### Quest Stage Types

 - **dialogue** - Talk to an NPC
 - **kill** - Defeat a specific number of NPCs
 - **gather** - Collect items through skilling
 - **interact** - Use items or stations (cooking, smithing, etc.)

 ---

@@ -957,7 +977,7 @@
    - Items: Add to appropriate file in `items/` directory
    - Gathering: Add to `gathering/woodcutting.json`, `mining.json`, or `fishing.json`
    - Recipes: Add to appropriate file in `recipes/` directory
    - NPCs: Add to `npcs.json`
  </Step>
  <Step title="Follow existing patterns">
    Use the same structure as existing entries. For tiered equipment, specify the `tier` field.
@@ -983,12 +1003,12 @@

 Three new artisan skills added with complete OSRS-accurate recipe manifests:

 - **Fletching**: Arrow shafts, headless arrows, shortbows, longbows, bow stringing, arrow tipping (40+ recipes)
 - **Crafting**: Leather armor, studded armor, dragonhide armor, jewelry, gem cutting (25+ recipes)
 - **Runecrafting**: Air, mind, water, earth, fire, chaos runes with multi-rune level thresholds

 **New Assets**:
 - Firemaking fire 3D model (`models/firemaking-fire/firemaking-fire.glb`)
 - Comprehensive armor manifest with 80+ armor pieces across all combat styles

 ### Manifest Refactor (PR #3)
@@ -997,13 +1017,13 @@

 - **Items split by type**: Weapons, tools, resources, food, ammunition, runes, armor, and misc are now in separate files
 - **Gathering resources**: Woodcutting, mining, and fishing data moved to dedicated files
 - **Recipe system**: New recipes directory for smelting, smithing, cooking, firemaking, fletching, crafting, and runecrafting
 - **Centralized requirements**: `tier-requirements.json` provides OSRS-accurate level requirements
 - **Skill unlocks**: `skill-unlocks.json` documents progression milestones

 ### New Vegetation (PR #4)

 Mushroom vegetation added to biomes with configurable density, clustering, and spawn parameters.

 ---