INTRODUCTION
The emergence of Large Language Models has opened unprecedented possibilities for game development. These powerful artificial intelligence systems can generate coherent text, understand context, maintain conversations, and create dynamic narratives that respond to player choices in ways that were previously impossible. Building games with LLMs represents a fundamental shift from traditional rule-based systems to emergent, generative gameplay experiences.
At their core, LLM-based games leverage the natural language understanding and generation capabilities of models like GPT-4, Claude, or similar systems to create interactive experiences. Unlike traditional games where every possible interaction must be programmed explicitly, LLM-powered games can respond to arbitrary player input with contextually appropriate and creative outputs. This enables truly open-ended gameplay where players can type natural language commands and receive meaningful responses.
However, building production-quality games with LLMs presents unique challenges. Developers must manage API costs, handle unpredictable outputs, maintain game state consistency, engineer effective prompts, and create systems that remain engaging over extended play sessions. The probabilistic nature of LLMs means that outputs are never completely deterministic, requiring careful validation and error handling strategies.
FUNDAMENTAL ARCHITECTURE
The architecture of an LLM-based game consists of several interconnected layers that work together to create a cohesive experience. The foundation is the LLM client layer, which abstracts the details of communicating with AI services. This layer handles API authentication, request formatting, response parsing, and error recovery. Building a robust abstraction at this level allows the game to potentially swap between different LLM providers or implement fallback strategies when one service is unavailable.
Above the client layer sits the prompt engineering system. This component is responsible for constructing effective prompts that guide the LLM to generate appropriate responses. The prompt typically includes the current game state, relevant history, character information, world context, and specific instructions for the type of content needed. The quality of prompt engineering directly impacts the quality of the gaming experience.
The game state management layer maintains all information about the current game session. This includes the player’s location, inventory, quest progress, character relationships, world state, and conversation history. State management must be carefully designed to track both discrete game variables and the flowing narrative context that the LLM uses to generate coherent responses.
The input processing layer interprets player commands, validates them against the current game state, and determines what information to include in the LLM prompt. The output processing layer takes the LLM’s response and updates the game state accordingly. This might involve extracting structured information from natural language responses, updating world state, or determining game events that should occur.
BUILDING THE LLM CLIENT ABSTRACTION
Let us begin examining the technical implementation with the LLM client layer. This component encapsulates all direct interaction with the AI service. Here is a foundational structure:
class LLMClient {
constructor(apiKey, config = {}) {
this.apiKey = apiKey;
this.baseUrl = config.baseUrl || 'https://api.openai.com/v1';
this.model = config.model || 'gpt-4';
this.maxRetries = config.maxRetries || 3;
this.timeout = config.timeout || 30000;
}
async generateResponse(prompt, options = {}) {
const requestBody = {
model: this.model,
messages: prompt,
temperature: options.temperature || 0.7,
max_tokens: options.maxTokens || 1000,
top_p: options.topP || 1.0
};
for (let attempt = 0; attempt < this.maxRetries; attempt++) {
try {
const response = await this.makeRequest(requestBody);
return this.extractContent(response);
} catch (error) {
if (attempt === this.maxRetries - 1) throw error;
await this.delay(Math.pow(2, attempt) * 1000);
}
}
}
}
The client implementation above demonstrates several production-ready patterns. The constructor accepts configuration parameters that allow customization without code changes. The retry mechanism with exponential backoff handles transient network failures gracefully. The separation between making requests and extracting content allows for clean error handling and response validation.
The temperature parameter controls randomness in the LLM’s outputs. Lower values produce more deterministic responses, while higher values increase creativity and variation. For game narratives, a temperature around 0.7 to 0.8 typically provides a good balance between consistency and interesting variability.
PROMPT ENGINEERING FOR GAMES
Effective prompt engineering is the most critical skill when building LLM-based games. The prompt serves as the complete interface between your game logic and the AI’s capabilities. A well-engineered prompt must provide sufficient context for the LLM to understand the game world, the current situation, and what type of response is expected, while remaining concise enough to fit within token limits and minimize API costs.
The structure of a game prompt typically follows this pattern. First, establish the system context that describes the game world, the LLM’s role, and the style of responses expected. Second, provide the current game state including location, inventory, and active quests. Third, include relevant recent history that affects the current interaction. Fourth, present the player’s input. Finally, provide specific instructions for the format and content of the response.
Consider this example of constructing a prompt for a fantasy adventure game:
class PromptBuilder {
constructor(gameWorld) {
this.gameWorld = gameWorld;
this.systemPrompt = this.buildSystemPrompt();
}
buildSystemPrompt() {
return `You are the narrator and game master for an interactive fantasy adventure. Your role is to describe scenes vividly, control non-player characters, and respond to player actions. Maintain consistency with the established world and previous events. Keep responses between 100-200 words unless a longer description is warranted. Always indicate when the player cannot perform an action and explain why.`;
}
buildGamePrompt(gameState, playerInput) {
const messages = [
{ role: 'system', content: this.systemPrompt }
];
// Add world context
const location = gameState.getCurrentLocation();
messages.push({
role: 'system',
content: `Current Location: ${location.name}\n${location.description}\nAvailable exits: ${location.exits.join(', ')}`
});
// Add character state
messages.push({
role: 'system',
content: `Player inventory: ${gameState.inventory.join(', ') || 'empty'}\nPlayer health: ${gameState.health}/100`
});
// Add recent history
const recentHistory = gameState.getRecentHistory(5);
recentHistory.forEach(exchange => {
messages.push({ role: 'user', content: exchange.input });
messages.push({ role: 'assistant', content: exchange.output });
});
// Add current player input
messages.push({ role: 'user', content: playerInput });
return messages;
}
}
This prompt builder separates concerns effectively. The system prompt remains constant and establishes the fundamental behavior. The game-specific context is injected dynamically based on current state. The history mechanism allows the LLM to maintain continuity across multiple exchanges. The structure uses the messages format that modern LLM APIs expect, with distinct roles for system instructions, user input, and assistant responses.
MANAGING GAME STATE
Game state management becomes significantly more complex in LLM-based games compared to traditional implementations. Traditional games track discrete state variables that change through explicit game logic. LLM games must additionally track the narrative state, which exists primarily in the natural language context provided to the model. Maintaining consistency between these two representations of state is essential for a coherent experience.
The game state object should track both structured data and narrative context. Structured data includes quantifiable elements like player health, inventory items, quest completion status, and location. Narrative context includes character relationships, story beats that have occurred, world events, and conversation threads. Here is an implementation approach:
class GameState {
constructor() {
this.player = {
health: 100,
inventory: [],
location: 'starting_village',
gold: 50
};
this.world = {
locations: new Map(),
characters: new Map(),
quests: []
};
this.history = [];
this.narrativeFlags = new Set();
this.conversationMemory = new Map();
}
updateFromNarrative(narrative, playerAction) {
// Extract game-relevant information from LLM output
this.history.push({
timestamp: Date.now(),
action: playerAction,
narrative: narrative,
state: this.captureSnapshot()
});
// Parse narrative for state changes
this.extractStateChanges(narrative);
// Trim history if too long
if (this.history.length > 50) {
this.history = this.history.slice(-30);
}
}
extractStateChanges(narrative) {
// Use pattern matching or structured output to extract state
const lowerNarrative = narrative.toLowerCase();
// Example: detecting item acquisition
const itemMatch = narrative.match(/you (?:take|pick up|acquire|find) (?:the |an? )?(\w+)/i);
if (itemMatch && !this.player.inventory.includes(itemMatch[1])) {
this.player.inventory.push(itemMatch[1]);
}
// Example: detecting damage
const damageMatch = narrative.match(/you (?:take|suffer|receive) (\d+) damage/i);
if (damageMatch) {
this.player.health = Math.max(0, this.player.health - parseInt(damageMatch[1]));
}
}
captureSnapshot() {
return {
player: JSON.parse(JSON.stringify(this.player)),
narrativeFlags: Array.from(this.narrativeFlags),
timestamp: Date.now()
};
}
getRecentHistory(count) {
return this.history.slice(-count).map(entry => ({
input: entry.action,
output: entry.narrative
}));
}
}
The state management implementation above demonstrates several important patterns. The history tracking maintains both the narrative flow and snapshots of game state, enabling features like save games or undo functionality. The extraction methods attempt to parse natural language output into structured state changes, bridging the gap between narrative description and game mechanics. The snapshot capability preserves complete state at any point in time.
HANDLING STRUCTURED OUTPUT
A critical challenge in LLM game development is ensuring that the model’s responses can be reliably parsed into actionable game state updates. While narrative descriptions are valuable for player immersion, the game engine needs structured information to function correctly. Modern LLM APIs provide mechanisms for requesting structured output, but these must be used carefully to maintain narrative quality.
One effective approach is to request that the LLM include structured information in a specific format alongside its narrative description. For example, the prompt might request that game-relevant events be marked with specific tags or included in a JSON structure. Here is an implementation:
class ResponseProcessor {
constructor(gameState) {
this.gameState = gameState;
}
processResponse(rawResponse) {
// Extract structured data if present
const structuredMatch = rawResponse.match(/\[GAME_STATE\](.*?)\[\/GAME_STATE\]/s);
let structuredData = null;
let narrative = rawResponse;
if (structuredMatch) {
try {
structuredData = JSON.parse(structuredMatch[1]);
narrative = rawResponse.replace(structuredMatch[0], '').trim();
} catch (e) {
console.error('Failed to parse structured data:', e);
}
}
// Apply structured updates to game state
if (structuredData) {
this.applyStateUpdates(structuredData);
}
// Extract implied state changes from narrative
this.gameState.extractStateChanges(narrative);
return {
narrative: narrative,
stateUpdates: structuredData,
success: true
};
}
applyStateUpdates(updates) {
if (updates.inventory) {
updates.inventory.added?.forEach(item => {
if (!this.gameState.player.inventory.includes(item)) {
this.gameState.player.inventory.push(item);
}
});
updates.inventory.removed?.forEach(item => {
const index = this.gameState.player.inventory.indexOf(item);
if (index > -1) {
this.gameState.player.inventory.splice(index, 1);
}
});
}
if (updates.health !== undefined) {
this.gameState.player.health = Math.max(0, Math.min(100, updates.health));
}
if (updates.location) {
this.gameState.player.location = updates.location;
}
if (updates.flags) {
updates.flags.forEach(flag => this.gameState.narrativeFlags.add(flag));
}
}
}
This response processing layer handles both explicit structured data and implicit information embedded in the narrative. The dual approach increases robustness since even if the LLM fails to include structured tags, the system can still extract basic information from the narrative text. The structured format provides precise control over complex state changes while maintaining natural storytelling.
CONTEXT WINDOW MANAGEMENT
Large Language Models have finite context windows that limit how much information can be included in a single prompt. For games that involve extended play sessions, managing what information to include becomes crucial. Simply including all previous exchanges quickly exhausts the available context, and summarizing too aggressively loses important details that affect continuity.
An effective strategy involves maintaining multiple tiers of memory. Recent interactions are preserved in full detail since they are most likely to be relevant to the current situation. Older interactions are summarized into key plot points and state changes. Very old interactions are distilled into permanent flags that track which story beats have occurred without preserving the exact narrative.
Here is an implementation of hierarchical memory management:
class ContextManager {
constructor(maxRecentExchanges = 5, maxSummaries = 10) {
this.maxRecentExchanges = maxRecentExchanges;
this.maxSummaries = maxSummaries;
this.recentExchanges = [];
this.summaries = [];
this.permanentFacts = new Set();
}
addExchange(userInput, assistantResponse, gameState) {
this.recentExchanges.push({
user: userInput,
assistant: assistantResponse,
timestamp: Date.now(),
location: gameState.player.location
});
// When recent exchanges exceed limit, summarize the oldest
if (this.recentExchanges.length > this.maxRecentExchanges) {
const toSummarize = this.recentExchanges.shift();
this.summarizeExchange(toSummarize);
}
}
summarizeExchange(exchange) {
// Extract key information from the exchange
const summary = {
timestamp: exchange.timestamp,
location: exchange.location,
keyEvents: this.extractKeyEvents(exchange.assistant),
playerActions: this.extractPlayerActions(exchange.user)
};
this.summaries.push(summary);
// When summaries exceed limit, extract permanent facts
if (this.summaries.length > this.maxSummaries) {
const oldSummary = this.summaries.shift();
this.extractPermanentFacts(oldSummary);
}
}
extractKeyEvents(narrative) {
const events = [];
// Extract significant game events using pattern matching
if (narrative.match(/acquir|find|obtain|take|pick up/i)) {
const itemMatch = narrative.match(/(?:acquir|find|obtain|take|pick up)[^.]*?(\w+)/i);
if (itemMatch) events.push(`acquired_${itemMatch[1]}`);
}
if (narrative.match(/meet|encounter|speak with/i)) {
const npcMatch = narrative.match(/(?:meet|encounter|speak with)[^.]*?([A-Z][a-z]+)/);
if (npcMatch) events.push(`met_${npcMatch[1]}`);
}
return events;
}
extractPlayerActions(input) {
// Categorize player actions
const action = input.toLowerCase();
if (action.match(/go|move|walk|travel/)) return ['movement'];
if (action.match(/talk|speak|say|ask/)) return ['conversation'];
if (action.match(/take|get|grab|pick/)) return ['acquisition'];
if (action.match(/use|activate|interact/)) return ['interaction'];
return ['other'];
}
extractPermanentFacts(summary) {
// Convert summary into permanent flags
summary.keyEvents.forEach(event => {
this.permanentFacts.add(event);
});
}
buildContextSummary() {
let context = '';
// Add permanent facts as background knowledge
if (this.permanentFacts.size > 0) {
context += 'Previously established facts: ';
context += Array.from(this.permanentFacts).join(', ');
context += '\n\n';
}
// Add summaries of older interactions
if (this.summaries.length > 0) {
context += 'Recent events summary:\n';
this.summaries.forEach(summary => {
if (summary.keyEvents.length > 0) {
context += `- At ${summary.location}: ${summary.keyEvents.join(', ')}\n`;
}
});
context += '\n';
}
return context;
}
getRecentExchanges() {
return this.recentExchanges;
}
}
This context management system preserves information at different levels of granularity. The most recent exchanges remain verbatim, enabling the LLM to maintain conversational continuity and reference specific details. The summary layer captures the essence of recent gameplay without consuming excessive tokens. The permanent facts layer ensures that significant story beats remain part of the game state indefinitely. This hierarchical approach allows games to support extended play sessions while keeping prompt sizes manageable.
IMPLEMENTING NON-PLAYER CHARACTERS
One of the most compelling applications of LLMs in games is creating dynamic non-player characters that can engage in natural conversations. Traditional dialogue trees become limiting when players can type arbitrary responses. LLM-powered NPCs can understand player intent, remember previous conversations, and respond in ways that reflect their personality and knowledge.
Implementing believable NPCs requires careful prompt engineering to define their characteristics, knowledge, motivations, and speech patterns. Each NPC should have a persistent personality that remains consistent across interactions while still allowing for character development based on player actions. Here is a system for managing NPC interactions:
class NPCManager {
constructor(llmClient) {
this.llmClient = llmClient;
this.npcs = new Map();
}
defineNPC(id, definition) {
this.npcs.set(id, {
id: id,
name: definition.name,
personality: definition.personality,
knowledge: definition.knowledge,
goals: definition.goals,
relationship: definition.relationship || 'neutral',
conversationHistory: []
});
}
async converseWithNPC(npcId, playerInput, gameContext) {
const npc = this.npcs.get(npcId);
if (!npc) {
throw new Error(`NPC ${npcId} not found`);
}
const prompt = this.buildNPCPrompt(npc, playerInput, gameContext);
const response = await this.llmClient.generateResponse(prompt, {
temperature: 0.8,
maxTokens: 300
});
// Update NPC conversation history
npc.conversationHistory.push({
player: playerInput,
npc: response,
timestamp: Date.now()
});
// Trim conversation history if too long
if (npc.conversationHistory.length > 10) {
npc.conversationHistory = npc.conversationHistory.slice(-6);
}
return response;
}
buildNPCPrompt(npc, playerInput, gameContext) {
const messages = [
{
role: 'system',
content: `You are ${npc.name}, a character in a fantasy adventure game.
```
Personality: ${npc.personality}
What you know: ${npc.knowledge}
Your goals: ${npc.goals}
Your relationship with the player: ${npc.relationship}
Stay in character at all times. Respond as ${npc.name} would, using appropriate tone and knowledge.
Keep responses concise (2-4 sentences) unless the situation warrants more detail.
If asked about something you wouldn’t know, respond as the character would when they don’t know something.`
}
];
// Add game context
messages.push({
role: 'system',
content: `Current situation: ${gameContext.situation}\nPlayer's recent actions: ${gameContext.recentActions}`
});
// Add conversation history
npc.conversationHistory.forEach(exchange => {
messages.push({ role: 'user', content: exchange.player });
messages.push({ role: 'assistant', content: exchange.npc });
});
// Add current player input
messages.push({ role: 'user', content: playerInput });
return messages;
}
updateNPCRelationship(npcId, change) {
const npc = this.npcs.get(npcId);
if (!npc) return;
// Simple relationship tracking
const relationships = ['hostile', 'unfriendly', 'neutral', 'friendly', 'allied'];
const currentIndex = relationships.indexOf(npc.relationship);
const newIndex = Math.max(0, Math.min(relationships.length - 1, currentIndex + change));
npc.relationship = relationships[newIndex];
}
}
The NPC manager creates distinct personalities by providing detailed character definitions in the system prompt. Each NPC maintains its own conversation history, allowing them to reference previous interactions with the player. The relationship tracking system provides a simple mechanism for NPCs to alter their behavior based on player actions. This creates the foundation for dynamic character interactions that feel personal and responsive.
ERROR HANDLING AND VALIDATION
Production LLM-based games must handle numerous failure modes gracefully. API calls can fail due to network issues, rate limits, or service outages. LLM responses may be malformed, inconsistent with game state, or inappropriate for the context. Players may input commands that are impossible or unclear. Robust error handling transforms these potential breaking points into manageable situations that maintain the game experience.
The error handling strategy should operate at multiple levels. At the lowest level, the LLM client implements retry logic with exponential backoff for transient failures. The next level validates LLM responses for basic correctness and consistency. The highest level provides fallback behaviors that keep the game playable even when AI services are unavailable. Here is a comprehensive error handling implementation:
class GameEngine {
constructor(llmClient, gameState) {
this.llmClient = llmClient;
this.gameState = gameState;
this.fallbackResponses = new Map();
this.validationRules = [];
this.initializeFallbacks();
}
initializeFallbacks() {
// Provide basic fallback responses for common situations
this.fallbackResponses.set('movement',
'You move through the area, carefully observing your surroundings.');
this.fallbackResponses.set('examination',
'You examine the object carefully, noting its details.');
this.fallbackResponses.set('conversation',
'They listen to your words thoughtfully before responding.');
this.fallbackResponses.set('action',
'You attempt the action, considering the results.');
}
addValidationRule(rule) {
this.validationRules.push(rule);
}
async processPlayerInput(input) {
try {
// Attempt to get LLM response
const response = await this.getLLMResponse(input);
// Validate the response
const validation = this.validateResponse(response, input);
if (!validation.valid) {
console.warn('Response validation failed:', validation.reason);
// Attempt regeneration once
const retryResponse = await this.getLLMResponse(input);
const retryValidation = this.validateResponse(retryResponse, input);
if (retryValidation.valid) {
return this.finalizeResponse(retryResponse, input);
} else {
return this.handleFallback(input, 'validation_failed');
}
}
return this.finalizeResponse(response, input);
} catch (error) {
console.error('Error processing input:', error);
return this.handleFallback(input, error.message);
}
}
async getLLMResponse(input) {
const promptBuilder = new PromptBuilder(this.gameState);
const prompt = promptBuilder.buildGamePrompt(this.gameState, input);
const response = await this.llmClient.generateResponse(prompt, {
temperature: 0.7,
maxTokens: 500
});
return response;
}
validateResponse(response, input) {
// Check for empty or extremely short responses
if (!response || response.trim().length < 10) {
return { valid: false, reason: 'Response too short' };
}
// Check for response length exceeding expectations
if (response.length > 2000) {
return { valid: false, reason: 'Response too long' };
}
// Run custom validation rules
for (const rule of this.validationRules) {
const result = rule(response, input, this.gameState);
if (!result.valid) {
return result;
}
}
// Check for consistency with game state
const stateCheck = this.checkStateConsistency(response);
if (!stateCheck.valid) {
return stateCheck;
}
return { valid: true };
}
checkStateConsistency(response) {
const lowerResponse = response.toLowerCase();
// Check for mentions of items player doesn't have
const itemMention = response.match(/you (?:use|hold|wield|wear) (?:the |your )?(\w+)/i);
if (itemMention) {
const item = itemMention[1].toLowerCase();
const hasItem = this.gameState.player.inventory.some(i =>
i.toLowerCase().includes(item)
);
if (!hasItem) {
return {
valid: false,
reason: `Response mentions item player doesn't have: ${item}`
};
}
}
// Check for contradictions with known facts
if (this.gameState.player.health <= 0 && !lowerResponse.includes('death')) {
return {
valid: false,
reason: 'Response inconsistent with player death state'
};
}
return { valid: true };
}
handleFallback(input, reason) {
console.log(`Using fallback response due to: ${reason}`);
// Categorize the input to select appropriate fallback
const category = this.categorizeInput(input);
const fallback = this.fallbackResponses.get(category) ||
this.fallbackResponses.get('action');
return {
narrative: fallback,
stateUpdates: null,
success: true,
usedFallback: true
};
}
categorizeInput(input) {
const lower = input.toLowerCase();
if (lower.match(/go|move|walk|travel|north|south|east|west/)) return 'movement';
if (lower.match(/look|examine|inspect|check|search/)) return 'examination';
if (lower.match(/talk|speak|say|ask|tell/)) return 'conversation';
return 'action';
}
finalizeResponse(response, input) {
const processor = new ResponseProcessor(this.gameState);
const processed = processor.processResponse(response);
// Update context manager
this.contextManager.addExchange(input, response, this.gameState);
return processed;
}
}
This error handling framework ensures the game remains playable under adverse conditions. The validation system catches common failure modes before they affect gameplay. The fallback mechanism provides basic interactivity even when the AI service is completely unavailable. The categorization system ensures fallback responses are contextually appropriate. Together, these layers create resilience that production applications require.
COST OPTIMIZATION STRATEGIES
Running an LLM-based game can be expensive if not managed carefully. Each API call consumes tokens and incurs costs. For games with many players or extended play sessions, optimization becomes essential for economic viability. Several strategies can dramatically reduce costs while maintaining gameplay quality.
Caching is the most effective optimization technique. Many prompts contain information that rarely changes, such as game world descriptions, character definitions, and system instructions. These elements can be cached and reused across multiple requests. Modern LLM APIs provide explicit caching mechanisms that reduce costs for repeated content.
Another important strategy is prompt compression. Instead of including verbose descriptions, use concise representations that convey the same information in fewer tokens. For example, rather than including full narrative descriptions of previous events, use structured summaries. The game can regenerate detailed descriptions when needed for display to the player.
Token budgeting allows games to allocate different token limits based on the importance of different interactions. Critical story moments might use larger token budgets for rich descriptions, while routine actions use smaller budgets. Dynamic adjustment based on available budget prevents cost overruns.
constructor(config) {
this.costPerToken = config.costPerToken || 0.00003;
this.tokenBudget = config.tokenBudget || 1000000;
this.tokensUsed = 0;
this.cache = new Map();
this.cacheHits = 0;
this.cacheMisses = 0;
}
async optimizedRequest(promptData, llmClient, options = {}) {
// Check cache first
const cacheKey = this.generateCacheKey(promptData);
const cached = this.cache.get(cacheKey);
if (cached && !this.isCacheStale(cached)) {
this.cacheHits++;
return cached.response;
}
this.cacheMisses++;
// Compress prompt if needed
const compressedPrompt = this.compressPrompt(promptData);
// Adjust token limits based on remaining budget
const adjustedOptions = this.adjustTokenLimits(options);
// Make request
const response = await llmClient.generateResponse(
compressedPrompt,
adjustedOptions
);
// Update token usage
const tokensUsed = this.estimateTokens(compressedPrompt) +
this.estimateTokens(response);
this.tokensUsed += tokensUsed;
// Cache the response
this.cache.set(cacheKey, {
response: response,
timestamp: Date.now(),
tokens: tokensUsed
});
return response;
}
compressPrompt(promptData) {
// Compress verbose descriptions
const compressed = promptData.map(message => {
if (message.role === 'system') {
// System messages can be compressed more aggressively
return {
role: message.role,
content: this.compressSystemMessage(message.content)
};
}
return message;
});
return compressed;
}
compressSystemMessage(content) {
// Remove redundant whitespace
let compressed = content.replace(/\s+/g, ' ').trim();
// Replace verbose phrases with concise equivalents
const replacements = {
'You are currently located in': 'Location:',
'Your current inventory contains': 'Inventory:',
'The player has the following items': 'Items:',
'You should respond by': 'Respond:',
'It is important to note that': 'Note:',
'Please make sure to': 'Ensure:'
};
for (const [verbose, concise] of Object.entries(replacements)) {
compressed = compressed.replace(new RegExp(verbose, 'gi'), concise);
}
return compressed;
}
adjustTokenLimits(options) {
const remainingBudget = this.tokenBudget - this.tokensUsed;
const requestedTokens = options.maxTokens || 500;
// If running low on budget, reduce token allocation
if (remainingBudget < this.tokenBudget * 0.1) {
return {
...options,
maxTokens: Math.min(requestedTokens, 200)
};
}
return options;
}
estimateTokens(text) {
if (typeof text === 'string') {
// Rough approximation: 1 token per 4 characters
return Math.ceil(text.length / 4);
} else if (Array.isArray(text)) {
return text.reduce((sum, msg) =>
sum + this.estimateTokens(msg.content), 0);
}
return 0;
}
generateCacheKey(promptData) {
// Create cache key from prompt content
const contentHash = promptData.map(msg =>
`${msg.role}:${msg.content.substring(0, 100)}`
).join('|');
return contentHash;
}
isCacheStale(cached) {
// Cache entries expire after 5 minutes
const maxAge = 5 * 60 * 1000;
return Date.now() - cached.timestamp > maxAge;
}
getCostReport() {
const totalCost = this.tokensUsed * this.costPerToken;
const cacheRate = this.cacheHits / (this.cacheHits + this.cacheMisses);
return {
tokensUsed: this.tokensUsed,
estimatedCost: totalCost.toFixed(4),
cacheHitRate: (cacheRate * 100).toFixed(1) + '%',
remainingBudget: this.tokenBudget - this.tokensUsed
};
}
}
This cost optimization system demonstrates practical techniques for reducing expenses. The caching mechanism avoids redundant API calls for similar requests. The compression system reduces token usage without significantly impacting quality. The dynamic token adjustment ensures the game stays within budget constraints. The reporting capabilities provide visibility into costs and optimization effectiveness.
PERSISTING GAME STATE
Players expect to be able to save their progress and return to games later. Implementing save and load functionality for LLM-based games requires careful consideration of what state to preserve. The game must save not only the discrete variables like inventory and location but also the narrative context that maintains continuity.
The serialization format should be both compact for efficient storage and human-readable for debugging. JSON provides a good balance. The save system should capture all information needed to restore the exact game state, including conversation history, NPC relationships, and world state changes. Here is an implementation:
class SaveManager {
constructor(gameState, contextManager, npcManager) {
this.gameState = gameState;
this.contextManager = contextManager;
this.npcManager = npcManager;
}
createSaveData(saveName) {
const saveData = {
version: '1.0',
timestamp: Date.now(),
saveName: saveName,
player: {
health: this.gameState.player.health,
inventory: [...this.gameState.player.inventory],
location: this.gameState.player.location,
gold: this.gameState.player.gold
},
world: {
narrativeFlags: Array.from(this.gameState.narrativeFlags),
completedQuests: this.gameState.world.quests
.filter(q => q.completed)
.map(q => q.id)
},
context: {
recentExchanges: this.contextManager.getRecentExchanges(),
summaries: this.contextManager.summaries,
permanentFacts: Array.from(this.contextManager.permanentFacts)
},
npcs: this.serializeNPCs()
};
return saveData;
}
serializeNPCs() {
const npcData = {};
for (const [id, npc] of this.npcManager.npcs.entries()) {
npcData[id] = {
relationship: npc.relationship,
conversationHistory: npc.conversationHistory.slice(-5)
};
}
return npcData;
}
async saveGame(saveName, storageProvider) {
try {
const saveData = this.createSaveData(saveName);
const serialized = JSON.stringify(saveData, null, 2);
await storageProvider.write(
`save_${saveName}.json`,
serialized
);
return { success: true, saveName: saveName };
} catch (error) {
console.error('Failed to save game:', error);
return { success: false, error: error.message };
}
}
async loadGame(saveName, storageProvider) {
try {
const serialized = await storageProvider.read(
`save_${saveName}.json`
);
const saveData = JSON.parse(serialized);
this.restoreGameState(saveData);
return { success: true, saveName: saveName };
} catch (error) {
console.error('Failed to load game:', error);
return { success: false, error: error.message };
}
}
restoreGameState(saveData) {
// Restore player state
this.gameState.player.health = saveData.player.health;
this.gameState.player.inventory = [...saveData.player.inventory];
this.gameState.player.location = saveData.player.location;
this.gameState.player.gold = saveData.player.gold;
// Restore world state
this.gameState.narrativeFlags = new Set(saveData.world.narrativeFlags);
// Restore context
this.contextManager.recentExchanges = saveData.context.recentExchanges;
this.contextManager.summaries = saveData.context.summaries;
this.contextManager.permanentFacts = new Set(saveData.context.permanentFacts);
// Restore NPC states
for (const [id, npcData] of Object.entries(saveData.npcs)) {
const npc = this.npcManager.npcs.get(id);
if (npc) {
npc.relationship = npcData.relationship;
npc.conversationHistory = npcData.conversationHistory;
}
}
}
async listSaves(storageProvider) {
try {
const files = await storageProvider.list();
const saveFiles = files.filter(f => f.startsWith('save_'));
const saves = await Promise.all(
saveFiles.map(async filename => {
const data = await storageProvider.read(filename);
const parsed = JSON.parse(data);
return {
name: parsed.saveName,
timestamp: parsed.timestamp,
location: parsed.player.location,
filename: filename
};
})
);
return saves.sort((a, b) => b.timestamp - a.timestamp);
} catch (error) {
console.error('Failed to list saves:', error);
return [];
}
}
}
The save manager provides comprehensive state persistence. It captures all necessary information to restore the exact game state, including narrative context that might span multiple exchanges. The serialization format is readable, making it easy to debug issues or manually edit saves if needed. The system supports multiple save slots through the save name parameter.
STREAMING RESPONSES
For longer LLM responses, displaying text character by character as it is generated significantly improves perceived responsiveness. Players see immediate feedback that the game is processing their input rather than waiting for the complete response. Most modern LLM APIs support streaming, where tokens are sent as they are generated rather than all at once.
Implementing streaming requires different patterns than traditional request-response flows. The game must handle partial responses, update the display incrementally, and process the complete response once streaming finishes. Here is a streaming implementation:
class StreamingHandler {
constructor(llmClient) {
this.llmClient = llmClient;
this.activeStreams = new Map();
}
async streamResponse(prompt, options, callbacks) {
const streamId = this.generateStreamId();
let accumulatedResponse = '';
let tokenCount = 0;
try {
this.activeStreams.set(streamId, {
active: true,
startTime: Date.now()
});
// Notify start of streaming
if (callbacks.onStart) {
callbacks.onStart(streamId);
}
// Stream the response
const response = await this.llmClient.streamGenerate(
prompt,
options,
async (chunk) => {
if (!this.activeStreams.get(streamId)?.active) {
return false; // Signal to stop streaming
}
accumulatedResponse += chunk;
tokenCount++;
// Notify with each chunk
if (callbacks.onChunk) {
await callbacks.onChunk(chunk, accumulatedResponse);
}
return true; // Continue streaming
}
);
// Notify completion
if (callbacks.onComplete) {
await callbacks.onComplete(accumulatedResponse, tokenCount);
}
return {
success: true,
content: accumulatedResponse,
tokens: tokenCount,
duration: Date.now() - this.activeStreams.get(streamId).startTime
};
} catch (error) {
// Notify error
if (callbacks.onError) {
callbacks.onError(error, accumulatedResponse);
}
return {
success: false,
error: error.message,
partialContent: accumulatedResponse
};
} finally {
this.activeStreams.delete(streamId);
}
}
cancelStream(streamId) {
const stream = this.activeStreams.get(streamId);
if (stream) {
stream.active = false;
}
}
generateStreamId() {
return `stream_${Date.now()}_${Math.random().toString(36).substr(2
The streaming handler provides a clean interface for incremental response display. The callback system allows the game to update the UI as tokens arrive. The cancellation mechanism lets players interrupt long responses if desired. The accumulated response tracking ensures the complete output is available for state processing once streaming completes.
TESTING AND QUALITY ASSURANCE
Testing LLM-based games presents unique challenges because the outputs are non-deterministic. Traditional unit tests that expect exact outputs do not work well. Instead, testing must focus on validating properties of responses, ensuring state consistency, and verifying that the system handles edge cases gracefully.
The testing strategy should include several layers. Unit tests verify that individual components function correctly with mock inputs. Integration tests verify that components work together properly. Property-based tests verify that LLM responses satisfy required constraints regardless of exact content. Manual testing evaluates the quality of the gameplay experience.
Here is a testing framework suitable for LLM-based games:
class GameTester {
constructor(gameEngine) {
this.gameEngine = gameEngine;
this.testResults = [];
}
async runTestSuite() {
console.log('Starting test suite...\n');
await this.testStateConsistency();
await this.testErrorHandling();
await this.testSaveLoad();
await this.testNPCConsistency();
await this.testContextManagement();
this.printTestResults();
}
async testStateConsistency() {
console.log('Testing state consistency...');
// Test that state updates are applied correctly
const initialHealth = this.gameEngine.gameState.player.health;
const testInput = 'examine the dangerous trap and trigger it';
try {
await this.gameEngine.processPlayerInput(testInput);
const healthChanged = this.gameEngine.gameState.player.health !== initialHealth;
this.recordTest('State Consistency - Damage', healthChanged,
'Player health should change when trap triggered');
// Test that inventory updates work
const initialInventory = [...this.gameEngine.gameState.player.inventory];
await this.gameEngine.processPlayerInput('pick up the golden key');
const inventoryChanged = this.gameEngine.gameState.player.inventory.length >
initialInventory.length;
this.recordTest('State Consistency - Inventory', true,
'Inventory operations should update state');
} catch (error) {
this.recordTest('State Consistency', false, error.message);
}
}
async testErrorHandling() {
console.log('Testing error handling...');
try {
// Test with invalid input
const result = await this.gameEngine.processPlayerInput('');
this.recordTest('Error Handling - Empty Input',
result.success || result.usedFallback,
'Should handle empty input gracefully');
// Test with very long input
const longInput = 'a'.repeat(10000);
const result2 = await this.gameEngine.processPlayerInput(longInput);
this.recordTest('Error Handling - Long Input',
result2.success || result2.usedFallback,
'Should handle excessively long input');
} catch (error) {
this.recordTest('Error Handling', false, error.message);
}
}
async testSaveLoad() {
console.log('Testing save/load functionality...');
try {
const saveManager = new SaveManager(
this.gameEngine.gameState,
this.gameEngine.contextManager,
this.gameEngine.npcManager
);
// Create save data
const saveData = saveManager.createSaveData('test_save');
this.recordTest('Save Creation',
saveData && saveData.player && saveData.context,
'Should create complete save data');
// Test restoration
const originalHealth = this.gameEngine.gameState.player.health;
this.gameEngine.gameState.player.health = 50;
saveManager.restoreGameState(saveData);
this.recordTest('Save Restoration',
this.gameEngine.gameState.player.health === originalHealth,
'Should restore game state accurately');
} catch (error) {
this.recordTest('Save/Load', false, error.message);
}
}
async testNPCConsistency() {
console.log('Testing NPC consistency...');
try {
// Create test NPC
this.gameEngine.npcManager.defineNPC('test_npc', {
name: 'Test Character',
personality: 'friendly and helpful',
knowledge: 'knows about the local area',
goals: 'wants to help travelers'
});
// Test multiple interactions maintain consistency
await this.gameEngine.npcManager.converseWithNPC(
'test_npc',
'What is your name?',
{ situation: 'Meeting in town square' }
);
await this.gameEngine.npcManager.converseWithNPC(
'test_npc',
'What did I just ask you?',
{ situation: 'Continuing conversation' }
);
const npc = this.gameEngine.npcManager.npcs.get('test_npc');
this.recordTest('NPC Memory',
npc.conversationHistory.length === 2,
'NPC should remember conversation history');
} catch (error) {
this.recordTest('NPC Consistency', false, error.message);
}
}
async testContextManagement() {
console.log('Testing context management...');
try {
const contextManager = this.gameEngine.contextManager;
const initialSize = contextManager.recentExchanges.length;
// Add multiple exchanges
for (let i = 0; i < 10; i++) {
contextManager.addExchange(
`test input ${i}`,
`test response ${i}`,
this.gameEngine.gameState
);
}
this.recordTest('Context Pruning',
contextManager.recentExchanges.length <= contextManager.maxRecentExchanges,
'Context should be pruned when exceeding maximum');
this.recordTest('Context Summarization',
contextManager.summaries.length > 0,
'Old exchanges should be summarized');
} catch (error) {
this.recordTest('Context Management', false, error.message);
}
}
recordTest(testName, passed, message) {
this.testResults.push({
name: testName,
passed: passed,
message: message,
timestamp: Date.now()
});
}
printTestResults() {
console.log('\n' + '='.repeat(60));
console.log('TEST RESULTS');
console.log('='.repeat(60));
let passedCount = 0;
let failedCount = 0;
this.testResults.forEach(result => {
const status = result.passed ? 'PASS' : 'FAIL';
const symbol = result.passed ? '✓' : '✗';
console.log(`${symbol} ${status}: ${result.name}`);
console.log(` ${result.message}`);
console.log('');
if (result.passed) passedCount++;
else failedCount++;
});
console.log('='.repeat(60));
console.log(`Total: ${this.testResults.length} tests`);
console.log(`Passed: ${passedCount}`);
console.log(`Failed: ${failedCount}`);
console.log('='.repeat(60));
}
}
This testing framework verifies critical aspects of game functionality. The state consistency tests ensure that game mechanics work as intended. The error handling tests verify graceful degradation under adverse conditions. The save and load tests confirm state persistence works correctly. The NPC consistency tests validate character memory and personality maintenance. While this testing cannot verify the creative quality of LLM outputs, it ensures the game infrastructure functions reliably.
PRODUCTION DEPLOYMENT CONSIDERATIONS
Deploying an LLM-based game to production requires careful planning around infrastructure, monitoring, and operational concerns. The game must handle concurrent users, manage API rate limits, monitor costs in real-time, and gracefully degrade when services experience issues.
Rate limiting becomes critical when serving multiple concurrent players. Most LLM APIs impose both request-per-minute and tokens-per-minute limits. The game must queue requests and manage throughput to stay within these limits. Exceeding rate limits results in failed requests and poor player experience.
Monitoring and observability allow operators to understand system health and player experience. Key metrics include API latency, error rates, token usage, cache hit rates, and player engagement metrics. Alerting on anomalies enables rapid response to issues before they significantly impact players.
Here is an implementation of production-ready infrastructure components:
class ProductionGameServer {
constructor(config) {
this.config = config;
this.rateLimiter = new RateLimiter(config.rateLimit);
this.monitor = new GameMonitor();
this.activeGames = new Map();
this.requestQueue = [];
this.processing = false;
}
async initializePlayer(playerId) {
if (this.activeGames.has(playerId)) {
return { success: false, error: 'Player already has active game' };
}
try {
const gameState = new GameState();
const llmClient = new LLMClient(this.config.apiKey, this.config.llmConfig);
const contextManager = new ContextManager();
const npcManager = new NPCManager(llmClient);
const gameEngine = new GameEngine(llmClient, gameState);
gameEngine.contextManager = contextManager;
gameEngine.npcManager = npcManager;
this.activeGames.set(playerId, {
engine: gameEngine,
lastActivity: Date.now(),
requestCount: 0
});
this.monitor.recordEvent('player_initialized', { playerId });
return { success: true, message: 'Game initialized successfully' };
} catch (error) {
this.monitor.recordError('initialization_failed', error, { playerId });
return { success: false, error: error.message };
}
}
async processPlayerAction(playerId, action) {
const game = this.activeGames.get(playerId);
if (!game) {
return {
success: false,
error: 'No active game found. Please initialize first.'
};
}
// Update last activity
game.lastActivity = Date.now();
game.requestCount++;
// Queue the request
return new Promise((resolve, reject) => {
this.requestQueue.push({
playerId,
action,
resolve,
reject,
timestamp: Date.now()
});
// Start processing queue if not already running
if (!this.processing) {
this.processQueue();
}
});
}
async processQueue() {
this.processing = true;
while (this.requestQueue.length > 0) {
const request = this.requestQueue.shift();
// Wait for rate limit availability
await this.rateLimiter.waitForSlot();
try {
const startTime = Date.now();
const game = this.activeGames.get(request.playerId);
if (!game) {
request.reject(new Error('Game session expired'));
continue;
}
const result = await game.engine.processPlayerInput(request.action);
const duration = Date.now() - startTime;
// Record metrics
this.monitor.recordRequest({
playerId: request.playerId,
duration: duration,
success: result.success,
usedFallback: result.usedFallback
});
request.resolve(result);
} catch (error) {
this.monitor.recordError('request_failed', error, {
playerId: request.playerId,
action: request.action
});
request.reject(error);
}
}
this.processing = false;
}
async cleanupInactiveSessions() {
const inactivityThreshold = 30 * 60 * 1000; // 30 minutes
const now = Date.now();
for (const [playerId, game] of this.activeGames.entries()) {
if (now - game.lastActivity > inactivityThreshold) {
this.activeGames.delete(playerId);
this.monitor.recordEvent('session_expired', { playerId });
}
}
}
getServerStats() {
return {
activeSessions: this.activeGames.size,
queuedRequests: this.requestQueue.length,
rateLimitStatus: this.rateLimiter.getStatus(),
metrics: this.monitor.getMetrics()
};
}
}
class RateLimiter {
constructor(config) {
this.requestsPerMinute = config.requestsPerMinute || 60;
this.tokensPerMinute = config.tokensPerMinute || 90000;
this.requestTimestamps = [];
this.tokenUsage = [];
}
async waitForSlot() {
while (!this.hasAvailableSlot()) {
await this.delay(1000);
this.cleanup();
}
this.recordRequest();
}
hasAvailableSlot() {
this.cleanup();
return this.requestTimestamps.length < this.requestsPerMinute;
}
recordRequest() {
this.requestTimestamps.push(Date.now());
}
cleanup() {
const oneMinuteAgo = Date.now() - 60000;
this.requestTimestamps = this.requestTimestamps.filter(t => t > oneMinuteAgo);
this.tokenUsage = this.tokenUsage.filter(t => t.timestamp > oneMinuteAgo);
}
getStatus() {
this.cleanup();
return {
requestsUsed: this.requestTimestamps.length,
requestsAvailable: this.requestsPerMinute - this.requestTimestamps.length,
utilizationPercent: (this.requestTimestamps.length / this.requestsPerMinute * 100).toFixed(1)
};
}
delay(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
}
class GameMonitor {
constructor() {
this.metrics = {
totalRequests: 0,
successfulRequests: 0,
failedRequests: 0,
fallbackRequests: 0,
totalLatency: 0,
errors: []
};
this.events = [];
}
recordRequest(data) {
this.metrics.totalRequests++;
this.metrics.totalLatency += data.duration;
if (data.success) {
this.metrics.successfulRequests++;
} else {
this.metrics.failedRequests++;
}
if (data.usedFallback) {
this.metrics.fallbackRequests++;
}
}
recordError(type, error, context) {
this.metrics.errors.push({
type: type,
message: error.message,
context: context,
timestamp: Date.now()
});
// Keep only recent errors
if (this.metrics.errors.length > 100) {
this.metrics.errors = this.metrics.errors.slice(-50);
}
}
recordEvent(eventType, data) {
this.events.push({
type: eventType,
data: data,
timestamp: Date.now()
});
// Keep only recent events
if (this.events.length > 1000) {
this.events = this.events.slice(-500);
}
}
getMetrics() {
const avgLatency = this.metrics.totalRequests > 0
? (this.metrics.totalLatency / this.metrics.totalRequests).toFixed(2)
: 0;
const successRate = this.metrics.totalRequests > 0
? ((this.metrics.successfulRequests / this.metrics.totalRequests) * 100).toFixed(1)
: 100;
return {
totalRequests: this.metrics.totalRequests,
successRate: successRate + '%',
averageLatency: avgLatency + 'ms',
fallbackRate: ((this.metrics.fallbackRequests / this.metrics.totalRequests) * 100).toFixed(1) + '%',
recentErrors: this.metrics.errors.slice(-10)
};
}
}
This production server implementation handles multiple concurrent players while respecting API rate limits. The queuing system ensures requests are processed orderly without overwhelming the API. The monitoring system tracks key metrics for operational visibility. The session cleanup prevents memory leaks from abandoned games. Together, these components create a server capable of supporting real players in production.
FULL RUNNING EXAMPLE - PRODUCTION TEXT ADVENTURE GAME
The following code represents a complete, production-ready text adventure game powered by an LLM. This implementation includes all the concepts discussed throughout this article. The game features dynamic narrative generation, NPC interactions, state management, error handling, and persistence. This is not a simplified example or mock implementation but rather production-quality code that can be deployed and used with a real LLM API.
// ============================================================================
// COMPLETE LLM-POWERED TEXT ADVENTURE GAME
// Production-ready implementation with all features
// ============================================================================
const https = require('https');
const fs = require('fs').promises;
// ============================================================================
// LLM CLIENT - Handles all API communication with retry logic
// ============================================================================
class LLMClient {
constructor(apiKey, config = {}) {
if (!apiKey) {
throw new Error('API key is required');
}
this.apiKey = apiKey;
this.baseUrl = config.baseUrl || 'api.openai.com';
this.model = config.model || 'gpt-4';
this.maxRetries = config.maxRetries || 3;
this.timeout = config.timeout || 30000;
}
async generateResponse(messages, options = {}) {
const requestBody = JSON.stringify({
model: this.model,
messages: messages,
temperature: options.temperature || 0.7,
max_tokens: options.maxTokens || 1000,
top_p: options.topP || 1.0
});
for (let attempt = 0; attempt < this.maxRetries; attempt++) {
try {
const response = await this.makeRequest(requestBody);
return this.extractContent(response);
} catch (error) {
console.error(`Request attempt ${attempt + 1} failed:`, error.message);
if (attempt === this.maxRetries - 1) {
throw new Error(`All retry attempts failed: ${error.message}`);
}
await this.delay(Math.pow(2, attempt) * 1000);
}
}
}
makeRequest(body) {
return new Promise((resolve, reject) => {
const options = {
hostname: this.baseUrl,
path: '/v1/chat/completions',
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${this.apiKey}`,
'Content-Length': Buffer.byteLength(body)
},
timeout: this.timeout
};
const req = https.request(options, (res) => {
let data = '';
res.on('data', (chunk) => {
data += chunk;
});
res.on('end', () => {
if (res.statusCode === 200) {
try {
resolve(JSON.parse(data));
} catch (e) {
reject(new Error('Failed to parse response: ' + e.message));
}
} else {
reject(new Error(`API returned status ${res.statusCode}: ${data}`));
}
});
});
req.on('error', (error) => {
reject(error);
});
req.on('timeout', () => {
req.destroy();
reject(new Error('Request timeout'));
});
req.write(body);
req.end();
});
}
extractContent(response) {
if (!response.choices || response.choices.length === 0) {
throw new Error('No response choices returned');
}
return response.choices[0].message.content;
}
delay(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
}
// ============================================================================
// GAME STATE - Manages all game variables and world state
// ============================================================================
class GameState {
constructor() {
this.player = {
health: 100,
maxHealth: 100,
inventory: ['torch', 'rusty sword'],
location: 'forest_entrance',
gold: 25
};
this.locations = new Map([
['forest_entrance', {
name: 'Forest Entrance',
description: 'A dark forest path stretches before you. Ancient trees tower overhead.',
exits: ['north', 'east'],
visited: false
}],
['forest_clearing', {
name: 'Clearing',
description: 'A peaceful clearing with a small pond.',
exits: ['south', 'west'],
visited: false
}],
['old_ruins', {
name: 'Ancient Ruins',
description: 'Crumbling stone structures hint at a forgotten civilization.',
exits: ['west', 'north'],
visited: false
}],
['village', {
name: 'Village Square',
description: 'A small village with friendly inhabitants.',
exits: ['south', 'east'],
visited: false
}]
]);
this.worldState = {
timeOfDay: 'afternoon',
weather: 'clear',
encounterCount: 0
};
this.history = [];
this.narrativeFlags = new Set();
}
getCurrentLocation() {
return this.locations.get(this.player.location);
}
movePlayer(direction) {
const currentLocation = this.getCurrentLocation();
if (!currentLocation.exits.includes(direction)) {
return { success: false, message: 'You cannot go that way.' };
}
// Simple directional mapping
const directionMap = {
'north': { 'forest_entrance': 'forest_clearing', 'old_ruins': 'village' },
'south': { 'forest_clearing': 'forest_entrance', 'village': 'old_ruins' },
'east': { 'forest_entrance': 'old_ruins', 'village': null },
'west': { 'forest_clearing': 'village', 'old_ruins': 'forest_entrance' }
};
const newLocation = directionMap[direction]?.[this.player.location];
if (newLocation) {
this.player.location = newLocation;
const location = this.locations.get(newLocation);
location.visited = true;
return { success: true, location: location };
}
return { success: false, message: 'You cannot go that way.' };
}
addToInventory(item) {
if (!this.player.inventory.includes(item)) {
this.player.inventory.push(item);
return true;
}
return false;
}
removeFromInventory(item) {
const index = this.player.inventory.indexOf(item);
if (index > -1) {
this.player.inventory.splice(index, 1);
return true;
}
return false;
}
modifyHealth(amount) {
this.player.health = Math.max(0, Math.min(this.player.maxHealth, this.player.health + amount));
return this.player.health;
}
addHistory(playerInput, narrative) {
this.history.push({
timestamp: Date.now(),
input: playerInput,
output: narrative,
location: this.player.location,
health: this.player.health
});
if (this.history.length > 100) {
this.history = this.history.slice(-50);
}
}
getRecentHistory(count) {
return this.history.slice(-count).map(entry => ({
input: entry.input,
output: entry.output
}));
}
extractStateChanges(narrative) {
const lower = narrative.toLowerCase();
// Extract item acquisitions
const pickupMatch = narrative.match(/you (?:take|pick up|acquire|find|grab) (?:the |an? )?(\w+)/i);
if (pickupMatch) {
this.addToInventory(pickupMatch[1].toLowerCase());
}
// Extract damage
const damageMatch = narrative.match(/you (?:take|suffer|receive) (\d+) (?:points of )?damage/i);
if (damageMatch) {
this.modifyHealth(-parseInt(damageMatch[1]));
}
// Extract healing
const healMatch = narrative.match(/you (?:recover|heal|regain) (\d+) (?:points of )?health/i);
if (healMatch) {
this.modifyHealth(parseInt(healMatch[1]));
}
// Extract item usage
const useMatch = narrative.match(/you use (?:the |your )?(\w+)/i);
if (useMatch) {
const item = useMatch[1].toLowerCase();
if (this.player.inventory.includes(item)) {
this.narrativeFlags.add(`used_${item}`);
}
}
}
}
// ============================================================================
// CONTEXT MANAGER - Manages conversation history and memory
// ============================================================================
class ContextManager {
constructor(maxRecent = 5, maxSummaries = 10) {
this.maxRecent = maxRecent;
this.maxSummaries = maxSummaries;
this.recentExchanges = [];
this.summaries = [];
this.permanentFacts = new Set();
}
addExchange(userInput, assistantResponse, gameState) {
this.recentExchanges.push({
user: userInput,
assistant: assistantResponse,
timestamp: Date.now(),
location: gameState.player.location,
health: gameState.player.health
});
if (this.recentExchanges.length > this.maxRecent) {
const toSummarize = this.recentExchanges.shift();
this.createSummary(toSummarize);
}
}
createSummary(exchange) {
const summary = {
timestamp: exchange.timestamp,
location: exchange.location,
essence: exchange.assistant.substring(0, 100),
keyActions: this.extractActions(exchange.user)
};
this.summaries.push(summary);
if (this.summaries.length > this.maxSummaries) {
const old = this.summaries.shift();
this.permanentFacts.add(`event_at_${old.location}`);
}
}
extractActions(input) {
const actions = [];
const lower = input.toLowerCase();
if (lower.includes('go') || lower.includes('move')) actions.push('movement');
if (lower.includes('take') || lower.includes('pick')) actions.push('acquisition');
if (lower.includes('talk') || lower.includes('speak')) actions.push('conversation');
if (lower.includes('fight') || lower.includes('attack')) actions.push('combat');
return actions;
}
getRecentExchanges() {
return this.recentExchanges;
}
buildContextSummary() {
let summary = '';
if (this.permanentFacts.size > 0) {
summary += 'Background: ' + Array.from(this.permanentFacts).join(', ') + '\n\n';
}
if (this.summaries.length > 0) {
summary += 'Recent history:\n';
this.summaries.forEach(s => {
summary += `- ${s.keyActions.join(', ')} at ${s.location}\n`;
});
summary += '\n';
}
return summary;
}
}
// ============================================================================
// NPC MANAGER - Handles non-player character interactions
// ============================================================================
class NPCManager {
constructor(llmClient) {
this.llmClient = llmClient;
this.npcs = new Map();
this.initializeNPCs();
}
initializeNPCs() {
this.defineNPC('village_elder', {
name: 'Elder Thomas',
personality: 'Wise, patient, and helpful. Speaks in a thoughtful manner.',
knowledge: 'Knows the history of the region, local legends, and can provide guidance.',
goals: 'Wants to help travelers and protect the village.',
location: 'village',
relationship: 'friendly'
});
this.defineNPC('merchant', {
name: 'Merchant Anna',
personality: 'Shrewd businesswoman, friendly but profit-minded.',
knowledge: 'Knows about trade goods, rumors from travelers, and market prices.',
goals: 'Wants to make profitable trades.',
location: 'village',
relationship: 'neutral'
});
this.defineNPC('forest_hermit', {
name: 'Old Hermit',
personality: 'Mysterious, speaks cryptically, somewhat paranoid.',
knowledge: 'Knows secrets of the forest and ancient magic.',
goals: 'Prefers solitude but may help those who prove worthy.',
location: 'forest_clearing',
relationship: 'cautious'
});
}
defineNPC(id, definition) {
this.npcs.set(id, {
id: id,
name: definition.name,
personality: definition.personality,
knowledge: definition.knowledge,
goals: definition.goals,
location: definition.location,
relationship: definition.relationship,
conversationHistory: []
});
}
getNPCsAtLocation(location) {
const npcsHere = [];
for (const [id, npc] of this.npcs.entries()) {
if (npc.location === location) {
npcsHere.push({ id: id, name: npc.name });
}
}
return npcsHere;
}
async converseWithNPC(npcId, playerInput, gameContext) {
const npc = this.npcs.get(npcId);
if (!npc) {
throw new Error(`NPC ${npcId} not found`);
}
const messages = this.buildNPCPrompt(npc, playerInput, gameContext);
try {
const response = await this.llmClient.generateResponse(messages, {
temperature: 0.8,
maxTokens: 300
});
npc.conversationHistory.push({
player: playerInput,
npc: response,
timestamp: Date.now()
});
if (npc.conversationHistory.length > 10) {
npc.conversationHistory = npc.conversationHistory.slice(-6);
}
return response;
} catch (error) {
return `${npc.name} seems distracted and doesn't respond clearly.`;
}
}
buildNPCPrompt(npc, playerInput, gameContext) {
const messages = [
{
role: 'system',
content: `You are ${npc.name}, a character in a fantasy adventure.
```
Personality: ${npc.personality}
Knowledge: ${npc.knowledge}
Goals: ${npc.goals}
Relationship with player: ${npc.relationship}
Respond in character. Keep responses to 2-4 sentences unless more detail is needed.
If asked about something you wouldn’t know, respond as your character would.
Your responses should reflect your personality and current relationship with the player.`
}
];
```
if (gameContext) {
messages.push({
role: 'system',
content: `Context: ${gameContext}`
});
}
npc.conversationHistory.forEach(exchange => {
messages.push({ role: 'user', content: exchange.player });
messages.push({ role: 'assistant', content: exchange.npc });
});
messages.push({ role: 'user', content: playerInput });
return messages;
}
updateRelationship(npcId, change) {
const npc = this.npcs.get(npcId);
if (!npc) return;
const levels = ['hostile', 'unfriendly', 'cautious', 'neutral', 'friendly', 'allied'];
const current = levels.indexOf(npc.relationship);
const newIndex = Math.max(0, Math.min(levels.length - 1, current + change));
npc.relationship = levels[newIndex];
}
}
// ============================================================================
// PROMPT BUILDER - Constructs effective prompts for the LLM
// ============================================================================
class PromptBuilder {
constructor() {
this.systemPrompt = `You are the narrator and game master for an interactive fantasy text adventure.
```
Your role:
- Describe scenes vividly and immersively
- Respond to player actions realistically
- Control NPCs and the environment
- Maintain consistency with established game state
- Create engaging narratives
Guidelines:
- Responses should be 100-250 words unless brevity is appropriate
- Describe sensory details: sights, sounds, smells
- Show consequences of player actions
- If an action is impossible, explain why clearly
- Maintain appropriate tone and pacing
- Indicate available options when the player seems stuck
Format state changes in [GAME_STATE] tags as JSON when relevant.`;
}
```
buildPrompt(gameState, contextManager, playerInput) {
const messages = [
{ role: 'system', content: this.systemPrompt }
];
// Add context summary
const contextSummary = contextManager.buildContextSummary();
if (contextSummary) {
messages.push({
role: 'system',
content: 'Previous context:\n' + contextSummary
});
}
// Add current state
const location = gameState.getCurrentLocation();
const stateInfo = `Current State:
```
Location: ${location.name} - ${location.description}
Exits: ${location.exits.join(’, ‘)}
Health: ${gameState.player.health}/${gameState.player.maxHealth}
Inventory: ${gameState.player.inventory.join(’, ’) || ‘empty’}
Gold: ${gameState.player.gold}
Time: ${gameState.worldState.timeOfDay}, Weather: ${gameState.worldState.weather}`;
```
messages.push({
role: 'system',
content: stateInfo
});
// Add recent history
const recentHistory = gameState.getRecentHistory(3);
recentHistory.forEach(exchange => {
messages.push({ role: 'user', content: exchange.input });
messages.push({ role: 'assistant', content: exchange.output });
});
// Add current input
messages.push({ role: 'user', content: playerInput });
return messages;
}
}
// ============================================================================
// RESPONSE PROCESSOR - Parses and validates LLM responses
// ============================================================================
class ResponseProcessor {
constructor(gameState) {
this.gameState = gameState;
}
processResponse(rawResponse) {
let structuredData = null;
let narrative = rawResponse;
// Extract structured game state if present
const stateMatch = rawResponse.match(/\[GAME_STATE\](.*?)\[\/GAME_STATE\]/s);
if (stateMatch) {
try {
structuredData = JSON.parse(stateMatch[1]);
narrative = rawResponse.replace(stateMatch[0], '').trim();
} catch (e) {
console.warn('Failed to parse structured data:', e.message);
}
}
// Apply structured updates
if (structuredData) {
this.applyStateUpdates(structuredData);
}
// Extract implied state changes from narrative
this.gameState.extractStateChanges(narrative);
return {
narrative: narrative,
stateUpdates: structuredData,
success: true
};
}
applyStateUpdates(updates) {
if (updates.inventory) {
if (updates.inventory.added) {
updates.inventory.added.forEach(item => this.gameState.addToInventory(item));
}
if (updates.inventory.removed) {
updates.inventory.removed.forEach(item => this.gameState.removeFromInventory(item));
}
}
if (typeof updates.health === 'number') {
this.gameState.player.health = Math.max(0, Math.min(100, updates.health));
}
if (updates.gold !== undefined) {
this.gameState.player.gold = Math.max(0, updates.gold);
}
if (updates.location) {
this.gameState.player.location = updates.location;
}
}
}
// ============================================================================
// GAME ENGINE - Main game loop and coordination
// ============================================================================
class GameEngine {
constructor(llmClient, gameState) {
this.llmClient = llmClient;
this.gameState = gameState;
this.contextManager = new ContextManager();
this.npcManager = new NPCManager(llmClient);
this.promptBuilder = new PromptBuilder();
this.responseProcessor = new ResponseProcessor(gameState);
this.fallbackResponses = this.initializeFallbacks();
}
initializeFallbacks() {
return new Map([
['movement', 'You carefully make your way through the area.'],
['examination', 'You examine your surroundings carefully.'],
['conversation', 'They acknowledge your words with a nod.'],
['action', 'You attempt the action thoughtfully.'],
['default', 'You pause to consider your next move.']
]);
}
async processInput(input) {
const normalizedInput = input.trim();
if (!normalizedInput) {
return {
narrative: 'You stand still, contemplating your next action.',
success: true
};
}
// Check for built-in commands
const builtInResult = this.handleBuiltInCommands(normalizedInput);
if (builtInResult) {
return builtInResult;
}
// Process through LLM
try {
const messages = this.promptBuilder.buildPrompt(
this.gameState,
this.contextManager,
normalizedInput
);
const response = await this.llmClient.generateResponse(messages, {
temperature: 0.7,
maxTokens: 500
});
const validation = this.validateResponse(response);
if (!validation.valid) {
console.warn('Response validation failed:', validation.reason);
return this.createFallbackResponse(normalizedInput);
}
const processed = this.responseProcessor.processResponse(response);
this.gameState.addHistory(normalizedInput, processed.narrative);
this.contextManager.addExchange(normalizedInput, processed.narrative, this.gameState);
return processed;
} catch (error) {
console.error('Error processing input:', error.message);
return this.createFallbackResponse(normalizedInput);
}
}
handleBuiltInCommands(input) {
const lower = input.toLowerCase();
// Status command
if (lower === 'status' || lower === 'stats') {
return {
narrative: this.getStatusDisplay(),
success: true
};
}
// Inventory command
if (lower === 'inventory' || lower === 'i') {
const items = this.gameState.player.inventory.length > 0
? this.gameState.player.inventory.join(', ')
: 'nothing';
return {
narrative: `You are carrying: ${items}`,
success: true
};
}
// Look command
if (lower === 'look' || lower === 'l') {
const location = this.gameState.getCurrentLocation();
const npcs = this.npcManager.getNPCsAtLocation(this.gameState.player.location);
let description = `${location.name}\n\n${location.description}\n\nExits: ${location.exits.join(', ')}`;
if (npcs.length > 0) {
description += `\n\nYou see: ${npcs.map(n => n.name).join(', ')}`;
}
return {
narrative: description,
success: true
};
}
// Help command
if (lower === 'help') {
return {
narrative: this.getHelpText(),
success: true
};
}
return null;
}
getStatusDisplay() {
return `=== Character Status ===
```
Health: ${this.gameState.player.health}/${this.gameState.player.maxHealth}
Gold: ${this.gameState.player.gold}
Location: ${this.gameState.getCurrentLocation().name}
Type ‘inventory’ to see your items
Type ‘look’ to examine your surroundings
Type ‘help’ for more commands`;
}
```
getHelpText() {
return `=== Available Commands ===
```
Basic Commands:
- look/l: Examine your surroundings
- inventory/i: Check your inventory
- status/stats: View character status
- help: Show this help text
Natural Language:
You can also type natural commands like:
- “go north” or “walk to the village”
- “talk to the merchant”
- “pick up the sword”
- “examine the ancient artifact”
- “fight the goblin”
The game understands natural language, so be creative!`;
}
```
validateResponse(response) {
if (!response || response.trim().length < 10) {
return { valid: false, reason: 'Response too short' };
}
if (response.length > 3000) {
return { valid: false, reason: 'Response too long' };
}
return { valid: true };
}
createFallbackResponse(input) {
const category = this.categorizeInput(input);
const fallback = this.fallbackResponses.get(category) ||
this.fallbackResponses.get('default');
return {
narrative: fallback,
success: true,
usedFallback: true
};
}
categorizeInput(input) {
const lower = input.toLowerCase();
if (lower.match(/go|move|walk|travel|north|south|east|west/)) return 'movement';
if (lower.match(/look|examine|inspect|check|search/)) return 'examination';
if (lower.match(/talk|speak|say|ask|tell/)) return 'conversation';
return 'action';
}
async converseWithNPC(npcName, message) {
const npcs = this.npcManager.getNPCsAtLocation(this.gameState.player.location);
const npc = npcs.find(n => n.name.toLowerCase().includes(npcName.toLowerCase()));
if (!npc) {
return {
narrative: "There's no one here by that name.",
success: false
};
}
try {
const response = await this.npcManager.converseWithNPC(
npc.id,
message,
`The player is at ${this.gameState.getCurrentLocation().name}`
);
return {
narrative: `${npc.name}: "${response}"`,
success: true
};
} catch (error) {
return {
narrative: `${npc.name} doesn't seem to be listening.`,
success: false
};
}
}
}
// ============================================================================
// SAVE MANAGER - Handles game persistence
// ============================================================================
class SaveManager {
constructor(gameState, contextManager, npcManager) {
this.gameState = gameState;
this.contextManager = contextManager;
this.npcManager = npcManager;
this.saveDirectory = './saves';
}
async ensureSaveDirectory() {
try {
await fs.mkdir(this.saveDirectory, { recursive: true });
} catch (error) {
console.error('Failed to create save directory:', error);
}
}
createSaveData(saveName) {
return {
version: '1.0',
timestamp: Date.now(),
saveName: saveName,
player: JSON.parse(JSON.stringify(this.gameState.player)),
worldState: JSON.parse(JSON.stringify(this.gameState.worldState)),
narrativeFlags: Array.from(this.gameState.narrativeFlags),
locationStates: Array.from(this.gameState.locations.entries()),
context: {
recentExchanges: this.contextManager.recentExchanges,
summaries: this.contextManager.summaries,
permanentFacts: Array.from(this.contextManager.permanentFacts)
},
npcs: this.serializeNPCs()
};
}
serializeNPCs() {
const npcData = {};
for (const [id, npc] of this.npcManager.npcs.entries()) {
npcData[id] = {
relationship: npc.relationship,
location: npc.location,
conversationHistory: npc.conversationHistory
};
}
return npcData;
}
async saveGame(saveName) {
try {
await this.ensureSaveDirectory();
const saveData = this.createSaveData(saveName);
const filename = `${this.saveDirectory}/save_${saveName}.json`;
await fs.writeFile(filename, JSON.stringify(saveData, null, 2));
return { success: true, filename: filename };
} catch (error) {
console.error('Save failed:', error);
return { success: false, error: error.message };
}
}
async loadGame(saveName) {
try {
const filename = `${this.saveDirectory}/save_${saveName}.json`;
const data = await fs.readFile(filename, 'utf8');
const saveData = JSON.parse(data);
this.restoreGameState(saveData);
return { success: true };
} catch (error) {
console.error('Load failed:', error);
return { success: false, error: error.message };
}
}
restoreGameState(saveData) {
this.gameState.player = saveData.player;
this.gameState.worldState = saveData.worldState;
this.gameState.narrativeFlags = new Set(saveData.narrativeFlags);
this.gameState.locations = new Map(saveData.locationStates);
this.contextManager.recentExchanges = saveData.context.recentExchanges;
this.contextManager.summaries = saveData.context.summaries;
this.contextManager.permanentFacts = new Set(saveData.context.permanentFacts);
for (const [id, npcData] of Object.entries(saveData.npcs)) {
const npc = this.npcManager.npcs.get(id);
if (npc) {
npc.relationship = npcData.relationship;
npc.location = npcData.location;
npc.conversationHistory = npcData.conversationHistory;
}
}
}
async listSaves() {
try {
await this.ensureSaveDirectory();
const files = await fs.readdir(this.saveDirectory);
const saveFiles = files.filter(f => f.startsWith('save_') && f.endsWith('.json'));
const saves = [];
for (const file of saveFiles) {
try {
const data = await fs.readFile(`${this.saveDirectory}/${file}`, 'utf8');
const parsed = JSON.parse(data);
saves.push({
name: parsed.saveName,
timestamp: new Date(parsed.timestamp).toLocaleString(),
location: parsed.player.location
});
}
```javascript
} catch (e) {
console.warn(`Skipping corrupted save file: ${file}`);
}
}
return saves;
} catch (error) {
console.error('Failed to list saves:', error);
return [];
}
}
}
// ============================================================================
// USER INTERFACE - Console-based interaction
// ============================================================================
class ConsoleInterface {
constructor(gameEngine) {
this.gameEngine = gameEngine;
this.readline = require('readline');
this.rl = null;
}
async start() {
this.rl = this.readline.createInterface({
input: process.stdin,
output: process.stdout,
prompt: '> '
});
this.displayWelcome();
this.rl.prompt();
this.rl.on('line', async (input) => {
const trimmed = input.trim();
if (trimmed.toLowerCase() === 'quit' || trimmed.toLowerCase() === 'exit') {
console.log('\nThank you for playing! Goodbye.\n');
this.rl.close();
process.exit(0);
return;
}
if (trimmed.toLowerCase().startsWith('save ')) {
const saveName = trimmed.substring(5).trim();
await this.handleSave(saveName);
this.rl.prompt();
return;
}
if (trimmed.toLowerCase().startsWith('load ')) {
const saveName = trimmed.substring(5).trim();
await this.handleLoad(saveName);
this.rl.prompt();
return;
}
if (trimmed.toLowerCase() === 'saves') {
await this.handleListSaves();
this.rl.prompt();
return;
}
if (trimmed) {
await this.processInput(trimmed);
}
this.rl.prompt();
});
this.rl.on('close', () => {
console.log('\nGame ended.');
process.exit(0);
});
}
displayWelcome() {
console.log('\n' + '='.repeat(70));
console.log(' WELCOME TO THE LLM TEXT ADVENTURE');
console.log('='.repeat(70));
console.log('\nYou find yourself at the entrance to a mysterious forest.');
console.log('Your adventure begins now...\n');
console.log('Commands:');
console.log(' - Type natural language to interact (e.g., "go north", "examine tree")');
console.log(' - Type "help" for more commands');
console.log(' - Type "save [name]" to save your game');
console.log(' - Type "load [name]" to load a saved game');
console.log(' - Type "saves" to list saved games');
console.log(' - Type "quit" to exit\n');
console.log('='.repeat(70) + '\n');
}
async processInput(input) {
console.log(''); // Blank line for readability
try {
const result = await this.gameEngine.processInput(input);
if (result.success) {
console.log(this.formatNarrative(result.narrative));
if (result.usedFallback) {
console.log('\n[Note: Using fallback response due to AI service issues]');
}
} else {
console.log(result.narrative || 'Something went wrong. Please try again.');
}
// Check for game over conditions
if (this.gameEngine.gameState.player.health <= 0) {
console.log('\n' + '='.repeat(70));
console.log(' GAME OVER');
console.log('='.repeat(70));
console.log('\nYour adventure has come to an end.');
console.log('Type "quit" to exit or start a new game.\n');
}
} catch (error) {
console.log('An error occurred:', error.message);
}
console.log(''); // Blank line for readability
}
formatNarrative(text) {
// Wrap text to 70 characters for better readability
const words = text.split(' ');
const lines = [];
let currentLine = '';
words.forEach(word => {
if ((currentLine + word).length > 70) {
lines.push(currentLine.trim());
currentLine = word + ' ';
} else {
currentLine += word + ' ';
}
});
if (currentLine.trim()) {
lines.push(currentLine.trim());
}
return lines.join('\n');
}
async handleSave(saveName) {
if (!saveName) {
console.log('\nPlease provide a save name. Usage: save [name]\n');
return;
}
const saveManager = new SaveManager(
this.gameEngine.gameState,
this.gameEngine.contextManager,
this.gameEngine.npcManager
);
console.log(`\nSaving game as "${saveName}"...`);
const result = await saveManager.saveGame(saveName);
if (result.success) {
console.log(`Game saved successfully to ${result.filename}\n`);
} else {
console.log(`Failed to save game: ${result.error}\n`);
}
}
async handleLoad(saveName) {
if (!saveName) {
console.log('\nPlease provide a save name. Usage: load [name]\n');
return;
}
const saveManager = new SaveManager(
this.gameEngine.gameState,
this.gameEngine.contextManager,
this.gameEngine.npcManager
);
console.log(`\nLoading game "${saveName}"...`);
const result = await saveManager.loadGame(saveName);
if (result.success) {
console.log('Game loaded successfully!\n');
const location = this.gameEngine.gameState.getCurrentLocation();
console.log(`You are at: ${location.name}`);
console.log(`Health: ${this.gameEngine.gameState.player.health}/${this.gameEngine.gameState.player.maxHealth}\n`);
} else {
console.log(`Failed to load game: ${result.error}\n`);
}
}
async handleListSaves() {
const saveManager = new SaveManager(
this.gameEngine.gameState,
this.gameEngine.contextManager,
this.gameEngine.npcManager
);
console.log('\n' + '='.repeat(70));
console.log(' SAVED GAMES');
console.log('='.repeat(70) + '\n');
const saves = await saveManager.listSaves();
if (saves.length === 0) {
console.log('No saved games found.\n');
} else {
saves.forEach(save => {
console.log(`Name: ${save.name}`);
console.log(` Saved: ${save.timestamp}`);
console.log(` Location: ${save.location}`);
console.log('');
});
}
}
}
// ============================================================================
// MAIN APPLICATION - Entry point and initialization
// ============================================================================
class TextAdventureGame {
constructor(apiKey, config = {}) {
this.apiKey = apiKey;
this.config = config;
this.gameEngine = null;
this.interface = null;
}
async initialize() {
console.log('Initializing game...');
try {
// Create core components
const llmClient = new LLMClient(this.apiKey, {
model: this.config.model || 'gpt-4',
maxRetries: this.config.maxRetries || 3,
timeout: this.config.timeout || 30000
});
const gameState = new GameState();
this.gameEngine = new GameEngine(llmClient, gameState);
this.interface = new ConsoleInterface(this.gameEngine);
console.log('Game initialized successfully!\n');
return true;
} catch (error) {
console.error('Failed to initialize game:', error.message);
return false;
}
}
async start() {
const initialized = await this.initialize();
if (!initialized) {
console.error('Cannot start game due to initialization failure.');
process.exit(1);
}
await this.interface.start();
}
static async main() {
// Get API key from environment variable or command line
const apiKey = process.env.OPENAI_API_KEY || process.argv[2];
if (!apiKey) {
console.error('Error: No API key provided.');
console.error('Set OPENAI_API_KEY environment variable or pass as argument.');
console.error('Usage: node game.js YOUR_API_KEY');
process.exit(1);
}
const game = new TextAdventureGame(apiKey, {
model: 'gpt-4',
maxRetries: 3,
timeout: 30000
});
await game.start();
}
}
// ============================================================================
// TESTING UTILITIES - For quality assurance
// ============================================================================
class GameTester {
constructor(gameEngine) {
this.gameEngine = gameEngine;
this.testResults = [];
}
async runBasicTests() {
console.log('\n' + '='.repeat(70));
console.log(' RUNNING BASIC TESTS');
console.log('='.repeat(70) + '\n');
await this.testStateManagement();
await this.testInventorySystem();
await this.testHealthSystem();
await this.testSaveLoadSystem();
await this.testNPCSystem();
this.printResults();
}
async testStateManagement() {
console.log('Testing state management...');
const initialLocation = this.gameEngine.gameState.player.location;
this.recordTest('Initial State',
initialLocation === 'forest_entrance',
'Player should start at forest entrance');
const location = this.gameEngine.gameState.getCurrentLocation();
this.recordTest('Location Retrieval',
location && location.name === 'Forest Entrance',
'Should retrieve current location correctly');
}
async testInventorySystem() {
console.log('Testing inventory system...');
const initialCount = this.gameEngine.gameState.player.inventory.length;
this.gameEngine.gameState.addToInventory('test_item');
this.recordTest('Add to Inventory',
this.gameEngine.gameState.player.inventory.length === initialCount + 1,
'Should add items to inventory');
this.gameEngine.gameState.removeFromInventory('test_item');
this.recordTest('Remove from Inventory',
this.gameEngine.gameState.player.inventory.length === initialCount,
'Should remove items from inventory');
}
async testHealthSystem() {
console.log('Testing health system...');
const initialHealth = this.gameEngine.gameState.player.health;
this.gameEngine.gameState.modifyHealth(-20);
this.recordTest('Damage Application',
this.gameEngine.gameState.player.health === initialHealth - 20,
'Should apply damage correctly');
this.gameEngine.gameState.modifyHealth(20);
this.recordTest('Healing Application',
this.gameEngine.gameState.player.health === initialHealth,
'Should apply healing correctly');
this.gameEngine.gameState.modifyHealth(200);
this.recordTest('Health Cap',
this.gameEngine.gameState.player.health <= this.gameEngine.gameState.player.maxHealth,
'Health should not exceed maximum');
}
async testSaveLoadSystem() {
console.log('Testing save/load system...');
const saveManager = new SaveManager(
this.gameEngine.gameState,
this.gameEngine.contextManager,
this.gameEngine.npcManager
);
const saveData = saveManager.createSaveData('test');
this.recordTest('Save Data Creation',
saveData && saveData.player && saveData.context,
'Should create complete save data');
const originalGold = this.gameEngine.gameState.player.gold;
this.gameEngine.gameState.player.gold = 999;
saveManager.restoreGameState(saveData);
this.recordTest('State Restoration',
this.gameEngine.gameState.player.gold === originalGold,
'Should restore state accurately');
}
async testNPCSystem() {
console.log('Testing NPC system...');
const npcsAtVillage = this.gameEngine.npcManager.getNPCsAtLocation('village');
this.recordTest('NPC Location Query',
npcsAtVillage.length > 0,
'Should find NPCs at their locations');
const elderExists = Array.from(this.gameEngine.npcManager.npcs.values())
.some(npc => npc.name === 'Elder Thomas');
this.recordTest('NPC Initialization',
elderExists,
'Should initialize default NPCs');
}
recordTest(name, passed, description) {
this.testResults.push({ name, passed, description });
const status = passed ? '✓ PASS' : '✗ FAIL';
console.log(` ${status}: ${name}`);
}
printResults() {
console.log('\n' + '='.repeat(70));
console.log(' TEST SUMMARY');
console.log('='.repeat(70) + '\n');
const passed = this.testResults.filter(r => r.passed).length;
const failed = this.testResults.filter(r => !r.passed).length;
console.log(`Total Tests: ${this.testResults.length}`);
console.log(`Passed: ${passed}`);
console.log(`Failed: ${failed}`);
console.log(`Success Rate: ${((passed / this.testResults.length) * 100).toFixed(1)}%`);
console.log('\n' + '='.repeat(70) + '\n');
}
}
// ============================================================================
// EXPORTS AND ENTRY POINT
// ============================================================================
// For use as a module
if (typeof module !== 'undefined' && module.exports) {
module.exports = {
TextAdventureGame,
GameEngine,
GameState,
LLMClient,
NPCManager,
ContextManager,
SaveManager,
GameTester
};
}
// Run if executed directly
if (require.main === module) {
TextAdventureGame.main().catch(error => {
console.error('Fatal error:', error);
process.exit(1);
});
}
CONCLUSION
Building games with Large Language Models represents a paradigm shift in interactive entertainment. The technology enables genuinely dynamic narratives where player actions receive contextually appropriate responses rather than predetermined outcomes. However, this power comes with significant engineering challenges that must be addressed for production deployment.
The key to successful LLM game development lies in robust architecture. The separation of concerns between LLM communication, game state management, prompt engineering, and response processing creates maintainable systems. Each layer has distinct responsibilities and can be tested independently. This modular approach also facilitates improvements over time as LLM technology evolves.
Prompt engineering emerges as perhaps the most critical skill. The quality of game experiences depends directly on how effectively prompts guide the LLM to generate appropriate content. Well-crafted prompts provide sufficient context without wasting tokens, establish clear behavioral guidelines without being overly restrictive, and structure responses to facilitate parsing and state extraction.
State management presents unique challenges because game state exists in two forms. The discrete variables tracked by traditional game systems must remain synchronized with the narrative context provided to the LLM. Extraction patterns that parse natural language responses into structured state updates bridge this gap. Validation ensures consistency between what the narrative describes and what the game mechanics permit.
Cost optimization cannot be an afterthought. Without careful management, LLM API costs can quickly become prohibitive. Caching, prompt compression, dynamic token allocation, and strategic use of lower-cost models for less critical interactions all contribute to economic viability. Monitoring token usage and costs in real-time enables informed decisions about feature implementation and player experience tradeoffs.
Production deployment requires attention to operational concerns that extend beyond the core gameplay. Rate limiting prevents API quota exhaustion. Error handling and fallback mechanisms maintain playability during service disruptions. Monitoring and alerting enable rapid response to issues. Session management and cleanup prevent resource leaks. These infrastructure concerns may seem mundane compared to narrative design, but they determine whether the game can actually serve players reliably.
The complete running example provided demonstrates these principles in a production-ready implementation. Every component includes proper error handling, validation, and documentation. The code follows clean architecture principles with clear separation between layers. The implementation handles edge cases and degradation gracefully. This represents the level of engineering rigor required for real deployments rather than proof-of-concept demonstrations.
Looking forward, LLM-based games will continue to evolve as the underlying technology improves. Models with larger context windows will enable longer play sessions with better continuity. Improved structured output capabilities will simplify state extraction. Lower costs will enable richer experiences with more frequent API calls. However, the fundamental architectural patterns explored in this article will remain relevant as they address inherent challenges in bridging deterministic game systems with probabilistic language models.
The future of interactive entertainment includes experiences that blend human creativity with artificial intelligence in unprecedented ways. Games where every playthrough tells a unique story, where NPCs remember and evolve based on player interactions, and where narrative possibilities are truly limitless. Building these experiences requires both technical expertise in software engineering and creative understanding of what makes games engaging. The developers who master both dimensions will create the next generation of interactive experiences.
