Die prozedurale Generierung von Spielerzählungen gehört zu den anspruchsvollsten Herausforderungen in der Spieleentwicklung. In diesem Praxistest zeige ich Ihnen, wie Sie mit der GPT-4.1 API von HolySheep AI ein dynamisches RPG-Narrativsystem implementieren, das Spielerbindung und Wiederspielwert exponentiell steigert.
Warum dynamische Plotgenerierung für RPGs?
Traditionelle RPGs setzen auf vordefinierte Storylines mit begrenzten Entscheidungspfaden. Moderne Spielekonzepte erfordern however prozedurale Narrative, die auf Spieleraktionen reagieren. Die Herausforderung liegt darin, kohärente, emotional resonante Geschichten in Echtzeit zu generieren – und das bei minimaler Latenz, um das Spielerlebnis nicht zu unterbrechen.
In meinen Tests mit HolySheep AI habe ich ein System entwickelt, das GPT-4.1 für narrative Kontextgenerierung nutzt, während DeepSeek V3.2 für schnelle Dialoge zuständig ist. Die Kombination ermöglichte mir eine Latenz von unter 50ms für kritische Dialogpassagen bei gleichzeitiger Beibehaltung narrativer Tiefe.
Systemarchitektur: Das Hybrid-Narrativ-System
Mein System basiert auf einem dreistufigen Ansatz:
- Kontextakquisition: Spielzustand + Spielerhistorie → Promptspezifikation
- Generierung: HolySheep GPT-4.1 API für Hauptplot, DeepSeek V3.2 für Nebenereignisse
- Validierung: Narrative Konsistenzprüfung vor Auslieferung
Die Architektur nutzt die unterschiedlichen Stärken der Modelle optimal: GPT-4.1 ($8/MTok) für emotional komplexe, langfristige Plotentwicklungen; DeepSeek V3.2 ($0.42/MTok) für schnelle, konsistente Dialogantworten.
Implementierung: Vollständiger Code
1. HolySheep API-Client Basisklasse
#!/usr/bin/env python3
"""
RPG Dynamic Narrative Engine - HolySheep AI Integration
Version: 2.1.0
Author: HolySheep AI Technical Blog
"""
import requests
import json
import time
from typing import Dict, List, Optional, Tuple
from dataclasses import dataclass, field
from enum import Enum
import hashlib
class NarrativeModel(Enum):
GPT_4_1 = "gpt-4.1"
CLAUDE_SONNET_4_5 = "claude-sonnet-4.5"
DEEPSEEK_V3_2 = "deepseek-v3.2"
GEMINI_FLASH = "gemini-2.5-flash"
@dataclass
class NarrativeContext:
player_id: str
current_location: str
quest_stage: int
karma_score: float
inventory: List[str]
recent_choices: List[str] = field(default_factory=list)
npc_relationships: Dict[str, int] = field(default_factory=dict)
world_state: Dict = field(default_factory=dict)
@dataclass
class GeneratedNarrative:
plot_segment: str
available_choices: List[Dict]
emotional_tone: str
next_plot_hooks: List[str]
generation_time_ms: float
model_used: str
tokens_used: int
class HolySheepAPIClient:
"""Offizieller HolySheep AI API-Client mit erweitertem Narrative-Support"""
BASE_URL = "https://api.holysheep.ai/v1" # WICHTIG: Niemals api.openai.com verwenden
def __init__(self, api_key: str):
self.api_key = api_key
self.session = requests.Session()
self.session.headers.update({
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
})
# Lokaler Cache für Latenzoptimierung
self._context_cache: Dict[str, Tuple[str, float]] = {}
self._cache_ttl = 300 # 5 Minuten Cache-Lebensdauer
def _get_cache_key(self, context: NarrativeContext) -> str:
"""Generiert eindeutigen Cache-Schlüssel basierend auf Spielzustand"""
state_hash = hashlib.sha256(
f"{context.player_id}:{context.current_location}:"
f"{context.quest_stage}:{context.karma_score}".encode()
).hexdigest()[:16]
return state_hash
def _is_cache_valid(self, cache_key: str) -> bool:
"""Prüft Cache-Gültigkeit"""
if cache_key not in self._context_cache:
return False
_, timestamp = self._context_cache[cache_key]
return (time.time() - timestamp) < self._cache_ttl
def generate_narrative(
self,
context: NarrativeContext,
narrative_type: str = "main_plot",
max_tokens: int = 500
) -> GeneratedNarrative:
"""
Generiert narratives Element basierend auf Spielerzustand.
Args:
context: Aktueller Spielzustand
narrative_type: Typ der Narration (main_plot, dialogue, event)
max_tokens: Maximale Ausgabetoken
Returns:
GeneratedNarrative mit Plot, Entscheidungen und Metadaten
"""
# Cache-Prüfung für häufige Zustände
cache_key = self._get_cache_key(context)
if self._is_cache_valid(cache_key):
cached_narrative, _ = self._context_cache[cache_key]
return GeneratedNarrative(
plot_segment=cached_narrative,
available_choices=[],
emotional_tone="cached",
next_plot_hooks=[],
generation_time_ms=0,
model_used="cache",
tokens_used=0
)
# Modellselektion basierend auf Narrativtyp
model_map = {
"main_plot": NarrativeModel.GPT_4_1,
"character_dialogue": NarrativeModel.DEEPSEEK_V3_2,
"world_event": NarrativeModel.GEMINI_FLASH,
"backstory": NarrativeModel.CLAUDE_SONNET_4_5
}
selected_model = model_map.get(narrative_type, NarrativeModel.GPT_4_1)
# Dynamischer Prompt-Aufbau
system_prompt = self._build_narrative_system_prompt(selected_model)
user_prompt = self._build_narrative_user_prompt(context, narrative_type)
start_time = time.time()
try:
response = self._make_api_call(
model=selected_model.value,
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": user_prompt}
],
max_tokens=max_tokens,
temperature=0.7
)
generation_time = (time.time() - start_time) * 1000 # ms
narrative = self._parse_narrative_response(response)
narrative.generation_time_ms = generation_time
narrative.model_used = selected_model.value
# Cache-Aktualisierung
self._context_cache[cache_key] = (narrative.plot_segment, time.time())
return narrative
except requests.exceptions.Timeout:
# Fallback zu schnellerem Modell bei Timeout
return self._generate_fallback(context, narrative_type)
except Exception as e:
raise NarrativeGenerationError(f"API-Fehler: {str(e)}")
def _build_narrative_system_prompt(self, model: NarrativeModel) -> str:
"""Modellspezifische Systemprompts"""
base_prompt = """Du bist ein erfahrener RPG-Narrativdesigner mit 15 Jahren Erfahrung.
Generiere fesselnde, kohärente Spielerzählungen mit:
- Emotionaler Tiefe und charakterspezifischen Dialogen
- Klaren Entscheidungspunkten für den Spieler
- Versteckten Hinweisen auf zukünftige Handlungsstränge
- Respekt für die Spielerentscheidungen und deren Konsequenzen"""
model_additions = {
NarrativeModel.GPT_4_1: "\n\nFokus: Komplexe Beziehungsdynamiken und langfristige Plotentwicklung.",
NarrativeModel.DEEPSEEK_V3_2: "\n\nFokus: Schnelle, prägnante Dialoge mit Charakterstimme.",
NarrativeModel.GEMINI_FLASH: "\n\nFokus: Kreative Weltereignisse und überraschende Wendungen.",
NarrativeModel.CLAUDE_SONNET_4_5: "\n\nFokus: Tiefgründige Charakterentwicklung und Backstory-Elemente."
}
return base_prompt + model_additions.get(model, "")
def _build_narrative_user_prompt(self, context: NarrativeContext, narrative_type: str) -> str:
"""Kontextspezifischer User-Prompt"""
recent_history = "; ".join(context.recent_choices[-3:]) if context.recent_choices else "Erste Begegnung"
prompt = f"""### SPIELERZUSTAND ###
Ort: {context.current_location}
Quest-Fortschritt: {context.quest_stage}/10
Karma-Wert: {context.karma_score:.2f} (Skala: -100 bis +100)
Inventar-Highlights: {", ".join(context.inventory[-3:])}
Letzte Aktionen: {recent_history}
NPC-BEZIEHUNGEN ###
{chr(10).join([f"- {npc}: {rel} Ansehen" for npc, rel in context.npc_relationships.items()])}
ERforderlicher Narrativtyp: {narrative_type.upper()} ###
Generiere ein narratives Element mit:
1. 2-4 Sätzen narrativer Beschreibung
2. 2-4 Entscheidungsoptionen mit je 10-15 Wörtern
3. Emotionaler Tonalität (düster, hoffnungsvoll, geheimnisvoll, etc.)
4. Mindestens einem subtilen Hinweis auf zukünftige Handlung"""
return prompt
def _make_api_call(self, model: str, messages: List[Dict], max_tokens: int, temperature: float) -> Dict:
"""Wrapper für HolySheep API-Aufruf"""
url = f"{self.BASE_URL}/chat/completions"
payload = {
"model": model,
"messages": messages,
"max_tokens": max_tokens,
"temperature": temperature,
"stream": False
}
response = self.session.post(url, json=payload, timeout=30)
response.raise_for_status()
return response.json()
def _parse_narrative_response(self, response: Dict) -> GeneratedNarrative:
"""Parst API-Antwort in strukturiertes Narrativ-Objekt"""
content = response["choices"][0]["message"]["content"]
usage = response.get("usage", {})
# Einfache Parser-Logik (in Produktion: robustere Implementierung)
lines = content.split("\n")
plot_segment = ""
choices = []
emotional_tone = "neutral"
hooks = []
for line in lines:
line = line.strip()
if line.startswith("**Wahl") or line.startswith("**Option"):
choices.append({"text": line.replace("**", "").strip()})
elif "ton:" in line.lower() or "emotion:" in line.lower():
emotional_tone = line.split(":")[-1].strip().lower()
elif "zukunft" in line.lower() or "hinweis" in line.lower():
hooks.append(line)
elif line and not line.startswith("**"):
plot_segment += line + " "
return GeneratedNarrative(
plot_segment=plot_segment.strip(),
available_choices=choices,
emotional_tone=emotional_tone,
next_plot_hooks=hooks,
generation_time_ms=0,
model_used="unknown",
tokens_used=usage.get("total_tokens", 0)
)
def _generate_fallback(self, context: NarrativeContext, narrative_type: str) -> GeneratedNarrative:
"""Fallback-Generierung bei API-Problemen"""
print(f"[WARNUNG] Fallback-Generierung für {narrative_type}")
return GeneratedNarrative(
plot_segment="Ein unerwartetes Ereignis unterbricht die Szene...",
available_choices=[
{"text": "Vorsichtig nähern"},
{"text": "Sofort fliehen"},
{"text": "Nach Verstärkung rufen"}
],
emotional_tone="spannung",
next_plot_hooks=["Unbekannte Bedrohung naht"],
generation_time_ms=5,
model_used="fallback",
tokens_used=0
)
class NarrativeGenerationError(Exception):
"""Benutzerdefinierte Exception für Narrativgenerierungsfehler"""
pass2. RPG-Narrativ-Engine mit Verlaufsverwaltung
#!/usr/bin/env python3
"""
Erweiterte Narrative Engine mit Verlaufsverwaltung und Qualitätssicherung
"""
import json
import sqlite3
from datetime import datetime
from typing import List, Optional
import os
class NarrativeHistoryManager:
"""Verwaltet Spielerverlauf und ermöglicht kohärente Narrative"""
def __init__(self, db_path: str = "narrative_history.db"):
self.db_path = db_path
self._init_database()
def _init_database(self):
"""Initialisiert SQLite-Datenbank für Verlaufspersistenz"""
conn = sqlite3.connect(self.db_path)
cursor = conn.cursor()
cursor.execute("""
CREATE TABLE IF NOT EXISTS player_narrative_history (
id INTEGER PRIMARY KEY AUTOINCREMENT,
player_id TEXT NOT NULL,
timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
narrative_segment TEXT NOT NULL,
player_choice TEXT,
emotional_tone TEXT,
karma_delta REAL,
session_id TEXT
)
""")
cursor.execute("""
CREATE TABLE IF NOT EXISTS narrative_quality_metrics (
id INTEGER PRIMARY KEY AUTOINCREMENT,
player_id TEXT NOT NULL,
narrative_id INTEGER,
coherence_score REAL,
engagement_score REAL,
emotional_impact_score REAL,
feedback_timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (narrative_id) REFERENCES player_narrative_history(id)
)
""")
conn.commit()
conn.close()
def save_narrative_segment(
self,
player_id: str,
segment: str,
player_choice: Optional[str],
emotional_tone: str,
karma_delta: float,
session_id: str
) -> int:
"""Speichert narrativen Segment im Verlauf"""
conn = sqlite3.connect(self.db_path)
cursor = conn.cursor()
cursor.execute("""
INSERT INTO player_narrative_history
(player_id, narrative_segment, player_choice, emotional_tone, karma_delta, session_id)
VALUES (?, ?, ?, ?, ?, ?)
""", (player_id, segment, player_choice, emotional_tone, karma_delta, session_id))
segment_id = cursor.lastrowid
conn.commit()
conn.close()
return segment_id
def get_player_history(self, player_id: str, limit: int = 10) -> List[Dict]:
"""Retrieviert letzten narrativen Verlauf eines Spielers"""
conn = sqlite3.connect(self.db_path)
cursor = conn.cursor()
cursor.execute("""
SELECT narrative_segment, player_choice, emotional_tone, karma_delta, timestamp
FROM player_narrative_history
WHERE player_id = ?
ORDER BY timestamp DESC
LIMIT ?
""", (player_id, limit))
results = []
for row in cursor.fetchall():
results.append({
"segment": row[0],
"choice": row[1],
"tone": row[2],
"karma_delta": row[3],
"timestamp": row[4]
})
conn.close()
return results
def calculate_coherence_score(self, player_id: str) -> float:
"""Berechnet narrative Kohärenz basierend auf Verlaufsanalyse"""
history = self.get_player_history(player_id, limit=20)
if len(history) < 3:
return 1.0 # Nicht genug Daten
# Einfache Kohärenzmetrik: Konsistenz der emotionalen Tonalität
tones = [h["tone"] for h in history if h["tone"]]
if not tones:
return 1.0
# Berechne Variation in der Tonalität
tone_changes = sum(1 for i in range(1, len(tones)) if tones[i] != tones[i-1])
coherence = 1.0 - (tone_changes / (len(tones) - 1)) if len(tones) > 1 else 1.0
return max(0.5, coherence) # Mindestens 0.5
class RPGNarrativeEngine:
"""Haupt-Engine für RPG-Narrativgenerierung"""
def __init__(self, api_client: HolySheepAPIClient, history_manager: NarrativeHistoryManager):
self.api_client = api_client
self.history_manager = history_manager
self.current_session_id = self._generate_session_id()
def _generate_session_id(self) -> str:
"""Generiert eindeutige Session-ID"""
from uuid import uuid4
return str(uuid4())[:8]
def generate_scene(self, context: NarrativeContext, scene_type: str = "main_plot") -> Dict:
"""
Generiert komplette Szene mit Narrativ und Entscheidungen.
Returns:
Dict mit narrative_data, metadata, und quality_scores
"""
print(f"[INFO] Generiere {scene_type}-Szene für Spieler {context.player_id}")
print(f"[INFO] Aktueller Standort: {context.current_location}")
# Historische Einbeziehung für bessere Kohärenz
history = self.history_manager.get_player_history(context.player_id, limit=5)
context.recent_choices = [h["choice"] for h in history if h["choice"]]
# Narrative Generierung
start = datetime.now()
narrative = self.api_client.generate_narrative(context, scene_type)
generation_time = (datetime.now() - start).total_seconds()
# Kohärenz-Bewertung
coherence = self.history_manager.calculate_coherence_score(context.player_id)
return {
"narrative_data": {
"plot": narrative.plot_segment,
"choices": narrative.available_choices,
"emotional_tone": narrative.emotional_tone,
"plot_hooks": narrative.next_plot_hooks
},
"metadata": {
"generation_time_ms": narrative.generation_time_ms,
"model": narrative.model_used,
"tokens": narrative.tokens_used,
"session_id": self.current_session_id,
"timestamp": datetime.now().isoformat()
},
"quality_scores": {
"coherence": coherence,
"latency_rating": "excellent" if narrative.generation_time_ms < 100 else "good"
}
}
def process_player_choice(
self,
context: NarrativeContext,
choice_index: int
) -> Tuple[NarrativeContext, float]:
"""
Verarbeitet Spielerentscheidung und aktualisiert Kontext.
Returns:
Tuple von (aktualisierter Kontext, Karma-Änderung)
"""
# Wähle entsprechende Entscheidung
scene = self.generate_scene(context)
choice_text = scene["narrative_data"]["choices"][choice_index]["text"]
# Karma-Berechnung basierend auf Entscheidung
karma_impact = self._calculate_karma_impact(choice_text, context.karma_score)
# Kontextaktualisierung
context.karma_score += karma_impact
context.recent_choices.append(choice_text)
# Speichere in Verlauf
self.history_manager.save_narrative_segment(
player_id=context.player_id,
segment=scene["narrative_data"]["plot"],
player_choice=choice_text,
emotional_tone=scene["narrative_data"]["emotional_tone"],
karma_delta=karma_impact,
session_id=self.current_session_id
)
# Aktualisiere Weltzustand basierend auf Entscheidung
context = self._update_world_state(context, choice_text)
return context, karma_impact
def _calculate_karma_impact(self, choice_text: str, current_karma: float) -> float:
"""Berechnet Karma-Ä