Escape-the-room-AI-stats-game

LLM Game Engine

The LLM Game Engine is a unique framework that integrates the immersive narrative experience of traditional game engines like Renpy and Twine with the dynamic interactivity of AI chat systems such as SillyTavern and AI Dungeon. This innovative engine allows players significant freedom to express themselves through natural language while simultaneously ensuring structured story progression and character development through a deterministic backend that retains narrative integrity.

Key Features

The LLM Game Engine stands out by offering a distinctive balance between player autonomy and narrative control. It allows players to communicate freely, but specific actions are required to advance the story and affect character stats. This controlled interaction guarantees that the gameplay experience remains focused and engaging, while still being responsive to player input.

Feature	Traditional Game (Twine/Renpy)	AI Chat Game (SillyTavern)	LLM Game Engine
Authorial Control	Full control by the author	Total freedom for players	Controlled freedom
Outcome Determinism	Deterministic outcomes	Unlimited possibilities	Bound outcomes
Dialogue Dynamics	No dynamic dialogue	Infinite dynamic dialogue	Dynamic dialogue with progression locks
Story Construction	Hand-crafted responses	No structured storytelling	Structured crafting with AI-generated dialogue

The design is influenced by Jacky Kaub's causal graph approach, enabling a sophisticated narrative model.

Game Mechanics

The LLM Game Engine is built around two core systems:

1. Causal Graph: This component consists of a directed graph where each node represents an impactful action. The node includes:

   • A description for matching player input
   • A consequence of the action that is only revealed upon execution
   • Prerequisites that must be completed beforehand
   • Optional stat gates, which require certain thresholds to be met before actions are available

   The engine allows players to articulate any input, with a classifier agent verifying the validity of the action. If an action does not match any available option, the player is informed that their action was ineffective.

2. Stat System: Characters in the game possess various attributes (e.g., trust, love, suspicion). Following each interaction with a non-player character (NPC), a system assesses the dialogue and adjusts stats according to strict parameters, ensuring gradual changes and clear character development. Stats trigger pivotal changes in NPC personas and unlock new pathways in the gameplay.

Player Interaction

Players are enabled to engage in varied actions with specific outcomes:

Player Action	Result
Match an available action	Progression of the story and changes in stats
No match found	Notification of no effect
Attempt to force outcomes	Regarded as non-matching input
Repeating an action	Filtered out and ignored
Inquire about advanced knowledge	NPC responses restricted to available context

Story Structure

Stories are organized within the stories/<story-name>/ directory and consist of three JSON files:

• graph.json — outlines the causal graph
• characters.json — defines NPCs and their statistics-based personas
• config.json — contains story configurations such as the existing stats and their initial values

Current Stories:

• escape_room: Experience the thrill of solving puzzles in a confined setting. Players must decipher clues provided by a ghost NPC, whose reliability hinges on the player's trust stat. Interactions range from enigmatic riddles at low trust to straightforward guidance at higher trust levels.

Technology Stack

• Language: Python 3.11+
• LLM: Claude Haiku (via Anthropic API) for efficient classification
• Data Management: JSON files are utilized for state management without a database
• Interface: Terminal-based interaction

The LLM Game Engine represents an innovative approach to narrative-driven gaming by merging player freedom with structural storytelling, ensuring both engaging gameplay and comprehensive narrative continuity.