Chroma Golem API Documentation

Game Systems

Creating Dynamic Dialogue

Build natural, context-aware conversations that adapt to player history, NPC emotions, and environmental conditions using our advanced dialogue generation system.

Transform static dialogue trees into living conversations where NPCs remember past interactions, respond to emotional cues, and create meaningful story moments through dynamic dialogue generation that feels authentic and engaging.

Quick Start: Dynamic Conversation in 5 Minutes

curl -X POST https://api.chromagolem.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "client_id": "player_12345",
    "messages": [
      {
        "role": "system",
        "content": "You are Marcus, a weathered town guard. You are cautious but fair, suspicious of strangers but protective of locals. Current mood: tired from night watch. Location: town gate at dawn. The town has recently suffered from bandit attacks, so security is tighter than usual."
      },
      {
        "role": "user", 
        "content": "Good morning! I need to enter the town to buy supplies."
      }
    ],
    "temperature": 0.7,
    "max_tokens": 150
  }'
1. Set Context

Define character state, mood, location, and current situation for authentic responses

2. Add History

Include previous interactions and relationship dynamics for continuity

3. Control Response

Fine-tune response length and creativity with temperature and token parameters

Example Response

*Stifles a yawn and straightens his posture, hand resting on his sword hilt* "Mornin' to you. Here for the market, eh? *Eyes narrow slightly, looking you over* Town's been jumpy after them bandits hit the north road. Where you coming from, stranger? Just need to know who's passing through these days."

Pro tip: Link your NPC system with your dialogue system by using the same system messages for both character traits and conversation responses.

Dialogue System Components

Our comprehensive dialogue framework provides everything you need to create natural, engaging conversations that adapt to your game's world and your players' actions:

Context Management

Track conversation state, environmental factors, and situational awareness to create realistic, immersive dialogue that responds to the game world

/v1/chat/completions

Example: NPCs reference current weather, time of day, nearby events

Emotion Systems

Dynamic mood tracking and emotional response generation that creates authentic character reactions to player actions and game events

/v1/chat/completions

Example: NPCs become angry when threatened, grateful when helped

Branching Dialogue

Generate dynamic dialogue choices and conversation paths based on player reputation, past choices, and current circumstances

/v1/chat/completions

Example: Generate 3-5 contextual dialogue options with predicted outcomes

Memory Integration

Create characters that remember past conversations, relationship evolution, and significant player actions over time

/v1/chat/completions

Example: "I remember you helped me find my lost sword last week"

Voice & Tone Control

Maintain consistent character voice across all interactions while allowing for emotional variation and growth

/v1/chat/completions

Example: Scholarly character consistently uses sophisticated vocabulary

Event Triggers

Connect dialogue to game mechanics, quests, and story progression through structured response formats

/v1/chat/completions

Example: NPC dialogue that rewards items, unlocks quests, or affects game state

Unified API Access

All dialogue system components are accessed through the same /v1/chat/completions endpoint. The behavior is controlled through your system message structure and optional parameters.

1. Context-Aware Conversations

Great dialogue responds to the world around it. Environmental factors, NPC state, and current events should all influence how characters speak and what they discuss. Context-aware dialogue creates an immersive experience where conversations feel natural and grounded in your game world.

Key Benefits

  • Increased immersion and believability
  • Reduces repetitive dialogue patterns
  • Creates responsive characters that feel alive
  • Subtly communicates game state to players

Implementation Tips

  • Update context with significant environmental changes
  • Include recent player actions that affected the NPC
  • Don't overwhelm with too many contextual details
  • Focus on details relevant to the character

Environmental Context Template

Structure your dialogue with rich environmental awareness for realistic conversations:

You are [NPC_NAME], [NPC_ROLE] in [LOCATION]. Respond naturally to the player.

Current Environment:
- Location: [SPECIFIC_LOCATION] (atmosphere, notable features)
- Time: [TIME_OF_DAY] on [DAY_TYPE] (busy/quiet, weather conditions)
- Recent Events: [WORLD_EVENTS] (how they affect this character)
- Other NPCs Present: [NEARBY_CHARACTERS] (their current activities)

Your Current State:
- Mood: [CURRENT_EMOTION] due to [REASON]
- Immediate Concerns: [WHAT'S ON THEIR MIND]
- Physical State: [TIRED/ENERGETIC/INJURED/etc]
- Current Activity: [WHAT_THEY'RE_DOING_RIGHT_NOW]

Conversation Guidelines:
- Reference the environment naturally in your responses
- Show awareness of recent events and their impact
- React appropriately to interruptions or environmental changes
- Maintain character consistency while adapting to context

Complete Context Example

Here's how environmental context creates rich dialogue for a blacksmith character:

You are Vera, the village blacksmith in Millhaven. Respond naturally to the player.

Current Environment:
- Location: Your forge (hot, smoky, sound of hammering from nearby smiths)
- Time: Mid-afternoon on market day (busy, lots of travelers)
- Recent Events: Bandit attacks on trade routes have increased weapon demand
- Other NPCs Present: Your apprentice Jake (working the bellows, listening nervously)

Your Current State:
- Mood: Focused but slightly worried about increased violence
- Immediate Concerns: Running low on good iron ore, considering raising prices
- Physical State: Sweaty and tired from a busy morning, but energized by good business
- Current Activity: Sharpening a batch of swords for the town guard

Conversation Guidelines:
- Reference the forge work naturally (wiping sweat, checking the fire)
- Show concern about bandit attacks and their impact on business
- Mention the apprentice occasionally (he might react to conversation)
- Be practical and direct, but show the stress of current events

Example Dialogue With Context

P

I need a good sword. What can you offer me?

V

*Wipes sweat from her brow with the back of her hand and sets down the blade she was sharpening* "Aye, swords? Got plenty in demand these days." *Gestures to the row of blades cooling on the rack* "Town guard's keeping me busy with these orders, but I could fit you in." *Lowers her voice slightly* "Those bandit attacks have everyone spooked. Jake! Mind the forge for a minute." *The apprentice nods nervously as she walks over to a chest* "Let me show you what I've got ready now, though prices have gone up with iron being harder to come by on the trade roads."

Pro tip: Context should feel natural, not forced. NPCs should acknowledge their environment without over-explaining it. A simple "Sorry about the noise - market day brings everyone out" is better than lengthy descriptions. Update your environmental context as the game world changes.

Dynamic Time Awareness

Update your context based on the game's time of day. NPCs should reference morning, afternoon, evening, or nighttime appropriately in their responses. This simple change creates immense realism.

"It's getting late. I'll be closing shop soon."
"Rise and shine! You're up early this morning."

Weather Integration

Weather conditions affect mood, activity, and conversation topics. Include current weather in your context and encourage NPCs to reference it naturally in conversation.

"This rain is bad for business. Nobody wants to shop in a downpour."
"The heat today is unbearable. I've had to take extra water breaks."

2. Emotional Intelligence Systems

NPCs with emotional depth create more engaging interactions. Our emotional intelligence system enables NPCs to experience and express a full spectrum of emotions, evolve their feelings based on player interactions, and maintain consistent emotional states across game sessions.

Why Emotional NPCs Matter

Characters that respond emotionally to player actions create more immersive and meaningful gameplay experiences. Players feel a greater connection to emotionally responsive NPCs, leading to higher engagement and more memorable moments.

Primary Emotions

Core emotional states that drive behavior

Anger Sadness Joy Fear

Secondary Emotions

Nuanced states that add depth

Frustration Relief Gratitude Guilt

Underlying Mood

Persistent emotional baseline

Optimistic Pessimistic Anxious Calm

Multi-Dimensional Emotion System

Implement realistic emotions by defining multiple aspects of an NPC's emotional state:

{
  "client_id": "player_12345", 
  "messages": [
    {
      "role": "system",
      "content": "You are Elena, a tavern keeper. Respond naturally with your current emotional state.

Emotional State:
- Primary Emotion: Frustrated (7/10) - difficult customers all morning
- Secondary Emotion: Tired (6/10) - stayed up late with inventory
- Underlying Mood: Generally optimistic despite current stress
- Emotional Triggers: Rude behavior, mention of local politics

Emotional Expression Guidelines:
- Show frustration through shorter, more direct responses
- Tiredness affects attention to detail, occasional sighs
- Maintain underlying warmth despite current stress
- Quick to anger if player is rude, but quick to forgive if they're kind

Current Context:
- Just finished dealing with a drunk patron
- Wiping down tables more aggressively than necessary
- The lunch rush is about to start"
    },
    {
      "role": "user",
      "content": "Excuse me, could I get some information about local rumors?"
    }
  ],
  "temperature": 0.7
}

Response With Emotional Intelligence

P

Excuse me, could I get some information about local rumors?

E

*Glances up from the table she's wiping, exhales audibly* "Rumors? Now?" *Sets down her rag with a bit more force than necessary* "Look, I've had quite the morning already." *Sighs, then softens slightly* "But I suppose you're not the one who caused it. Give me a moment." *Rubs her temples briefly* "There's talk of new taxes coming from the baron's court. The blacksmith's apprentice ran off with a merchant's daughter three nights ago. And someone claims the old mill is haunted again." *Picks up her rag* "That enough for now? Got tables to finish before everyone piles in for lunch."

Notice how the response shows Elena's frustration (short sentences, abrupt tone) and tiredness (sighing, rubbing temples), while still providing the requested information due to her underlying optimistic nature.

Dynamic Emotion Evolution

NPCs can shift emotions based on player actions, creating evolving relationships:

Player Interaction

"I'm sorry about your rough morning. Your tavern is the best in town - always clean and welcoming. Let me know if I can help with anything before the lunch rush."

Emotional Response Update

{
  "emotional_update": {
    "primary": {
      "emotion": "Frustrated",
      "intensity": "7/10 → 4/10",
      "reason": "Soothed by kindness and compliment"
    },
    "secondary": {
      "emotion": "Touched",
      "intensity": "5/10",
      "reason": "Appreciation was unexpected"
    },
    "mood_shift": {
      "from": "Stressed but optimistic",
      "to": "Grateful and more relaxed"
    }
  },
  "relationship_impact": {
    "disposition": "+10% towards player",
    "memory": "Player was kind during a difficult day",
    "future_interactions": "More patient and helpful"
  }
}

Updated NPC Response

*Her expression softens noticeably, shoulders relaxing* "That's... actually very kind of you to say." *Sets down her rag and offers a genuine smile* "Been one of those mornings where you wonder why you opened the doors at all." *Chuckles* "But customers like you make it worthwhile. If you've got a moment, there's actually more to that mill story I didn't mention..." *Leans in, now seemingly in no rush to finish cleaning*

Emotion Memory

Store emotional responses to player actions in your NPC's memory. This creates NPCs that remember how players made them feel, not just what they did.

"Last time you were here, you helped my daughter. 
I won't forget that kindness." 

"You cheated me before. Why should I trust you now?"

Emotional Triggers

Define specific topics or actions that evoke strong emotional responses in your NPCs, creating more dynamic and personalized interactions.

"triggers": [
  {"topic": "The Great War", "reaction": "grief"},
  {"topic": "Mayor Thorne", "reaction": "disgust"},
  {"topic": "The old lighthouse", "reaction": "fear"}
]

Best practice: For most characters, start with a simple emotional system of 1-2 primary emotions and gradually add complexity. Too many emotional parameters can make characters seem erratic or confusing. Link emotional states to your Memory System to ensure consistency across conversations.

3. Dynamic Dialogue Trees & Branching

Move beyond static dialogue trees to dynamic conversation generation that creates meaningful choices based on context, character relationships, and story progression. Our dialogue branching system enables truly responsive conversations that adapt to player decisions.

Traditional Dialogue Trees

  • Pre-written responses
  • Limited branching paths
  • Cannot adapt to unexpected scenarios
  • Requires extensive manual authoring

Dynamic Dialogue System

  • Generates dialogue in real-time
  • Responds to new situations fluidly
  • Creates contextual, meaningful choices
  • Adapts to changing story conditions

Choice Generation System

Generate contextual dialogue options dynamically that present meaningful choices to players:

{
  "client_id": "player_12345",
  "messages": [
    {
      "role": "system",
      "content": "You are Captain Torres, leader of the town guard. The player has just asked about recent bandit attacks.

Generate 3-4 dialogue options for the player's response. Format as JSON:
{
  \"npc_response\": \"Your response to their question\",
  \"player_choices\": [
    {
      \"option\": \"What the player can say\",
      \"tone\": \"diplomatic/aggressive/curious/etc\",
      \"consequences\": \"What this choice might lead to\",
      \"requirements\": \"Any prerequisites for this option\"
    }
  ]
}

Available Options Based On:
- Player Reputation: Neutral (no special standing)
- Previous Conversations: First meeting
- Current Context: Public area, other guards listening
- Player's Visible Equipment: Standard traveler gear
- Recent Events: Increased bandit activity, guard morale is low"
    },
    {
      "role": "user",
      "content": "I've heard there's been trouble with bandits on the roads lately."
    }
  ],
  "response_format": { "type": "json_object" }
}

Note: The response_format parameter ensures you get a properly formatted JSON response that can be directly parsed by your game.

Interactive Dialogue Flow

1. NPC Response

"Aye, the roads haven't been safe lately. Lost two patrols last week, and the merchants are scared to travel alone." *glances at nearby guards* "We're doing what we can, but they're organized."

2. Player Choices

  • I'm skilled with a blade. Perhaps I could help patrol the roads?
  • Do you have any idea who's leading these bandits?
  • How much are you paying for bandit heads?

Example Generated Response

The API returns a structured JSON object with NPC response and player choices:

{
  "npc_response": "Aye, the roads haven't been safe lately. Lost two patrols last week, and the merchants are scared to travel alone. *glances at nearby guards* We're doing what we can, but they're organized.",
  
  "player_choices": [
    {
      "option": "I'm skilled with a blade. Perhaps I could help patrol the roads?",
      "tone": "helpful",
      "consequences": "May lead to guard recruitment quest or partnership",
      "requirements": "none"
    },
    {
      "option": "Do you have any idea who's leading these bandits?",
      "tone": "investigative", 
      "consequences": "Torres shares intelligence, possible investigation quest",
      "requirements": "none"
    },
    {
      "option": "How much are you paying for bandit heads?",
      "tone": "mercenary",
      "consequences": "Torres becomes more guarded, discusses bounties",
      "requirements": "none"
    },
    {
      "option": "I've dealt with organized bandits before. This sounds like more than just desperate thieves.",
      "tone": "experienced",
      "consequences": "Torres takes player seriously, shares strategic concerns",
      "requirements": "Player has combat experience or reputation"
    }
  ]
}

Context-Aware Options

Generate dialogue choices that reflect the player's current situation, equipped items, and previous actions. This creates more immersive and realistic conversation flow.

if (player.hasItem("captain_badge")) {
  choices.push({
    option: "As a fellow captain, I need details on your defenses.",
    consequences: "Torres shares confidential information"
  });
}

Multi-Path Conversations

Create branching dialogues that lead to different narrative paths. Each choice can unlock unique content, quests, or character relationship development.

"dialogue_paths": {
  "alliance": "Leads to guard cooperation questline",
  "investigation": "Opens detective storyline",
  "mercenary": "Unlocks bounty hunting system"
}

Advanced Implementation: Filtering & Processing Choices

For a smooth gameplay experience, you'll want to process generated dialogue choices before presenting them to players:

1. Validate Requirements

Check if player meets any prerequisites for special dialogue options (skills, inventory, reputation) and filter choices accordingly.

2. Apply Game Context

Match options with your game's capabilities. Remove choices that reference mechanics your game doesn't support.

3. Limit Options

Consider your UI constraints. Most games work best with 3-4 dialogue options maximum for readability and player decision-making.

Best practice: Store all dialogue choices and their consequences in your game's NPC Memory System. This allows NPCs to reference player's past dialogue choices in future conversations, creating continuity in your game's narrative.

4. Implementation Examples

Ready-to-use code examples for implementing dynamic dialogue systems in popular game development languages and engines.

JavaScript Dialogue Manager

Complete dialogue system for web games:

class DialogueManager {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.conversationHistory = new Map();
    this.emotionStates = new Map();
    this.baseUrl = 'https://api.chromagolem.com/v1';
  }

  async generateDialogue(npcId, playerMessage, context = {}) {
    const history = this.conversationHistory.get(npcId) || [];
    const emotions = this.emotionStates.get(npcId) || {};
    
    const messages = [
      {
        role: 'system',
        content: this.buildSystemMessage(context, emotions)
      },
      ...history.slice(-10), // Keep last 10 exchanges
      { role: 'user', content: playerMessage }
    ];

    try {
      const response = await fetch(`${this.baseUrl}/chat/completions`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${this.apiKey}`
        },
        body: JSON.stringify({
          messages,
          client_id: context.playerId || 'default'
        })
      });

      const data = await response.json();
      const npcResponse = data.choices[0].message.content;
      
      // Update conversation history
      this.updateHistory(npcId, playerMessage, npcResponse);
      this.updateEmotions(npcId, playerMessage, context);
      
      return {
        response: npcResponse,
        emotions: this.emotionStates.get(npcId),
        context: context
      };
    } catch (error) {
      console.error('Dialogue generation error:', error);
      return this.getFallbackResponse(npcId);
    }
  }

  buildSystemMessage(context, emotions) {
    return `You are ${context.npcName}, ${context.npcRole}.

Current Emotional State:
- Primary: ${emotions.primary || 'neutral'} (${emotions.intensity || 5}/10)
- Mood: ${emotions.mood || 'balanced'}
- Recent Trigger: ${emotions.lastTrigger || 'none'}

Environment & Context:
- Location: ${context.location}
- Time: ${context.timeOfDay}
- Recent Events: ${context.recentEvents}
- Other Present: ${context.othersPresent}

Dialogue Guidelines:
- Respond naturally based on your emotional state
- Reference the environment when appropriate
- Remember our conversation history
- Stay true to your character while adapting to the situation`;
  }
}

C# Unity Dialogue System

Unity MonoBehaviour for NPC dialogue:

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using UnityEngine;
using Newtonsoft.Json;

[System.Serializable]
public class EmotionState
{
    public string primary;
    public int intensity;
    public string mood;
    public string lastTrigger;
}

public class DialogueNPC : MonoBehaviour
{
    [Header("NPC Configuration")]
    public string npcName = "Guard";
    public string npcRole = "Town Guard";
    public string apiKey = "your_api_key_here";
    
    [Header("Dialogue State")]
    public EmotionState currentEmotions;
    public List<string> conversationHistory;
    
    private const string API_BASE_URL = "https://api.chromagolem.com/v1";
    
    public async Task<string> GenerateDialogueAsync(string playerMessage, string context = "")
    {
        var systemMessage = BuildSystemMessage(context);
        var messages = BuildMessageArray(systemMessage, playerMessage);
        
        var requestData = new
        {
            messages = messages,
            client_id = SystemInfo.deviceUniqueIdentifier
        };
        
        string jsonRequest = JsonConvert.SerializeObject(requestData);
        
        using (UnityWebRequest request = new UnityWebRequest($"{API_BASE_URL}/chat/completions", "POST"))
        {
            byte[] jsonBytes = System.Text.Encoding.UTF8.GetBytes(jsonRequest);
            request.uploadHandler = new UploadHandlerRaw(jsonBytes);
            request.downloadHandler = new DownloadHandlerBuffer();
            request.SetRequestHeader("Content-Type", "application/json");
            request.SetRequestHeader("Authorization", $"Bearer {apiKey}");
            
            await SendWebRequest(request);
            
            if (request.result == UnityWebRequest.Result.Success)
            {
                var response = JsonConvert.DeserializeObject<DialogueResponse>(request.downloadHandler.text);
                string npcResponse = response.choices[0].message.content;
                
                // Update conversation history
                UpdateConversationHistory(playerMessage, npcResponse);
                UpdateEmotionalState(playerMessage);
                
                return npcResponse;
            }
            else
            {
                Debug.LogError($"Dialogue API Error: {request.error}");
                return GetFallbackResponse();
            }
        }
    }
}

Python Dialogue Engine

Complete dialogue system for Python-based games:

import json
import time
import requests
from typing import Dict, List, Optional
from dataclasses import dataclass, asdict

@dataclass
class EmotionState:
    primary: str = "neutral"
    intensity: int = 5
    mood: str = "balanced"
    last_trigger: str = "none"
    timestamp: float = 0.0

class DialogueEngine:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.chromagolem.com/v1"
        self.npc_states = {}
        self.conversation_histories = {}
        
    async def generate_dialogue(self, npc_id: str, player_message: str, 
                           context: Dict = None) -> Dict:
        """Generate dynamic dialogue response with emotional context."""
        if context is None:
            context = {}
            
        # Get or initialize NPC state
        emotions = self.npc_states.get(npc_id, EmotionState())
        history = self.conversation_histories.get(npc_id, [])
        
        # Build system message with full context
        system_message = self._build_system_message(context, emotions)
        
        messages = [
            {"role": "system", "content": system_message},
            *history[-10:],  # Last 10 exchanges
            {"role": "user", "content": player_message}
        ]
        
        try:
            response = requests.post(
                f"{self.base_url}/chat/completions",
                headers={
                    "Content-Type": "application/json",
                    "Authorization": f"Bearer {self.api_key}"
                },
                json={
                    "messages": messages,
                    "client_id": context.get("player_id", "default")
                },
                timeout=30
            )
            
            response.raise_for_status()
            data = response.json()
            npc_response = data["choices"][0]["message"]["content"]
            
            # Update NPC state
            self._update_conversation_history(npc_id, player_message, npc_response)
            self._update_emotional_state(npc_id, player_message, context)
            
            return {
                "response": npc_response,
                "emotions": asdict(self.npc_states[npc_id]),
                "context": context
            }
            
        except requests.RequestException as e:
            print(f"Dialogue generation error: {e}")
            return self._get_fallback_response(npc_id, context)

Troubleshooting & Best Practices

Common issues and solutions when implementing dynamic dialogue systems.

🚨 Common Issues

NPCs break character in conversation

Solution: Include character consistency reminders in your system message and provide examples of in-character responses for complex situations.

Conversations feel repetitive

Solution: Vary emotional states, reference recent events, and include environmental details to keep conversations fresh and contextual.

NPCs don't remember important events

Solution: Implement proper conversation history storage and include key plot points in the system message for each interaction.

Response times are too slow

Solution: Cache common responses, pre-generate background conversations, or use shorter context messages for non-critical NPCs.

💡 Best Practices

Layer emotional complexity gradually

Start with basic emotions and add complexity as you refine the system. Simple happy/sad/angry states work better than overly complex emotion models.

Test with diverse player inputs

Include edge cases, hostile players, and unusual conversation paths in your testing to ensure robust NPC behavior.

Balance context and performance

More context creates better dialogue but increases API costs. Find the sweet spot for your game's needs and budget.

Plan for offline scenarios

Always have fallback dialogue for network issues. Pre-written responses can maintain immersion when the API is unavailable.

Frequently Asked Questions

Q: How much dialogue history should I include?

A: 5-10 recent exchanges usually provide enough context without overwhelming the system. For crucial NPCs, consider maintaining separate "important moments" that always get included.

Q: Can NPCs have conversations with each other?

A: Yes! Generate NPC-to-NPC dialogue by setting up conversations where one NPC's response becomes the input for another NPC's dialogue generation.

Q: How do I handle multiple languages?

A: Include language preferences in your system message: "Respond in [language]" or "Detect the player's language and respond accordingly."

Q: What's the best way to handle inappropriate player input?

A: Include content guidelines in your system message and implement client-side filtering. NPCs can be instructed to redirect inappropriate conversations back to appropriate topics.

Need More Help?

Questions about implementing dynamic dialogue systems in your game?

Ready to Build Dynamic Dialogue?

Follow these steps to create engaging conversations in your game

1

Set Up Your API Key

Create your API key and start making requests to our dialogue generation endpoints.

Get API Key
2

Design Your NPCs

Create rich character profiles with emotional states and conversation contexts.

View Examples
3

Implement & Test

Use our code examples to build your dialogue system and test with real players.

Implementation Guide

Need help with dialogue systems?

Join our community of game developers to share dialogue techniques and get advice. Join our Discord server

Back to your dashboard
View my API keys