Chroma Golem API Documentation

Game Systems

Creating Dynamic Crafting Systems

Create dynamic crafting systems that adapt to player skills, world state, and environmental conditions using generative AI to deliver unique gameplay experiences.

What Makes Crafting Systems Special?

Crafting systems are more than just recipe lists - they're core gameplay loops that drive exploration, progression, and mastery.

Player Agency

Crafting empowers players to create exactly what they want instead of hoping for lucky drops. It provides meaningful choices and strategic depth, giving players control over their progression path.

Progression Loop

Crafting creates a virtuous cycle: gather resources, craft items, use those items to gather better resources, craft better items, and so on. This drives long-term engagement and provides a sense of accomplishment.

Emergent Gameplay

AI-powered crafting can create unexpected combinations and discoveries that even game designers didn't anticipate. This emergent quality keeps crafting fresh and exciting, rewarding creative experimentation.

Effective crafting systems balance structured mechanics with player discovery and AI-driven variation to create memorable gameplay experiences.

Quick Start Guide

1
Define Recipe Base

Start with core ingredients and basic crafting requirements

{ "name": "Basic Healing Potion", "base_ingredients": ["herbs", "water"], "difficulty": "novice" }
2
Add Context

Include environment, tools, and player skill levels

{ "environment": "forest", "tools": ["mortar_and_pestle"], "player_skill": 3, "time_of_day": "night" }
3
Generate Results

Let the API determine outcomes and quality levels

{ "result": "Minor Healing Potion", "quality": "standard", "potency": 25, "unique_property": "Glows faintly in dark" }

Complete API Example

// API Request for crafting a potion
POST /v1/chat/completions

{
  "client_id": "player_12345",
  "client_id": "player_12345",
  "messages": [
    {
      "role": "system",
      "content": "You are an alchemical crafting system that determines potion outcomes based on ingredients, environment, tools, and player skill. Provide structured JSON responses with name, quality, effects, appearance, and any special properties."
    },
    {
      "role": "user",
      "content": "Player with Alchemy skill level 3 is crafting a healing potion using: 2 common herbs, 1 rare mountain flower, spring water. They're working at night in a forest grove using basic equipment. Determine the outcome."
    }
  ],
  "response_format": { "type": "json_object" }
}

Key components of crafting systems

Crafting System Architecture

A robust crafting system architecture provides the foundation for all gameplay interactions. This section outlines key components and their relationships to help you design scalable, engaging crafting mechanics.

Core Components of a Crafting System

1. Resource System

  • Gathering mechanics - How players obtain raw materials
  • Resource properties - Qualities that affect crafting outcomes
  • Storage & management - How resources are organized and transported
  • Rarity tiers - Common to legendary classification system

The resource system drives exploration and forms the foundation of your crafting economy.

2. Recipe Framework

  • Recipe structure - Input/output definitions
  • Discovery system - How players learn new recipes
  • Modification rules - How recipes can be customized
  • Quality system - Factors that affect output quality

The recipe framework provides structure while allowing for creativity and progression.

3. Crafting Process

  • Interface design - How players interact with crafting
  • Time & effort costs - What crafting requires beyond materials
  • Skill checks - Success/failure/quality determination
  • Feedback loops - How players improve their crafting

The crafting process determines moment-to-moment engagement and satisfaction.

4. Economy Integration

  • Value determination - How crafted items are priced
  • Market dynamics - Supply/demand effects
  • Specialization - Player roles in crafting ecosystem
  • Progression balance - Crafting power relative to other sources

Economy integration ensures crafting remains relevant throughout the game lifecycle.

Crafting System Flow

Resource Acquisition
Gathering Trading Looting
Resource Inventory & Management
Recipe Knowledge
Known formulas
Crafting Interface
Tools & workspace
Player Skills
Ability levels
Crafting Process
Input Processing Output
AI Integration
Partial Results
Byproducts
Crafted Item
Success outcome
Game Economy & Player Progression

A crafting system connects resource gathering, processing, and economic impacts with AI integration for enhanced gameplay.

Recipe Generation

Generate contextually relevant recipes that dynamically adapt to available materials, player progression, and environmental factors to create a continuously evolving crafting experience.

Recipe Design Principles

Effective recipe design balances structure with flexibility, allowing for creativity while maintaining game balance.

Flexibility Scale

Design recipes on a spectrum from rigid to flexible:

Rigid Recipe Exact ingredients
Category Substitution Same type
Property-Based Any with traits
Fully Dynamic AI-generated

Recipe Structure

Core elements to include in recipe definitions:

  • Base Information: Name, difficulty, category
  • Ingredients: Items, quantities, qualities
  • Process: Steps, timing, tools required
  • Outcomes: Results, quality factors, byproducts
  • Contextual Factors: Environment effects, skill impacts
Design Tip: Include both mandatory and optional ingredients to create flexibility.

Quality Determinants

Factors that affect crafting outcome quality:

Factor Impact
Ingredient Quality High
Player Skill High
Tool Quality Medium
Environment Medium
Time Invested Variable

Advanced Recipe Generation Implementation

Recipe Request

// Complete API implementation with context handling
const generateRecipe = async () => {
  // 1. Collect context from game state
  const playerContext = {
    level: playerData.alchemyLevel,
    location: currentRegion.biomeType,
    availableEquipment: getPlayerEquipment('alchemy'),
    knownRecipes: playerData.recipes.filter(r => r.type === 'alchemy'),
    recentDiscoveries: inventorySystem.getRecentItems(24) // last 24 hours
  };

  // 2. Prepare environmental modifiers
  const environmentalFactors = {
    temperature: weatherSystem.getCurrentTemp(),
    time: gameTime.getCurrentDayPhase(),
    nearby_elements: locationSystem.getNearbyElements(),
    magical_influence: locationSystem.getMagicDensity()
  };

  // 3. Make API request with comprehensive context
  const response = await fetch('https://api.chromagolem.com/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${CONFIG.API_KEY}`
      },
      client_id: playerData.id,
      messages: [
        {
          role: 'system',
          content: `You are an alchemical recipe generator that creates contextually appropriate crafting instructions based on player skills and environmental conditions. Generate a complete recipe with ingredients, process steps, and expected results.`
        },
        {
          role: 'user',
          content: `Create a recipe using recently discovered frost herbs.\n\nPlayer context: ${JSON.stringify(playerContext)}\nEnvironmental factors: ${JSON.stringify(environmentalFactors)}`
        }
      ],
      response_format: { type: 'json_object' }
    })
  });

  // 4. Process and validate the response
  const data = await response.json();
  const validatedRecipe = validateRecipeBalance(data);
  
  // 5. Store in recipe book and return
  if (validatedRecipe.isBalanced) {
    recipeSystem.addToDiscovered(validatedRecipe);
    return validatedRecipe;
  } else {
    return fallbackRecipeSystem.getBalancedAlternative(data);
  }
};

Generated Recipe

{
  "recipe": {
    "name": "Frost Resistance Potion",
    "type": "alchemy_potion",
    "difficulty": "Novice",
    "base_success_rate": 80,
    "ingredients": [
      {
        "item": "Frost Herb",
        "quantity": 2,
        "preparation": "Crushed",
        "quality_requirement": "Fresh",
        "substitutions": [{
          "item": "Winter Bloom",
          "quantity": 3,
          "effect": "Reduced potency (-15%)"
        }]
      },
      {
        "item": "Mountain Spring Water",
        "quantity": 1,
        "preparation": "Chilled",
        "quality_requirement": "Pure",
        "substitutions": [{
          "item": "Clear Stream Water",
          "quantity": 1,
          "effect": "Shorter duration (-20%)"
        }]
      },
      {
        "item": "Crystal Vial",
        "quantity": 1,
        "reusable": true
      }
    ],
    "process": [
      {
        "step": 1,
        "action": "Add chilled water to clean vial",
        "duration": "1 minute",
        "failure_chance": 5,
        "skill_check": {
          "type": "precision",
          "difficulty": 2
        }
      },
      {
        "step": 2,
        "action": "Gradually add crushed frost herbs",
        "duration": "2 minutes",
        "failure_chance": 15,
        "critical_point": true,
        "skill_check": {
          "type": "timing",
          "difficulty": 4
        }
      },
      {
        "step": 3,
        "action": "Stir clockwise while chanting protection words",
        "duration": "30 seconds",
        "skill_check": {
          "type": "focus",
          "difficulty": 3
        }
      }
    ],
    "results": {
      "success": {
        "item": "Frost Resistance Potion",
        "quality_levels": [
          {"name": "Flawed", "threshold": 50, "duration": 180},
          {"name": "Standard", "threshold": 75, "duration": 300},
          {"name": "Superior", "threshold": 90, "duration": 480}
        ],
        "effect": "Provides {potency}% resistance to cold damage for {duration} seconds"
      },
      "partial_success": {
        "item": "Weak Frost Resistance Potion",
        "effect": "Provides 25% resistance to cold damage for 120 seconds"
      },
      "failure": {
        "item": "Murky Substance",
        "effect": "No useful properties"
      },
      "critical_failure": {
        "effect": "Damages vial and wastes ingredients"
      }
    },
    "environmental_effects": {
      "cold_climate": "+10% potency",
      "altitude": "Requires longer brewing time (+30 seconds)",
      "night_time": "+15% duration",
      "heavy_precipitation": "-5% success chance"
    },
    "experience_reward": {
      "base": 25,
      "quality_multiplier": true
    }
  }
}
Implementation Tips
  • Always validate recipes against your game's balance framework before applying them
  • Implement fallback mechanisms for when the API is unavailable or returns unsuitable results
  • Cache frequently generated recipes to reduce API calls and ensure consistency
  • Consider generating variations of recipes rather than completely new ones for better control

Material Properties

Define how different materials interact and contribute to crafting outcomes.

Example Material Analysis

System: Analyze material properties and interactions for crafting.

Material: Ancient Oak Wood
Context: Being used for bow crafting

Response: {
  "material_properties": {
    "base_properties": {
      "flexibility": 85,
      "durability": 90,
      "weight": "Medium",
      "grain_quality": "Excellent"
    },
    "crafting_characteristics": {
      "workability": "Requires seasoned hands",
      "optimal_tools": ["Sharp Carving Knife", "Fine Rasp"],
      "special_treatments": ["Steam bending possible", "Takes well to natural finishes"]
    },
    "environmental_factors": {
      "humidity": {
        "effect": "Affects flexibility",
        "optimal_range": "40-60%"
      },
      "temperature": {
        "effect": "Impacts workability",
        "optimal_range": "18-24°C"
      }
    },
    "quality_indicators": [
      "Straight, tight grain patterns",
      "No visible knots in working area",
      "Rich, even coloring"
    ]
  }
}

Tool Interactions

Create meaningful interactions between tools and resources in your harvesting system.

Example Tool Interaction

System: Determine the outcome of using a tool on a resource node.

Context:
- Tool: Enchanted Mining Pick
- Resource: Gold Vein
- Player Mining Skill: 7
- Environmental Conditions: Underground, Well-Lit

Response: {
  "interaction_result": {
    "success": true,
    "yield": [
      {
        "item": "Gold Ore",
        "quantity": 3,
        "quality": "High",
        "bonus_from": ["tool_enchantment", "skill_level"]
      },
      {
        "item": "Raw Gem",
        "quantity": 1,
        "quality": "Normal",
        "source": "lucky_strike"
      }
    ],
    "tool_impact": {
      "durability_loss": 2,
      "enchantment_proc": "Minor vein revelation",
      "maintenance_needed": false
    },
    "skill_experience": {
      "base": 25,
      "bonus": 5,
      "reason": "Clean extraction"
    },
    "node_state": {
      "depletion": 35,
      "regeneration_time": "3 game days",
      "quality_remaining": "High"
    }
  }
}

Player Engagement Strategies

Exceptional crafting systems drive long-term player engagement by integrating thoughtfully designed progression paths, discovery mechanics, and mastery opportunities that evolve throughout the player journey.

Engagement Pillars

1

Meaningful Progression

Players need to feel their crafting skills are growing and opening new possibilities.

Skill Tiers

Define clear progression tiers that unlock new recipe categories and abilities

Tool Upgrades

Create meaningful tool progression that expands crafting possibilities

Specialization Paths

Allow players to develop expertise in specific crafting disciplines

2

Discovery & Experimentation

Crafting should reward curiosity and creative thinking.

Experimentation System Design
Do
  • Reward failed experiments with hints
  • Create "almost right" states that guide players
  • Log discoveries automatically
  • Make experimentation affordable
Don't
  • Make failure too punishing
  • Hide critical recipes behind extreme RNG
  • Require external guides to discover basics
  • Force trial-and-error without feedback
3

Social & Economic Integration

Connect crafting to the broader game world and player community.

Single Player
  • NPC recognition of crafting skill
  • Crafted items affect world state
  • Story integration of crafting ability
  • Crafting-specific quests & challenges
Multiplayer
  • Player trading of crafted items
  • Reputation systems for master crafters
  • Collaborative crafting for special items
  • Guild/community crafting projects
Player Motivations

Different players engage with crafting for different reasons. A well-designed system addresses multiple motivations:

  • Achievers: Seek to master all recipes and create the highest quality items
  • Explorers: Enjoy discovering hidden recipes and unexpected combinations
  • Socializers: Value crafting as a way to help friends and gain recognition
  • Competitors: Want to craft better/faster/more valuable items than others

Discovery Systems

Create engaging systems for players to discover and learn new crafting techniques.

Example Recipe Discovery

System: Generate discovery event for experimental crafting attempt.

Player Action: Combining Moonflower and Silver Dust in a mortar
Context: Full moon night, near magical shrine

Response: {
  "discovery_event": {
    "result": "New Recipe Discovered",
    "recipe": {
      "name": "Moonlight Essence",
      "type": "Magical Reagent",
      "difficulty": "Intermediate",
      "learned_details": {
        "known_steps": [
          "Grind under moonlight",
          "Components must be equal parts"
        ],
        "hidden_steps": [
          "Requires magical focal point nearby",
          "Temperature affects potency"
        ]
      }
    },
    "unlocked_hints": [
      "The mixture glows faintly - perhaps useful in illumination recipes",
      "The full moon seems to strengthen the reaction"
    ],
    "research_directions": [
      "Experiment with different lunar phases",
      "Try varying grinding techniques"
    ]
  }
}

Discovery Methods

  • Experimentation: Trial and error with materials
  • Research: Finding and studying recipes
  • Mentorship: Learning from NPCs

Learning Progression

  • Basic Understanding: Core recipe elements
  • Refinement: Quality improvements
  • Mastery: Recipe modifications

AI Integration Approaches

Generative AI transforms static crafting systems into adaptive, personalized experiences that respond intelligently to player actions. This section outlines strategic integration approaches that balance AI creativity with gameplay consistency.

Strategic AI Integration

Integrate AI where it adds the most value to your crafting experience while maintaining consistent gameplay:

High-Value AI Applications

  • 1
    Recipe Discovery

    Generate unique recipes based on available materials, player skills, and world context

  • 2
    Dynamic Results

    Create varied outcomes even when using the same recipe based on execution quality and conditions

  • 3
    Flavor & Description

    Generate rich descriptions and lore for crafted items that reflect their creation process

  • 4
    Contextual Adaptation

    Adjust crafting outcomes based on location, weather, time of day, or narrative events

AI Implementation Strategy

Integration Models
AI-First

AI drives core crafting experiences

Hybrid

AI enhances traditional systems

AI-Optional

AI for special cases only

Technical Approaches
  • Client-Side Generation - Pre-generated recipes with client-side variation
  • Server-Side API - Real-time API calls for dynamic content
  • Batch Generation - Regular updates with new AI-generated content
  • Hybrid Cache - Combine pre-generated content with live generation

Example API Implementation: Dynamic Recipe Generation

// API Request for crafting recipe generation
POST /v1/chat/completions

{
  "api_key": "your_api_key",
  "client_id": "player_12345",
  "messages": [
    {
      "role": "system",
      "content": "You are a crafting recipe generator for a fantasy RPG. Generate appropriate recipes based on available materials and player context. Format output as structured JSON with the following fields: name, difficulty, ingredients (array), process (array of steps), results (object with success and failure outcomes)."
    },
    {
      "role": "user",
      "content": "Player is a level 7 alchemist in a coastal region. They have collected seaweed, phosphorescent algae, and a strange crystal from an underwater cave. They want to create something useful for night exploration. Their alchemy lab has basic equipment."
    }
  ],
  "response_format": { "type": "json_object" }
}

Best Practices & Real-World Examples

Leverage industry-tested implementation patterns and avoid common design pitfalls by studying real-world examples with demonstrable success metrics and practical lessons learned.

Case Study: Wildcraft Legends

An open-world survival crafting game that uses AI to create a dynamic crafting experience that adapts to player choices and environmental conditions.

What They Did Right

The game implemented a multi-layer crafting system that combines traditional recipes with AI-driven discovery and adaptation:

Contextual Recipe Adaptation

Base recipes adapt to available materials, player location, and weather conditions. For example, cooking times vary based on altitude, and certain ingredients can be substituted based on local availability.

Layered Discovery System

Players first learn basic recipes through NPC mentoring, then discover variations through experimentation, and finally unlock completely new recipes by combining materials in creative ways.

Memory & Learning Mechanics

The system remembers player crafting patterns and gradually improves results when players craft similar items repeatedly, simulating skill development through practice.

Performance Optimization

The game uses a hybrid approach, with common recipes handled client-side and unique discoveries processed through API calls, with results cached for similar future attempts.

Key Metric: Average player engagement with the crafting system is 37% higher than industry standard, with 82% of players regularly experimenting with new combinations.

Implementation Challenges

Despite overall success, the development team encountered several challenges:

Initial Balance Issues

Early versions of the system allowed players to discover overpowered recipes that disrupted progression. Solution: Implemented multi-stage validation and power scaling based on player level and material rarity.

Performance Bottlenecks

API calls for every crafting attempt created latency and cost issues. Solution: Implemented smart caching system and pre-generated common variations, reserving live generation for truly novel combinations.

System Architecture Summary

Component Implementation AI Integration Level
Base Recipes Static templates with variation points Low - Parameter substitution
Recipe Discovery Pattern matching + API calls High - Creates new recipes
Outcome Generation Hybrid system with quality tiers Medium - Enhances preset results
Description & Lore Full API generation High - Complete generation

Do ✓

  • Consider environmental effects

    Design recipes that adapt to location, weather, and time factors for immersive gameplay

  • Scale difficulty with skill

    Provide clear progression paths that unlock new possibilities as player skill increases

  • Reward experimentation

    Create discovery mechanics that encourage players to try new combinations and approaches

  • Blend procedural with handcrafted

    Combine AI-generated content with designer-created content for the best balance

Don't ✗

  • Make recipes too rigid

    Avoid exact-match-only systems that frustrate players when materials are slightly different

  • Ignore tool quality impact

    Tools should meaningfully affect crafting outcomes, not just be checkbox requirements

  • Neglect failure states

    Design interesting partial successes and informative failures instead of binary success/fail outcomes

  • Rely exclusively on AI generation

    Always implement fallback systems and validation to ensure consistent player experience

Performance Optimization

Scale your AI-powered crafting system to support thousands of concurrent players while maintaining responsiveness and cost-efficiency. These proven optimization strategies help you balance performance demands with generation quality.

Core Optimization Strategies

Smart Caching

Implement multi-level caching to minimize API calls and ensure consistent performance.

  • Cache entire recipes for common ingredient combinations
  • Cache partial results for recipe components
  • Implement LRU (Least Recently Used) cache eviction
  • Add variation to cached results to maintain freshness
// Multi-tier recipe caching system
class RecipeCache {
  constructor(options = {}) {
    this.exactCache = new LRUCache({
      max: options.exactCacheSize || 1000,
      ttl: options.exactCacheTTL || 3600000 // 1 hour
    });
    
    this.similarCache = new LRUCache({
      max: options.similarCacheSize || 5000,
      ttl: options.similarCacheTTL || 86400000 // 24 hours
    });
  }
  
  async getRecipe(ingredients, context) {
    // Check for exact match
    const cacheKey = this.createCacheKey(ingredients, context);
    if (this.exactCache.has(cacheKey)) {
      const cached = this.exactCache.get(cacheKey);
      return this.addVariation(cached, 0.05); // Small variations
    }
    
    // Check for similar recipes
    const similarKey = this.findSimilarRecipeKey(ingredients, context);
    if (similarKey) {
      const similar = this.similarCache.get(similarKey);
      return this.adaptSimilarRecipe(similar, ingredients, context);
    }
    
    // Generate new recipe
    const recipe = await this.generateNewRecipe(ingredients, context);
    
    // Store in cache
    this.exactCache.set(cacheKey, recipe);
    this.updateSimilarCache(recipe, ingredients, context);
    
    return recipe;
  }
}

Batch Processing

Leverage batch operations to amortize API costs and optimize throughput.

  • Pre-generate recipes during off-peak hours
  • Create recipe pools for different contexts and environments
  • Generate recipes in bulk when player behavior is predictable
  • Implement priority queues for recipe generation
// Batch recipe generation service
class BatchRecipeService {
  constructor() {
    this.recipeQueue = [];
    this.processingBatch = false;
    this.recipePool = new Map(); // Environment -> recipes
    
    // Process queue every 30 seconds
    setInterval(() => this.processBatchIfNeeded(), 30000);
  }
  
  queueRecipeGeneration(parameters, priority = 'normal') {
    this.recipeQueue.push({
      parameters,
      priority,
      timestamp: Date.now()
    });
    
    // Process immediately if high priority
    if (priority === 'high' && !this.processingBatch) {
      this.processBatch();
    }
  }
  
  async processBatch() {
    if (this.recipeQueue.length === 0) return;
    if (this.processingBatch) return;
    
    this.processingBatch = true;
    
    try {
      // Sort by priority and timestamp
      this.recipeQueue.sort((a, b) => {
        const priorityValues = {
          'high': 0,
          'normal': 1,
          'low': 2
        };
        
        return priorityValues[a.priority] - priorityValues[b.priority] || 
               a.timestamp - b.timestamp;
      });
      
      // Take up to 50 items
      const batch = this.recipeQueue.splice(0, 50);
      
      // Process each group by context
      const contextGroups = this.groupByContext(batch);
      for (const [context, items] of contextGroups) {
        await this.processContextGroup(context, items);
      }
    } finally {
      this.processingBatch = false;
    }
  }
}

Tiered Generation

Implement a tiered approach to recipe generation based on player needs and expectations.

  • Use templates for common recipes
  • Reserve complex generation for special or unique items
  • Scale generation complexity with recipe importance
  • Combine template-based and AI generation approaches
// Tiered recipe generation strategy
class TieredGenerator {
  constructor() {
    this.templateEngine = new RecipeTemplateEngine();
    this.parameterGenerator = new ParameterizedGenerator();
    this.aiGenerator = new AIRecipeGenerator();
    
    // Define tiers and their processing rules
    this.tiers = {
      basic: {
        description: 'Common recipes with minor variations',
        method: 'template',
        complexityThreshold: 0.3,
        cacheTTL: 86400000 // 24 hours
      },
      standard: {
        description: 'Uncommon recipes with moderate variation',
        method: 'parameterized',
        complexityThreshold: 0.6,
        cacheTTL: 3600000 // 1 hour
      },
      premium: {
        description: 'Rare recipes with significant uniqueness',
        method: 'hybrid',
        complexityThreshold: 0.8,
        cacheTTL: 300000 // 5 minutes
      },
      legendary: {
        description: 'Unique recipes with maximum creativity',
        method: 'full_ai',
        complexityThreshold: 1.0,
        cacheTTL: null // No caching
      }
    };
  }
  
  async generateRecipe(request) {
    const tier = this.determineRecipeTier(request);
    const tierConfig = this.tiers[tier];
    
    // Generate based on tier method
    switch (tierConfig.method) {
      case 'template':
        return this.templateEngine.generate(request);
      case 'parameterized':
        return this.parameterGenerator.generate(request);
      case 'hybrid': {
        const baseRecipe = this.parameterGenerator.generate(request);
        return this.aiGenerator.enhance(baseRecipe, request);
      }
      case 'full_ai':
        return this.aiGenerator.generate(request);
      default:
        throw new Error(`Unknown generation method: ${tierConfig.method}`);
    }
  }
}

Client-Side Optimizations

Improve perceived performance with client-side techniques

1

Predictive Loading

Pre-generate recipes based on likely player actions

// Anticipate player crafting needs
function predictNextCraft(player) {
  // Look at inventory to detect potential recipes
  const potentialRecipes = matchInventoryToRecipes(
    player.inventory, 
    recipeDatabase
  );
  
  // Check player behavior patterns
  const historicalPattern = playerBehaviorModel.predict(
    player.id, 
    player.currentActivity,
    player.recentActions
  );
  
  // Pre-load most likely recipes
  for (const recipe of potentialRecipes) {
    if (recipe.probability > 0.4) {
      recipeCache.preload(recipe.ingredients, {
        playerLevel: player.level,
        location: player.location
      });
    }
  }
}
2

Progressive Loading

Display crafting results in stages to improve perceived performance

// Progressive recipe reveal
function progressiveRecipeReveal(ingredients) {
  // Immediately show basic recipe structure
  const baseTemplate = getBaseTemplate(ingredients);
  UI.showRecipeStructure(baseTemplate);
  
  // Quickly show quality and basic properties
  setTimeout(() => {
    const qualityEstimate = estimateQuality(ingredients);
    UI.updateRecipeQuality(qualityEstimate);
  }, 100);
  
  // Show detailed properties as they're calculated
  setTimeout(() => {
    const properties = calculateBasicProperties(ingredients);
    UI.updateRecipeProperties(properties);
  }, 250);
  
  // Make full API call for complete recipe
  requestAnimationFrame(async () => {
    const fullRecipe = await generateCompleteRecipe(ingredients);
    UI.finalizeRecipe(fullRecipe);
  });
}
3

Offline Support

Enable crafting even when connectivity is limited

// Offline-first crafting system
const craftingSystem = {
  async craftItem(ingredients, context) {
    // Check online status
    if (navigator.onLine) {
      try {
        // Try online crafting with timeout
        const result = await Promise.race([
          onlineCraftingService.craft(ingredients, context),
          new Promise((_, reject) => 
            setTimeout(() => reject('timeout'), 3000)
          )
        ]);
        
        // Cache successful result
        offlineRecipeCache.store(
          createCacheKey(ingredients, context),
          result
        );
        
        return result;
      } catch (error) {
        console.log('Falling back to offline crafting');
        // Fall through to offline crafting
      }
    }
    
    // Offline crafting logic
    return offlineCraftingEngine.craftItem(
      ingredients,
      context
    );
  }
};

Server-Side Optimizations

Scale efficiently on the backend

Request Pooling

Combine similar requests to reduce API costs

// Request pooling service
class RequestPoolingService {
  constructor() {
    this.requestQueue = new Map();
    this.processingInterval = 50; // ms
    this.batchSize = 5;
    
    setInterval(() => this.processQueue(), this.processingInterval);
  }
  
  async generateRecipe(ingredients, context) {
    return new Promise((resolve) => {
      const requestId = uuidv4();
      const poolKey = this.createPoolKey(ingredients, context);
      
      if (!this.requestQueue.has(poolKey)) {
        this.requestQueue.set(poolKey, []);
      }
      
      this.requestQueue.get(poolKey).push({
        requestId,
        ingredients,
        context,
        resolve
      });
    });
  }
  
  async processQueue() {
    // Process batches from the queue
    for (const [poolKey, requests] of this.requestQueue.entries()) {
      if (requests.length === 0) continue;
      
      // Take batch from front of queue
      const batch = requests.splice(0, this.batchSize);
      if (requests.length === 0) {
        this.requestQueue.delete(poolKey);
      }
      
      // Process this batch
      this.processBatch(poolKey, batch);
    }
  }
  
  async processBatch(poolKey, batch) {
    if (batch.length === 1) {
      // Single request - process normally
      const req = batch[0];
      const result = await apiClient.generateRecipe(
        req.ingredients,
        req.context
      );
      req.resolve(result);
      return;
    }
    
    // Multiple similar requests - batch process
    try {
      // Create a combined prompt that covers all requests
      const combinedRequest = this.createCombinedRequest(batch);
      const results = await apiClient.batchGenerateRecipes(
        combinedRequest
      );
      
      // Distribute results back to individual requesters
      this.distributeBatchResults(batch, results);
    } catch (error) {
      // Fall back to individual processing on error
      for (const req of batch) {
        try {
          const result = await apiClient.generateRecipe(
            req.ingredients,
            req.context
          );
          req.resolve(result);
        } catch (innerError) {
          req.resolve(this.getFallbackRecipe(
            req.ingredients, req.context
          ));
        }
      }
    }
  }
}

Database Optimization

Efficiently store and retrieve recipe data

  • Index frequently queried recipe attributes
  • Use denormalized data structures for recipe templates
  • Implement ingredient-based lookup tables
  • Cache frequently accessed recipe collections

Load Distribution

Balance crafting workloads across server resources

Time-based request scheduling
Location-based server routing
Recipe complexity-based worker allocation
Player priority tiers for resource allocation

Performance Benchmarks & Targets

Metric Target Warning Critical Optimization Tips
Response Time < 300ms 300ms - 1s > 1s Use caching, reduce prompt size, template simple recipes
API Calls / Player / Hour < 10 10 - 30 > 30 Implement request batching, predictive caching, tiered generation
Cache Hit Rate > 80% 50% - 80% < 50% Optimize cache key generation, improve cache warming strategies
Cost / 1000 Recipes < $0.50 $0.50 - $2.00 > $2.00 Use tiered generation, implement batch processing
Concurrent Crafting Sessions > 1000 200 - 1000 < 200 Optimize database queries, implement request pooling

* Benchmarks based on production data from games with 50,000+ monthly active users

Pro tip: Use our Analytics Dashboard to monitor your crafting system performance in real-time and identify optimization opportunities.

Troubleshooting & Common Issues

Navigate the unique challenges of AI-driven crafting systems with practical solutions to common implementation issues. This comprehensive troubleshooting guide addresses technical, design, and player experience concerns.

Generation Issues

Inconsistent Recipe Quality

AI-generated recipes show significant variance in quality and balance.

Solution:
  • Implement multi-stage validation for all generated recipes
  • Define clear quality tiers with specific attribute ranges
  • Use template recipes as starting points for generation
  • Create fallback systems for when generation quality falls below thresholds
// Recipe validation pipeline
function validateRecipe(generatedRecipe) {
  const validationStages = [
    balanceValidator,  // Check if attributes are within game balance
    coherenceValidator, // Check internal recipe consistency
    economyValidator   // Check impact on game economy
  ];
  
  let currentRecipe = generatedRecipe;
  let issues = [];
  
  for (const validator of validationStages) {
    const {isValid, adjustedRecipe, validationIssues} = 
      validator(currentRecipe);
    
    if (!isValid) issues.push(...validationIssues);
    currentRecipe = adjustedRecipe || currentRecipe;
  }
  
  return {
    recipe: currentRecipe,
    isValid: issues.length === 0,
    issues
  };
}

Unbalanced Recipes

AI generates recipes that are too powerful or too weak for their intended level.

Solution:
  • Implement specific power curve formulas for each recipe tier
  • Create comparative analysis against baseline items
  • Scale rewards and difficulty proportionately
  • Set clear attribute min/max ranges by player level
// Power scaling by level
function calculateRecipePower(recipe, playerLevel) {
  const basePower = POWER_TIERS[recipe.tier];
  const levelScaling = 1 + (playerLevel * 0.085);
  const qualityMultiplier = QUALITY_MULTIPLIERS[recipe.quality];
  
  // Calculate expected power for this level and quality
  const expectedPower = basePower * levelScaling * qualityMultiplier;
  const actualPower = calculateActualPower(recipe); // Your power calculation
  
  // If power deviation exceeds threshold, adjust
  if (Math.abs(actualPower - expectedPower) / expectedPower > 0.2) {
    return adjustRecipePower(recipe, expectedPower);
  }
  
  return recipe;
}

System Integration

Performance Bottlenecks

API calls for complex crafting operations create noticeable delays.

Solution:
  • Implement client-side caching for common recipes
  • Use batch generation during game loading screens
  • Create a tiered generation system based on recipe complexity
  • Generate variations of base recipes instead of from scratch
// Tiered generation with caching
class RecipeGenerator {
  constructor() {
    this.recipeCache = new Map();
    this.generationQueue = [];
    this.isGenerating = false;
  }
  
  async getRecipe(ingredients, context) {
    const cacheKey = this.createCacheKey(ingredients, context);
    
    // Check cache first
    if (this.recipeCache.has(cacheKey)) {
      const cachedRecipe = this.recipeCache.get(cacheKey);
      // Create small variations in non-critical attributes
      return this.createVariation(cachedRecipe);
    }
    
    // Determine generation complexity
    const complexity = this.calculateComplexity(ingredients);
    
    if (complexity === 'simple') {
      // Generate immediately using templates
      return this.generateFromTemplate(ingredients, context);
    } else {
      // Queue complex generations
      return new Promise((resolve) => {
        this.generationQueue.push({
          ingredients,
          context,
          resolve,
          complexity
        });
        
        if (!this.isGenerating) {
          this.processQueue();
        }
      });
    }
  }
}

Inconsistent JSON Responses

AI responses sometimes deviate from expected schema formats.

Solution:
  • Implement robust schema validation for all responses
  • Create normalization functions to standardize fields
  • Build fallback response templates for parsing failures
  • Use more specific prompts with explicit format examples
// Schema validation and normalization
function processApiResponse(response) {
  try {
    // Parse JSON response
    const data = JSON.parse(response);
    
    // Validate against expected schema
    const validationResult = validateSchema(data, RECIPE_SCHEMA);
    
    if (validationResult.valid) {
      // Normalize field formats
      return normalizeRecipeData(data);
    } else {
      console.error('Schema validation failed:', validationResult.errors);
      // Attempt to fix common issues
      const fixedData = attemptSchemaFix(data, validationResult.errors);
      return fixedData || generateFallbackRecipe();
    }
  } catch (error) {
    console.error('Failed to parse response:', error);
    return generateFallbackRecipe();
  }
}

Player Experience

Recipe Discovery Issues

Players struggle to find or understand dynamic crafting mechanics.

Solution:
  • Implement progressive discovery with clear in-game hints
  • Create "almost success" states that guide players closer to recipes
  • Add a recipe journal that records partial discoveries
  • Design mentor NPCs that provide crafting guidance
// Progressive hint system
function evaluateCraftingAttempt(ingredients, targetRecipe) {
  // Calculate similarity to known recipes
  const matches = knownRecipes.map(recipe => ({
    recipe,
    similarity: calculateSimilarity(ingredients, recipe.ingredients)
  }));
  
  // Sort by similarity
  matches.sort((a, b) => b.similarity - a.similarity);
  const bestMatch = matches[0];
  
  // Determine hint type based on similarity
  if (bestMatch.similarity > 0.8) {
    return {
      result: 'almost',
      message: `You're very close! The recipe needs a ${getMissingIngredientType(bestMatch.recipe, ingredients)}`,
      discovery: addRecipeProgress(bestMatch.recipe.id, 0.2)
    };
  } else if (bestMatch.similarity > 0.5) {
    return {
      result: 'promising',
      message: `You're on the right track. The recipe requires ${getCategoryHint(bestMatch.recipe)}`,
      discovery: addRecipeProgress(bestMatch.recipe.id, 0.1)
    };
  } else {
    return {
      result: 'experimental',
      message: getRandomEncouragement(),
      discovery: recordExperiment(ingredients)
    };
  }
}

Repetitive or Generic Recipes

AI generates similar recipes despite different inputs or contexts.

Solution:
  • Track previously generated recipes for each player
  • Use diversity parameters to encourage unique results
  • Create themed recipe generation based on environment
  • Implement content diversity tracking across recipe database
// Diversity tracking for recipe generation
class RecipeDiversifier {
  constructor(userId) {
    this.userId = userId;
    this.generatedHistory = loadUserRecipeHistory(userId);
    this.attributeFrequency = this.analyzeAttributeFrequency();
  }
  
  prepareGenerationContext(baseContext) {
    // Calculate which attributes are overrepresented
    const overrepresentedAttributes = this.getOverrepresentedAttributes();
    
    // Calculate which attributes are underrepresented
    const underrepresentedAttributes = this.getUnderrepresentedAttributes();
    
    // Add diversity guidance to generation context
    return {
      ...baseContext,
      diversityGuidance: {
        avoidAttributes: overrepresentedAttributes,
        emphasizeAttributes: underrepresentedAttributes,
        recentThemes: this.getRecentThemes(5), // Last 5 themes to avoid
        playerPreferences: this.getPlayerPreferenceModel()
      }
    };
  }
  
  recordGenerated(recipe) {
    this.generatedHistory.push({
      recipeId: recipe.id,
      timestamp: Date.now(),
      attributes: extractRecipeAttributes(recipe)
    });
    
    this.updateAttributeFrequency(recipe);
    saveUserRecipeHistory(this.userId, this.generatedHistory);
    updateGlobalRecipeStats(recipe);
  }
}

Technical Implementation

API Cost Optimization

Frequent API calls for crafting become expensive at scale.

Solution:
  • Implement tiered generation based on recipe importance
  • Use client-side generation for common recipes
  • Batch generate recipes during server maintenance
  • Create parameter-driven templates for simple recipes
// Cost-optimized recipe generation strategy
class CostOptimizedGenerator {
  constructor(config) {
    this.apiClient = new ApiClient(config.apiKey);
    this.templateEngine = new RecipeTemplateEngine();
    this.recipeDatabase = new RecipeDatabase();
    this.batchQueue = [];
    this.costBudget = config.dailyBudget || 10.0; // Default $10/day
    this.costTracking = loadCostTracking();
  }
  
  async getRecipe(parameters) {
    // Check if we're over budget
    if (this.isOverBudget()) {
      return this.generateFromTemplate(parameters);
    }
    
    // Determine generation tier
    const tier = this.calculateGenerationTier(parameters);
    
    switch (tier) {
      case 'template': // ~0% of API budget - use templates
        return this.generateFromTemplate(parameters);
        
      case 'hybrid': // ~30% of API budget - enhance templates
        const baseRecipe = this.generateFromTemplate(parameters);
        return this.enhanceWithApi(baseRecipe, 'low_detail');
        
      case 'important': // ~60% of API budget - full generation
        return this.generateWithApi(parameters, 'standard_detail');
        
      case 'critical': // ~10% of API budget - premium generation
        return this.generateWithApi(parameters, 'high_detail');
    }
  }
  
  batchGenerateRecipes() {
    // Process queue during off-peak hours
    if (this.batchQueue.length === 0) return;
    
    console.log(`Batch generating ${this.batchQueue.length} recipes`);
    // Implementation details...
  }
}

Error Handling & Fallbacks

API failures or timeouts disrupt the crafting experience.

Solution:
  • Implement comprehensive error handling with fallbacks
  • Create an offline mode with pre-generated recipes
  • Use exponential backoff for retry attempts
  • Design graceful degradation to simpler crafting systems
// Robust error handling with fallbacks
async function craftItem(ingredients, context) {
  const MAX_RETRIES = 3;
  let retries = 0;
  let backoffTime = 1000; // Start with 1s backoff
  
  while (retries < MAX_RETRIES) {
    try {
      // Attempt API generation
      const response = await recipeGenerator.generateRecipe(ingredients, context);
      return processSuccessfulCraft(response);
    } catch (error) {
      console.error(`Crafting failed (attempt ${retries + 1}):`, error);
      retries++;
      
      if (error.type === 'network_error' && retries < MAX_RETRIES) {
        // Network error - use exponential backoff
        await sleep(backoffTime);
        backoffTime *= 2; // Exponential backoff
        continue;
      } else if (error.type === 'timeout') {
        // Timeout - try simplified request
        return await fallbackGenerator.generateSimplified(ingredients, context);
      } else {
        // Other errors - use offline fallback
        return offlineCraftingSystem.craft(ingredients);
      }
    }
  }
  
  // All retries failed - use deterministic template
  return deterministicCrafting.craft(ingredients);
}

Monitoring & Improvement

Key Metrics to Track

Recipe generation success rate
Average generation time
Fallback system usage frequency
Player satisfaction with crafting outcomes
Recipe uniqueness/diversity score

Continuous Improvement

  • Collect player feedback on generated recipes
  • Use A/B testing to compare different generation strategies
  • Implement a feedback loop to improve generation prompts
  • Regularly audit recipe balance across your economy
  • Monitor API costs and optimize generation frequency

Real-world Impact

A medium-sized MMORPG implemented these troubleshooting strategies and saw:

  • 70% reduction in crafting system errors
  • 35% increase in player engagement with crafting
  • 58% decrease in API costs through optimized requests
  • 91% increase in unique recipes generated per month

Top reported improvements:

Crafting reliability 85%
Recipe diversity 78%
System performance 92%

Want to learn more?

Check out our guides on creating items and building NPCs.

Back to your dashboard
View my API keys