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

# Data Providers

> Runtime data access for manifests and recipes

# Data Providers

Data providers offer runtime access to game content loaded from JSON manifests. They provide type-safe APIs for querying items, recipes, requirements, and station configurations.

## ProcessingDataProvider

Provides access to cooking, firemaking, smelting, and smithing recipes.

### Import

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
import { processingDataProvider } from '@hyperscape/shared';
```

### Initialization

The provider is automatically initialized by `DataManager` after loading recipe manifests. You can manually rebuild if needed:

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
// Force rebuild (e.g., after hot-reloading manifests)
processingDataProvider.rebuild();

// Check if initialized
const isReady = processingDataProvider.isReady();
```

***

## Smelting API

### Check if Bar is Smeltable

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const canSmelt = processingDataProvider.isSmeltableBar('bronze_bar');
// Returns: true
```

### Get Smelting Data

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const data = processingDataProvider.getSmeltingData('bronze_bar');
// Returns: {
//   barItemId: 'bronze_bar',
//   primaryOre: 'copper_ore',
//   secondaryOre: 'tin_ore',
//   coalRequired: 0,
//   levelRequired: 1,
//   xp: 6.25,
//   successRate: 1.0,
//   ticks: 4
// }
```

### Get Smeltable Bars from Inventory

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const inventory = [
  { itemId: 'copper_ore', quantity: 10 },
  { itemId: 'tin_ore', quantity: 10 },
  { itemId: 'iron_ore', quantity: 5 },
  { itemId: 'coal', quantity: 20 }
];

const smithingLevel = 30;
const availableBars = processingDataProvider.getSmeltableBarsFromInventory(
  inventory,
  smithingLevel
);
// Returns: [bronzeBarData, ironBarData, steelBarData]
```

### Get All Smeltable Bar IDs

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const barIds = processingDataProvider.getSmeltableBarIds();
// Returns: Set(['bronze_bar', 'iron_bar', 'steel_bar', ...])
```

### Get Smelting Level/XP

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const level = processingDataProvider.getSmeltingLevel('steel_bar');
// Returns: 30

const xp = processingDataProvider.getSmeltingXP('steel_bar');
// Returns: 17.5

const ticks = processingDataProvider.getSmeltingTicks('steel_bar');
// Returns: 4
```

***

## Smithing API

### Check if Item is Smithable

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const canSmith = processingDataProvider.isSmithableItem('bronze_sword');
// Returns: true
```

### Get Smithing Recipe

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const recipe = processingDataProvider.getSmithingRecipe('bronze_sword');
// Returns: {
//   itemId: 'bronze_sword',
//   name: 'Bronze Sword',
//   barType: 'bronze_bar',
//   barsRequired: 1,
//   levelRequired: 4,
//   xp: 12.5,
//   category: 'weapons',
//   ticks: 4
// }
```

### Get Recipes for Bar Type

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const recipes = processingDataProvider.getSmithingRecipesForBar('bronze_bar');
// Returns: [bronzeDaggerRecipe, bronzeSwordRecipe, bronzePlateBodyRecipe, ...]
```

### Get Smithable Items with Availability

Shows ALL recipes for bar types the player has, with flags for UI display:

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const inventory = [
  { itemId: 'bronze_bar', quantity: 10 },
  { itemId: 'iron_bar', quantity: 3 }
];

const smithingLevel = 20;
const available = processingDataProvider.getSmithableItemsWithAvailability(
  inventory,
  smithingLevel
);
// Returns: [
//   { ...bronzeDaggerRecipe, meetsLevel: true, hasBars: true },
//   { ...ironPlateBodyRecipe, meetsLevel: false, hasBars: false },
//   ...
// ]
```

<Info>
  Use `getSmithableItemsWithAvailability()` for UI display to show greyed-out items the player can't make yet.
</Info>

### Get All Smithing Recipes

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const allRecipes = processingDataProvider.getAllSmithingRecipes();
// Returns: Array of all smithing recipes
```

### Get Smithing Level/XP

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const level = processingDataProvider.getSmithingLevel('rune_platebody');
// Returns: 99

const xp = processingDataProvider.getSmithingXP('rune_platebody');
// Returns: 375

const ticks = processingDataProvider.getSmithingTicks('rune_platebody');
// Returns: 4
```

***

## Cooking API

### Check if Item is Cookable

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const canCook = processingDataProvider.isCookable('raw_shrimp');
// Returns: true
```

### Get Cooking Data

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const data = processingDataProvider.getCookingData('raw_shrimp');
// Returns: {
//   rawItemId: 'raw_shrimp',
//   cookedItemId: 'shrimp',
//   burntItemId: 'burnt_shrimp',
//   levelRequired: 1,
//   xp: 30,
//   stopBurnLevel: { fire: 34, range: 34 }
// }
```

### Get Cooked/Burnt Item IDs

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const cookedId = processingDataProvider.getCookedItemId('raw_shrimp');
// Returns: 'shrimp'

const burntId = processingDataProvider.getBurntItemId('raw_shrimp');
// Returns: 'burnt_shrimp'
```

### Get Stop Burn Level

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const stopBurnFire = processingDataProvider.getStopBurnLevel('raw_shrimp', 'fire');
// Returns: 34

const stopBurnRange = processingDataProvider.getStopBurnLevel('raw_shrimp', 'range');
// Returns: 34
```

***

## Firemaking API

### Check if Log is Burnable

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const canBurn = processingDataProvider.isBurnableLog('oak_logs');
// Returns: true
```

### Get Firemaking Data

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const data = processingDataProvider.getFiremakingData('oak_logs');
// Returns: {
//   logId: 'oak_logs',
//   levelRequired: 15,
//   xp: 60
// }
```

### Get All Burnable Log IDs

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const logIds = processingDataProvider.getBurnableLogIds();
// Returns: Set(['logs', 'oak_logs', 'willow_logs', ...])
```

***

## TierDataProvider

Provides tier-based level requirements for equipment and tools.

### Import

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
import { TierDataProvider } from '@hyperscape/shared';
```

### Get Requirements for Item

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const requirements = TierDataProvider.getRequirements({
  id: 'steel_sword',
  type: 'weapon',
  tier: 'steel',
  equipSlot: 'weapon',
  attackType: 'MELEE'
});
// Returns: { attack: 5 }
```

### Get Tier Data

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const meleeTier = TierDataProvider.getTierData('melee', 'rune');
// Returns: { attack: 40, defence: 40 }

const toolTier = TierDataProvider.getTierData('tools', 'steel');
// Returns: { attack: 5, woodcutting: 6, mining: 6 }
```

### Get Available Tiers

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const tiers = TierDataProvider.getAvailableTiers('melee');
// Returns: ['bronze', 'iron', 'steel', 'mithril', 'adamant', 'rune', 'dragon']
```

### Check if Loaded

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const isLoaded = TierDataProvider.isLoaded();
// Returns: true if tier-requirements.json was loaded
```

***

## StationDataProvider

Provides configuration for world stations (anvils, furnaces, ranges, banks).

### Import

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
import { stationDataProvider } from '@hyperscape/shared';
```

### Get Station Data

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const anvilData = stationDataProvider.getStationData('anvil');
// Returns: {
//   type: 'anvil',
//   name: 'Anvil',
//   model: 'asset://models/anvil/anvil.glb',
//   modelScale: 0.5,
//   modelYOffset: 0.4,
//   examine: 'An anvil for smithing metal bars into weapons and tools.'
// }
```

### Get Model Path

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const modelPath = stationDataProvider.getModelPath('furnace');
// Returns: 'asset://models/furnace/furnace.glb'
```

### Get Model Scale and Offset

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const scale = stationDataProvider.getModelScale('anvil');
// Returns: 0.5

const yOffset = stationDataProvider.getModelYOffset('furnace');
// Returns: 1.0
```

### Get Examine Text

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const examineText = stationDataProvider.getExamineText('range');
// Returns: 'A range for cooking food.'
```

### Check if Station Exists

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const hasStation = stationDataProvider.hasStation('anvil');
// Returns: true
```

### Get All Station Types

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
const types = stationDataProvider.getAllStationTypes();
// Returns: ['anvil', 'furnace', 'range', 'bank']
```

***

## Type Definitions

### SmeltingItemData

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
interface SmeltingItemData {
  barItemId: string;
  primaryOre: string;
  secondaryOre: string | null;
  coalRequired: number;
  levelRequired: number;
  xp: number;
  successRate: number;
  ticks: number;
}
```

### SmithingRecipeData

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
interface SmithingRecipeData {
  itemId: string;
  name: string;
  barType: string;
  barsRequired: number;
  levelRequired: number;
  xp: number;
  category: SmithingCategory;
  ticks: number;
}

type SmithingCategory = 'weapons' | 'armor' | 'tools' | 'misc';
```

### SmithingRecipeWithAvailability

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
interface SmithingRecipeWithAvailability extends SmithingRecipeData {
  meetsLevel: boolean;  // Player has sufficient level
  hasBars: boolean;     // Player has enough bars
}
```

### CookingItemData

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
interface CookingItemData {
  rawItemId: string;
  cookedItemId: string;
  burntItemId: string;
  levelRequired: number;
  xp: number;
  stopBurnLevel: {
    fire: number;
    range: number;
  };
}
```

### FiremakingItemData

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
interface FiremakingItemData {
  logId: string;
  levelRequired: number;
  xp: number;
}
```

### StationData

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
interface StationData {
  type: string;
  name: string;
  model: string | null;
  modelScale: number;
  modelYOffset: number;
  examine: string;
}
```

***

## Performance Considerations

### Pre-allocated Buffers

ProcessingDataProvider uses pre-allocated buffers to avoid allocations in hot paths:

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
// Internal buffer reused for inventory counting
private readonly inventoryCountBuffer = new Map<string, number>();
```

This optimization reduces garbage collection pressure when checking smithable/smeltable items.

### Lazy Initialization

All providers use lazy initialization - they build lookup tables on first access:

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
private ensureInitialized(): void {
  if (!this.isInitialized) {
    this.initialize();
  }
}
```

***

## Related Documentation

* [Manifests](/concepts/manifests) - Manifest file structure
* [Smithing System](/wiki/game-systems/smithing) - Smithing gameplay
* [Skills](/wiki/game-systems/skills) - Skill system overview
* [Database Schema](/wiki/engine/database) - Persistence layer