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

# CHANGELOG ARTISAN SKILLS

# Changelog: Artisan Skills Update

Comprehensive changelog for the artisan skills update (Crafting, Fletching, Runecrafting).

## Version 1.0.0 - Artisan Skills Release (2026-01-31)

### Major Features

#### Crafting Skill (PR #698)

**New System:** `CraftingSystem.ts`

* Tick-based crafting sessions with thread consumption
* 30+ recipes for leather, dragonhide, jewelry, and gems
* Movement and combat cancellation
* Make-X functionality with quantity memory
* Recipe filtering by input item and station

**Categories:**

* Leather crafting (levels 1-18): 6 items
* Dragonhide crafting (levels 57-84): 12 items
* Jewelry crafting (levels 5-40): 10 items
* Gem cutting (levels 20-43): 4 items

**Tanning System:**

* Instant hide-to-leather conversion at tanner NPCs
* 5 tanning recipes with coin costs
* No XP granted (service, not skill)

**UI:**

* `CraftingPanel.tsx`: Category-based recipe selection
* `TanningPanel.tsx`: Hide selection with cost display
* Desktop and mobile responsive layouts

**Database:**

* Migration 0029: Add `craftingLevel` and `craftingXp` columns
* Auto-save every 5 seconds
* Persisted with character data

**Manifests:**

* `recipes/crafting.json`: 30+ crafting recipes
* `recipes/tanning.json`: 5 tanning recipes

**Tests:**

* 19 unit tests covering lifecycle, cancellation, edge cases
* Thread consumption validation
* Recipe filtering tests

#### Fletching Skill (PR #699)

**New System:** `FletchingSystem.ts`

* Tick-based fletching sessions with multi-output support
* 37 recipes for bows and arrows
* Item-on-item interactions (bowstring + bow, arrowtips + arrows)
* Movement and combat cancellation
* Recipe filtering by input item pair

**Categories:**

* Arrow shafts (levels 1-60): 6 recipes, 15 per action
* Headless arrows (level 1): 1 recipe, 15 per action
* Arrows (levels 1-75): 6 recipes, 15 per action
* Shortbows (levels 5-80): 6 recipes
* Longbows (levels 10-85): 6 recipes
* Stringing (levels 5-85): 12 recipes

**UI:**

* `FletchingPanel.tsx`: Category-based recipe selection with output quantity display
* Modal wiring for desktop and mobile
* Recipe filtering by input item pair

**Database:**

* Migration 0030: Add `fletchingLevel` and `fletchingXp` columns
* Auto-save every 5 seconds
* Persisted with character data

**Manifests:**

* `recipes/fletching.json`: 37 fletching recipes

**Tests:**

* 15 unit tests covering multi-output, item-on-item, cancellation
* Recipe filtering by input pair
* Output quantity validation

#### Runecrafting Skill (PR #703)

**New System:** `RunecraftingSystem.ts`

* Instant essence-to-rune conversion at altars
* Multi-rune multipliers at higher levels
* Two essence types (rune\_essence, pure\_essence)
* 11 rune types with unique altars

**Rune Types:**

* Basic runes (levels 1-27): Air, Mind, Water, Earth, Fire, Body
* Advanced runes (levels 27-65): Cosmic, Chaos, Nature, Law, Death

**New Entity:** `RunecraftingAltarEntity.ts`

* Interactable altar entity
* Stores rune type
* Visual model with glow effect
* Server-authoritative rune type (prevents client manipulation)

**UI:**

* No panel required (instant conversion)
* Feedback via UI messages
* XP drops displayed

**Database:**

* Migration 0031: Add `runecraftingLevel` and `runecraftingXp` columns
* Auto-save every 5 seconds
* Persisted with character data

**Manifests:**

* `recipes/runecrafting.json`: 11 runecrafting recipes

**Tests:**

* 12 unit tests covering multipliers, essence validation, levels
* Multi-rune calculation tests
* Essence type validation

### Equipment System Improvements (PR #697)

**Arrow Quantity Tracking:**

* Arrows now stored with full quantity in equipment slot
* `consumeArrow()` decrements quantity by 1 per shot
* Auto-unequips when quantity reaches 0
* Quantity persisted to database on equip/unequip/consume
* Prevents arrow duplication on crashes

**Idempotency Protection:**

* Duplicate equip/unequip requests blocked with 5s dedup window
* Prevents item duplication from double-clicks or network lag

**Equipment Manifest Validation:**

* Validates `equipSlot` matches manifest
* Catches configuration errors
* Detailed error logging

**Bank Equipment Tab Integration:**

* `equipItemDirect()`: Equip from bank without inventory
* `unequipItemDirect()`: Unequip to bank without inventory
* `getAllEquippedItems()`: Get all equipped items for deposit-all
* Handles 2h weapon/shield conflicts
* Returns displaced items for bank insertion

**Trade and Duel Protection:**

* Cannot equip/unequip during active trades
* Cannot equip/unequip during active duels
* Prevents item duplication exploits

**11-Slot Equipment:**

* Weapon, Shield, Helmet, Body, Legs
* Boots, Gloves, Cape, Amulet, Ring
* Arrows (ammunition slot)

**Database:**

* Equipment table tracks `quantity` for stackable items
* Parallelized auto-save with `Promise.allSettled`
* Async destroy for graceful shutdown

### ProcessingDataProvider Enhancements

**New Recipe Types:**

* Crafting recipes with tools and consumables
* Fletching recipes with multi-output support
* Runecrafting recipes with multi-rune levels
* Tanning recipes with coin costs

**New Methods:**

* `getCraftingRecipe(outputItemId)`
* `getCraftingRecipesByStation(station)`
* `getCraftingInputsForTool(toolId)`
* `getFletchingRecipe(recipeId)`
* `getFletchingRecipesForInput(itemId)`
* `getFletchingRecipesForInputPair(itemA, itemB)`
* `getRunecraftingRecipe(runeType)`
* `getRunecraftingMultiplier(runeType, level)`
* `getTanningRecipe(inputItemId)`

**Validation:**

* Comprehensive manifest validation on load
* Detailed error reporting for invalid recipes
* Item existence checks against ITEMS manifest
* Level range validation (1-99)
* XP and tick validation (positive numbers)

**Performance:**

* Pre-allocated inventory count buffer
* Lazy initialization
* Singleton pattern
* Recipe caching

### Visual Improvements

#### Mining Rock Material Fix (PR #710)

**Issue:** Mining rocks rendered with metallic appearance due to default metalness=1 in PBR materials.

**Fix:**

* Force metalness=0 on all PBR materials for rock models
* Correct stone appearance
* Depleted rock models align to ground using bounding box

**Implementation:**

```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
// In ResourceEntity.createMesh()
child.traverse((node) => {
  if (node instanceof THREE.Mesh && node.material) {
    if (node.material.metalness !== undefined) {
      node.material.metalness = 0; // Stone is not metallic
    }
  }
});
```

#### Headstone Model Replacement

**Change:** Replaced placeholder box with proper headstone.glb model for death markers.

**Features:**

* Proper 3D model (headstone.glb)
* Scaled to 0.5 for appropriate size
* Aligned to ground using bounding box
* Maintains collision and interaction functionality

**Location:** `packages/shared/src/entities/world/HeadstoneEntity.ts`

### Network Protocol Updates

**New Packet Types:**

* `craftingInteract`, `craftingRequest`, `craftingInterfaceOpen`, `craftingStart`, `craftingComplete`
* `fletchingInteract`, `fletchingRequest`, `fletchingInterfaceOpen`, `fletchingStart`, `fletchingComplete`
* `tanningInteract`, `tanningRequest`, `tanningInterfaceOpen`, `tanningComplete`
* `runecraftingInteract`, `runecraftingComplete`

**Event System:**

* 15+ new event types for artisan skills
* Type-safe event payloads
* Server-authoritative validation

### Performance Optimizations

**Crafting System:**

* Single inventory scan per tick (consolidated from 4 separate scans)
* Reusable arrays to avoid per-tick allocations
* Once-per-tick processing guard
* Pre-allocated inventory state buffer

**Fletching System:**

* Single inventory scan per tick
* Reusable arrays for completed session tracking
* Once-per-tick processing guard

**Runecrafting System:**

* No tick-based processing (instant conversion)
* Single inventory scan per interaction
* Pre-calculated multi-rune multipliers

### Security Enhancements

**Rate Limiting:**

* Crafting interact: 1 request per 500ms
* Fletching interact: 1 request per 500ms
* Runecrafting interact: 1 request per 500ms

**Audit Logging:**

* Structured logging on craft/fletch completion
* Economic tracking for all artisan actions
* Detailed input/output logging

**Input Validation:**

* Recipe ID validation
* Level requirement checks
* Material availability checks
* Tool presence validation
* Consumable availability checks

**Monotonic Counters:**

* Item IDs use monotonic counters to prevent Date.now() collisions
* Separate counters for craft, fletch, and inventory items

### Code Quality

**Type Safety:**

* Strong typing throughout (no `any` types)
* Type guards for skill access
* Typed event payloads
* Interface segregation

**Testing:**

* 46+ new unit tests
* Integration tests for full workflows
* Recipe validation tests
* Performance benchmarks

**Documentation:**

* Comprehensive JSDoc comments
* OSRS wiki references
* Usage examples
* Architecture diagrams

## Breaking Changes

None. All changes are backwards compatible.

**Existing Characters:**

* Automatically receive new skills at level 1 with 0 XP
* No data loss or character reset required

**Existing Items:**

* All existing items remain functional
* New items added for artisan skills

## Migration Notes

### Database

Migrations run automatically on server startup:

* 0029: Add crafting skill columns
* 0030: Add fletching skill columns
* 0031: Add runecrafting skill columns

No manual intervention required.

### Code

**SkillsSystem Updates:**

* Now supports 17 skills (was 14)
* `getTotalLevel()` includes new skills
* `getTotalXP()` includes new skills
* `getSkills()` returns all 17 skills

**ProcessingDataProvider Updates:**

* Extended with crafting, fletching, runecrafting methods
* New recipe manifest loading
* Validation on load

**Client UI Updates:**

* Skills panel displays 17 skills
* New panels: CraftingPanel, FletchingPanel, TanningPanel
* Navigation ribbon updated

## Commit History

### Crafting Skill (PR #698)

* `3c650a5`: Add crafting skill with full-stack persistence and UI support
* `69eb3a5`: Extend ProcessingDataProvider with crafting recipe loading
* `f08fac1`: Add CraftingSystem with tick-based sessions and network wiring
* `b0f1a22`: Add tanning system with NPC dialogue and instant conversion
* `31582c1`: Add CraftingPanel and TanningPanel client UI
* `d0e2ef7`: Add crafting and tanning recipe tests
* `81672858`: Wire up client-side crafting interactions
* `0c8d705`: Filter crafting recipes by input item
* `947f4c2`: Add crafting/magic/agility skills to player stats component
* `0273bc0`: Strengthen type safety with typed payloads
* `2b483f1`: Add rate limiting and structured audit logging
* `8d7f752`: Cancel crafting on player movement or combat start
* `05221b6`: Consolidate inventory scans and eliminate per-tick allocations
* `aa7a3cb`: Collision-free item IDs, round XP at DB boundary
* `b11933b`: Consistent skill fallbacks and deduplicate formatItemName
* `a0e5e6a`: Auto-select single recipe in crafting panel
* `f730c55`: Add 19 unit tests covering crafting lifecycle

### Fletching Skill (PR #699)

* `1050f1a`: Add fletching skill foundation (types, DB migration, skill registration)
* `08618548`: Add 37 fletching recipes with validated data provider
* `44997040`: Add FletchingSystem with event types and session management
* `4d32f38`: Add server network handlers and packet definitions
* `eb6ac9d`: Add FletchingPanel UI with category grouping
* `beed760`: Add outputQuantity support and 6 OSRS-accurate arrowtip recipes
* `d328f22`: Add fletching system tests
* `0573030`: Add DB persistence, client network handlers, skill panel entry

### Runecrafting Skill (PR #703)

* `1559cf5`: Register skill across type system, events, components
* `a8c14f6`: Add database schema, types, and repository persistence
* `4d4eaf6`: Add RunecraftingAltarEntity with world spawning
* `65f229f`: Add core RunecraftingSystem and recipe loading
* `46ab465`: Add client interaction handler and server network handler
* `05ba523`: Export new types, entity, and handlers from shared package
* `5cc57e9`: Server-authoritative runeType, per-altar names, raycast routing
* `7519e53`: Add missing runecrafting skill migration (0031)
* `34ecbfb`: Add unit tests covering crafting, levels, essence validation

### Equipment System (PR #697)

* `287f430`: Remove \~150 lines of dead ECS visual code
* `1541a2c`: Delete dead equipment files, fix arrow quantity bug
* `44f6d69`: Parallelize auto-save, validate equipSlot manifests
* `cbda4ed`: Add 11-slot mocks, trade/death guards, arrow quantity persistence
* `e5c816c`: Add idempotency checks to equip/unequip handlers

### Visual Fixes

* `e08d275`: Force metalness=0 on PBR materials for mining rocks (PR #710)
* `fa9d8fe`: Replace placeholder box with headstone.glb model

## Detailed Changes

### Files Added

**Systems:**

* `packages/shared/src/systems/shared/interaction/CraftingSystem.ts`
* `packages/shared/src/systems/shared/interaction/FletchingSystem.ts`
* `packages/shared/src/systems/shared/interaction/RunecraftingSystem.ts`
* `packages/shared/src/systems/shared/interaction/TanningSystem.ts`

**Entities:**

* `packages/shared/src/entities/world/RunecraftingAltarEntity.ts`

**UI Panels:**

* `packages/client/src/game/panels/CraftingPanel.tsx`
* `packages/client/src/game/panels/FletchingPanel.tsx`
* `packages/client/src/game/panels/TanningPanel.tsx`

**Tests:**

* `packages/shared/src/systems/shared/interaction/__tests__/CraftingSystem.test.ts`
* `packages/shared/src/systems/shared/interaction/__tests__/FletchingSystem.test.ts`
* `packages/shared/src/systems/shared/interaction/__tests__/RunecraftingSystem.test.ts`
* `packages/shared/src/data/__tests__/ProcessingDataProvider.test.ts`

**Manifests:**

* `packages/server/world/assets/manifests/recipes/crafting.json`
* `packages/server/world/assets/manifests/recipes/tanning.json`
* `packages/server/world/assets/manifests/recipes/fletching.json`
* `packages/server/world/assets/manifests/recipes/runecrafting.json`

**Migrations:**

* `packages/server/src/database/migrations/0029_add_crafting_skill.sql`
* `packages/server/src/database/migrations/0030_add_fletching_skill.sql`
* `packages/server/src/database/migrations/0031_add_runecrafting_skill.sql`

**Documentation:**

* `ARTISAN-SKILLS.md`
* `API-ARTISAN-SKILLS.md`
* `MIGRATION-ARTISAN-SKILLS.md`
* `CHANGELOG-ARTISAN-SKILLS.md`

### Files Modified

**Core Systems:**

* `packages/shared/src/systems/shared/character/SkillsSystem.ts`: Add crafting, fletching, runecrafting skills
* `packages/shared/src/systems/shared/character/EquipmentSystem.ts`: Arrow quantity tracking, idempotency, bank integration
* `packages/shared/src/data/ProcessingDataProvider.ts`: Add crafting, fletching, runecrafting, tanning methods

**Database:**

* `packages/server/src/database/schema.ts`: Add skill columns
* `packages/server/src/database/repositories/CharacterRepository.ts`: Persist new skills

**Network:**

* `packages/shared/src/platform/shared/packets.ts`: Add artisan skill packets
* `packages/server/src/systems/ServerNetwork/handlers/`: Add crafting, fletching, runecrafting handlers

**UI:**

* `packages/client/src/game/panels/SkillsPanel.tsx`: Display 17 skills
* `packages/client/src/game/interface/InterfaceManager.tsx`: Register new panels

**Types:**

* `packages/shared/src/types/events/event-types.ts`: Add artisan skill events
* `packages/shared/src/types/core/core.ts`: Add crafting, fletching, runecrafting to Skills type

**Constants:**

* `packages/shared/src/constants/ProcessingConstants.ts`: Add crafting, fletching constants

**Visual:**

* `packages/shared/src/entities/world/ResourceEntity.ts`: Force metalness=0 on rock materials
* `packages/shared/src/entities/world/HeadstoneEntity.ts`: Load headstone.glb model

### Files Deleted

* `docs/CRAFTING-PLAN.md`: Completed, no longer needed
* `ASSET-INVENTORY.md`: Unused, removed

### Documentation Updates

**Root Documentation:**

* `README.md`: Updated skills list (15 → 17), added artisan skills section
* `CLAUDE.md`: Added artisan skills architecture, ProcessingDataProvider API, equipment improvements

**Package Documentation:**

* `packages/server/README.md`: Updated skills list, added artisan skills section, migration notes
* `packages/client/README.md`: Updated skills list, added artisan skills section

**Wiki Documentation:**

* `wiki/game-systems/skills.mdx`: Added crafting, fletching, runecrafting sections with XP tables

## Statistics

### Lines of Code

**Added:**

* Systems: \~2,500 lines
* UI Panels: \~1,200 lines
* Tests: \~800 lines
* Manifests: \~1,500 lines (JSON)
* Documentation: \~2,000 lines
* **Total: \~8,000 lines**

**Removed:**

* Dead equipment code: \~150 lines
* Unused files: \~200 lines
* **Total: \~350 lines**

**Net Change: +7,650 lines**

### Test Coverage

**New Tests:**

* CraftingSystem: 19 tests
* FletchingSystem: 15 tests
* RunecraftingSystem: 12 tests
* ProcessingDataProvider: 25 tests
* **Total: 71 new tests**

**Coverage:**

* Crafting: 95% statement coverage
* Fletching: 93% statement coverage
* Runecrafting: 97% statement coverage
* ProcessingDataProvider: 89% statement coverage

### Recipe Count

**Crafting:**

* Leather: 6 recipes
* Dragonhide: 12 recipes
* Jewelry: 10 recipes
* Gem cutting: 4 recipes
* **Total: 32 recipes**

**Tanning:**

* 5 recipes

**Fletching:**

* Arrow shafts: 6 recipes
* Headless arrows: 1 recipe
* Arrows: 6 recipes
* Shortbows: 6 recipes
* Longbows: 6 recipes
* Stringing: 12 recipes
* **Total: 37 recipes**

**Runecrafting:**

* 11 rune types

**Grand Total: 85 new recipes**

## Performance Impact

### Memory Usage

**Per Active Session:**

* CraftingSession: \~200 bytes (includes consumableUses Map)
* FletchingSession: \~150 bytes
* RunecraftingSystem: No active sessions (instant)

**Recipe Data:**

* Crafting: \~15KB
* Fletching: \~15KB
* Runecrafting: \~3KB
* Tanning: \~1KB
* **Total: \~34KB**

### CPU Usage

**Tick Processing:**

* CraftingSystem: O(n) where n = active sessions
* FletchingSystem: O(n) where n = active sessions
* RunecraftingSystem: No tick processing

**Inventory Scans:**

* Single scan per tick per active session
* Pre-allocated buffers to avoid allocations
* Reusable arrays for completed sessions

### Database Impact

**New Columns:**

* 6 integer columns per character (\~24 bytes)
* Auto-save every 5 seconds (existing behavior)
* No additional queries (skills saved with character)

**Storage:**

* \~24 bytes per character for new skills
* Negligible impact on database size

## Known Issues

None.

## Future Enhancements

### Planned Features

**Crafting:**

* Studded leather armor (requires steel studs)
* Snakeskin armor (requires snakeskin)
* Battlestaves (requires orbs and battlestaves)

**Fletching:**

* Crossbows and bolts
* Javelins and throwing knives
* Darts

**Runecrafting:**

* Combination runes (e.g., mist runes = water + air)
* Rune pouches for extra essence capacity
* Runecrafting tiaras for altar teleports

**General:**

* Recipe discovery system (unlock recipes by level)
* Crafting guilds with XP bonuses
* Master craftsman NPCs with special recipes

## Contributors

* @dreaminglucid: All artisan skills implementation, testing, documentation

## References

* [OSRS Crafting Wiki](https://oldschool.runescape.wiki/w/Crafting)
* [OSRS Fletching Wiki](https://oldschool.runescape.wiki/w/Fletching)
* [OSRS Runecrafting Wiki](https://oldschool.runescape.wiki/w/Runecrafting)
* [OSRS Smithing Wiki](https://oldschool.runescape.wiki/w/Smithing)

## License

GPL-3.0-only - See LICENSE file