Port changes from duplicate space to original

Sync major feature development from duplicate HuggingFace space:

- Expand core app with enhanced UI and functionality
- Merge many separate tabs into streamlined UI (consolidation in progress)
- Add exporters package (Godot, Unreal, PlayCanvas, Ren'Py, RPGMaker,
Roblox, Twine, Ink, Flutter, GameMaker, AR, HTML, fiction exporters)
- Add modular ui_tabs package (RPG scale, config analysis, DnD GM,
LLM playtest, narrative engine, story architect, story graph, 3D study)
- Add scenario templates (beat, dnd, film, mystery, song, timeline, world)
- Add game engine components (game_configs, game_state, condition_evaluator,
config_linting, json_utils)
- Add LLM playtester and demo examples
- Port related HF spaces (dnd_game_master, narrativeengine, storygenattempt)
- Add PlayCanvas integration
- Update requirements and documentation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.pyo
+.DS_Store
+*.log
+sd_output_*.png

TECHNICAL_DEBT_PLAN_2026-01-21.md

@@ -0,0 +1,136 @@
+# Technical Debt & Refactoring Plan
+**Created**: 2026-01-21
+**Status**: Pending - UX improvements in progress first
+**Last Updated**: 2026-01-21
+
+---
+
+## Executive Summary
+
+GameConfigIdeaEditBrainstorm is a sophisticated AI-powered game design platform with ~24,343 lines of Python across 79 files. While feature-rich, it has accumulated technical debt that impacts maintainability, testability, and extensibility.
+
+**Decision**: Focus on UX improvements first to better understand real usage patterns, then return to this restructuring plan with concrete insights.
+
+---
+
+## Current Architecture Overview
+
+```
+├── app.py (4,104 lines)              # Monolithic main file - PRIMARY CONCERN
+├── Core Engine
+│   ├── my_text_game_engine_attempt.py
+│   ├── game_state.py
+│   ├── condition_evaluator.py
+│   └── game_configs.py
+├── AI/ML Integration
+│   ├── leveraging_machine_learning.py
+│   └── llm_playtester.py
+├── UI Tabs (ui_tabs/)                # Already modularized - GOOD
+├── Exporters (exporters/)            # 14 platforms - GOOD separation
+├── External Ports
+│   ├── narrativeengine_hfport/
+│   ├── storygenattempt_hfport/
+│   └── dnd_game_master_hfport/
+└── Scenario Templates (*_scenarios.py)
+```
+
+---
+
+## Issues by Priority
+
+### P0 - Critical (Blocks scaling)
+
+| Issue | Impact | Effort | Notes |
+|-------|--------|--------|-------|
+| Monolithic `app.py` (4,104 lines) | Hard to maintain, test, or onboard contributors | High | Break into feature modules |
+| No automated tests | Can't refactor safely | Medium | Add pytest suite |
+| Tight UI-engine coupling | Can't unit test game logic | High | Extract pure engine layer |
+
+### P1 - High (Impacts development velocity)
+
+| Issue | Impact | Effort | Notes |
+|-------|--------|--------|-------|
+| Mixed state management (Player + GameState) | Confusing, potential bugs | Medium | Complete migration to GameState |
+| 60+ hardcoded LLM list | Hard to maintain/extend | Low | Create ModelRegistry class |
+| Sparse error handling | Silent failures confuse users | Medium | Add structured logging |
+| Lambda consequences + declarative effects coexisting | Inconsistent, harder to validate | Medium | Migrate all to declarative |
+
+### P2 - Medium (Quality of life)
+
+| Issue | Impact | Effort | Notes |
+|-------|--------|--------|-------|
+| Code duplication in exporters | Maintenance burden | Medium | Extract base exporter class |
+| Missing type hints | IDE support, bugs | Low | Add progressively |
+| Inconsistent naming | Cognitive load | Low | Establish conventions |
+| Magic strings/numbers | Bugs, hard to refactor | Low | Create enums/constants |
+
+### P3 - Low (Nice to have)
+
+| Issue | Impact | Effort | Notes |
+|-------|--------|--------|-------|
+| Exporter quality variance | Some exports may fail | Medium | Add capability metadata |
+| No caching for LLM inferences | Repeated work | Medium | Add caching layer |
+| Sparse docstrings | Onboarding difficulty | Low | Document as we go |
+
+---
+
+## Proposed Refactoring Phases
+
+### Phase 1: Foundation (After UX work)
+- [ ] Extract `app.py` into logical modules:
+  - `app_core.py` - Gradio app setup, shared state
+  - `app_generation.py` - Content generation handlers
+  - `app_playtest.py` - Playtest/preview handlers
+  - `app_export.py` - Export handlers
+  - `app_media.py` - Media generation handlers
+- [ ] Add basic pytest infrastructure
+- [ ] Create constants/enums for magic strings
+
+### Phase 2: Engine Isolation
+- [ ] Extract pure game engine (no Gradio dependencies)
+- [ ] Complete Player → GameState migration
+- [ ] Migrate lambda consequences to declarative effects
+- [ ] Add engine unit tests
+
+### Phase 3: ML Infrastructure
+- [ ] Create ModelRegistry class with metadata
+- [ ] Add structured error handling + logging
+- [ ] Implement inference caching
+
+### Phase 4: Polish
+- [ ] Extract shared exporter base class
+- [ ] Add type hints throughout
+- [ ] Comprehensive documentation pass
+- [ ] Add integration tests
+
+---
+
+## Metrics to Track
+
+- Lines in `app.py` (target: <500)
+- Test coverage % (target: >60%)
+- Average function length (target: <50 lines)
+- Number of untyped functions (target: 0)
+
+---
+
+## UX Insights to Gather First
+
+Before restructuring, document insights from UX work:
+
+- [ ] Which tabs/features are actually used most?
+- [ ] What are common user workflows?
+- [ ] Where do users get confused or stuck?
+- [ ] Which exporters are production-quality vs experimental?
+- [ ] What error messages do users encounter?
+
+These insights will inform which modules to prioritize and how to structure the codebase for real usage patterns.
+
+---
+
+## Notes / Updates
+
+*Add notes here as UX work progresses*
+
+- 2026-01-21: Plan created. Starting UX improvements first.
+

TODO_MOVINGDOTSPACE.md

@@ -0,0 +1,91 @@
+# MovingDotSpace Export - Known Issues
+
+## Status: Deferred for later fix
+
+Last updated: 2025-01-11
+
+---
+
+## Issues to Fix
+
+### 1. Stats Panel Not Updating
+- **Money stat** doesn't update in the player stats display
+- **Inventory section** remains empty despite items being in config
+- **Skills section** not populating
+
+**Debug info:** Console should log `Stats loaded: {...}` with counts. Check if:
+- Data is in the exported config (`exportedConfig.themes['Exported Game']`)
+- `gameState.inventory`, `gameState.skills`, `gameState.playerStats.money` are set
+- `renderStats()` is being called and executing
+
+**Possible causes:**
+- Timing issue with `loadTheme()` overwriting values after we set them
+- `renderStats()` function not finding the DOM elements
+- Data format mismatch between config and what `renderStats()` expects
+
+### 2. Format Verification Needed
+Check that extracted data matches MovingDotSpace expected format:
+
+**Inventory items:**
+```javascript
+{ type: "weapon", name: "Iron Sword", description: "A sturdy blade" }
+```
+
+**Skills:**
+```javascript
+{ branch: "Combat", name: "One-Handed", learned: false }
+```
+
+**Objectives:**
+```javascript
+{ id: "quest_id", name: "Quest Name", complete: false }
+```
+
+---
+
+## What Works
+
+- Autotravel toggle (checkbox in top-right)
+- Location locking/unlocking system
+- Cross-location transitions (only when location actually changes)
+- Modal state machine navigation within locations
+- Special locations filtered out (game_start, inventory, quest_journal)
+
+---
+
+## Files Involved
+
+- `exporters/html_exporters.py` - Main MovingDotSpace exporter
+- `ui_tabs/big_rpg_scale_tab.py` - Adds `_movingdotspace_meta` with items/skills
+- `MovingDotSpaceExport/MovingDotSpaceStandalone.html` - Template with `renderStats()`
+
+---
+
+## Testing Steps
+
+1. Load Big RPG Scale demo data
+2. Export to Game Config
+3. Use Platform Export > MovingDotSpace
+4. Open browser DevTools (F12) > Console
+5. Check for `Stats loaded: {...}` log
+6. Inspect `gameState.inventory`, `gameState.skills`, `gameState.playerStats`
+
+---
+
+## Potential Fixes to Try
+
+1. **Move stats loading after a delay:**
+   ```javascript
+   setTimeout(() => {
+     gameState.inventory = themeConfig.inventory;
+     renderStats();
+   }, 500);
+   ```
+
+2. **Check if loadTheme overwrites:**
+   - In MovingDotSpaceStandalone.html, `loadTheme()` sets `gameState.inventory = theme.inventory || []`
+   - Our explicit setting happens after, so should work
+
+3. **Verify DOM elements exist:**
+   - `elements.inventoryList` must exist before `renderStats()` runs
+   - Check for null element references

beat_scenarios.py

@@ -0,0 +1,237 @@
+"""Story beat data and sequence generation.
+
+This module provides:
+- STORY_BEATS: Dictionary of story beats organized by format and genre
+- generate_beat_sequence: Function to generate story sequences based on format/genre
+"""
+
+import json
+import random
+
+# Story beats organized by narrative function
+STORY_BEATS = {
+    "setup": [
+        ("Ordinary World", "Establish the protagonist's normal life before the adventure"),
+        ("Meet the Hero", "Introduction to protagonist with defining character moment"),
+        ("Establish Stakes", "Show what the protagonist stands to lose"),
+        ("The Want", "Protagonist expresses a desire or goal"),
+        ("The Flaw", "Hint at protagonist's weakness that must be overcome"),
+        ("Supporting Cast", "Introduce key allies and their relationships"),
+    ],
+    "catalyst": [
+        ("Call to Adventure", "External event disrupts the ordinary world"),
+        ("Inciting Incident", "Something happens that demands a response"),
+        ("The Invitation", "Opportunity presents itself to the protagonist"),
+        ("The Challenge", "Direct challenge forces protagonist to act"),
+        ("Bad News", "Devastating information changes everything"),
+        ("The Stranger", "New character brings change or information"),
+    ],
+    "debate": [
+        ("Refusal of Call", "Protagonist hesitates or refuses the challenge"),
+        ("The Doubt", "Protagonist questions their ability"),
+        ("Seeking Advice", "Protagonist consults mentor or wise figure"),
+        ("Weighing Options", "Protagonist considers paths forward"),
+        ("The Warning", "Someone cautions against the journey"),
+        ("Internal Conflict", "Protagonist struggles with competing desires"),
+    ],
+    "rising_action": [
+        ("Crossing Threshold", "Protagonist commits to the journey"),
+        ("New World Rules", "Protagonist learns how this new world works"),
+        ("Tests and Allies", "Series of challenges, gaining companions"),
+        ("Fun and Games", "Promise of the premise fulfilled"),
+        ("Skill Building", "Protagonist develops abilities needed for climax"),
+        ("B-Story Develops", "Secondary plot line advances"),
+        ("Approaching Cave", "Preparing for the major challenge"),
+    ],
+    "midpoint": [
+        ("False Victory", "Apparent success that will prove hollow"),
+        ("False Defeat", "Apparent failure that motivates comeback"),
+        ("Major Revelation", "Game-changing information revealed"),
+        ("Point of No Return", "Commitment that cannot be undone"),
+        ("Raised Stakes", "The cost of failure increases dramatically"),
+        ("New Goal", "Original objective shifts to something bigger"),
+    ],
+    "complications": [
+        ("Bad Guys Close In", "Opposition intensifies, allies scatter"),
+        ("Betrayal", "Trusted ally reveals true colors"),
+        ("All Is Lost", "Lowest point - everything seems hopeless"),
+        ("Death Moment", "Literal or symbolic death experience"),
+        ("Dark Night", "Protagonist faces their deepest fears"),
+        ("Whiff of Death", "Mortality or failure becomes very real"),
+    ],
+    "climax": [
+        ("Gathering the Team", "Final assembly before the battle"),
+        ("The Plan", "Strategy for the final confrontation revealed"),
+        ("Storming the Castle", "Direct assault on the antagonist"),
+        ("Final Battle", "Climactic confrontation begins"),
+        ("High Tower Surprise", "Unexpected complication in the climax"),
+        ("The Dig Deep", "Protagonist must use everything they've learned"),
+        ("Victory/Defeat", "The outcome of the main conflict"),
+    ],
+    "resolution": [
+        ("New Equilibrium", "World rebalanced after the adventure"),
+        ("Character Changed", "Demonstrate protagonist's transformation"),
+        ("Reward", "Protagonist receives what they've earned"),
+        ("Return Home", "Protagonist returns to ordinary world, changed"),
+        ("Open Loop", "Hint at future adventures"),
+        ("Final Image", "Mirror of opening that shows change"),
+    ],
+}
+
+# Genre-specific flavor modifiers
+GENRE_FLAVORS = {
+    "action": {
+        "prefix": "PULSE-POUNDING: ",
+        "descriptors": ["explosive", "high-octane", "adrenaline-fueled", "relentless"],
+    },
+    "drama": {
+        "prefix": "EMOTIONALLY CHARGED: ",
+        "descriptors": ["poignant", "raw", "intimate", "devastating"],
+    },
+    "comedy": {
+        "prefix": "HILARIOUS: ",
+        "descriptors": ["absurd", "witty", "chaotic", "perfectly timed"],
+    },
+    "thriller": {
+        "prefix": "HEART-STOPPING: ",
+        "descriptors": ["tense", "paranoid", "claustrophobic", "nerve-wracking"],
+    },
+    "romance": {
+        "prefix": "SWOON-WORTHY: ",
+        "descriptors": ["tender", "passionate", "yearning", "chemistry-filled"],
+    },
+    "scifi": {
+        "prefix": "MIND-BENDING: ",
+        "descriptors": ["futuristic", "technological", "alien", "conceptual"],
+    },
+    "fantasy": {
+        "prefix": "EPIC: ",
+        "descriptors": ["mystical", "legendary", "enchanted", "otherworldly"],
+    },
+    "horror": {
+        "prefix": "TERRIFYING: ",
+        "descriptors": ["dread-filled", "nightmarish", "unsettling", "visceral"],
+    },
+}
+
+# Format-specific beat counts (simplified for game flow)
+FORMAT_BEATS = {
+    "film_90min": {
+        "name": "90-Minute Feature Film",
+        "structure": ["setup", "catalyst", "debate", "rising_action", "midpoint",
+                      "complications", "climax", "resolution"],
+        "typical_count": 8,
+    },
+    "tv_30min": {
+        "name": "30-Minute TV Episode",
+        "structure": ["setup", "catalyst", "rising_action", "midpoint",
+                      "complications", "climax", "resolution"],
+        "typical_count": 6,
+    },
+    "youtube_9min": {
+        "name": "9-Minute YouTube Video",
+        "structure": ["setup", "catalyst", "rising_action", "climax", "resolution"],
+        "typical_count": 5,
+    },
+    "short_3min": {
+        "name": "3-Minute Short",
+        "structure": ["setup", "catalyst", "climax", "resolution"],
+        "typical_count": 4,
+    },
+}
+
+
+def generate_beat_sequence(format_type, genre, beat_count):
+    """Generate a story beat sequence based on format and genre.
+
+    Args:
+        format_type: One of 'film_90min', 'tv_30min', 'youtube_9min', 'short_3min'
+        genre: One of 'action', 'drama', 'comedy', 'thriller', 'romance', 'scifi', 'fantasy', 'horror'
+        beat_count: Number of beats to generate (3-15)
+
+    Returns:
+        Tuple of (list_output, json_output, prompts_output)
+    """
+    format_info = FORMAT_BEATS.get(format_type, FORMAT_BEATS["film_90min"])
+    genre_info = GENRE_FLAVORS.get(genre, GENRE_FLAVORS["drama"])
+
+    structure = format_info["structure"]
+
+    # Build sequence following structure
+    sequence = []
+    beats_per_section = max(1, beat_count // len(structure))
+    remaining = beat_count - (beats_per_section * len(structure))
+
+    for section in structure:
+        section_beats = STORY_BEATS.get(section, STORY_BEATS["setup"])
+        # Pick random beats from this section
+        count_for_section = beats_per_section + (1 if remaining > 0 else 0)
+        if remaining > 0:
+            remaining -= 1
+
+        available = list(section_beats)
+        random.shuffle(available)
+        for beat in available[:count_for_section]:
+            descriptor = random.choice(genre_info["descriptors"])
+            sequence.append((beat[0], beat[1], section, descriptor))
+
+    # Trim or pad to exact count
+    if len(sequence) > beat_count:
+        sequence = sequence[:beat_count]
+
+    if not sequence:
+        return "Select a valid format and genre!", "{}", ""
+
+    # Format as list
+    list_output = f"## {format_info['name']} - {genre.title()} Genre\n\n"
+    for i, (name, desc, section, descriptor) in enumerate(sequence, 1):
+        list_output += f"**{i}. {name}** [{section}]\n{descriptor.title()}: {desc}\n\n"
+
+    # Format as config JSON
+    config = {"story_location": {}}
+    for i, (name, desc, section, descriptor) in enumerate(sequence, 1):
+        state_name = name.lower().replace(" ", "_").replace("/", "_").replace("-", "_")
+        current_state_id = f"beat_{i}_{state_name}"
+
+        # Determine next state
+        if i < len(sequence):
+            next_name = sequence[i][0]
+            next_state_name = next_name.lower().replace(" ", "_").replace("/", "_").replace("-", "_")
+            next_state_id = f"beat_{i+1}_{next_state_name}"
+        else:
+            next_state_id = "story_end"
+
+        config["story_location"][current_state_id] = {
+            "description": f"[{section.upper()}] {genre_info['prefix']}{desc}",
+            "media_prompt": f"{genre.title()} {format_info['name']} scene: {name} - {descriptor} {desc}",
+            "choices": ["Continue"],
+            "transitions": {
+                "Continue": next_state_id
+            }
+        }
+
+    # Add ending state
+    first_beat = sequence[0][0].lower().replace(" ", "_").replace("/", "_").replace("-", "_")
+    config["story_location"]["story_end"] = {
+        "description": f"The {genre} story concludes. The journey has changed everything.",
+        "choices": ["Experience Again"],
+        "transitions": {
+            "Experience Again": f"beat_1_{first_beat}"
+        }
+    }
+
+    json_output = json.dumps(config, indent=2)
+
+    # Format prompts
+    prompts_output = f"## {genre.title()} Story Prompts\n\n"
+    for i, (name, desc, section, descriptor) in enumerate(sequence, 1):
+        prompts_output += f"{genre.title()} {format_info['name']} scene: {name} - {descriptor} {desc}\n"
+
+    return list_output, json_output, prompts_output
+
+
+# Quick test
+if __name__ == "__main__":
+    list_out, json_out, prompts_out = generate_beat_sequence("film_90min", "thriller", 5)
+    print(list_out)
+    print(json_out)

bible_as_inspiration_source.py

@@ -0,0 +1,502 @@
+import gradio as gr
+
+# =============================================================================
+# BIBLE STORY TEMPLATES - Structured Data for Game Config Generation
+# Priority: Locations, People, Politics/Laws/Moral Rules
+# =============================================================================
+
+BIBLE_TEMPLATES = {
+    "matthew": {
+        "book_name": "Gospel of Matthew",
+        "youtube_link": "https://www.youtube.com/watch?v=mgUWg3ZY_C8",
+        "chapters": {
+            "1": {
+                "title": "Jesus' Lineage",
+                "summary": "Genealogy from Abraham to Jesus through David's line",
+                "locations": [
+                    {"name": "Bethlehem", "type": "city", "significance": "Birthplace of Jesus, City of David"},
+                    {"name": "Judea", "type": "region", "significance": "Southern kingdom, seat of Jewish religious authority"}
+                ],
+                "people": [
+                    {"name": "Abraham", "role": "ancestor", "faction": "Patriarchs", "description": "Father of the Jewish nation"},
+                    {"name": "David", "role": "ancestor", "faction": "Kings of Israel", "description": "Greatest king, promised eternal dynasty"},
+                    {"name": "Joseph", "role": "protagonist_support", "faction": "House of David", "description": "Carpenter, legal father of Jesus"},
+                    {"name": "Mary", "role": "protagonist_support", "faction": "House of David", "description": "Virgin mother of Jesus"},
+                    {"name": "Jesus", "role": "protagonist", "faction": "Divine", "description": "The Messiah, Son of God"}
+                ],
+                "politics_laws_morals": [
+                    {"type": "law", "name": "Mosaic Law", "description": "Jewish religious and civil law governing all aspects of life"},
+                    {"type": "moral", "name": "Righteousness through lineage", "description": "Importance of family line and covenant promises"},
+                    {"type": "political", "name": "Davidic Covenant", "description": "God's promise of eternal kingship to David's descendants"}
+                ]
+            },
+            "2": {
+                "title": "King Herod's Order",
+                "summary": "Magi visit, flight to Egypt, massacre of innocents",
+                "locations": [
+                    {"name": "Bethlehem", "type": "city", "significance": "Where Jesus was born, target of Herod's massacre"},
+                    {"name": "Jerusalem", "type": "capital", "significance": "Herod's seat of power, religious center"},
+                    {"name": "Egypt", "type": "foreign_land", "significance": "Place of refuge, echoes of Exodus"},
+                    {"name": "Nazareth", "type": "town", "significance": "Final settlement of the holy family"}
+                ],
+                "people": [
+                    {"name": "Herod the Great", "role": "antagonist", "faction": "Roman Client Kings", "description": "Paranoid king who orders massacre of infants"},
+                    {"name": "The Magi", "role": "ally", "faction": "Eastern Wise Men", "description": "Foreign astrologers who seek the newborn king"},
+                    {"name": "Joseph", "role": "protagonist_support", "faction": "House of David", "description": "Protector who flees with family to Egypt"},
+                    {"name": "Mary", "role": "protagonist_support", "faction": "House of David", "description": "Mother protecting her child"},
+                    {"name": "Jesus", "role": "protagonist", "faction": "Divine", "description": "Infant king, target of Herod's jealousy"}
+                ],
+                "politics_laws_morals": [
+                    {"type": "political", "name": "Roman Occupation", "description": "Judea under Roman rule through client kings"},
+                    {"type": "political", "name": "Herodian Paranoia", "description": "Herod kills anyone threatening his throne, including family"},
+                    {"type": "moral", "name": "Protection of the innocent", "description": "Joseph acts on divine warning to save his family"},
+                    {"type": "moral", "name": "Sacrifice of innocents", "description": "Tragedy of children killed for one man's fear"},
+                    {"type": "prophecy", "name": "Out of Egypt", "description": "Fulfillment of 'Out of Egypt I called my son'"}
+                ]
+            },
+            "3": {
+                "title": "John the Baptist",
+                "summary": "John prepares the way, Jesus is baptized",
+                "locations": [
+                    {"name": "Judean Wilderness", "type": "wilderness", "significance": "Place of repentance and preparation"},
+                    {"name": "Jordan River", "type": "river", "significance": "Site of baptism, boundary crossing symbolism"}
+                ],
+                "people": [
+                    {"name": "John the Baptist", "role": "herald", "faction": "Prophets", "description": "Voice crying in wilderness, prepares way for Messiah"},
+                    {"name": "Jesus", "role": "protagonist", "faction": "Divine", "description": "Receives baptism to fulfill righteousness"},
+                    {"name": "Pharisees", "role": "antagonist", "faction": "Religious Elite", "description": "Religious leaders challenged by John"},
+                    {"name": "Sadducees", "role": "antagonist", "faction": "Religious Elite", "description": "Temple aristocracy, political collaborators"}
+                ],
+                "politics_laws_morals": [
+                    {"type": "moral", "name": "Repentance", "description": "Turn from sin, change of heart and direction"},
+                    {"type": "ritual", "name": "Baptism", "description": "Symbolic cleansing and public commitment"},
+                    {"type": "moral", "name": "Bearing fruit", "description": "True repentance shown through changed actions"},
+                    {"type": "warning", "name": "Judgment coming", "description": "Axe at root of trees, winnowing fork ready"}
+                ]
+            },
+            "4": {
+                "title": "Temptation and First Disciples",
+                "summary": "Jesus tempted by Satan, begins ministry, calls first disciples",
+                "locations": [
+                    {"name": "Judean Wilderness", "type": "wilderness", "significance": "40 days of fasting and temptation"},
+                    {"name": "Temple Pinnacle", "type": "landmark", "significance": "Site of second temptation"},
+                    {"name": "High Mountain", "type": "landmark", "significance": "Where Satan shows all kingdoms"},
+                    {"name": "Galilee", "type": "region", "significance": "Jesus' ministry headquarters"},
+                    {"name": "Capernaum", "type": "city", "significance": "Jesus' home base for ministry"},
+                    {"name": "Sea of Galilee", "type": "body_of_water", "significance": "Where fishermen disciples are called"},
+                    {"name": "Syria", "type": "region", "significance": "Fame spreads, sick brought from here"}
+                ],
+                "people": [
+                    {"name": "Jesus", "role": "protagonist", "faction": "Divine", "description": "Overcomes temptation, begins public ministry"},
+                    {"name": "Satan", "role": "antagonist", "faction": "Demonic", "description": "The tempter, offers worldly power"},
+                    {"name": "Peter (Simon)", "role": "ally", "faction": "Disciples", "description": "Fisherman, first called disciple"},
+                    {"name": "Andrew", "role": "ally", "faction": "Disciples", "description": "Peter's brother, also a fisherman"},
+                    {"name": "James son of Zebedee", "role": "ally", "faction": "Disciples", "description": "Fisherman, one of inner circle"},
+                    {"name": "John son of Zebedee", "role": "ally", "faction": "Disciples", "description": "James' brother, beloved disciple"}
+                ],
+                "politics_laws_morals": [
+                    {"type": "moral", "name": "Scripture as defense", "description": "Jesus counters temptation with 'It is written'"},
+                    {"type": "moral", "name": "Man shall not live by bread alone", "description": "Spiritual sustenance over physical"},
+                    {"type": "moral", "name": "Do not test God", "description": "Faith doesn't demand proof through stunts"},
+                    {"type": "moral", "name": "Worship God alone", "description": "Reject all other powers and kingdoms"},
+                    {"type": "calling", "name": "Fishers of men", "description": "New purpose for disciples - gathering people"}
+                ]
+            },
+            "5": {
+                "title": "Sermon on the Mount - Part 1",
+                "summary": "Beatitudes, salt and light, fulfilling the law",
+                "locations": [
+                    {"name": "Mountain in Galilee", "type": "landmark", "significance": "Site of greatest sermon, new Sinai"}
+                ],
+                "people": [
+                    {"name": "Jesus", "role": "protagonist", "faction": "Divine", "description": "Teacher giving new interpretation of law"},
+                    {"name": "Disciples", "role": "ally", "faction": "Disciples", "description": "Inner circle receiving teaching"},
+                    {"name": "Crowds", "role": "neutral", "faction": "Common People", "description": "Masses drawn to Jesus' teaching"},
+                    {"name": "Pharisees", "role": "antagonist", "faction": "Religious Elite", "description": "Referenced as example of insufficient righteousness"}
+                ],
+                "politics_laws_morals": [
+                    {"type": "moral", "name": "Beatitudes", "description": "Blessed are the poor in spirit, mourning, meek, hungry for righteousness, merciful, pure, peacemakers, persecuted"},
+                    {"type": "moral", "name": "Salt and Light", "description": "Believers must preserve and illuminate the world"},
+                    {"type": "law", "name": "Law fulfilled not abolished", "description": "Jesus completes the law's true meaning"},
+                    {"type": "moral", "name": "Righteousness exceeding Pharisees", "description": "External compliance insufficient, heart matters"},
+                    {"type": "moral", "name": "Anger equals murder", "description": "Heart attitude as serious as the act"},
+                    {"type": "moral", "name": "Lust equals adultery", "description": "Internal sin as serious as external"},
+                    {"type": "moral", "name": "Cut off what causes sin", "description": "Radical measures against temptation"},
+                    {"type": "law", "name": "Divorce only for unfaithfulness", "description": "Stricter standard than Moses allowed"},
+                    {"type": "moral", "name": "Let yes be yes", "description": "No oaths needed for honest people"},
+                    {"type": "moral", "name": "Turn the other cheek", "description": "Non-retaliation, absorb evil"},
+                    {"type": "moral", "name": "Love your enemies", "description": "Radical love extending to persecutors"}
+                ]
+            },
+            "6": {
+                "title": "Sermon on the Mount - Part 2",
+                "summary": "Secret righteousness, Lord's Prayer, treasures in heaven",
+                "locations": [
+                    {"name": "Mountain in Galilee", "type": "landmark", "significance": "Continuation of sermon"}
+                ],
+                "people": [
+                    {"name": "Jesus", "role": "protagonist", "faction": "Divine", "description": "Teaching on authentic spirituality"},
+                    {"name": "Disciples", "role": "ally", "faction": "Disciples", "description": "Learning to pray and trust"},
+                    {"name": "Hypocrites", "role": "antagonist", "faction": "Religious Elite", "description": "Those who practice piety for show"}
+                ],
+                "politics_laws_morals": [
+                    {"type": "moral", "name": "Secret giving", "description": "Give to needy without announcement or recognition"},
+                    {"type": "moral", "name": "Secret prayer", "description": "Pray in private, not for public display"},
+                    {"type": "prayer", "name": "Lord's Prayer", "description": "Model prayer: hallowed name, kingdom come, daily bread, forgiveness, deliverance"},
+                    {"type": "moral", "name": "Forgive to be forgiven", "description": "Receiving forgiveness linked to giving it"},
+                    {"type": "moral", "name": "Secret fasting", "description": "Fast without showing it to others"},
+                    {"type": "moral", "name": "Treasures in heaven", "description": "Store up eternal rewards, not earthly wealth"},
+                    {"type": "moral", "name": "Eye as lamp", "description": "What you focus on determines your inner state"},
+                    {"type": "moral", "name": "Cannot serve God and money", "description": "Divided loyalty impossible"},
+                    {"type": "moral", "name": "Do not worry", "description": "Trust God for provision like birds and flowers"},
+                    {"type": "moral", "name": "Seek first the kingdom", "description": "Priority of God's kingdom, other needs follow"}
+                ]
+            },
+            "7": {
+                "title": "Sermon on the Mount - Part 3",
+                "summary": "Judging others, ask-seek-knock, narrow gate, wise builder",
+                "locations": [
+                    {"name": "Mountain in Galilee", "type": "landmark", "significance": "Conclusion of sermon"}
+                ],
+                "people": [
+                    {"name": "Jesus", "role": "protagonist", "faction": "Divine", "description": "Concluding with warnings and wisdom"},
+                    {"name": "Disciples", "role": "ally", "faction": "Disciples", "description": "Called to build on solid foundation"},
+                    {"name": "False prophets", "role": "antagonist", "faction": "Deceivers", "description": "Wolves in sheep's clothing"},
+                    {"name": "Crowds", "role": "neutral", "faction": "Common People", "description": "Amazed at teaching with authority"}
+                ],
+                "politics_laws_morals": [
+                    {"type": "moral", "name": "Do not judge hypocritically", "description": "Remove own plank before addressing others' speck"},
+                    {"type": "moral", "name": "Pearls before swine", "description": "Discernment about sharing sacred things"},
+                    {"type": "moral", "name": "Ask, seek, knock", "description": "Persistent prayer receives answer"},
+                    {"type": "moral", "name": "Golden Rule", "description": "Do to others what you want done to you"},
+                    {"type": "moral", "name": "Narrow gate", "description": "Few find the difficult path to life"},
+                    {"type": "warning", "name": "False prophets known by fruit", "description": "Actions reveal true nature"},
+                    {"type": "warning", "name": "Not everyone saying Lord Lord", "description": "Relationship over religious activity"},
+                    {"type": "moral", "name": "Wise and foolish builders", "description": "Hearing and doing vs hearing only"}
+                ]
+            },
+            "8": {
+                "title": "Healings and Authority",
+                "summary": "Jesus heals many, calms storm, casts out demons",
+                "locations": [
+                    {"name": "Capernaum", "type": "city", "significance": "Base of ministry, centurion's servant healed"},
+                    {"name": "Peter's House", "type": "building", "significance": "Peter's mother-in-law healed"},
+                    {"name": "Sea of Galilee", "type": "body_of_water", "significance": "Storm calmed, disciples' faith tested"},
+                    {"name": "Region of Gadarenes", "type": "region", "significance": "Two demon-possessed men healed, pigs drowned"}
+                ],
+                "people": [
+                    {"name": "Jesus", "role": "protagonist", "faction": "Divine", "description": "Demonstrates authority over sickness, nature, demons"},
+                    {"name": "Man with leprosy", "role": "supplicant", "faction": "Outcast", "description": "Cleansed by Jesus' touch"},
+                    {"name": "Roman Centurion", "role": "ally", "faction": "Roman Military", "description": "Gentile with great faith for servant's healing"},
+                    {"name": "Peter's mother-in-law", "role": "recipient", "faction": "Disciples' Family", "description": "Healed of fever, immediately serves"},
+                    {"name": "Disciples", "role": "ally", "faction": "Disciples", "description": "Fearful in storm, amazed at Jesus' power"},
+                    {"name": "Two demon-possessed men", "role": "recipient", "faction": "Outcast", "description": "Violent men freed from Legion of demons"},
+                    {"name": "Abraham, Isaac, Jacob", "role": "reference", "faction": "Patriarchs", "description": "Gentiles will feast with them in kingdom"}
+                ],
+                "politics_laws_morals": [
+                    {"type": "law", "name": "Show yourself to priest", "description": "Jesus respects Mosaic law for cleansing verification"},
+                    {"type": "moral", "name": "Faith over nationality", "description": "Centurion's faith exceeds Israel's"},
+                    {"type": "warning", "name": "Sons of kingdom thrown out", "description": "Jewish privilege not automatic salvation"},
+                    {"type": "cost", "name": "Foxes have holes", "description": "Following Jesus means homelessness"},
+                    {"type": "cost", "name": "Let dead bury dead", "description": "Following Jesus takes absolute priority"},
+                    {"type": "authority", "name": "Even winds and waves obey", "description": "Jesus has divine authority over creation"},
+                    {"type": "spiritual", "name": "Demons recognize Jesus", "description": "Evil spirits know who Jesus is"}
+                ]
+            },
+            "9": {
+                "title": "More Healings and Calling of Matthew",
+                "summary": "Paralytic forgiven and healed, Matthew called, various healings",
+                "locations": [
+                    {"name": "Capernaum", "type": "city", "significance": "Jesus' own town, paralytic healed"},
+                    {"name": "Tax collector's booth", "type": "workplace", "significance": "Matthew's place of work"},
+                    {"name": "Matthew's house", "type": "building", "significance": "Dinner with tax collectors and sinners"},
+                    {"name": "Ruler's house", "type": "building", "significance": "Where dead girl is raised"},
+                    {"name": "Towns and villages", "type": "region", "significance": "Jesus' teaching circuit"}
+                ],
+                "people": [
+                    {"name": "Jesus", "role": "protagonist", "faction": "Divine", "description": "Claims authority to forgive sins"},
+                    {"name": "Paralytic man", "role": "recipient", "faction": "Common People", "description": "Lowered through roof, sins forgiven, then healed"},
+                    {"name": "Matthew/Levi", "role": "ally", "faction": "Tax Collectors", "description": "Tax collector who becomes disciple and gospel writer"},
+                    {"name": "Pharisees", "role": "antagonist", "faction": "Religious Elite", "description": "Question Jesus eating with sinners"},
+                    {"name": "John's disciples", "role": "questioner", "faction": "John the Baptist", "description": "Ask about fasting practices"},
+                    {"name": "Synagogue ruler", "role": "supplicant", "faction": "Religious Leaders", "description": "Daughter dies, raised by Jesus"},
+                    {"name": "Woman with bleeding", "role": "recipient", "faction": "Outcast", "description": "12 years suffering, healed by touching cloak"},
+                    {"name": "Two blind men", "role": "recipient", "faction": "Disabled", "description": "Healed according to their faith"},
+                    {"name": "Mute demon-possessed man", "role": "recipient", "faction": "Possessed", "description": "Speaks after demon driven out"}
+                ],
+                "politics_laws_morals": [
+                    {"type": "authority", "name": "Son of Man forgives sins", "description": "Jesus claims divine prerogative"},
+                    {"type": "moral", "name": "Healthy don't need doctor", "description": "Jesus comes for sinners, not self-righteous"},
+                    {"type": "moral", "name": "Mercy not sacrifice", "description": "God desires compassion over ritual"},
+                    {"type": "teaching", "name": "New wine in new wineskins", "description": "Jesus brings new covenant, not patching old"},
+                    {"type": "faith", "name": "Your faith has healed you", "description": "Faith as conduit for healing power"},
+                    {"type": "warning", "name": "Harvest plentiful, workers few", "description": "Need for more disciples to reach people"},
+                    {"type": "accusation", "name": "By prince of demons", "description": "Pharisees accuse Jesus of satanic power"}
+                ]
+            },
+            "10": {
+                "title": "Sending Out the Twelve",
+                "summary": "Twelve apostles commissioned with authority and warnings",
+                "locations": [
+                    {"name": "Israel", "type": "nation", "significance": "Mission field limited to lost sheep of Israel"},
+                    {"name": "Towns and villages", "type": "region", "significance": "Where disciples are sent"},
+                    {"name": "Sodom and Gomorrah", "type": "reference", "significance": "Judgment comparison for rejecting towns"}
+                ],
+                "people": [
+                    {"name": "Jesus", "role": "protagonist", "faction": "Divine", "description": "Commissions and instructs the Twelve"},
+                    {"name": "Peter", "role": "ally", "faction": "Twelve Apostles", "description": "Listed first among apostles"},
+                    {"name": "Andrew", "role": "ally", "faction": "Twelve Apostles", "description": "Peter's brother"},
+                    {"name": "James son of Zebedee", "role": "ally", "faction": "Twelve Apostles", "description": "One of inner three"},
+                    {"name": "John", "role": "ally", "faction": "Twelve Apostles", "description": "Brother of James"},
+                    {"name": "Philip", "role": "ally", "faction": "Twelve Apostles", "description": "From Bethsaida"},
+                    {"name": "Bartholomew", "role": "ally", "faction": "Twelve Apostles", "description": "Also called Nathanael"},
+                    {"name": "Thomas", "role": "ally", "faction": "Twelve Apostles", "description": "Later known as doubter"},
+                    {"name": "Matthew", "role": "ally", "faction": "Twelve Apostles", "description": "The tax collector"},
+                    {"name": "James son of Alphaeus", "role": "ally", "faction": "Twelve Apostles", "description": "The lesser James"},
+                    {"name": "Thaddaeus", "role": "ally", "faction": "Twelve Apostles", "description": "Also called Judas son of James"},
+                    {"name": "Simon the Zealot", "role": "ally", "faction": "Twelve Apostles", "description": "Former political revolutionary"},
+                    {"name": "Judas Iscariot", "role": "traitor", "faction": "Twelve Apostles", "description": "The one who would betray Jesus"}
+                ],
+                "politics_laws_morals": [
+                    {"type": "mission", "name": "Go to lost sheep of Israel", "description": "Initial mission limited to Jews, not Gentiles or Samaritans"},
+                    {"type": "provision", "name": "Freely received, freely give", "description": "No payment for healing ministry"},
+                    {"type": "provision", "name": "Worker deserves his keep", "description": "Depend on hospitality, travel light"},
+                    {"type": "judgment", "name": "Shake dust off feet", "description": "Symbolic rejection of rejecting towns"},
+                    {"type": "warning", "name": "Sheep among wolves", "description": "Danger awaits, be shrewd as snakes"},
+                    {"type": "warning", "name": "Handed over to councils", "description": "Persecution by religious and civil authorities"},
+                    {"type": "promise", "name": "Spirit will speak through you", "description": "Divine help in persecution"},
+                    {"type": "warning", "name": "Family betrayal", "description": "Even family members will turn against believers"},
+                    {"type": "cost", "name": "Take up cross", "description": "Following Jesus means death to self"},
+                    {"type": "promise", "name": "Whoever receives you receives me", "description": "Disciples represent Jesus himself"}
+                ]
+            },
+            "11": {
+                "title": "Jesus and John the Baptist",
+                "summary": "John's question from prison, Jesus' testimony about John, woes on unrepentant cities",
+                "locations": [
+                    {"name": "Prison", "type": "building", "significance": "Where John is held by Herod Antipas"},
+                    {"name": "Chorazin", "type": "city", "significance": "Unrepentant city despite miracles"},
+                    {"name": "Bethsaida", "type": "city", "significance": "Unrepentant city despite miracles"},
+                    {"name": "Capernaum", "type": "city", "significance": "Jesus' base, will be brought down to Hades"},
+                    {"name": "Tyre", "type": "city", "significance": "Gentile city that would have repented"},
+                    {"name": "Sidon", "type": "city", "significance": "Gentile city that would have repented"},
+                    {"name": "Sodom", "type": "reference", "significance": "Would have remained if it saw Jesus' miracles"}
+                ],
+                "people": [
+                    {"name": "Jesus", "role": "protagonist", "faction": "Divine", "description": "Praises John, condemns unrepentant cities"},
+                    {"name": "John the Baptist", "role": "ally", "faction": "Prophets", "description": "In prison, sends disciples to ask if Jesus is the one"},
+                    {"name": "John's disciples", "role": "messenger", "faction": "John the Baptist", "description": "Carry question to Jesus and answer back"},
+                    {"name": "Elijah", "role": "reference", "faction": "Prophets", "description": "John is Elijah who was to come"}
+                ],
+                "politics_laws_morals": [
+                    {"type": "proof", "name": "Deeds prove identity", "description": "Blind see, lame walk, dead raised - proof Jesus is Messiah"},
+                    {"type": "honor", "name": "Greatest born of women", "description": "John's unique role in salvation history"},
+                    {"type": "paradox", "name": "Least in kingdom is greater", "description": "New covenant position exceeds old"},
+                    {"type": "warning", "name": "Kingdom suffers violence", "description": "Forceful opposition since John's ministry"},
+                    {"type": "criticism", "name": "This generation like children", "description": "Neither John's asceticism nor Jesus' fellowship satisfied critics"},
+                    {"type": "judgment", "name": "Woe to unrepentant cities", "description": "Greater light means greater accountability"},
+                    {"type": "revelation", "name": "Hidden from wise, revealed to children", "description": "God's reversal of expected recipients"},
+                    {"type": "invitation", "name": "Come to me, all weary", "description": "Jesus offers rest from religious burden"},
+                    {"type": "promise", "name": "My yoke is easy", "description": "Jesus' way lighter than Pharisaic law"}
+                ]
+            }
+        }
+    }
+}
+
+# =============================================================================
+# HELPER FUNCTIONS
+# =============================================================================
+
+def get_all_locations(book="matthew"):
+    """Extract all unique locations from a book"""
+    locations = []
+    if book in BIBLE_TEMPLATES:
+        for chapter_num, chapter in BIBLE_TEMPLATES[book]["chapters"].items():
+            for loc in chapter.get("locations", []):
+                if loc not in locations:
+                    locations.append(loc)
+    return locations
+
+def get_all_people(book="matthew"):
+    """Extract all unique people from a book"""
+    people = {}
+    if book in BIBLE_TEMPLATES:
+        for chapter_num, chapter in BIBLE_TEMPLATES[book]["chapters"].items():
+            for person in chapter.get("people", []):
+                if person["name"] not in people:
+                    people[person["name"]] = person
+    return list(people.values())
+
+def get_all_politics_laws_morals(book="matthew"):
+    """Extract all unique politics/laws/morals from a book"""
+    plm = []
+    seen = set()
+    if book in BIBLE_TEMPLATES:
+        for chapter_num, chapter in BIBLE_TEMPLATES[book]["chapters"].items():
+            for item in chapter.get("politics_laws_morals", []):
+                key = (item["type"], item["name"])
+                if key not in seen:
+                    seen.add(key)
+                    plm.append(item)
+    return plm
+
+def get_chapter_data(book="matthew", chapter="1"):
+    """Get all data for a specific chapter"""
+    if book in BIBLE_TEMPLATES and chapter in BIBLE_TEMPLATES[book]["chapters"]:
+        return BIBLE_TEMPLATES[book]["chapters"][chapter]
+    return None
+
+def format_locations_for_display(locations):
+    """Format locations list as markdown"""
+    if not locations:
+        return "No locations defined"
+    lines = ["| Location | Type | Significance |", "|----------|------|--------------|"]
+    for loc in locations:
+        lines.append(f"| {loc['name']} | {loc['type']} | {loc['significance']} |")
+    return "\n".join(lines)
+
+def format_people_for_display(people):
+    """Format people list as markdown"""
+    if not people:
+        return "No people defined"
+    lines = ["| Name | Role | Faction | Description |", "|------|------|---------|-------------|"]
+    for person in people:
+        lines.append(f"| {person['name']} | {person['role']} | {person['faction']} | {person['description']} |")
+    return "\n".join(lines)
+
+def format_politics_for_display(plm):
+    """Format politics/laws/morals as markdown"""
+    if not plm:
+        return "No rules defined"
+    lines = ["| Type | Name | Description |", "|------|------|-------------|"]
+    for item in plm:
+        lines.append(f"| {item['type']} | {item['name']} | {item['description']} |")
+    return "\n".join(lines)
+
+def get_chapter_summary_md(book="matthew", chapter="1"):
+    """Get formatted markdown summary for a chapter"""
+    data = get_chapter_data(book, chapter)
+    if not data:
+        return "Chapter not found"
+
+    md = f"## Chapter {chapter}: {data['title']}\n\n"
+    md += f"**Summary:** {data['summary']}\n\n"
+    md += "### Locations\n" + format_locations_for_display(data.get("locations", [])) + "\n\n"
+    md += "### People\n" + format_people_for_display(data.get("people", [])) + "\n\n"
+    md += "### Politics, Laws & Moral Rules\n" + format_politics_for_display(data.get("politics_laws_morals", []))
+    return md
+
+def generate_game_elements_from_chapter(book="matthew", chapter="1"):
+    """Generate game config elements from a chapter"""
+    data = get_chapter_data(book, chapter)
+    if not data:
+        return {}
+
+    # Convert to game config format
+    config_elements = {
+        "setting": {
+            "title": data["title"],
+            "description": data["summary"],
+            "locations": {loc["name"]: {"type": loc["type"], "description": loc["significance"]}
+                        for loc in data.get("locations", [])}
+        },
+        "characters": {
+            person["name"]: {
+                "role": person["role"],
+                "faction": person["faction"],
+                "description": person["description"]
+            } for person in data.get("people", [])
+        },
+        "rules": [
+            {"type": item["type"], "name": item["name"], "effect": item["description"]}
+            for item in data.get("politics_laws_morals", [])
+        ]
+    }
+    return config_elements
+
+# =============================================================================
+# GRADIO UI
+# =============================================================================
+
+def bible_story_elements():
+    with gr.Tab("Using Bible as Inspiration") as story_inspiration:
+        gr.Markdown("""
+        # Bible Story Templates for Game Config Generation
+
+        Use these structured templates to generate game configs based on Biblical narratives.
+        Each chapter is broken down into **Locations**, **People**, and **Politics/Laws/Moral Rules**.
+        """)
+
+        with gr.Tab("Matthew Overview"):
+            gr.Markdown(f"**Source:** [{BIBLE_TEMPLATES['matthew']['book_name']}]({BIBLE_TEMPLATES['matthew']['youtube_link']})")
+
+            # Summary stats
+            all_locs = get_all_locations("matthew")
+            all_people = get_all_people("matthew")
+            all_plm = get_all_politics_laws_morals("matthew")
+
+            gr.Markdown(f"""
+            ### Template Statistics (Chapters 1-11)
+            - **Locations:** {len(all_locs)} unique places
+            - **People:** {len(all_people)} unique characters
+            - **Rules/Morals:** {len(all_plm)} unique laws, morals, and political elements
+            """)
+
+            with gr.Accordion("All Locations", open=False):
+                gr.Markdown(format_locations_for_display(all_locs))
+
+            with gr.Accordion("All People", open=False):
+                gr.Markdown(format_people_for_display(all_people))
+
+            with gr.Accordion("All Politics/Laws/Morals", open=False):
+                gr.Markdown(format_politics_for_display(all_plm))
+
+        with gr.Tab("Chapter Browser"):
+            chapter_dropdown = gr.Dropdown(
+                choices=[(f"Chapter {k}: {v['title']}", k) for k, v in BIBLE_TEMPLATES["matthew"]["chapters"].items()],
+                label="Select Chapter",
+                value="1"
+            )
+            chapter_display = gr.Markdown(get_chapter_summary_md("matthew", "1"))
+
+            chapter_dropdown.change(
+                fn=lambda ch: get_chapter_summary_md("matthew", ch),
+                inputs=[chapter_dropdown],
+                outputs=[chapter_display]
+            )
+
+        with gr.Tab("Generate Game Elements"):
+            gr.Markdown("Select a chapter to generate game config elements from its narrative structure.")
+
+            gen_chapter = gr.Dropdown(
+                choices=[(f"Chapter {k}: {v['title']}", k) for k, v in BIBLE_TEMPLATES["matthew"]["chapters"].items()],
+                label="Select Chapter",
+                value="1"
+            )
+
+            def random_bible_chapter():
+                """Select a random chapter from available chapters."""
+                import random
+                chapters = list(BIBLE_TEMPLATES["matthew"]["chapters"].keys())
+                return random.choice(chapters)
+
+            with gr.Row():
+                random_chapter_btn = gr.Button("🎲 Random Chapter", variant="secondary")
+                generate_btn = gr.Button("Generate Game Elements", variant="primary")
+
+            output_json = gr.Code(language="json", label="Generated Game Elements")
+
+            random_chapter_btn.click(
+                fn=random_bible_chapter,
+                outputs=[gen_chapter]
+            )
+
+            import json
+            generate_btn.click(
+                fn=lambda ch: json.dumps(generate_game_elements_from_chapter("matthew", ch), indent=2),
+                inputs=[gen_chapter],
+                outputs=[output_json]
+            )
+
+    return story_inspiration

condition_evaluator.py

@@ -0,0 +1,458 @@
+"""
+Condition Evaluator - Logic system for game config conditions and transitions.
+
+Provides:
+- ConditionEvaluator: Evaluate condition expressions against GameState
+- TransitionResolver: Resolve dynamic transitions (random, conditional)
+- EffectApplicator: Apply declarative effects to GameState
+"""
+
+from typing import Any, Dict, List, Optional, Union
+import random
+
+from game_state import GameState
+
+
+class ConditionEvaluator:
+    """
+    Evaluates condition expressions against GameState.
+
+    Supports:
+    - Atomic conditions: has_item, met_person, flag, visited, mission_*, money, counter, knowledge
+    - Compound conditions: and, or, not
+    - Numeric comparisons: gte, lte, gt, lt, eq
+    """
+
+    def __init__(self, game_state: GameState):
+        self.state = game_state
+
+    def evaluate(self, condition: Any) -> bool:
+        """
+        Evaluate a condition expression.
+
+        Args:
+            condition: Can be:
+                - None/empty dict: Always True (no condition)
+                - str: Flag name to check
+                - dict: Condition expression
+
+        Returns:
+            bool: Whether condition is satisfied
+        """
+        # No condition = always true (backwards compatible)
+        if condition is None or condition == {}:
+            return True
+
+        # Simple string = flag check
+        if isinstance(condition, str):
+            return self.state.has_flag(condition)
+
+        if not isinstance(condition, dict):
+            return False
+
+        # Compound operators
+        if "and" in condition:
+            return all(self.evaluate(c) for c in condition["and"])
+
+        if "or" in condition:
+            return any(self.evaluate(c) for c in condition["or"])
+
+        if "not" in condition:
+            return not self.evaluate(condition["not"])
+
+        # Atomic conditions
+        return self._evaluate_atomic(condition)
+
+    def _evaluate_atomic(self, condition: Dict) -> bool:
+        """Evaluate a single atomic condition."""
+
+        # ==================== Item Checks ====================
+        if "has_item" in condition:
+            return self.state.has_item(condition["has_item"])
+
+        if "not_has_item" in condition:
+            return not self.state.has_item(condition["not_has_item"])
+
+        # ==================== Person Checks ====================
+        if "met_person" in condition:
+            return self.state.has_met(condition["met_person"])
+
+        if "not_met_person" in condition:
+            return not self.state.has_met(condition["not_met_person"])
+
+        # ==================== Flag Checks ====================
+        if "flag" in condition:
+            return self.state.has_flag(condition["flag"])
+
+        if "not_flag" in condition:
+            return not self.state.has_flag(condition["not_flag"])
+
+        # ==================== Location Checks ====================
+        if "visited" in condition:
+            return self.state.has_visited(condition["visited"])
+
+        if "not_visited" in condition:
+            return not self.state.has_visited(condition["not_visited"])
+
+        if "discovered" in condition:
+            return self.state.has_discovered(condition["discovered"])
+
+        # ==================== Mission Checks ====================
+        if "mission_complete" in condition:
+            return self.state.is_mission_complete(condition["mission_complete"])
+
+        if "mission_active" in condition:
+            return self.state.is_mission_active(condition["mission_active"])
+
+        if "mission_failed" in condition:
+            return self.state.is_mission_failed(condition["mission_failed"])
+
+        # ==================== Money Comparison ====================
+        if "money" in condition:
+            return self._compare_numeric(self.state.money, condition["money"])
+
+        # ==================== Counter Comparison ====================
+        if "counter" in condition:
+            counter_cond = condition["counter"]
+            for counter_name, comparison in counter_cond.items():
+                value = self.state.get_counter(counter_name)
+                if not self._compare_numeric(value, comparison):
+                    return False
+            return True
+
+        # ==================== Knowledge Checks ====================
+        if "knowledge" in condition:
+            return self.state.has_knowledge(condition["knowledge"])
+
+        if "knowledge_value" in condition:
+            kv = condition["knowledge_value"]
+            key = kv.get("key")
+            actual = self.state.get_knowledge(key)
+            if "eq" in kv:
+                return actual == kv["eq"]
+            if "neq" in kv:
+                return actual != kv["neq"]
+            return False
+
+        # ==================== Reputation Check ====================
+        if "reputation" in condition:
+            rep_cond = condition["reputation"]
+            npc = rep_cond.get("npc")
+            actual = self.state.get_reputation(npc)
+            return self._compare_numeric(actual, rep_cond)
+
+        # ==================== Visit Count Check ====================
+        if "visit_count" in condition:
+            vc = condition["visit_count"]
+            state_key = vc.get("state")
+            actual = self.state.get_visit_count(state_key)
+            return self._compare_numeric(actual, vc)
+
+        # Unknown condition type - return False (safe default)
+        return False
+
+    def _compare_numeric(self, actual: int, comparison: Any) -> bool:
+        """
+        Evaluate numeric comparisons.
+
+        comparison can be:
+            - int: exact match
+            - {"gte": n}: >=
+            - {"lte": n}: <=
+            - {"gt": n}: >
+            - {"lt": n}: <
+            - {"eq": n}: ==
+            - {"neq": n}: !=
+        """
+        if isinstance(comparison, (int, float)):
+            return actual == comparison
+
+        if isinstance(comparison, dict):
+            if "gte" in comparison:
+                return actual >= comparison["gte"]
+            if "lte" in comparison:
+                return actual <= comparison["lte"]
+            if "gt" in comparison:
+                return actual > comparison["gt"]
+            if "lt" in comparison:
+                return actual < comparison["lt"]
+            if "eq" in comparison:
+                return actual == comparison["eq"]
+            if "neq" in comparison:
+                return actual != comparison["neq"]
+
+        return False
+
+
+class TransitionResolver:
+    """
+    Resolves transition specifications to concrete target states.
+    Handles deterministic, random, and conditional transitions.
+    """
+
+    def __init__(self, game_state: GameState):
+        self.state = game_state
+        self.evaluator = ConditionEvaluator(game_state)
+
+    def resolve(self, transition: Any) -> str:
+        """
+        Resolve a transition specification to a target state.
+
+        Args:
+            transition: Can be:
+                - str: Direct target (current behavior, deterministic)
+                - dict: Complex transition spec (random, conditional)
+
+        Returns:
+            str: Target state name
+
+        Raises:
+            ValueError: If transition format is invalid or no condition matches
+        """
+        # Simple string = deterministic transition (backwards compatible)
+        if isinstance(transition, str):
+            return transition
+
+        if not isinstance(transition, dict):
+            raise ValueError(f"Invalid transition type: {type(transition)}")
+
+        # Weighted random: {"random": [["state_a", 0.7], ["state_b", 0.3]]}
+        if "random" in transition:
+            return self._resolve_weighted_random(transition["random"])
+
+        # Equal-weight pool: {"random_from": ["a", "b", "c"]}
+        if "random_from" in transition:
+            pool = transition["random_from"]
+            if not pool:
+                raise ValueError("random_from pool is empty")
+            return random.choice(pool)
+
+        # Simple conditional: {"if": condition, "then": target, "else": fallback}
+        if "if" in transition:
+            condition = transition["if"]
+            if self.evaluator.evaluate(condition):
+                then_target = transition.get("then")
+                if then_target:
+                    return self.resolve(then_target)
+            else:
+                else_target = transition.get("else")
+                if else_target:
+                    return self.resolve(else_target)
+            # If no matching branch, this is an error
+            raise ValueError("Conditional transition has no matching branch")
+
+        # Chained conditions: {"conditions": [{if, then}, {if, then}, {default}]}
+        if "conditions" in transition:
+            for cond_block in transition["conditions"]:
+                # Default case (no condition)
+                if "default" in cond_block:
+                    return self.resolve(cond_block["default"])
+                # Conditional case
+                if "if" in cond_block and self.evaluator.evaluate(cond_block["if"]):
+                    return self.resolve(cond_block["then"])
+            # No condition matched and no default
+            raise ValueError("No condition matched and no default provided")
+
+        raise ValueError(f"Unknown transition format: {transition}")
+
+    def _resolve_weighted_random(self, weights: List) -> str:
+        """
+        Select from weighted random options.
+
+        Args:
+            weights: List of [state, probability] pairs
+
+        Returns:
+            Selected state name
+        """
+        if not weights:
+            raise ValueError("Weighted random list is empty")
+
+        states = [w[0] for w in weights]
+        probs = [w[1] for w in weights]
+
+        # Normalize probabilities if they don't sum to 1
+        total = sum(probs)
+        if total <= 0:
+            raise ValueError("Weights must sum to positive number")
+        if abs(total - 1.0) > 0.001:
+            probs = [p / total for p in probs]
+
+        return random.choices(states, weights=probs, k=1)[0]
+
+
+class EffectApplicator:
+    """
+    Applies declarative effect specifications to GameState.
+
+    Supports:
+    - Items: add_item, remove_item
+    - Money: add_money, remove_money
+    - People: add_person
+    - Locations: add_location
+    - Flags: set_flag, clear_flag
+    - Counters: set_counter, increment, decrement
+    - Knowledge: set_knowledge
+    - Missions: start_mission, complete_mission, fail_mission
+    - Reputation: adjust_reputation
+    """
+
+    def __init__(self, game_state: GameState):
+        self.state = game_state
+
+    def apply(self, effects: Dict) -> None:
+        """
+        Apply a set of effects to the game state.
+
+        Args:
+            effects: Dict of effect specifications
+        """
+        if not effects:
+            return
+
+        # ==================== Item Effects ====================
+        if "add_item" in effects:
+            item = effects["add_item"]
+            if isinstance(item, list):
+                self.state.add_items(item)
+            else:
+                self.state.add_item(item)
+
+        if "remove_item" in effects:
+            item = effects["remove_item"]
+            if isinstance(item, list):
+                for i in item:
+                    self.state.remove_item(i)
+            else:
+                self.state.remove_item(item)
+
+        # ==================== Money Effects ====================
+        if "add_money" in effects:
+            self.state.add_money(effects["add_money"])
+
+        if "remove_money" in effects:
+            self.state.remove_money(effects["remove_money"])
+
+        if "set_money" in effects:
+            self.state.money = effects["set_money"]
+
+        # ==================== Person Effects ====================
+        if "add_person" in effects:
+            person = effects["add_person"]
+            if isinstance(person, list):
+                for p in person:
+                    self.state.meet_person(p)
+            else:
+                self.state.meet_person(person)
+
+        # ==================== Location Effects ====================
+        if "add_location" in effects:
+            location = effects["add_location"]
+            if isinstance(location, list):
+                for loc in location:
+                    self.state.discover_location(loc)
+            else:
+                self.state.discover_location(location)
+
+        if "visit_location" in effects:
+            location = effects["visit_location"]
+            if isinstance(location, list):
+                for loc in location:
+                    self.state.visit_location(loc)
+            else:
+                self.state.visit_location(location)
+
+        # ==================== Flag Effects ====================
+        if "set_flag" in effects:
+            flag = effects["set_flag"]
+            if isinstance(flag, list):
+                for f in flag:
+                    self.state.set_flag(f, True)
+            elif isinstance(flag, dict):
+                for f, v in flag.items():
+                    self.state.set_flag(f, v)
+            else:
+                self.state.set_flag(flag, True)
+
+        if "clear_flag" in effects:
+            flag = effects["clear_flag"]
+            if isinstance(flag, list):
+                for f in flag:
+                    self.state.clear_flag(f)
+            else:
+                self.state.clear_flag(flag)
+
+        if "toggle_flag" in effects:
+            flag = effects["toggle_flag"]
+            if isinstance(flag, list):
+                for f in flag:
+                    self.state.toggle_flag(f)
+            else:
+                self.state.toggle_flag(flag)
+
+        # ==================== Counter Effects ====================
+        if "set_counter" in effects:
+            for name, value in effects["set_counter"].items():
+                self.state.set_counter(name, value)
+
+        if "increment" in effects:
+            for name, amount in effects["increment"].items():
+                self.state.increment_counter(name, amount)
+
+        if "decrement" in effects:
+            for name, amount in effects["decrement"].items():
+                self.state.decrement_counter(name, amount)
+
+        # ==================== Knowledge Effects ====================
+        if "set_knowledge" in effects:
+            for key, value in effects["set_knowledge"].items():
+                self.state.update_knowledge(key, value)
+
+        if "remove_knowledge" in effects:
+            key = effects["remove_knowledge"]
+            if isinstance(key, list):
+                for k in key:
+                    self.state.remove_knowledge(k)
+            else:
+                self.state.remove_knowledge(key)
+
+        # ==================== Mission Effects ====================
+        if "start_mission" in effects:
+            mission = effects["start_mission"]
+            if isinstance(mission, str):
+                self.state.start_mission(mission)
+            elif isinstance(mission, dict):
+                for m_id, m_data in mission.items():
+                    self.state.start_mission(m_id, m_data if isinstance(m_data, dict) else None)
+            elif isinstance(mission, list):
+                for m in mission:
+                    self.state.start_mission(m)
+
+        if "complete_mission" in effects:
+            mission = effects["complete_mission"]
+            if isinstance(mission, list):
+                for m in mission:
+                    self.state.complete_mission(m)
+            else:
+                self.state.complete_mission(mission)
+
+        if "fail_mission" in effects:
+            mission = effects["fail_mission"]
+            if isinstance(mission, list):
+                for m in mission:
+                    self.state.fail_mission(m)
+            else:
+                self.state.fail_mission(mission)
+
+        if "update_mission" in effects:
+            for mission_id, updates in effects["update_mission"].items():
+                self.state.update_mission(mission_id, updates)
+
+        # ==================== Reputation Effects ====================
+        if "adjust_reputation" in effects:
+            for npc, change in effects["adjust_reputation"].items():
+                self.state.adjust_reputation(npc, change)
+
+        if "set_reputation" in effects:
+            for npc, value in effects["set_reputation"].items():
+                self.state.npc_reputation[npc] = value

config_dev_assistance_reference.md

@@ -0,0 +1,273 @@
+# Config Development Assistance - Reference Guide
+
+> End Goal for this tab is to be able to make Story based games using mechanics based games (Chess, Poker, Sudoku, Rubiks Cube, etc.) as a conduit
+
+## Core Principles
+
+- Sometimes a fun game includes unfairness - Elden Ring (Controls and movement restrictions), Boss fights in every game
+- Jonas Tyroller (https://youtu.be/o5K0uqhxgsE) - This problem changes your perspective on game dev - minimise the cost of exploration so you can explore more (17:00) | dont make the same game again but worse. How can we measure worse? (Negative Reviews (Eg. Steam / Play or Apple Store / Game Journalists) / Reddit posts with complaints / Youtube Video Analysis Conclusions)
+- Every theme in the world can be turned into a battle story as that is how resource accumulation works --> Resources are normally hard to find and therefore scatter across a map
+- Ending Conditions --> Main Villain Antagonist Themes --> Travel, Politics and Combat needed to reach ending --> Characters
+
+---
+
+## 1. Some Ideas About Games Fundamentals
+
+- Is the universal rule as something done in less time is always harder and sought after
+- Games are ruled by one rule that determines win / loss (personal objective / competition). The main rule comes from the environment of the game eg. soccer = field + players + ball + marked goals and only then main rule is when ball goes into goal then goal scored. After that extra rules try keep the game interesting and sustainable eg. offside, deadballs, cards
+- **Tangible environments** (mainly real life)
+- **Intangible environments** (void / in your head / fictional places)
+- Fun = Avoiding Negatives and experiencing all content. Need a list of negative things that can happen
+- A game is alive when the same decisions wont work over and over - this means the game is designed to have the user answer all options and then have random choices get random answers
+- Good environments for randomness = anything with a queue like traffic or even the weather (rain / flood chance) - lead to player being overprepared for some situations and underprepared at the same time for others
+
+---
+
+## 2. Simple with Consequences and 'Fun' Built
+
+- Ask for x stories reached through x decision points
+- **Prompt 1** - Is there a way to tell 8 stories from the same opening using 2 decision points to reach them
+- **Prompt 2** - For each verb item list things a normal person wouldn't want to happen
+
+---
+
+## 3. Simple Structure
+
+> AI is good walking a tightrope but not setting up the tightrope. Structure in final format (JSON / Twee) --> current prompt: what would this config look like in Twee?
+
+### 3.1 Generator
+- A long game is a bunch of short games
+- Click the button to generate a random timeline and story based on UI elements and story events. Ask an LLM to use this to write a story around
+
+---
+
+## 4. More Robust
+
+- The main idea is locations + Personal Relationships + bystanders = foundation to write game mechanics into eg. random bystander = candidate for a DLC / sequel story and can be rewritten as character acquaintances / relatives
+- Conflict Ideas - in Overengineered Tab
+
+---
+
+## 5. Overengineered
+
+> Current [Timeline] Workflow = [Precreation] Mermaid Diagram to (1) Story to (2) [Creation] Initial JSON (through LLM and fix JSON by hand) to (3) [Postcreation] JSON Corrections (through LLM and fix JSON by hand) to (4) Media prompts to (5) Asset Generation to (6) JSON Media field population
+
+### 5.1 Pre - Qualitative Considerations
+
+- Ending Conditions --> Main Villain Antagonist Themes --> Travel, Politics and Combat needed to reach ending --> Characters
+- Modern game commonalities = travel, 'politics' (cheatcode is related family members in high positions) (personal relationship effects on the world) and combat (physical or verbal eg. negotiation)
+- Politics within a group origins = Easiest to understand interpersonal issues = betrayal and lack of sympathy, unfair expectations (Oblivious Decision making) or misinterpretation of actions under these categories
+- A game is about conveying an experience to the user - this is why media is heavily used
+- Need to learn how rules (our preferences) affect the config creation process. eg. core game loop - Write a story where the plot only moves based on - [insert core game loop]
+
+#### 5.1.1 Ending as the Start
+
+- The issue with a comprehensive game is that decisions with consequences can be made therefore as many endings as possible so one ending as the start is an incorrect approach
+
+**Prompts:**
+- "Analyse the following statement and provide 50 ideas for good starting points to develop from - A good ending is predictable in shape from the beginning of the story but the finer details hidden till the very end" (Tested with o1)
+- "List 30 stereotypical story endings" (Tested with groq llama-3.3-70B-specdec)
+
+**How to turn an ending into an intro:**
+- What is the furthest away point from this that the main character can be?
+
+#### 5.1.2 In Between the Ending and the Intro
+
+- Travel, Politics and Combat needed to reach ending and Character development
+
+#### 5.1.3 Review / Parody as the Start
+
+- For a story Movies are a better source of inspiration for structures you can use (There's way more popular movies than popular games) - Screen Junkies (For Cliches Exposure) / Cinema Sins (For plotholes/inconsistencies to avoid)
+
+#### 5.1.4 Game/Story Wiki Contents Pages
+
+- Game/Story Wiki Contents pages are normally long lists so they help you to see how many lists you need and the length of the lists to give an idea / reference for whether you need more or less complexity
+
+#### 5.1.5 Media as Inspiration
+
+- Models like QVQ-72B-Preview can turn any picture into a list of potential scenes the image can represent. Need to find a way for LLMs to judge melodies and songs
+- Some Songs I would like to be able base a game around - Tank and Various = If you Dream, Michael Buble = Home
+
+#### 5.1.6 Main Parts of Stories to Put into Structures
+
+**Purpose (The types of decisions you want the user to make) (Main Theme):**
+- Unpredictable Nuances (Any movie) / Simulation (eg. Work - mixing rare industry crossover) (eg. A phrasebook into interactive game) / Time capsule / Tangible Metaphor / Song Concept as game / Advert as a game
+- References: https://en.wikipedia.org/wiki/Philosophy, https://en.wikipedia.org/wiki/Moral_injury
+
+**Conflicts:**
+- Most stories are based around conflicts
+
+**Setting:**
+- Reference: https://en.wikipedia.org/wiki/History#Periods
+
+**Locations:**
+- Jungle, Sea, Desert, Snow, City, Village, Space
+
+**Character Relations:**
+- Friend or foe
+
+**Character Archetypes:**
+- (To be expanded)
+
+**Additional Themes:**
+- (To be expanded)
+
+#### 5.1.7 Generalized Inspiration from Existing Games
+
+- Random Scenario / Song to 'full game' manual or auto is end goal
+- Components (outside Code Support for Config): Decisions (and context explanation), Nested Sections, Media (Especially to affect decisions), Replayability (GTA and Tekken type mechanics in text form), Theme integration (Modified Variables that affect UI or config order)
+- Existing Games eg. GTA Heists - Same Map with overlapping branching narratives, Battlefront - Elites amongst Commoners, Tekken Casino (one mistake = 1/2 or 1/3 of your Resources) and Turn based: 'Tactics' type nintendo games, Chess (and any other tile based game)
+- Existing Game Rules for text - Cyberpunk RED
+- Community playthrough = Tally of players choices, Random item placed in a random location - first person to get it wins, Survival by location or characters met
+- Some Kinds of game skeletons ideas - Timelines, Graph as State machine paths, Economy ecosystem
+
+**Structural Inspirations:**
+- GTA Heists - Replayability and stakes
+- Tekken - 2/3 mistakes = lost round
+- Elden Ring - Story telling by traversal of map
+- Sports Scores
+
+**Test Prompt for Models:**
+> Please make 10 python lists for the types of media files and their purposes in a game and then use those lists to random generate a timeline of 20 items when the function is called. Great next suggest ways to improve this function to create better timelines
+
+#### 5.1.8 Worldbuilding Tools
+
+- Good worldbuilding makes new scenarios automatic
+- In a game awareness = directly affect one of the characters - Any time fights are involved, paralympics categorisations can be inspiration (watched paralympics and wanted to learn the categories eg. s10)
+
+**Using Law as inspiration:**
+- SA Constitution
+- SA Companies Act
+
+#### 5.1.9 Concept Combination Brainstorm
+
+- The story and the gameplay don't have to occur at the same time
+- A timeline is the most important part of the story - once that is set you can do anything?
+- Media Critiques (eg. Youtube Rants) as Prompts to whole games as interactive explanation
+
+---
+
+### 5.2 Mermaid Diagram / Structural Considerations to Story
+
+#### 5.2.1 HF Datasets as Scenario Inspiration
+
+- https://huggingface.co/datasets/thesven/gsm8k-reasoning
+- https://huggingface.co/datasets/HuggingFaceFW/fineweb
+- HuggingFaceFW/fineweb-edu
+- https://huggingface.co/datasets/HuggingFaceFV/finevideo
+- https://huggingface.co/spaces/HuggingFaceFV/FineVideo-Explorer
+- Translations: https://huggingface.co/datasets/opencsg/chinese-fineweb-edu
+
+#### 5.2.2 Structure - (Non/)Linear Storylines
+
+> Trying to abstract the process into one workflow is beyond me so multiple paths to goal (config) is the aim now
+
+**Branching - Decisions / Timeline Creation:**
+- Structures for interesting timeline progression
+- Claude Artifacts to illustrate nested structure brainstorms:
+  - https://claude.site/artifacts/4a910d81-1541-49f4-8531-4f27fe56cd1e
+  - https://claude.site/artifacts/265e9242-2093-46e1-9011-ed6ad938be90?fullscreen=false
+- Consideration: Story from the perspective of Main character or NPC in the LLM generated story
+
+**Linear - Existing Media eg. Songs and Screenshots:**
+- Media position in the story part: beginning, during or end
+- Create media first and then ask LLM to make join points in the config. For images need to add the location to every prompt or images will be in random locations
+
+**Linear - Machine Learning Architectures as Game Maps:**
+- Transformers, SSMs, Image and Video Generation Architectures, GANs, RNNs, etc.
+
+**Linear - Prompt Engineering as Basis for Ideation:**
+- Current Assisted workflow idea: Story timeline events suggestions (LLM / Premade List) | Merging events with premade mermaid structures (LLM + Story Text + Mermaid Text) | Edit mermaid till satisfied (LLM + Story Text) | Ask LLM to convert to config (LLM + JSON Text) | Edit config (LLM / User with format assistance or not) | Playtest and go back to mermaid or config if there are problems
+- Interactive movie (UI interaction or no progress) vs Branching Paths (Maze)
+- Things that can change the workflow: Asset First (Make Asset and make the transitions using LLM), Export First (Custom JS config, Playcanvas, Unreal Engine reverse engineered to this spaces config?) Game Mechanics First (eg. Player Stats, Inventory and NPCS not implemented yet, so traversal type games best aka graph like structures)
+- Config writing = Remix old one, Ask LLM to make one, Endless combination testing using the prompt engineering above or writing by hand (prompt engineering on yourself)
+- Can use song lyrics as thematic source
+
+**Branching - Network Analysis to Game Config:**
+- Placeholder for analysing multiple stories for their network structures and creating general rules for a structure generator based on named entity recognition and bias to locations or people - The extreme long way
+
+**Linear - Chess PNG to Game Config:**
+- Any Chess match can serve as end of game final battle
+
+**Note:** Below 70B (April 2024) seem to struggle here
+
+---
+
+### 5.3 Config Creation
+
+> Can use Mermaid scaffold or not
+
+**AI Generates Scaffolds - Notes:**
+- 8b size models make Format mistakes. For extension purposes this step specifically might have to be function call only if you explain the tool can take as many blocks as necessary
+
+**Extension Ideas:**
+- The basic idea is just make a new story and fight the JSON issues to make them fit and then rinse and repeat
+- Extension = any description in original JSON as the theme using the prompt template
+- Ask for incorporation of mermaid structure into JSON or ask for how the mermaid structure would change the JSON / story
+
+---
+
+### 5.4 Post-creation
+
+> Assumed story is complete at this stage / will be continued in separate config
+
+#### 5.4.1 Initial Media Generation
+- Placeholder for verb extraction from description and choices - to help guide initial media population
+- To do a full test need media - Fast and quality: https://huggingface.co/spaces/black-forest-labs/FLUX.1-schnell
+
+#### 5.4.2 JSON Corrections
+
+**Prompt:** "Let's critique this JSON to find areas to fix"
+
+#### 5.4.3 JSON to Media Prompts
+
+- This Step specifically has to be function call only
+- Gemma-9b and Mistral 8x7b is better at this prompt than llama 3.1 8b and 70b. Can add (each media field must get an entry) and (in python list of list format for plug and play) but they affect final output
+
+**Prompt:** "Let's make a list for the prompts we will use to make media objects in this JSON. Make one for a person to interpret and one for direct media generators that focus on keywords:"
+
+#### 5.4.4 Media Prompts to Asset Generation to JSON Population
+
+- This Step specifically has to be function call only
+- This Step can be merged with the next if we can make an editor like in the semi-Auto space in test and edit tailored to just accepting the JSON and exposing only media part for editing
+
+**Prompts:**
+- "For each Media item described classify it by media type and comment if in a story setting it would need timing"
+- "Here is a list of file names - assume they are in the order of the empty media sections of the JSON and rewrite the JSON"
+
+#### 5.4.5 Quick Ways to Evaluate Current Config
+
+**Prompt to use with SOTA LLMs:**
+> This config is for a basic text based game engine. I don't have any structural metrics to assess the quality of the config. What JSON things can we look at to see if it may be too bland for a person testing the game?
+
+**Original Claude 3.5 Sonnet Response snippets:**
+
+1. **Limited state variety:** With only 13 states across 5 locations, the game might feel short and lacking in diversity. Consider adding more locations or states within existing locations.
+2. **Low average choices:** An average of 1.92 choices per state might make the game feel linear. Increasing the number of choices in more states could improve player engagement.
+3. **Limited consequences:** Only 3 states have consequences, which might make player choices feel less impactful. Adding more consequences could increase the sense of agency.
+4. **Short descriptions:** The average description length of 13.15 words might not provide enough detail to immerse players. Consider expanding descriptions to create a richer narrative.
+5. **Lack of media:** No states currently use media elements, which could make the game feel less engaging. Adding images, sound effects, or other media could enhance the player experience.
+6. **Limited narrative branching:** While there are some loops and choices, the overall structure is relatively linear. Adding more branching paths could increase replayability and player interest.
+
+**To make the game less bland, consider:**
+- Adding more states and locations
+- Increasing the number of choices in each state
+- Implementing more consequences for player actions
+- Expanding descriptions to create a richer narrative
+- Incorporating media elements
+- Creating more diverse paths through the game
+
+#### 5.4.6 Improvement of the Default Config
+
+- Example of how to advance a game config with LLM - end goal is to have automatic workflow that takes these considerations into account
+- Things missing from the game engine - Economics and Basic Politics (NPC affiliation)
+
+---
+
+## 6. Translated/Transposed Mechanics
+
+- Interactive Fun (one form) = Avoiding something you don't want to happen in as dramatic fashion as possible = in '1D' format that can mean avoiding deadends and if you stack stories on stories the deadends can pile up
+- 1D games fun = ??? (Haven't figured it out yet) same as a navigation game? Reaching the end is the current end aka the game is essentially a number password and wrong input means a deadend where the full password = full story - chained stories with deadends = same missing back story in a long story = a punishment to some and a reward to others
+- Ideas for options based on existing 2D / 3D games
+- Most game mechanics = button press + animation == in 1D animations = text description / picture
+- Tekken - Kick and Punch in extreme detail + complex input buttons

config_linting.py

@@ -0,0 +1,1256 @@
+"""
+Config Linting / Story Health Validation
+
+Automated checks for game config quality:
+- Branching validation (graph integrity)
+- Story flags (potential issues)
+- Mermaid diagram generation
+"""
+
+import json
+from collections import deque
+
+
+def parse_config(config_input):
+    """Parse config from string or dict, handle wrapper keys."""
+    if isinstance(config_input, str):
+        try:
+            data = json.loads(config_input)
+        except json.JSONDecodeError as e:
+            return None, f"JSON Parse Error: {e}"
+    else:
+        data = config_input
+
+    # Handle wrapper keys (masterlocation1, etc.)
+    if len(data) == 1:
+        key = list(data.keys())[0]
+        if isinstance(data[key], dict) and 'end' in data[key]:
+            return data[key], None
+
+    return data, None
+
+
+def flatten_nested_config(data):
+    """
+    Flatten a nested location->state config into flat state dict.
+
+    Detects if config is nested (location contains states with 'description')
+    vs flat (states directly have 'description').
+
+    Returns: (flattened_dict, is_nested)
+    """
+    if not data or not isinstance(data, dict):
+        return data, False
+
+    # Check if this is a nested structure
+    # A nested structure has: location -> state -> {description, choices, transitions}
+    # A flat structure has: state -> {description, choices, transitions}
+
+    first_key = list(data.keys())[0]
+    first_value = data[first_key]
+
+    if not isinstance(first_value, dict):
+        return data, False
+
+    # If the first value has 'description', it's flat
+    if 'description' in first_value:
+        return data, False
+
+    # Check if first value contains dicts with 'description' (nested)
+    for inner_key, inner_value in first_value.items():
+        if isinstance(inner_value, dict) and 'description' in inner_value:
+            # This is nested - flatten it
+            flattened = {}
+            for location, states in data.items():
+                if isinstance(states, dict):
+                    for state_name, state_data in states.items():
+                        if isinstance(state_data, dict) and 'description' in state_data:
+                            flat_key = f"{location}_{state_name}"
+                            flattened[flat_key] = state_data
+            return flattened, True
+
+    # Not clearly nested, return as-is
+    return data, False
+
+
+def validate_branching(config_input):
+    """
+    Validate config branching/graph integrity.
+
+    Returns dict with:
+    - errors: Critical issues (broken transitions)
+    - warnings: Potential issues (orphaned states, dead ends)
+    - stats: Metrics about the config
+    """
+    data, error = parse_config(config_input)
+    if error:
+        return {"errors": [error], "warnings": [], "stats": {}}
+
+    # Flatten nested configs (location -> state -> data)
+    data, is_nested = flatten_nested_config(data)
+
+    errors = []
+    warnings = []
+
+    all_states = set(data.keys())
+
+    # Track which states are targeted by transitions
+    targeted_states = set()
+
+    for state_name, state_data in data.items():
+        if not isinstance(state_data, dict):
+            continue
+
+        choices = state_data.get('choices', [])
+        transitions = state_data.get('transitions', {})
+
+        # Check: All transition targets exist
+        for choice, target in transitions.items():
+            # Handle nested location_state format
+            if '_' in target and target not in all_states:
+                # Try parsing as location_state
+                parts = target.rsplit('_', 1)
+                if len(parts) == 2:
+                    location, inner_state = parts
+                    if location in all_states:
+                        loc_data = data.get(location, {})
+                        if isinstance(loc_data, dict) and inner_state in loc_data:
+                            targeted_states.add(location)
+                            continue
+
+                errors.append(f"'{state_name}': transition '{choice}' -> '{target}' (target doesn't exist)")
+            else:
+                if target in all_states:
+                    targeted_states.add(target)
+                else:
+                    errors.append(f"'{state_name}': transition '{choice}' -> '{target}' (target doesn't exist)")
+
+        # Check: Choices match transition keys
+        choice_set = set(choices) if choices else set()
+        transition_keys = set(transitions.keys())
+
+        missing_transitions = choice_set - transition_keys
+        extra_transitions = transition_keys - choice_set
+
+        if missing_transitions:
+            errors.append(f"'{state_name}': choices without transitions: {missing_transitions}")
+        if extra_transitions:
+            warnings.append(f"'{state_name}': transitions without choices: {extra_transitions}")
+
+    # Find orphaned states (not targeted by any transition, except start states)
+    # Assume first state or common names are start states
+    start_candidates = {'start', 'intro', 'beginning', 'arrival', 'location1'}
+    first_state = list(data.keys())[0] if data else None
+
+    orphaned = all_states - targeted_states - {'end'} - start_candidates
+    if first_state:
+        orphaned.discard(first_state)
+
+    if orphaned:
+        warnings.append(f"Potentially orphaned states (unreachable): {orphaned}")
+
+    # Find dead ends (no transitions out, excluding valid ending states)
+    dead_ends = []
+    valid_endings = []
+    for state_name, state_data in data.items():
+        if not isinstance(state_data, dict):
+            continue
+        transitions = state_data.get('transitions', {})
+        if not transitions:
+            # Check if this looks like an intentional ending
+            state_lower = state_name.lower()
+            is_ending = (
+                state_lower == 'end' or
+                state_lower.startswith('end_') or
+                state_lower.startswith('ending_') or
+                '_end' in state_lower or
+                '_ending' in state_lower or
+                'finale' in state_lower or
+                'conclusion' in state_lower
+            )
+            if is_ending:
+                valid_endings.append(state_name)
+            else:
+                dead_ends.append(state_name)
+
+    if dead_ends:
+        warnings.append(f"Dead-end states (no exits): {dead_ends}")
+
+    # Calculate stats
+    stats = {
+        "total_states": len(all_states),
+        "valid_endings": len(valid_endings),
+        "reachable_states": len(targeted_states) + 1,  # +1 for start
+        "orphaned_count": len(orphaned),
+        "dead_end_count": len(dead_ends),
+        "total_transitions": sum(
+            len(d.get('transitions', {}))
+            for d in data.values()
+            if isinstance(d, dict)
+        ),
+        "total_choices": sum(
+            len(d.get('choices', []))
+            for d in data.values()
+            if isinstance(d, dict)
+        ),
+    }
+
+    if stats["total_states"] > 0:
+        stats["reachability_pct"] = round(
+            (stats["reachable_states"] / stats["total_states"]) * 100, 1
+        )
+    else:
+        stats["reachability_pct"] = 0
+
+    return {
+        "errors": errors,
+        "warnings": warnings,
+        "stats": stats
+    }
+
+
+def generate_story_flags(config_input):
+    """
+    Generate story-level flags/warnings (qualitative hints).
+
+    These are softer warnings about potential narrative issues.
+    """
+    data, error = parse_config(config_input)
+    if error:
+        return [f"Cannot analyze: {error}"]
+
+    # Flatten nested configs
+    data, is_nested = flatten_nested_config(data)
+
+    flags = []
+
+    # Collect path lengths from each state
+    state_depths = {}
+    descriptions = {}
+
+    for state_name, state_data in data.items():
+        if not isinstance(state_data, dict):
+            continue
+
+        desc = state_data.get('description', '')
+        descriptions[state_name] = desc
+        choices = state_data.get('choices', [])
+
+        # Flag: Empty or very short description
+        if len(desc) < 20:
+            flags.append({
+                "type": "sparse_content",
+                "state": state_name,
+                "message": f"Very short description ({len(desc)} chars)",
+                "severity": "info"
+            })
+
+        # Flag: Many choices (complexity)
+        if len(choices) > 5:
+            flags.append({
+                "type": "high_complexity",
+                "state": state_name,
+                "message": f"Many choices ({len(choices)}) - may overwhelm player",
+                "severity": "info"
+            })
+
+        # Flag: Description doesn't mention any choices
+        # Note: This is just informational - good narrative often sets scene
+        # without literally mentioning the choice text
+        if choices and desc:
+            desc_lower = desc.lower()
+            mentioned = any(c.lower() in desc_lower for c in choices)
+            if not mentioned:
+                flags.append({
+                    "type": "disconnected_choices",
+                    "state": state_name,
+                    "message": "Description doesn't reference any of the available choices",
+                    "severity": "info"  # Changed from warning - this is just a hint
+                })
+
+        # Flag: No media in state (if others have media)
+        media = state_data.get('media', [])
+        if not media:
+            # This is just tracked, we'll flag if inconsistent
+            pass
+
+    # Flag: Inconsistent media usage
+    states_with_media = sum(
+        1 for s, d in data.items()
+        if isinstance(d, dict) and d.get('media')
+    )
+    states_without_media = len([
+        s for s, d in data.items()
+        if isinstance(d, dict) and not d.get('media') and s != 'end'
+    ])
+
+    if states_with_media > 0 and states_without_media > 0:
+        ratio = states_with_media / (states_with_media + states_without_media)
+        if 0.2 < ratio < 0.8:
+            flags.append({
+                "type": "inconsistent_media",
+                "state": "global",
+                "message": f"Inconsistent media: {states_with_media} states have media, {states_without_media} don't",
+                "severity": "info"
+            })
+
+    # Flag: Very different description lengths (tone/pacing inconsistency)
+    desc_lengths = [len(d) for d in descriptions.values() if d]
+    if desc_lengths:
+        avg_len = sum(desc_lengths) / len(desc_lengths)
+        for state_name, desc in descriptions.items():
+            if desc and len(desc) > avg_len * 3:
+                flags.append({
+                    "type": "length_outlier",
+                    "state": state_name,
+                    "message": f"Description much longer than average ({len(desc)} vs avg {int(avg_len)})",
+                    "severity": "info"
+                })
+            elif desc and len(desc) < avg_len * 0.3 and len(desc) > 0:
+                flags.append({
+                    "type": "length_outlier",
+                    "state": state_name,
+                    "message": f"Description much shorter than average ({len(desc)} vs avg {int(avg_len)})",
+                    "severity": "info"
+                })
+
+    return flags
+
+
+def generate_mermaid_diagram(config_input):
+    """
+    Generate a Mermaid flowchart diagram from config.
+
+    Returns mermaid code string.
+    """
+    data, error = parse_config(config_input)
+    if error:
+        return f"%%Error: {error}"
+
+    # Flatten nested configs
+    data, is_nested = flatten_nested_config(data)
+
+    lines = ["flowchart TD"]
+
+    # Mermaid reserved keywords that need escaping
+    RESERVED_KEYWORDS = {'end', 'graph', 'subgraph', 'direction', 'click', 'style', 'class', 'linkStyle', 'classDef'}
+
+    def make_safe_name(name):
+        """Convert state name to mermaid-safe identifier."""
+        safe = name.replace(' ', '_').replace('-', '_')
+        # Escape reserved keywords by prefixing with 'state_'
+        if safe.lower() in RESERVED_KEYWORDS:
+            safe = f"state_{safe}"
+        return safe
+
+    # Track states for styling
+    all_states = set(data.keys())
+    targeted_states = set()
+    dead_ends = set()
+
+    # First pass: identify targeted states
+    for state_name, state_data in data.items():
+        if not isinstance(state_data, dict):
+            continue
+        for target in state_data.get('transitions', {}).values():
+            if target in all_states:
+                targeted_states.add(target)
+            elif '_' in target:
+                parts = target.rsplit('_', 1)
+                if parts[0] in all_states:
+                    targeted_states.add(parts[0])
+
+    # Generate nodes and edges
+    for state_name, state_data in data.items():
+        if not isinstance(state_data, dict):
+            continue
+
+        # Sanitize state name for mermaid
+        safe_name = make_safe_name(state_name)
+
+        # Get short description for node label
+        desc = state_data.get('description', state_name)
+        short_desc = desc[:30] + '...' if len(desc) > 30 else desc
+        short_desc = short_desc.replace('"', "'").replace('\n', ' ')
+
+        # Node shape based on type
+        if state_name == 'end':
+            lines.append(f'    {safe_name}(["{short_desc}"])')
+        elif state_name in ['start', 'intro', 'beginning', 'arrival'] or state_name == list(data.keys())[0]:
+            lines.append(f'    {safe_name}[/"{short_desc}"\\]')
+        else:
+            lines.append(f'    {safe_name}["{short_desc}"]')
+
+        # Edges for transitions
+        transitions = state_data.get('transitions', {})
+        if not transitions:
+            dead_ends.add(state_name)
+
+        for choice, target in transitions.items():
+            safe_target = make_safe_name(target)
+            safe_choice = choice[:20].replace('"', "'")
+            lines.append(f'    {safe_name} -->|"{safe_choice}"| {safe_target}')
+
+    # Add styling
+    lines.append("")
+    lines.append("    %% Styling")
+
+    # Start state styling
+    first_state = list(data.keys())[0] if data else None
+    if first_state:
+        safe_first = make_safe_name(first_state)
+        lines.append(f"    style {safe_first} fill:#90EE90")
+
+    # End state styling
+    if 'end' in all_states:
+        lines.append(f"    style {make_safe_name('end')} fill:#FFB6C1")
+
+    # Dead end styling
+    for de in dead_ends:
+        if de != 'end':
+            safe_de = make_safe_name(de)
+            lines.append(f"    style {safe_de} fill:#FFD700")
+
+    # Orphaned state styling
+    orphaned = all_states - targeted_states - {'end'}
+    if first_state:
+        orphaned.discard(first_state)
+    for orph in orphaned:
+        safe_orph = make_safe_name(orph)
+        lines.append(f"    style {safe_orph} fill:#FF6347")
+
+    return "\n".join(lines)
+
+
+def get_config_health_summary(config_input):
+    """
+    Get a comprehensive health summary of the config.
+
+    Returns formatted string for display.
+    """
+    validation = validate_branching(config_input)
+    flags = generate_story_flags(config_input)
+
+    stats = validation['stats']
+    errors = validation['errors']
+    warnings = validation['warnings']
+
+    lines = []
+
+    # Overall health score (simple heuristic)
+    error_penalty = len(errors) * 20
+    warning_penalty = len(warnings) * 5
+    flag_penalty = len([f for f in flags if f.get('severity') == 'warning']) * 3
+
+    health_score = max(0, 100 - error_penalty - warning_penalty - flag_penalty)
+
+    lines.append(f"## Config Health Score: {health_score}/100")
+    lines.append("")
+
+    # Stats
+    lines.append("### Statistics")
+    lines.append(f"- Total States: {stats.get('total_states', 0)}")
+    lines.append(f"- Reachability: {stats.get('reachability_pct', 0)}%")
+    lines.append(f"- Total Transitions: {stats.get('total_transitions', 0)}")
+    lines.append(f"- Valid Endings: {stats.get('valid_endings', 0)}")
+    lines.append(f"- Dead Ends (unintentional): {stats.get('dead_end_count', 0)}")
+    lines.append(f"- Orphaned States: {stats.get('orphaned_count', 0)}")
+    lines.append("")
+
+    # Errors
+    if errors:
+        lines.append("### Errors (Must Fix)")
+        for err in errors:
+            lines.append(f"- {err}")
+        lines.append("")
+
+    # Warnings
+    if warnings:
+        lines.append("### Warnings")
+        for warn in warnings:
+            lines.append(f"- {warn}")
+        lines.append("")
+
+    # Story Flags
+    if flags:
+        lines.append("### Story Flags")
+        for flag in flags:
+            severity_icon = "" if flag.get('severity') == 'warning' else ""
+            lines.append(f"- {severity_icon} [{flag.get('state')}] {flag.get('message')}")
+        lines.append("")
+
+    if not errors and not warnings and not flags:
+        lines.append("*No issues detected*")
+
+    return "\n".join(lines)
+
+
+def get_llm_cohesion_prompts():
+    """
+    Return preset prompts for LLM-assisted story cohesion checks.
+    """
+    return {
+        "summarize_paths": """Analyze this game config and summarize each possible path through the story.
+For each major branch, describe:
+1. The path taken (which states)
+2. Key events/decisions
+3. The ending reached
+
+Config:
+{config}""",
+
+        "find_contradictions": """Review this game config for narrative contradictions or plot holes.
+Look for:
+1. Events that contradict each other across branches
+2. Character actions that don't make sense
+3. World/setting inconsistencies
+4. Logical impossibilities
+
+Config:
+{config}""",
+
+        "tone_check": """Analyze the tone and mood consistency across this game config.
+Check:
+1. Does the writing style stay consistent?
+2. Are there jarring tone shifts?
+3. Does the atmosphere match the story type?
+
+Config:
+{config}""",
+
+        "improve_descriptions": """Review the descriptions in this game config and suggest improvements.
+For each state, note if the description:
+1. Sets the scene adequately
+2. Connects to the available choices
+3. Maintains narrative flow
+
+Config:
+{config}""",
+
+        "suggest_branches": """Analyze this game config and suggest additional branching opportunities.
+Look for:
+1. States where more choices would make sense
+2. Missing consequences for actions
+3. Opportunities for alternate paths
+
+Config:
+{config}"""
+    }
+
+
+# ============================================================
+# LOGIC GATES VALIDATION
+# ============================================================
+
+# Valid keys for condition expressions
+VALID_CONDITION_KEYS = {
+    'and', 'or', 'not',
+    'has_item', 'not_has_item',
+    'met_person', 'not_met_person',
+    'flag', 'not_flag',
+    'visited', 'not_visited', 'discovered',
+    'mission_complete', 'mission_active', 'mission_failed',
+    'money', 'counter',
+    'knowledge', 'knowledge_value',
+    'reputation', 'visit_count'
+}
+
+# Valid keys for effect specifications
+VALID_EFFECT_KEYS = {
+    'add_item', 'remove_item',
+    'add_money', 'remove_money', 'set_money',
+    'add_person',
+    'add_location', 'visit_location',
+    'set_flag', 'clear_flag', 'toggle_flag',
+    'set_counter', 'increment', 'decrement',
+    'set_knowledge', 'remove_knowledge',
+    'start_mission', 'complete_mission', 'fail_mission', 'update_mission',
+    'adjust_reputation', 'set_reputation'
+}
+
+# Valid keys for dynamic transitions
+VALID_TRANSITION_KEYS = {
+    'random', 'random_from',
+    'if', 'then', 'else',
+    'conditions', 'default'
+}
+
+
+def validate_condition(condition, path, issues):
+    """
+    Recursively validate a condition expression.
+
+    Args:
+        condition: The condition to validate
+        path: String path for error reporting
+        issues: List to append issues to
+    """
+    if condition is None or condition == {}:
+        return
+
+    if isinstance(condition, str):
+        return  # Simple flag name - valid
+
+    if not isinstance(condition, dict):
+        issues.append({
+            "type": "invalid_condition",
+            "path": path,
+            "message": f"Condition must be dict or string, got {type(condition).__name__}"
+        })
+        return
+
+    for key in condition:
+        if key not in VALID_CONDITION_KEYS:
+            issues.append({
+                "type": "unknown_condition_key",
+                "path": path,
+                "message": f"Unknown condition key: '{key}'"
+            })
+
+        # Recurse into compound conditions
+        if key in ('and', 'or'):
+            if not isinstance(condition[key], list):
+                issues.append({
+                    "type": "invalid_condition",
+                    "path": path,
+                    "message": f"'{key}' must be a list"
+                })
+            else:
+                for i, sub in enumerate(condition[key]):
+                    validate_condition(sub, f"{path}.{key}[{i}]", issues)
+
+        if key == 'not':
+            validate_condition(condition[key], f"{path}.not", issues)
+
+        # Validate numeric comparisons
+        if key in ('money', 'counter', 'reputation', 'visit_count'):
+            val = condition[key]
+            if isinstance(val, dict):
+                valid_comparisons = {'gte', 'lte', 'gt', 'lt', 'eq', 'neq', 'npc', 'state'}
+                for cmp_key in val:
+                    if cmp_key not in valid_comparisons and not isinstance(val[cmp_key], dict):
+                        issues.append({
+                            "type": "invalid_comparison",
+                            "path": f"{path}.{key}",
+                            "message": f"Unknown comparison operator: '{cmp_key}'"
+                        })
+
+
+def validate_effects(effects, path, issues):
+    """
+    Validate effect specifications.
+
+    Args:
+        effects: The effects dict to validate
+        path: String path for error reporting
+        issues: List to append issues to
+    """
+    if not effects or not isinstance(effects, dict):
+        return
+
+    for key in effects:
+        if key not in VALID_EFFECT_KEYS:
+            issues.append({
+                "type": "unknown_effect_key",
+                "path": path,
+                "message": f"Unknown effect key: '{key}'"
+            })
+
+
+def validate_transition(transition, path, issues):
+    """
+    Validate transition specification.
+
+    Args:
+        transition: The transition spec to validate
+        path: String path for error reporting
+        issues: List to append issues to
+    """
+    if isinstance(transition, str):
+        return  # Simple string target - valid (basic check only)
+
+    if not isinstance(transition, dict):
+        issues.append({
+            "type": "invalid_transition",
+            "path": path,
+            "message": f"Transition must be string or dict, got {type(transition).__name__}"
+        })
+        return
+
+    # Check for unknown keys
+    for key in transition:
+        if key not in VALID_TRANSITION_KEYS:
+            issues.append({
+                "type": "unknown_transition_key",
+                "path": path,
+                "message": f"Unknown transition key: '{key}'"
+            })
+
+    # Validate random weights
+    if 'random' in transition:
+        weights = transition['random']
+        if not isinstance(weights, list):
+            issues.append({
+                "type": "invalid_transition",
+                "path": path,
+                "message": "'random' must be a list of [state, weight] pairs"
+            })
+        else:
+            total = 0
+            for item in weights:
+                if not isinstance(item, list) or len(item) != 2:
+                    issues.append({
+                        "type": "invalid_transition",
+                        "path": path,
+                        "message": f"Random item must be [state, weight]: {item}"
+                    })
+                else:
+                    total += item[1] if isinstance(item[1], (int, float)) else 0
+
+            if abs(total - 1.0) > 0.01 and total > 0:
+                issues.append({
+                    "type": "weight_warning",
+                    "path": path,
+                    "message": f"Random weights sum to {total}, not 1.0 (will be normalized)"
+                })
+
+    # Validate random_from pool
+    if 'random_from' in transition:
+        pool = transition['random_from']
+        if not isinstance(pool, list) or len(pool) == 0:
+            issues.append({
+                "type": "invalid_transition",
+                "path": path,
+                "message": "'random_from' must be a non-empty list"
+            })
+
+    # Validate conditional transition
+    if 'if' in transition:
+        validate_condition(transition['if'], f"{path}.if", issues)
+        if 'then' not in transition and 'else' not in transition:
+            issues.append({
+                "type": "invalid_transition",
+                "path": path,
+                "message": "Conditional transition needs 'then' or 'else'"
+            })
+        if 'then' in transition:
+            validate_transition(transition['then'], f"{path}.then", issues)
+        if 'else' in transition:
+            validate_transition(transition['else'], f"{path}.else", issues)
+
+    # Validate chained conditions
+    if 'conditions' in transition:
+        has_default = False
+        for i, cond_block in enumerate(transition['conditions']):
+            if 'default' in cond_block:
+                has_default = True
+                validate_transition(cond_block['default'], f"{path}.conditions[{i}].default", issues)
+            elif 'if' in cond_block:
+                validate_condition(cond_block['if'], f"{path}.conditions[{i}].if", issues)
+                if 'then' in cond_block:
+                    validate_transition(cond_block['then'], f"{path}.conditions[{i}].then", issues)
+            else:
+                issues.append({
+                    "type": "invalid_transition",
+                    "path": f"{path}.conditions[{i}]",
+                    "message": "Condition block needs 'if' or 'default'"
+                })
+
+        if not has_default:
+            issues.append({
+                "type": "missing_default",
+                "path": path,
+                "message": "Chained conditions should have a 'default' fallback"
+            })
+
+
+def validate_logic_gates(config_input):
+    """
+    Validate all logic gates (conditions, effects, transitions) in a config.
+
+    Returns list of validation issues.
+    """
+    data, error = parse_config(config_input)
+    if error:
+        return [{"type": "parse_error", "path": "", "message": error}]
+
+    data, _ = flatten_nested_config(data)
+    issues = []
+
+    for state_name, state_data in data.items():
+        if not isinstance(state_data, dict):
+            continue
+
+        base_path = state_name
+
+        # Validate choice_config conditions
+        choice_config = state_data.get('choice_config', {})
+        for choice, config in choice_config.items():
+            if isinstance(config, dict) and 'condition' in config:
+                validate_condition(
+                    config['condition'],
+                    f"{base_path}.choice_config.{choice}.condition",
+                    issues
+                )
+
+        # Validate effects
+        effects = state_data.get('effects', {})
+        for choice, effect_spec in effects.items():
+            if isinstance(effect_spec, dict):
+                validate_effects(effect_spec, f"{base_path}.effects.{choice}", issues)
+
+        # Validate on_enter effects
+        on_enter = state_data.get('on_enter')
+        if on_enter and isinstance(on_enter, dict):
+            validate_effects(on_enter, f"{base_path}.on_enter", issues)
+
+        # Validate transitions (including dynamic ones)
+        transitions = state_data.get('transitions', {})
+        for choice, trans in transitions.items():
+            validate_transition(trans, f"{base_path}.transitions.{choice}", issues)
+
+        # Validate encounter_chance
+        encounter = state_data.get('encounter_chance')
+        if encounter and isinstance(encounter, dict):
+            if 'bypass_conditions' in encounter:
+                validate_condition(
+                    encounter['bypass_conditions'],
+                    f"{base_path}.encounter_chance.bypass_conditions",
+                    issues
+                )
+            if 'probability' in encounter:
+                prob = encounter['probability']
+                if not isinstance(prob, (int, float)) or prob < 0 or prob > 1:
+                    issues.append({
+                        "type": "invalid_probability",
+                        "path": f"{base_path}.encounter_chance.probability",
+                        "message": f"Probability must be between 0 and 1, got {prob}"
+                    })
+            if 'pool' in encounter:
+                pool = encounter['pool']
+                if not isinstance(pool, list) or len(pool) == 0:
+                    issues.append({
+                        "type": "invalid_encounter_pool",
+                        "path": f"{base_path}.encounter_chance.pool",
+                        "message": "Encounter pool must be a non-empty list"
+                    })
+
+    return issues
+
+
+def get_logic_gates_summary(config_input):
+    """
+    Get a summary of logic gates validation results.
+
+    Returns formatted string for display.
+    """
+    issues = validate_logic_gates(config_input)
+
+    if not issues:
+        return "**Logic Gates Validation:** No issues found"
+
+    lines = ["**Logic Gates Validation Issues:**", ""]
+
+    errors = [i for i in issues if i['type'] not in ('weight_warning', 'missing_default')]
+    warnings = [i for i in issues if i['type'] in ('weight_warning', 'missing_default')]
+
+    if errors:
+        lines.append("### Errors")
+        for issue in errors:
+            lines.append(f"- [{issue['path']}] {issue['message']}")
+        lines.append("")
+
+    if warnings:
+        lines.append("### Warnings")
+        for issue in warnings:
+            lines.append(f"- [{issue['path']}] {issue['message']}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+# ==================== ACTIONABLE VALIDATION FUNCTIONS ====================
+
+def get_validation_with_fixes(config_input):
+    """
+    Enhanced validation that returns errors with suggested fixes.
+
+    Returns dict with:
+    - issues: List of issues with fix suggestions
+    - quick_fixes: Dict of auto-fixable issues
+    - stats: Config statistics
+    """
+    data, error = parse_config(config_input)
+    if error:
+        return {
+            "issues": [{"type": "parse_error", "message": error, "fixable": False}],
+            "quick_fixes": {},
+            "stats": {}
+        }
+
+    data, is_nested = flatten_nested_config(data)
+
+    issues = []
+    quick_fixes = {}
+    all_states = set(data.keys())
+
+    for state_name, state_data in data.items():
+        if not isinstance(state_data, dict):
+            continue
+
+        choices = state_data.get('choices', [])
+        transitions = state_data.get('transitions', {})
+
+        # Issue: Broken transitions
+        for choice, target in transitions.items():
+            target_exists = False
+
+            if target in all_states:
+                target_exists = True
+            elif '_' in target:
+                # Check nested format
+                for split_pos in range(len(target)):
+                    if target[split_pos] == '_':
+                        loc = target[:split_pos]
+                        st = target[split_pos+1:]
+                        if loc in all_states:
+                            target_exists = True
+                            break
+
+            if not target_exists:
+                # Suggest similar state names
+                suggestions = find_similar_states(target, all_states)
+                issues.append({
+                    "type": "broken_transition",
+                    "state": state_name,
+                    "choice": choice,
+                    "target": target,
+                    "message": f"Transition '{choice}' points to non-existent state '{target}'",
+                    "suggestions": suggestions,
+                    "fixable": len(suggestions) > 0,
+                    "fix_type": "replace_target"
+                })
+
+                if suggestions:
+                    quick_fixes[f"{state_name}|{choice}"] = {
+                        "action": "replace_transition_target",
+                        "old_target": target,
+                        "suggested_target": suggestions[0],
+                        "all_suggestions": suggestions
+                    }
+
+        # Issue: Choice without transition
+        choice_set = set(choices) if choices else set()
+        transition_keys = set(transitions.keys())
+        missing_transitions = choice_set - transition_keys
+
+        for missing in missing_transitions:
+            # Suggest next logical state
+            suggestions = suggest_next_states(state_name, all_states)
+            issues.append({
+                "type": "missing_transition",
+                "state": state_name,
+                "choice": missing,
+                "message": f"Choice '{missing}' has no transition defined",
+                "suggestions": suggestions,
+                "fixable": True,
+                "fix_type": "add_transition"
+            })
+
+            quick_fixes[f"{state_name}|{missing}|add"] = {
+                "action": "add_transition",
+                "choice": missing,
+                "suggested_target": suggestions[0] if suggestions else "end"
+            }
+
+        # Issue: Dead end (not an ending state)
+        if not transitions and not is_ending_state(state_name):
+            issues.append({
+                "type": "dead_end",
+                "state": state_name,
+                "message": f"State '{state_name}' has no exits and doesn't appear to be an ending",
+                "suggestions": ["Add transitions to continue the story", "Rename to indicate it's an ending (e.g., ending_X)"],
+                "fixable": True,
+                "fix_type": "add_ending_transition"
+            })
+
+            quick_fixes[f"{state_name}|dead_end"] = {
+                "action": "convert_to_ending",
+                "add_choices": ["restart"],
+                "add_transitions": {"restart": list(all_states)[0]}
+            }
+
+        # Issue: Orphaned state
+        targeted_states = set()
+        for s, sd in data.items():
+            if isinstance(sd, dict):
+                for t in sd.get('transitions', {}).values():
+                    targeted_states.add(t)
+                    if '_' in t:
+                        parts = t.split('_', 1)
+                        targeted_states.add(parts[0])
+
+        first_state = list(data.keys())[0] if data else None
+        if state_name not in targeted_states and state_name != first_state and not is_ending_state(state_name):
+            # Find states that could link here
+            potential_sources = find_potential_source_states(state_name, data)
+            issues.append({
+                "type": "orphaned_state",
+                "state": state_name,
+                "message": f"State '{state_name}' is not reachable from any other state",
+                "suggestions": [f"Add a transition from '{s}' to '{state_name}'" for s in potential_sources[:3]],
+                "fixable": len(potential_sources) > 0,
+                "fix_type": "add_incoming_transition"
+            })
+
+    # Calculate stats
+    stats = {
+        "total_states": len(all_states),
+        "total_issues": len(issues),
+        "fixable_issues": len([i for i in issues if i.get("fixable")]),
+        "issue_types": {}
+    }
+
+    for issue in issues:
+        issue_type = issue["type"]
+        stats["issue_types"][issue_type] = stats["issue_types"].get(issue_type, 0) + 1
+
+    return {
+        "issues": issues,
+        "quick_fixes": quick_fixes,
+        "stats": stats
+    }
+
+
+def find_similar_states(target, all_states, threshold=0.6):
+    """Find states with similar names to the target."""
+    suggestions = []
+
+    for state in all_states:
+        # Simple similarity: common characters ratio
+        common = set(target.lower()) & set(state.lower())
+        similarity = len(common) / max(len(target), len(state))
+
+        if similarity >= threshold:
+            suggestions.append(state)
+
+        # Also check if target is a substring or vice versa
+        if target.lower() in state.lower() or state.lower() in target.lower():
+            if state not in suggestions:
+                suggestions.append(state)
+
+    return suggestions[:5]
+
+
+def suggest_next_states(current_state, all_states):
+    """Suggest logical next states based on naming patterns."""
+    suggestions = []
+
+    # If current state has a number, suggest the next number
+    import re
+    match = re.search(r'(\d+)$', current_state)
+    if match:
+        num = int(match.group(1))
+        next_name = current_state[:match.start()] + str(num + 1)
+        if next_name in all_states:
+            suggestions.append(next_name)
+
+    # Suggest 'end' if it exists
+    if 'end' in all_states:
+        suggestions.append('end')
+
+    # Suggest states that start with similar prefix
+    prefix = current_state.split('_')[0] if '_' in current_state else current_state[:3]
+    for state in all_states:
+        if state.startswith(prefix) and state != current_state and state not in suggestions:
+            suggestions.append(state)
+
+    return suggestions[:5]
+
+
+def find_potential_source_states(target_state, data):
+    """Find states that could logically link to the target."""
+    potential = []
+
+    # States with similar names/prefixes
+    target_prefix = target_state.split('_')[0] if '_' in target_state else target_state[:3]
+
+    for state_name, state_data in data.items():
+        if state_name == target_state:
+            continue
+        if not isinstance(state_data, dict):
+            continue
+
+        # Check if this state has room for more choices
+        choices = state_data.get('choices', [])
+        if len(choices) < 4:  # Can add more choices
+            # Prefer states with similar prefix
+            if state_name.startswith(target_prefix) or target_state.startswith(state_name.split('_')[0]):
+                potential.insert(0, state_name)
+            else:
+                potential.append(state_name)
+
+    return potential
+
+
+def is_ending_state(state_name):
+    """Check if a state name indicates it's an ending."""
+    name_lower = state_name.lower()
+    return (
+        name_lower == 'end' or
+        name_lower.startswith('end_') or
+        name_lower.startswith('ending_') or
+        '_end' in name_lower or
+        '_ending' in name_lower or
+        'finale' in name_lower or
+        'conclusion' in name_lower or
+        'victory' in name_lower or
+        'defeat' in name_lower or
+        'death' in name_lower
+    )
+
+
+def apply_quick_fix(config_input, fix_key, fix_data):
+    """
+    Apply a quick fix to the config.
+
+    Args:
+        config_input: JSON config string
+        fix_key: Key identifying the fix (e.g., "state|choice")
+        fix_data: Fix data from quick_fixes dict
+
+    Returns:
+        Updated JSON config string
+    """
+    data, error = parse_config(config_input)
+    if error:
+        return config_input
+
+    data, is_nested = flatten_nested_config(data)
+
+    action = fix_data.get("action")
+
+    if action == "replace_transition_target":
+        parts = fix_key.split("|")
+        if len(parts) >= 2:
+            state_name, choice = parts[0], parts[1]
+            if state_name in data and "transitions" in data[state_name]:
+                data[state_name]["transitions"][choice] = fix_data["suggested_target"]
+
+    elif action == "add_transition":
+        parts = fix_key.split("|")
+        if len(parts) >= 2:
+            state_name, choice = parts[0], parts[1]
+            if state_name in data:
+                if "transitions" not in data[state_name]:
+                    data[state_name]["transitions"] = {}
+                data[state_name]["transitions"][choice] = fix_data["suggested_target"]
+
+    elif action == "convert_to_ending":
+        parts = fix_key.split("|")
+        state_name = parts[0]
+        if state_name in data:
+            data[state_name]["choices"] = fix_data.get("add_choices", [])
+            data[state_name]["transitions"] = fix_data.get("add_transitions", {})
+
+    return json.dumps(data, indent=2)
+
+
+def apply_all_quick_fixes(config_input):
+    """
+    Apply all auto-fixable issues to the config.
+
+    Returns:
+        Tuple of (updated_config, fixes_applied_count, fixes_log)
+    """
+    validation = get_validation_with_fixes(config_input)
+    quick_fixes = validation["quick_fixes"]
+
+    if not quick_fixes:
+        return config_input, 0, ["No auto-fixable issues found"]
+
+    current_config = config_input
+    fixes_log = []
+
+    for fix_key, fix_data in quick_fixes.items():
+        try:
+            current_config = apply_quick_fix(current_config, fix_key, fix_data)
+            fixes_log.append(f"Applied: {fix_data['action']} for {fix_key}")
+        except Exception as e:
+            fixes_log.append(f"Failed: {fix_data['action']} for {fix_key} - {str(e)}")
+
+    return current_config, len(quick_fixes), fixes_log
+
+
+def get_state_issues_map(config_input):
+    """
+    Get a mapping of state names to their issues for inline highlighting.
+
+    Returns:
+        Dict mapping state_name -> list of issues
+    """
+    validation = get_validation_with_fixes(config_input)
+    issues = validation["issues"]
+
+    state_issues = {}
+    for issue in issues:
+        state = issue.get("state", "global")
+        if state not in state_issues:
+            state_issues[state] = []
+        state_issues[state].append(issue)
+
+    return state_issues
+
+
+def format_issues_for_display(issues):
+    """
+    Format issues list as markdown for Gradio display.
+    """
+    if not issues:
+        return "No issues found!"
+
+    lines = ["## Validation Issues\n"]
+
+    # Group by type
+    by_type = {}
+    for issue in issues:
+        t = issue["type"]
+        if t not in by_type:
+            by_type[t] = []
+        by_type[t].append(issue)
+
+    type_icons = {
+        "broken_transition": "🔴",
+        "missing_transition": "🟠",
+        "dead_end": "🟡",
+        "orphaned_state": "⚪",
+        "parse_error": "❌"
+    }
+
+    type_names = {
+        "broken_transition": "Broken Transitions",
+        "missing_transition": "Missing Transitions",
+        "dead_end": "Dead Ends",
+        "orphaned_state": "Orphaned States",
+        "parse_error": "Parse Errors"
+    }
+
+    for issue_type, type_issues in by_type.items():
+        icon = type_icons.get(issue_type, "⚠️")
+        name = type_names.get(issue_type, issue_type)
+        lines.append(f"### {icon} {name} ({len(type_issues)})\n")
+
+        for issue in type_issues:
+            state = issue.get("state", "")
+            message = issue.get("message", "")
+            fixable = "✅ Auto-fixable" if issue.get("fixable") else ""
+
+            lines.append(f"- **{state}**: {message} {fixable}")
+
+            suggestions = issue.get("suggestions", [])
+            if suggestions:
+                lines.append(f"  - Suggestions: {', '.join(suggestions[:3])}")
+
+        lines.append("")
+
+    return "\n".join(lines)

demo_llm_loop_examples.py

@@ -0,0 +1,935 @@
+"""Demo examples for the LLM Improvement Loop workflow.
+
+This module provides example configs showing the progression through
+the Mystery Deepening workflow:
+- Round 1: Environment (plant clues in descriptions)
+- Round 2: Characters (hidden motivations)
+- Round 3: Choices (investigation options)
+- Round 4: Tension (red herrings and reveals)
+"""
+
+# Original starter config (7 states, basic mystery)
+DEMO_MYSTERY_STARTER = '''{
+  "investigation": {
+    "crime_scene": {
+      "description": "A dimly lit office. Papers scattered everywhere. A broken window.",
+      "choices": ["Examine the desk", "Check the window", "Leave"],
+      "transitions": {
+        "Examine the desk": "desk_clue",
+        "Check the window": "window_clue",
+        "Leave": "hallway"
+      }
+    },
+    "desk_clue": {
+      "description": "The desk has a half-written letter and an empty coffee cup.",
+      "choices": ["Read the letter", "Back to scene"],
+      "transitions": {
+        "Read the letter": "letter_reveal",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "window_clue": {
+      "description": "Glass shards on the inside. Someone broke in from outside.",
+      "choices": ["Look outside", "Back to scene"],
+      "transitions": {
+        "Look outside": "outside_view",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "letter_reveal": {
+      "description": "The letter mentions a meeting tonight. It's unfinished.",
+      "choices": ["Continue investigating"],
+      "transitions": {
+        "Continue investigating": "crime_scene"
+      }
+    },
+    "outside_view": {
+      "description": "Footprints in the mud lead toward the parking lot.",
+      "choices": ["Follow the footprints", "Back inside"],
+      "transitions": {
+        "Follow the footprints": "hallway",
+        "Back inside": "crime_scene"
+      }
+    },
+    "hallway": {
+      "description": "The hallway is quiet. A security guard approaches.",
+      "choices": ["Talk to guard", "Return to office"],
+      "transitions": {
+        "Talk to guard": "guard_talk",
+        "Return to office": "crime_scene"
+      }
+    },
+    "guard_talk": {
+      "description": "The guard says he heard nothing unusual tonight.",
+      "choices": ["Press for details", "Thank him and leave"],
+      "transitions": {
+        "Press for details": "guard_talk",
+        "Thank him and leave": "hallway"
+      }
+    }
+  }
+}'''
+
+# After Round 1: Environment focus - plant clues in descriptions
+DEMO_AFTER_ROUND_1 = '''{
+  "investigation": {
+    "crime_scene": {
+      "description": "A dimly lit corner office on the 14th floor. Papers are scattered across the mahogany desk and floor - financial reports, all dated from last month. A broken window lets in cold night air, and you notice the glass shards fell inward, onto an expensive Persian rug now stained with what looks like coffee. A framed photo lies face-down near the overturned chair.",
+      "choices": ["Examine the desk", "Check the window", "Look at the photo", "Leave"],
+      "transitions": {
+        "Examine the desk": "desk_clue",
+        "Check the window": "window_clue",
+        "Look at the photo": "photo_clue",
+        "Leave": "hallway"
+      }
+    },
+    "desk_clue": {
+      "description": "The desk has a half-written letter addressed to 'M' - the handwriting grows increasingly shaky toward the end. An empty coffee cup sits beside it, a faint lipstick mark on the rim despite this being a man's office. The desk drawer is slightly ajar, revealing a corner of what looks like a passport.",
+      "choices": ["Read the letter", "Check the drawer", "Examine the coffee cup", "Back to scene"],
+      "transitions": {
+        "Read the letter": "letter_reveal",
+        "Check the drawer": "drawer_contents",
+        "Examine the coffee cup": "coffee_clue",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "window_clue": {
+      "description": "Glass shards cover the inside of the windowsill and floor - definitely broken from outside. But something's wrong: the window latch is still locked from the inside. On the exterior ledge, you spot a small piece of torn fabric caught on a nail, dark blue like a uniform.",
+      "choices": ["Look outside", "Examine the fabric", "Back to scene"],
+      "transitions": {
+        "Look outside": "outside_view",
+        "Examine the fabric": "fabric_clue",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "photo_clue": {
+      "description": "The frame's glass is cracked. The photo shows two men shaking hands at what looks like a company event - one is clearly the office's occupant, the other wears a security uniform. On the back, someone has written 'Partners - Nov 2019' in neat handwriting.",
+      "choices": ["Keep the photo", "Put it back", "Back to scene"],
+      "transitions": {
+        "Keep the photo": "crime_scene",
+        "Put it back": "crime_scene",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "letter_reveal": {
+      "description": "The letter reads: 'Dear M, I can't keep doing this. They're going to find out about the transfers, and when they do...' The writing stops abruptly. A single drop of dried coffee stains the page, as if the cup was knocked over mid-sentence.",
+      "choices": ["Continue investigating"],
+      "transitions": {
+        "Continue investigating": "crime_scene"
+      }
+    },
+    "drawer_contents": {
+      "description": "Inside the drawer: a passport with several recent stamps to the Cayman Islands, a burner phone with a cracked screen, and a sticky note with a phone number and the words 'CALL BEFORE FRIDAY' underlined three times.",
+      "choices": ["Take the phone", "Note the number", "Back to desk"],
+      "transitions": {
+        "Take the phone": "desk_clue",
+        "Note the number": "desk_clue",
+        "Back to desk": "desk_clue"
+      }
+    },
+    "coffee_clue": {
+      "description": "The lipstick shade is a distinctive coral pink. The cup still has dregs at the bottom - the coffee smells slightly bitter, different from regular office coffee. There's a faint residue around the rim that doesn't look like dried cream.",
+      "choices": ["Back to desk"],
+      "transitions": {
+        "Back to desk": "desk_clue"
+      }
+    },
+    "fabric_clue": {
+      "description": "The fabric is from a security uniform - you can see part of a stitched logo. It's torn at an angle suggesting someone climbed up, not down. But why would security break in through a window?",
+      "choices": ["Back to window"],
+      "transitions": {
+        "Back to window": "window_clue"
+      }
+    },
+    "outside_view": {
+      "description": "Footprints in the mud lead toward the parking lot - two sets, one coming and one going. The incoming prints are deep, as if carrying something heavy. The outgoing prints are lighter, faster, heading toward a side exit that bypasses the main security desk.",
+      "choices": ["Follow the footprints", "Back inside"],
+      "transitions": {
+        "Follow the footprints": "hallway",
+        "Back inside": "crime_scene"
+      }
+    },
+    "hallway": {
+      "description": "The hallway is quiet, lit by flickering fluorescent lights. A security camera in the corner has a small red light - but you notice it's pointing at the wall, not the office door. A security guard approaches, his boots leaving muddy prints on the polished floor.",
+      "choices": ["Talk to guard", "Check the camera", "Return to office"],
+      "transitions": {
+        "Talk to guard": "guard_talk",
+        "Check the camera": "camera_check",
+        "Return to office": "crime_scene"
+      }
+    },
+    "camera_check": {
+      "description": "The camera has been manually rotated away from the office door. The adjustment screw is loose, recently turned. Whoever did this knew exactly which camera to move.",
+      "choices": ["Back to hallway"],
+      "transitions": {
+        "Back to hallway": "hallway"
+      }
+    },
+    "guard_talk": {
+      "description": "The guard - his name tag reads 'Martinez' - says he heard nothing unusual tonight. His uniform is slightly disheveled, and there's a small tear near his sleeve. He keeps glancing at his watch.",
+      "choices": ["Press for details", "Thank him and leave"],
+      "transitions": {
+        "Press for details": "guard_pressed",
+        "Thank him and leave": "hallway"
+      }
+    },
+    "guard_pressed": {
+      "description": "'Look, I was on my rounds, okay? The 14th floor wasn't scheduled until midnight.' He shifts his weight nervously. 'Ask Jenkins at the front desk - he'll confirm my times.' But you notice his boots match the muddy prints in the hallway.",
+      "choices": ["Confront about the boots", "Let it go", "Ask about the photo"],
+      "transitions": {
+        "Confront about the boots": "confrontation",
+        "Let it go": "hallway",
+        "Ask about the photo": "photo_question"
+      }
+    },
+    "confrontation": {
+      "description": "Martinez's face pales. 'Those... those aren't... look, I can explain.' His hand moves toward his radio, then stops. 'Not here. Meet me in the parking garage in ten minutes. There are things you need to know about what really happened in that office.'",
+      "choices": ["Agree to meet", "Detain him now"],
+      "transitions": {
+        "Agree to meet": "hallway",
+        "Detain him now": "hallway"
+      }
+    },
+    "photo_question": {
+      "description": "At the mention of the photo, Martinez goes very still. 'Where did you find that? That was supposed to be... nevermind.' He takes a deep breath. 'Richardson and I go way back. But that was before I knew what he was really doing with those accounts.'",
+      "choices": ["Ask about the accounts", "Back to hallway"],
+      "transitions": {
+        "Ask about the accounts": "accounts_info",
+        "Back to hallway": "hallway"
+      }
+    },
+    "accounts_info": {
+      "description": "'He was moving money - lots of it. Company funds to offshore accounts. I found out six months ago and... I should have reported it. But he promised me a cut.' Martinez looks defeated. 'Tonight, someone else found out too. Someone who doesn't negotiate.'",
+      "choices": ["Who else knew?", "Back to hallway"],
+      "transitions": {
+        "Who else knew?": "hallway",
+        "Back to hallway": "hallway"
+      }
+    }
+  }
+}'''
+
+# After Round 2: Characters focus - hidden motivations, personality through dialogue
+DEMO_AFTER_ROUND_2 = '''{
+  "investigation": {
+    "crime_scene": {
+      "description": "A dimly lit corner office on the 14th floor. Papers are scattered across the mahogany desk and floor - financial reports, all dated from last month. A broken window lets in cold night air, and you notice the glass shards fell inward, onto an expensive Persian rug now stained with what looks like coffee. A framed photo lies face-down near the overturned chair. On the desk, a half-eaten sandwich suggests Richardson left in a hurry - or was interrupted mid-meal.",
+      "choices": ["Examine the desk", "Check the window", "Look at the photo", "Leave"],
+      "transitions": {
+        "Examine the desk": "desk_clue",
+        "Check the window": "window_clue",
+        "Look at the photo": "photo_clue",
+        "Leave": "hallway"
+      }
+    },
+    "desk_clue": {
+      "description": "The desk has a half-written letter addressed to 'M' - the handwriting grows increasingly shaky toward the end, betraying Richardson's fear. An empty coffee cup sits beside it, a faint coral lipstick mark on the rim - Richardson's wife wears red, not coral. The desk drawer is slightly ajar, revealing a corner of what looks like a passport. A sticky note on the monitor reads 'MIRANDA CALLED - URGENT' in what looks like a secretary's handwriting.",
+      "choices": ["Read the letter", "Check the drawer", "Examine the coffee cup", "Back to scene"],
+      "transitions": {
+        "Read the letter": "letter_reveal",
+        "Check the drawer": "drawer_contents",
+        "Examine the coffee cup": "coffee_clue",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "window_clue": {
+      "description": "Glass shards cover the inside of the windowsill and floor - definitely broken from outside. But something's wrong: the window latch is still locked from the inside. On the exterior ledge, you spot a small piece of torn fabric caught on a nail, dark blue like a security uniform. The tear pattern suggests someone climbed up, not down - but Martinez is the only guard on duty tonight.",
+      "choices": ["Look outside", "Examine the fabric", "Back to scene"],
+      "transitions": {
+        "Look outside": "outside_view",
+        "Examine the fabric": "fabric_clue",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "photo_clue": {
+      "description": "The frame's glass is cracked. The photo shows two men shaking hands at the company Christmas party 2019 - Richardson in an expensive suit, Martinez in his security uniform, both grinning like old friends. On the back, someone has written 'Partners in crime - Nov 2019' in feminine handwriting, with a small heart. The same coral lipstick has left a faint kiss mark in the corner.",
+      "choices": ["Keep the photo", "Put it back", "Back to scene"],
+      "transitions": {
+        "Keep the photo": "crime_scene",
+        "Put it back": "crime_scene",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "letter_reveal": {
+      "description": "The letter reads: 'Dear M, I can't keep doing this. They're going to find out about the transfers, and when they do, neither of us will be safe. Elena is getting suspicious - she found the Cayman statements. I need to disappear, but I can't leave you behind. Meet me at the usual place at midnight. If I'm not there by 12:30, assume the worst and run. Don't trust Martinez anymore - he's been asking questions. All my love, R.' The writing stops mid-sentence, a single drop of dried coffee staining the page.",
+      "choices": ["Continue investigating"],
+      "transitions": {
+        "Continue investigating": "crime_scene"
+      }
+    },
+    "drawer_contents": {
+      "description": "Inside the drawer: a passport with several recent stamps to the Cayman Islands - the last trip was three days ago. A burner phone with a cracked screen shows the last call was to 'M' at 11:47 PM. A sticky note reads 'CALL BEFORE FRIDAY - E knows' with 'E' underlined three times. Elena, Richardson's wife, is known for her jealous streak and family money.",
+      "choices": ["Take the phone", "Note the number", "Back to desk"],
+      "transitions": {
+        "Take the phone": "desk_clue",
+        "Note the number": "desk_clue",
+        "Back to desk": "desk_clue"
+      }
+    },
+    "coffee_clue": {
+      "description": "The coral lipstick shade is distinctive - 'Sunset Kiss' by Luxe, the kind sold at high-end department stores. Richardson's secretary Miranda wears this exact shade. The cup still has dregs at the bottom - the coffee smells bitter, with an underlying chemical note. There's a faint crystalline residue around the rim. Either Miranda has unusual taste in coffee additives, or someone wanted to make sure Richardson didn't finish his drink.",
+      "choices": ["Back to desk"],
+      "transitions": {
+        "Back to desk": "desk_clue"
+      }
+    },
+    "fabric_clue": {
+      "description": "The fabric is from a security uniform - you can see part of a stitched company logo. It's torn at an angle suggesting someone climbed up, not down. The thread count matches Martinez's uniform exactly, but the tear on his sleeve is on the right arm. This fabric came from a left sleeve. Either Martinez changed uniforms, or there's another security guard involved.",
+      "choices": ["Back to window"],
+      "transitions": {
+        "Back to window": "window_clue"
+      }
+    },
+    "outside_view": {
+      "description": "Footprints in the mud lead toward the parking lot - two sets, one coming and one going. The incoming prints are deep, size 11 work boots, carrying something heavy. The outgoing prints are lighter, faster, size 7 women's heels, heading toward a side exit. A cigarette butt near the window smells fresh - Virginia Slims, a women's brand. Miranda smokes Virginia Slims.",
+      "choices": ["Follow the footprints", "Back inside"],
+      "transitions": {
+        "Follow the footprints": "hallway",
+        "Back inside": "crime_scene"
+      }
+    },
+    "hallway": {
+      "description": "The hallway is quiet, lit by flickering fluorescent lights. A security camera in the corner has a small red light - but you notice it's pointing at the wall, not the office door. Martinez approaches, his boots leaving muddy prints on the polished floor. His jaw is tight, eyes darting. 'Detective. Didn't expect you so soon.' His hand rests near his radio, as if ready to call for backup - or warn someone.",
+      "choices": ["Talk to guard", "Check the camera", "Return to office"],
+      "transitions": {
+        "Talk to guard": "guard_talk",
+        "Check the camera": "camera_check",
+        "Return to office": "crime_scene"
+      }
+    },
+    "camera_check": {
+      "description": "The camera has been manually rotated away from the office door. The adjustment screw is loose, recently turned - you can still see fresh scratches on the metal. Whoever did this knew exactly which camera to move. The timestamp log shows the adjustment happened at 11:42 PM, five minutes before the estimated time of the incident. Martinez clocked in at 11:30 PM.",
+      "choices": ["Back to hallway"],
+      "transitions": {
+        "Back to hallway": "hallway"
+      }
+    },
+    "guard_talk": {
+      "description": "'Evening, Detective.' Martinez's voice is steady but his hands aren't - they're shaking slightly. His name tag reads 'Martinez, J.' - the same J.M. initialed on the back of the photo in Richardson's office. His uniform is disheveled, with a small tear near his left sleeve. 'I heard nothing unusual tonight. Just doing my rounds.' He keeps glancing at his watch. It's 12:15 AM.",
+      "choices": ["Press for details", "Thank him and leave"],
+      "transitions": {
+        "Press for details": "guard_pressed",
+        "Thank him and leave": "hallway"
+      }
+    },
+    "guard_pressed": {
+      "description": "'Look, I was on my rounds, okay?' Martinez's voice rises, defensive. 'The 14th floor wasn't scheduled until midnight.' He shifts his weight, mud flaking from his boots. 'Ask Jenkins at the front desk - he'll confirm my times.' His phone buzzes. He glances at it and his face goes pale. 'I need to... excuse me.' He starts to turn away. His boots are definitely size 11.",
+      "choices": ["Confront about the boots", "Let it go", "Ask about the photo"],
+      "transitions": {
+        "Confront about the boots": "confrontation",
+        "Let it go": "hallway",
+        "Ask about the photo": "photo_question"
+      }
+    },
+    "confrontation": {
+      "description": "Martinez's face drains of color. 'Those... those aren't...' He takes a shaky breath. 'Fine. Yes, I was up there tonight. But not to hurt him - to WARN him.' His voice cracks. 'Richardson and I... we were partners. In more ways than one. Someone found out about the money, about us. They called Richardson at 11:30, threatened to tell his wife everything unless he paid. I went up to help him figure out what to do. But when I got there...' He stops, unable to continue.",
+      "choices": ["Agree to meet", "Detain him now"],
+      "transitions": {
+        "Agree to meet": "hallway",
+        "Detain him now": "hallway"
+      }
+    },
+    "photo_question": {
+      "description": "At the mention of the photo, Martinez goes rigid. 'Where did you find that? That was supposed to be... Miranda was supposed to get rid of it.' He realizes what he's said too late. 'Look, Richardson and I were close, okay? Closer than his wife knew. Miranda found out - she's been covering for us, but lately she's been acting strange. Jealous, maybe. She kept saying if she couldn't have him, no one would.'",
+      "choices": ["Ask about the accounts", "Back to hallway"],
+      "transitions": {
+        "Ask about the accounts": "accounts_info",
+        "Back to hallway": "hallway"
+      }
+    },
+    "accounts_info": {
+      "description": "'He was moving money - lots of it. Company funds to offshore accounts. We were going to leave together, start fresh in Costa Rica.' Martinez's voice is hollow. 'I found out six months ago what he was doing. Should have reported it. But he promised we'd run away, disappear. Tonight was supposed to be the night.' He looks at his watch again - 12:28 AM. 'Someone else found out. Someone who doesn't make deals. Elena Richardson has family in organized crime. She called Richardson at 11:30 PM. I heard her voice through the door.'",
+      "choices": ["Who else knew?", "Back to hallway"],
+      "transitions": {
+        "Who else knew?": "hallway",
+        "Back to hallway": "hallway"
+      }
+    },
+    "miranda_lead": {
+      "description": "You find Miranda Chen at her desk on the 12th floor, still typing despite the late hour. Her coral lipstick is freshly applied, and she startles when she sees you. 'Detective! I didn't hear about... is Mr. Richardson alright?' Her voice is too high, too practiced. On her desk sits an empty coffee cup - the same brand as the one in Richardson's office. A Virginia Slims pack peeks from her purse.",
+      "choices": ["Ask about Richardson", "Ask about the coffee", "Leave"],
+      "transitions": {
+        "Ask about Richardson": "miranda_confession",
+        "Ask about the coffee": "miranda_coffee",
+        "Leave": "hallway"
+      }
+    },
+    "miranda_confession": {
+      "description": "'He was going to leave.' Miranda's composure cracks. 'After everything I did for him - covering up the affair with Martinez, hiding the money transfers, lying to Elena when she called. And he was going to take HIM instead of me.' Her hands tremble. 'I brought him coffee at 11:40. We talked. I told him I knew about the midnight flight. He laughed. Said I wasn't his type.' She looks at you with hollow eyes. 'I didn't mean for... the pills were just supposed to make him sleepy. Elena's man must have arrived while he was drowsy.'",
+      "choices": ["Continue investigating"],
+      "transitions": {
+        "Continue investigating": "hallway"
+      }
+    },
+    "miranda_coffee": {
+      "description": "'I always bring Mr. Richardson his evening coffee. It's part of my job.' Miranda's smile is too bright. 'Tonight was no different.' But her eyes flick to her purse. Inside, you can see an empty prescription bottle - the label reads 'Alprazolam.' Enough dissolved in coffee would make anyone confused, disoriented. Easy prey.",
+      "choices": ["Confront about pills", "Back away"],
+      "transitions": {
+        "Confront about pills": "miranda_confession",
+        "Back away": "hallway"
+      }
+    }
+  }
+}'''
+
+# After Round 3: Choices focus - investigation options, multiple approaches
+DEMO_AFTER_ROUND_3 = '''{
+  "investigation": {
+    "crime_scene": {
+      "description": "A dimly lit corner office on the 14th floor. Papers are scattered across the mahogany desk and floor - financial reports, all dated from last month. A broken window lets in cold night air, and you notice the glass shards fell inward, onto an expensive Persian rug now stained with what looks like coffee. A framed photo lies face-down near the overturned chair. On the desk, a half-eaten sandwich suggests Richardson left in a hurry - or was interrupted mid-meal.",
+      "choices": ["Examine the desk carefully", "Check the broken window", "Look at the fallen photo", "Search the floor for evidence", "Leave and check the hallway"],
+      "transitions": {
+        "Examine the desk carefully": "desk_clue",
+        "Check the broken window": "window_clue",
+        "Look at the fallen photo": "photo_clue",
+        "Search the floor for evidence": "floor_search",
+        "Leave and check the hallway": "hallway"
+      }
+    },
+    "desk_clue": {
+      "description": "The desk has a half-written letter addressed to 'M' - the handwriting grows increasingly shaky toward the end, betraying Richardson's fear. An empty coffee cup sits beside it, a faint coral lipstick mark on the rim - Richardson's wife wears red, not coral. The desk drawer is slightly ajar, revealing a corner of what looks like a passport. A sticky note on the monitor reads 'MIRANDA CALLED - URGENT' in what looks like a secretary's handwriting.",
+      "choices": ["Read the letter", "Check the drawer", "Examine the coffee cup", "Look at the sticky note closely", "Back to scene"],
+      "transitions": {
+        "Read the letter": "letter_reveal",
+        "Check the drawer": "drawer_contents",
+        "Examine the coffee cup": "coffee_clue",
+        "Look at the sticky note closely": "sticky_note_clue",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "window_clue": {
+      "description": "Glass shards cover the inside of the windowsill and floor - definitely broken from outside. But something's wrong: the window latch is still locked from the inside. On the exterior ledge, you spot a small piece of torn fabric caught on a nail, dark blue like a security uniform. The tear pattern suggests someone climbed up, not down - but Martinez is the only guard on duty tonight.",
+      "choices": ["Look outside carefully", "Examine the fabric closely", "Test the lock mechanism", "Check for fingerprints", "Back to scene"],
+      "transitions": {
+        "Look outside carefully": "outside_view",
+        "Examine the fabric closely": "fabric_clue",
+        "Test the lock mechanism": "lock_test",
+        "Check for fingerprints": "fingerprint_search",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "photo_clue": {
+      "description": "The frame's glass is cracked. The photo shows two men shaking hands at the company Christmas party 2019 - Richardson in an expensive suit, Martinez in his security uniform, both grinning like old friends. On the back, someone has written 'Partners in crime - Nov 2019' in feminine handwriting, with a small heart. The same coral lipstick has left a faint kiss mark in the corner.",
+      "choices": ["Keep the photo as evidence", "Study the handwriting", "Compare the lipstick shade", "Put it back for now", "Back to scene"],
+      "transitions": {
+        "Keep the photo as evidence": "evidence_collected",
+        "Study the handwriting": "handwriting_analysis",
+        "Compare the lipstick shade": "lipstick_comparison",
+        "Put it back for now": "crime_scene",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "floor_search": {
+      "description": "Crouching low, you scan the Persian rug and hardwood floor. Beneath the overturned chair, you find a crumpled receipt from a pharmacy dated today - Alprazolam prescription filled at 6:15 PM, patient name obscured by a coffee stain. Near the window, a single pearl earring catches the light. Elena Richardson was photographed wearing pearls at last month's gala.",
+      "choices": ["Pocket the receipt", "Examine the earring", "Check under the desk", "Back to scene"],
+      "transitions": {
+        "Pocket the receipt": "receipt_clue",
+        "Examine the earring": "earring_clue",
+        "Check under the desk": "under_desk",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "letter_reveal": {
+      "description": "The letter reads: 'Dear M, I can't keep doing this. They're going to find out about the transfers, and when they do, neither of us will be safe. Elena is getting suspicious - she found the Cayman statements. I need to disappear, but I can't leave you behind. Meet me at the usual place at midnight. If I'm not there by 12:30, assume the worst and run. Don't trust Martinez anymore - he's been asking questions. All my love, R.' The writing stops mid-sentence, a single drop of dried coffee staining the page.",
+      "choices": ["Who is 'M'?", "What transfers?", "Why not trust Martinez?", "Continue investigating"],
+      "transitions": {
+        "Who is 'M'?": "m_mystery",
+        "What transfers?": "transfer_investigation",
+        "Why not trust Martinez?": "martinez_suspicion",
+        "Continue investigating": "crime_scene"
+      }
+    },
+    "drawer_contents": {
+      "description": "Inside the drawer: a passport with several recent stamps to the Cayman Islands - the last trip was three days ago. A burner phone with a cracked screen shows the last call was to 'M' at 11:47 PM. A sticky note reads 'CALL BEFORE FRIDAY - E knows' with 'E' underlined three times. Elena, Richardson's wife, is known for her jealous streak and family money.",
+      "choices": ["Take the phone", "Check the passport dates", "Examine the sticky note", "Look for hidden compartments", "Back to desk"],
+      "transitions": {
+        "Take the phone": "phone_evidence",
+        "Check the passport dates": "passport_clue",
+        "Examine the sticky note": "friday_deadline",
+        "Look for hidden compartments": "secret_compartment",
+        "Back to desk": "desk_clue"
+      }
+    },
+    "coffee_clue": {
+      "description": "The coral lipstick shade is distinctive - 'Sunset Kiss' by Luxe, the kind sold at high-end department stores. Richardson's secretary Miranda wears this exact shade. The cup still has dregs at the bottom - the coffee smells bitter, with an underlying chemical note. There's a faint crystalline residue around the rim. Either Miranda has unusual taste in coffee additives, or someone wanted to make sure Richardson didn't finish his drink.",
+      "choices": ["Smell the coffee", "Scrape the residue for analysis", "Photograph the lipstick mark", "Back to desk"],
+      "transitions": {
+        "Smell the coffee": "poison_hint",
+        "Scrape the residue for analysis": "residue_analysis",
+        "Photograph the lipstick mark": "lipstick_evidence",
+        "Back to desk": "desk_clue"
+      }
+    },
+    "sticky_note_clue": {
+      "description": "The handwriting on 'MIRANDA CALLED - URGENT' is hurried, slanted - written by someone right-handed in a rush. But Richardson is left-handed. Someone else wrote this. The time stamp in the corner reads 11:35 PM. Miranda Chen is Richardson's secretary. Her desk is on the 12th floor.",
+      "choices": ["Go find Miranda", "Call Miranda's extension", "Back to desk"],
+      "transitions": {
+        "Go find Miranda": "miranda_lead",
+        "Call Miranda's extension": "miranda_call",
+        "Back to desk": "desk_clue"
+      }
+    },
+    "fabric_clue": {
+      "description": "The fabric is from a security uniform - you can see part of a stitched company logo. It's torn at an angle suggesting someone climbed up, not down. The thread count matches Martinez's uniform exactly, but the tear on his sleeve is on the right arm. This fabric came from a left sleeve. Either Martinez changed uniforms, or there's another security guard involved.",
+      "choices": ["Check the security roster", "Confront Martinez about this", "Examine more closely", "Back to window"],
+      "transitions": {
+        "Check the security roster": "security_roster",
+        "Confront Martinez about this": "confrontation",
+        "Examine more closely": "fabric_detail",
+        "Back to window": "window_clue"
+      }
+    },
+    "outside_view": {
+      "description": "Footprints in the mud lead toward the parking lot - two sets, one coming and one going. The incoming prints are deep, size 11 work boots, carrying something heavy. The outgoing prints are lighter, faster, size 7 women's heels, heading toward a side exit. A cigarette butt near the window smells fresh - Virginia Slims, a women's brand. Miranda smokes Virginia Slims.",
+      "choices": ["Follow the boot prints", "Follow the heel prints", "Collect the cigarette butt", "Photograph the prints", "Back inside"],
+      "transitions": {
+        "Follow the boot prints": "parking_lot",
+        "Follow the heel prints": "side_exit",
+        "Collect the cigarette butt": "cigarette_evidence",
+        "Photograph the prints": "print_documentation",
+        "Back inside": "crime_scene"
+      }
+    },
+    "hallway": {
+      "description": "The hallway is quiet, lit by flickering fluorescent lights. A security camera in the corner has a small red light - but you notice it's pointing at the wall, not the office door. Martinez approaches, his boots leaving muddy prints on the polished floor. His jaw is tight, eyes darting. 'Detective. Didn't expect you so soon.' His hand rests near his radio, as if ready to call for backup - or warn someone.",
+      "choices": ["Talk to Martinez directly", "Check the security camera first", "Examine his muddy boots", "Ask about other staff on duty", "Return to office"],
+      "transitions": {
+        "Talk to Martinez directly": "guard_talk",
+        "Check the security camera first": "camera_check",
+        "Examine his muddy boots": "boot_examination",
+        "Ask about other staff on duty": "staff_inquiry",
+        "Return to office": "crime_scene"
+      }
+    },
+    "camera_check": {
+      "description": "The camera has been manually rotated away from the office door. The adjustment screw is loose, recently turned - you can still see fresh scratches on the metal. Whoever did this knew exactly which camera to move. The timestamp log shows the adjustment happened at 11:42 PM, five minutes before the estimated time of the incident. Martinez clocked in at 11:30 PM.",
+      "choices": ["Check the camera footage", "Dust for prints on the camera", "Confront Martinez about timing", "Back to hallway"],
+      "transitions": {
+        "Check the camera footage": "footage_review",
+        "Dust for prints on the camera": "camera_prints",
+        "Confront Martinez about timing": "timing_confrontation",
+        "Back to hallway": "hallway"
+      }
+    },
+    "guard_talk": {
+      "description": "'Evening, Detective.' Martinez's voice is steady but his hands aren't - they're shaking slightly. His name tag reads 'Martinez, J.' - the same J.M. initialed on the back of the photo in Richardson's office. His uniform is disheveled, with a small tear near his left sleeve. 'I heard nothing unusual tonight. Just doing my rounds.' He keeps glancing at his watch. It's 12:15 AM.",
+      "choices": ["Press for details about tonight", "Ask about his relationship with Richardson", "Point out the tear in his uniform", "Thank him and leave"],
+      "transitions": {
+        "Press for details about tonight": "guard_pressed",
+        "Ask about his relationship with Richardson": "relationship_question",
+        "Point out the tear in his uniform": "uniform_confrontation",
+        "Thank him and leave": "hallway"
+      }
+    },
+    "guard_pressed": {
+      "description": "'Look, I was on my rounds, okay?' Martinez's voice rises, defensive. 'The 14th floor wasn't scheduled until midnight.' He shifts his weight, mud flaking from his boots. 'Ask Jenkins at the front desk - he'll confirm my times.' His phone buzzes. He glances at it and his face goes pale. 'I need to... excuse me.' He starts to turn away. His boots are definitely size 11.",
+      "choices": ["Confront about the muddy boots", "Demand to see his phone", "Let him go and follow", "Ask about the photo"],
+      "transitions": {
+        "Confront about the muddy boots": "confrontation",
+        "Demand to see his phone": "phone_demand",
+        "Let him go and follow": "follow_martinez",
+        "Ask about the photo": "photo_question"
+      }
+    },
+    "confrontation": {
+      "description": "Martinez's face drains of color. 'Those... those aren't...' He takes a shaky breath. 'Fine. Yes, I was up there tonight. But not to hurt him - to WARN him.' His voice cracks. 'Richardson and I... we were partners. In more ways than one. Someone found out about the money, about us. They called Richardson at 11:30, threatened to tell his wife everything unless he paid. I went up to help him figure out what to do. But when I got there...' He stops, unable to continue.",
+      "choices": ["What did you find when you arrived?", "Who called Richardson?", "Tell me about Elena Richardson", "You're under arrest"],
+      "transitions": {
+        "What did you find when you arrived?": "martinez_discovery",
+        "Who called Richardson?": "caller_identity",
+        "Tell me about Elena Richardson": "elena_info",
+        "You're under arrest": "arrest_martinez"
+      }
+    },
+    "photo_question": {
+      "description": "At the mention of the photo, Martinez goes rigid. 'Where did you find that? That was supposed to be... Miranda was supposed to get rid of it.' He realizes what he's said too late. 'Look, Richardson and I were close, okay? Closer than his wife knew. Miranda found out - she's been covering for us, but lately she's been acting strange. Jealous, maybe. She kept saying if she couldn't have him, no one would.'",
+      "choices": ["Tell me more about Miranda", "Ask about the accounts", "Was Miranda here tonight?", "Back to hallway"],
+      "transitions": {
+        "Tell me more about Miranda": "miranda_background",
+        "Ask about the accounts": "accounts_info",
+        "Was Miranda here tonight?": "miranda_whereabouts",
+        "Back to hallway": "hallway"
+      }
+    },
+    "accounts_info": {
+      "description": "'He was moving money - lots of it. Company funds to offshore accounts. We were going to leave together, start fresh in Costa Rica.' Martinez's voice is hollow. 'I found out six months ago what he was doing. Should have reported it. But he promised we'd run away, disappear. Tonight was supposed to be the night.' He looks at his watch again - 12:28 AM. 'Someone else found out. Someone who doesn't make deals. Elena Richardson has family in organized crime. She called Richardson at 11:30 PM. I heard her voice through the door.'",
+      "choices": ["Tell me about Elena's family", "Who else knew about the money?", "What happened at 11:30?", "Back to hallway"],
+      "transitions": {
+        "Tell me about Elena's family": "elena_family",
+        "Who else knew about the money?": "money_knowledge",
+        "What happened at 11:30?": "eleven_thirty",
+        "Back to hallway": "hallway"
+      }
+    },
+    "miranda_lead": {
+      "description": "You find Miranda Chen at her desk on the 12th floor, still typing despite the late hour. Her coral lipstick is freshly applied, and she startles when she sees you. 'Detective! I didn't hear about... is Mr. Richardson alright?' Her voice is too high, too practiced. On her desk sits an empty coffee cup - the same brand as the one in Richardson's office. A Virginia Slims pack peeks from her purse.",
+      "choices": ["Ask about Richardson directly", "Ask about the coffee", "Mention the cigarettes outside", "Ask why she's working late", "Leave quietly"],
+      "transitions": {
+        "Ask about Richardson directly": "miranda_richardson",
+        "Ask about the coffee": "miranda_coffee",
+        "Mention the cigarettes outside": "miranda_cigarettes",
+        "Ask why she's working late": "miranda_late",
+        "Leave quietly": "hallway"
+      }
+    },
+    "miranda_confession": {
+      "description": "'He was going to leave.' Miranda's composure cracks. 'After everything I did for him - covering up the affair with Martinez, hiding the money transfers, lying to Elena when she called. And he was going to take HIM instead of me.' Her hands tremble. 'I brought him coffee at 11:40. We talked. I told him I knew about the midnight flight. He laughed. Said I wasn't his type.' She looks at you with hollow eyes. 'I didn't mean for... the pills were just supposed to make him sleepy. Elena's man must have arrived while he was drowsy.'",
+      "choices": ["What pills did you use?", "Who is Elena's man?", "You're under arrest", "Continue investigating"],
+      "transitions": {
+        "What pills did you use?": "pills_confession",
+        "Who is Elena's man?": "elenas_enforcer",
+        "You're under arrest": "miranda_arrest",
+        "Continue investigating": "hallway"
+      }
+    },
+    "miranda_coffee": {
+      "description": "'I always bring Mr. Richardson his evening coffee. It's part of my job.' Miranda's smile is too bright. 'Tonight was no different.' But her eyes flick to her purse. Inside, you can see an empty prescription bottle - the label reads 'Alprazolam.' Enough dissolved in coffee would make anyone confused, disoriented. Easy prey.",
+      "choices": ["Confront about the prescription", "Ask who else visited tonight", "Mention the lipstick on the cup", "Back away slowly"],
+      "transitions": {
+        "Confront about the prescription": "miranda_confession",
+        "Ask who else visited tonight": "visitor_info",
+        "Mention the lipstick on the cup": "lipstick_confrontation",
+        "Back away slowly": "hallway"
+      }
+    },
+    "lock_test": {
+      "description": "You examine the window lock mechanism carefully. It's a standard sash lock, latched from the inside. But there are faint scratches around the latch - someone jimmied it closed AFTER the glass was broken. This wasn't a break-in. It was staged to look like one. The real entrance was probably the office door.",
+      "choices": ["Check the office door lock", "Re-examine the glass pattern", "Back to scene"],
+      "transitions": {
+        "Check the office door lock": "door_lock",
+        "Re-examine the glass pattern": "glass_analysis",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "fingerprint_search": {
+      "description": "Dusting the window frame reveals multiple prints. Most are smudged, but you get two clean sets: one matches the security database (Martinez), and another belongs to a woman - long, manicured nails. The woman's prints are on the INSIDE of the window latch. Someone closed it from inside after the glass was broken.",
+      "choices": ["Run the unknown prints", "Confront Martinez", "Back to scene"],
+      "transitions": {
+        "Run the unknown prints": "print_results",
+        "Confront Martinez": "confrontation",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "evidence_collected": {
+      "description": "You slip the photo into an evidence bag. The connection between Martinez and Richardson goes deeper than a professional relationship. The feminine handwriting and lipstick mark suggest a third party - someone close enough to Richardson to know about his affairs, someone who might feel betrayed.",
+      "choices": ["Continue investigating"],
+      "transitions": {
+        "Continue investigating": "crime_scene"
+      }
+    },
+    "handwriting_analysis": {
+      "description": "The handwriting on the photo back is distinctive - elegant, educated, with a slight leftward slant. Comparing it to the sticky note on Richardson's monitor, you notice similarities. Both were written by the same person. Miranda Chen is left-handed.",
+      "choices": ["Go find Miranda", "Back to scene"],
+      "transitions": {
+        "Go find Miranda": "miranda_lead",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "m_mystery": {
+      "description": "Who is 'M'? The letter suggests an intimate relationship. Martinez's first name is Jorge - that doesn't match. But Miranda Chen's last name starts with M. Or could 'M' refer to someone else entirely? Richardson's wife Elena was born Elena Morrison. Three suspects, one initial.",
+      "choices": ["Focus on Martinez", "Investigate Miranda", "Look into Elena", "Continue investigating"],
+      "transitions": {
+        "Focus on Martinez": "guard_talk",
+        "Investigate Miranda": "miranda_lead",
+        "Look into Elena": "elena_investigation",
+        "Continue investigating": "crime_scene"
+      }
+    }
+  }
+}'''
+
+# After Round 4: Tension focus - time pressure, red herrings, dramatic reveals
+DEMO_AFTER_ROUND_4 = '''{
+  "investigation": {
+    "crime_scene": {
+      "description": "A dimly lit corner office on the 14th floor. Papers are scattered across the mahogany desk and floor - financial reports, all dated from last month. A broken window lets in cold night air, and you notice the glass shards fell inward, onto an expensive Persian rug now stained with what looks like coffee. A framed photo lies face-down near the overturned chair. On the desk, a half-eaten sandwich suggests Richardson left in a hurry - or was interrupted mid-meal. Your phone buzzes: 'URGENT - Richardson's wife just landed at the airport. ETA 45 minutes.' The clock is ticking.",
+      "choices": ["Examine the desk carefully", "Check the broken window", "Look at the fallen photo", "Search the floor for evidence", "Leave and check the hallway"],
+      "transitions": {
+        "Examine the desk carefully": "desk_clue",
+        "Check the broken window": "window_clue",
+        "Look at the fallen photo": "photo_clue",
+        "Search the floor for evidence": "floor_search",
+        "Leave and check the hallway": "hallway"
+      }
+    },
+    "desk_clue": {
+      "description": "The desk has a half-written letter addressed to 'M' - the handwriting grows increasingly shaky toward the end, betraying Richardson's fear. An empty coffee cup sits beside it, a faint coral lipstick mark on the rim - Richardson's wife wears red, not coral. The desk drawer is slightly ajar, revealing a corner of what looks like a passport. A sticky note on the monitor reads 'MIRANDA CALLED - URGENT' in what looks like a secretary's handwriting. Wait - there's another note underneath: 'Elena knows. Tonight. Midnight.' Someone warned him, but he didn't run.",
+      "choices": ["Read the letter", "Check the drawer", "Examine the coffee cup", "Look at both sticky notes", "Back to scene"],
+      "transitions": {
+        "Read the letter": "letter_reveal",
+        "Check the drawer": "drawer_contents",
+        "Examine the coffee cup": "coffee_clue",
+        "Look at both sticky notes": "sticky_notes_comparison",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "window_clue": {
+      "description": "Glass shards cover the inside of the windowsill and floor - definitely broken from outside. But something's wrong: the window latch is still locked from the inside. RED HERRING ALERT: Your gut says this is staged. On the exterior ledge, you spot a small piece of torn fabric caught on a nail, dark blue like a security uniform. But wait - security uniforms were switched to BLACK last month. This fabric is from an OLD uniform. Someone planted this.",
+      "choices": ["Look outside carefully", "Examine the planted fabric", "Test the lock mechanism", "Check for fingerprints", "Back to scene"],
+      "transitions": {
+        "Look outside carefully": "outside_view",
+        "Examine the planted fabric": "fabric_clue",
+        "Test the lock mechanism": "lock_test",
+        "Check for fingerprints": "fingerprint_search",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "photo_clue": {
+      "description": "The frame's glass is cracked. The photo shows two men shaking hands at the company Christmas party 2019 - Richardson in an expensive suit, Martinez in his security uniform, both grinning like old friends. On the back, someone has written 'Partners in crime - Nov 2019' in feminine handwriting, with a small heart. The same coral lipstick has left a faint kiss mark in the corner. But here's what catches your eye: the photo has been recently handled - fresh fingerprints over old dust. Someone looked at this TONIGHT.",
+      "choices": ["Keep the photo as evidence", "Study the fresh fingerprints", "Compare the lipstick shade", "Check for hidden messages", "Back to scene"],
+      "transitions": {
+        "Keep the photo as evidence": "evidence_collected",
+        "Study the fresh fingerprints": "fresh_prints",
+        "Compare the lipstick shade": "lipstick_comparison",
+        "Check for hidden messages": "hidden_message",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "floor_search": {
+      "description": "Crouching low, you scan the Persian rug and hardwood floor. Beneath the overturned chair, you find a crumpled receipt from a pharmacy dated today - Alprazolam prescription filled at 6:15 PM, patient name obscured by a coffee stain. Near the window, a single pearl earring catches the light. Elena Richardson was photographed wearing pearls at last month's gala. But pearls are common - is this really hers, or another planted clue?",
+      "choices": ["Pocket the receipt - crucial evidence", "Examine the earring skeptically", "Check under the desk", "Look for more planted evidence", "Back to scene"],
+      "transitions": {
+        "Pocket the receipt - crucial evidence": "receipt_clue",
+        "Examine the earring skeptically": "earring_analysis",
+        "Check under the desk": "under_desk",
+        "Look for more planted evidence": "planted_evidence_search",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "letter_reveal": {
+      "description": "The letter reads: 'Dear M, I can't keep doing this. They're going to find out about the transfers, and when they do, neither of us will be safe. Elena is getting suspicious - she found the Cayman statements. I need to disappear, but I can't leave you behind. Meet me at the usual place at midnight. If I'm not there by 12:30, assume the worst and run. Don't trust Martinez anymore - he's been asking questions. All my love, R.' The writing stops mid-sentence. WAIT - the ink at the end is different. Someone ADDED that last line about Martinez. The original letter ended at 'run.'",
+      "choices": ["Examine the different inks", "Who is 'M'?", "Why was Martinez's name added?", "Continue investigating"],
+      "transitions": {
+        "Examine the different inks": "ink_analysis",
+        "Who is 'M'?": "m_mystery",
+        "Why was Martinez's name added?": "martinez_framed",
+        "Continue investigating": "crime_scene"
+      }
+    },
+    "drawer_contents": {
+      "description": "Inside the drawer: a passport with several recent stamps to the Cayman Islands - the last trip was three days ago. A burner phone with a cracked screen shows the last call was to 'M' at 11:47 PM - just fifteen minutes before the estimated incident. A sticky note reads 'CALL BEFORE FRIDAY - E knows' with 'E' underlined three times. Your phone buzzes again: 'Elena Richardson's car just passed the highway exit. 30 minutes.' You need to solve this before she arrives and lawyers up.",
+      "choices": ["Grab the phone - check call history", "Check the passport dates", "Examine the 'E knows' note", "Look for hidden compartments", "Back to desk"],
+      "transitions": {
+        "Grab the phone - check call history": "phone_evidence",
+        "Check the passport dates": "passport_clue",
+        "Examine the 'E knows' note": "friday_deadline",
+        "Look for hidden compartments": "secret_compartment",
+        "Back to desk": "desk_clue"
+      }
+    },
+    "coffee_clue": {
+      "description": "The coral lipstick shade is distinctive - 'Sunset Kiss' by Luxe, sold exclusively at Nordstrom. Richardson's secretary Miranda wears this exact shade - you've seen her wear it. But so does ELENA RICHARDSON in her Instagram photos. The cup still has dregs at the bottom - the coffee smells bitter, with an underlying chemical note. There's a faint crystalline residue around the rim. TWIST: The residue isn't a sedative. Field test shows it's artificial sweetener - the expensive kind Elena uses for her diet. Miranda takes her coffee black.",
+      "choices": ["This changes everything", "Test the residue again", "Photograph the evidence", "Back to desk"],
+      "transitions": {
+        "This changes everything": "elena_revelation",
+        "Test the residue again": "residue_confirmation",
+        "Photograph the evidence": "evidence_photo",
+        "Back to desk": "desk_clue"
+      }
+    },
+    "hallway": {
+      "description": "The hallway is quiet, lit by flickering fluorescent lights. A security camera in the corner has a small red light - but you notice it's pointing at the wall, not the office door. Martinez approaches, his boots leaving muddy prints on the polished floor. His jaw is tight, eyes darting. 'Detective. Didn't expect you so soon.' His hand rests near his radio. Then he says something strange: 'Whatever they told you about me and Richardson - it's not the whole story. Elena's people got here first. I tried to warn him.' He looks genuinely scared.",
+      "choices": ["What do you mean, Elena's people?", "Check the security camera first", "Examine his muddy boots", "Ask about the warning", "Return to office"],
+      "transitions": {
+        "What do you mean, Elena's people?": "elena_people",
+        "Check the security camera first": "camera_check",
+        "Examine his muddy boots": "boot_examination",
+        "Ask about the warning": "warning_details",
+        "Return to office": "crime_scene"
+      }
+    },
+    "camera_check": {
+      "description": "The camera has been manually rotated away from the office door. The adjustment screw is loose, recently turned - you can still see fresh scratches on the metal. Whoever did this knew exactly which camera to move. The timestamp log shows the adjustment happened at 11:42 PM. But here's the CRUCIAL DETAIL: there are TWO sets of scratches. Someone adjusted this camera TWICE. First at 11:42 PM, then again at 11:58 PM - after the incident. Someone came back to make sure it was still pointed away.",
+      "choices": ["Check footage from other cameras", "Who came back at 11:58?", "Confront Martinez about timing", "Back to hallway"],
+      "transitions": {
+        "Check footage from other cameras": "other_cameras",
+        "Who came back at 11:58?": "second_adjustment",
+        "Confront Martinez about timing": "timing_confrontation",
+        "Back to hallway": "hallway"
+      }
+    },
+    "guard_talk": {
+      "description": "'Evening, Detective.' Martinez's voice is steady but his hands aren't - they're shaking. His name tag reads 'Martinez, J.' His uniform is disheveled, with a small tear near his left sleeve. 'I heard nothing unusual tonight. Just doing my rounds.' He keeps glancing at his watch. It's 12:15 AM. Then he leans closer and whispers: 'The woman who came up at 11:35 - it wasn't Miranda. It was Elena. She was wearing Miranda's coat, but I recognized her perfume. Chanel No. 5. I didn't say anything because... her family...' He draws a finger across his throat.",
+      "choices": ["Elena was HERE?", "Tell me about her family", "Why didn't you stop her?", "You're lying to protect yourself"],
+      "transitions": {
+        "Elena was HERE?": "elena_presence",
+        "Tell me about her family": "family_connections",
+        "Why didn't you stop her?": "martinez_fear",
+        "You're lying to protect yourself": "martinez_defense"
+      }
+    },
+    "guard_pressed": {
+      "description": "'Look, I was on my rounds, okay?' Martinez's voice rises, then drops to a whisper. 'The 14th floor wasn't scheduled until midnight. But I went up early because Richardson texted me at 11:25 - said someone was coming, someone dangerous. When I got there at 11:40, I heard voices inside. A woman, screaming. Then silence. I... I hid. I'm not proud of it.' He shows you his phone - the text from Richardson reads: 'SHE FOUND OUT. Coming to office. Help me. Please.' Sent at 11:25 PM.",
+      "choices": ["Who is 'she'?", "Why did you hide?", "Show me the rest of the texts", "What happened after the silence?"],
+      "transitions": {
+        "Who is 'she'?": "she_identity",
+        "Why did you hide?": "hiding_reason",
+        "Show me the rest of the texts": "full_texts",
+        "What happened after the silence?": "aftermath"
+      }
+    },
+    "confrontation": {
+      "description": "Martinez breaks down completely. 'Fine! Yes, Richardson and I were together. For two years. But I didn't hurt him - I LOVED him.' Tears stream down his face. 'When I got to the office, he was already on the floor. The coffee cup was knocked over. A woman in Miranda's coat was climbing out the window - that's why there's fabric on the ledge. But the way she moved... it wasn't Miranda. It was Elena, I swear to God. She set this whole thing up to frame Miranda, frame me. She's been planning this for months.'",
+      "choices": ["How do you know it was Elena?", "Where is Richardson now?", "What do you mean, planning for months?", "You're under arrest"],
+      "transitions": {
+        "How do you know it was Elena?": "elena_identification",
+        "Where is Richardson now?": "richardson_fate",
+        "What do you mean, planning for months?": "long_con",
+        "You're under arrest": "arrest_martinez"
+      }
+    },
+    "photo_question": {
+      "description": "At the mention of the photo, Martinez's face changes from fear to realization. 'That photo... Elena found it last month. She came to me, showed it to me. Said she'd destroy both our careers unless I helped her.' He pulls out his phone, shows you a text thread. Elena Richardson: 'I know about you and my husband. Friday night. You will let me into the building after hours. You will turn off the camera. Or these photos go to HR, the board, and every news outlet in the city.' Dated three days ago.",
+      "choices": ["She blackmailed you into helping", "Did you know what she planned?", "Why didn't you warn Richardson?", "Show this to my captain"],
+      "transitions": {
+        "She blackmailed you into helping": "blackmail_reveal",
+        "Did you know what she planned?": "plan_knowledge",
+        "Why didn't you warn Richardson?": "warning_failure",
+        "Show this to my captain": "evidence_secured"
+      }
+    },
+    "accounts_info": {
+      "description": "'He was moving money - lots of it. Company funds to offshore accounts.' Martinez wipes his eyes. 'We were going to leave together, start fresh. But Elena found out about everything - the money AND us. She didn't just want a divorce. She wanted revenge.' He checks his watch nervously. 'Her family has connections to people who make problems disappear. The coffee, the staged break-in - this was a professional hit made to look like a crime of passion. And I...' His voice breaks. 'I let her in. God help me, I let her in.'",
+      "choices": ["Where is Elena now?", "The coffee was poisoned?", "Who else helped her?", "We need to find Richardson"],
+      "transitions": {
+        "Where is Elena now?": "elena_location",
+        "The coffee was poisoned?": "poison_confirmation",
+        "Who else helped her?": "accomplices",
+        "We need to find Richardson": "richardson_search"
+      }
+    },
+    "miranda_lead": {
+      "description": "You find Miranda Chen at her desk on the 12th floor, furiously packing a box. She freezes when she sees you. 'Detective! I was just... organizing.' Her coral lipstick is smeared, mascara running. 'I heard sirens. Is Mr. Richardson okay?' She's lying - her coat is hanging on the back of her chair, dry and clean. But someone wearing her coat was at the scene. On her desk, a resignation letter dated TODAY. She was planning to leave before any of this happened.",
+      "choices": ["Where's your other coat, Miranda?", "Who borrowed your coat tonight?", "Why are you resigning?", "Did you bring Richardson coffee tonight?"],
+      "transitions": {
+        "Where's your other coat, Miranda?": "coat_question",
+        "Who borrowed your coat tonight?": "coat_borrower",
+        "Why are you resigning?": "resignation_reason",
+        "Did you bring Richardson coffee tonight?": "coffee_denial"
+      }
+    },
+    "miranda_confession": {
+      "description": "'I didn't hurt him!' Miranda sobs. 'Yes, I brought him coffee at 11:40. Yes, I've been in love with him for three years. But when I got to his office, Elena was already there. She was wearing MY coat - must have taken it from my desk earlier. She told me to leave, that this was between her and her husband. I... I ran. I was scared.' She pulls out her phone. 'Look - I called 911 at 11:52 PM. Anonymously. That's how you got here so fast. I tried to help him, I swear.'",
+      "choices": ["The 911 call - that was you?", "What did you see Elena doing?", "Why was she wearing your coat?", "You're coming with me"],
+      "transitions": {
+        "The 911 call - that was you?": "911_confirmation",
+        "What did you see Elena doing?": "elena_actions",
+        "Why was she wearing your coat?": "coat_explanation",
+        "You're coming with me": "miranda_detained"
+      }
+    },
+    "miranda_coffee": {
+      "description": "'I always bring Mr. Richardson his evening coffee.' Miranda's hands shake as she grabs the edge of her desk. 'But tonight - tonight Elena intercepted me in the hallway. Took the cup right out of my hands. Said she wanted to make up with her husband, bring him coffee as a peace offering. I thought it was sweet.' Her face crumbles. 'Oh God. She put something in it, didn't she? She used MY cup, MY lipstick shade - she was setting me up from the start.'",
+      "choices": ["Elena took the coffee from you?", "She planned to frame you", "What time was this?", "I need you to come with me"],
+      "transitions": {
+        "Elena took the coffee from you?": "coffee_interception",
+        "She planned to frame you": "frame_job",
+        "What time was this?": "timeline_clarification",
+        "I need you to come with me": "miranda_witness"
+      }
+    },
+    "ink_analysis": {
+      "description": "Examining the letter under your UV light, the truth becomes clear. The original letter was written with Richardson's usual fountain pen - blue-black Montblanc ink. But the last line about Martinez was added with a cheap ballpoint, common office supply. Someone added that line to redirect suspicion toward Martinez and away from the real killer. The handwriting is close to Richardson's but not exact - slightly more angular. Elena Richardson is known for her perfect forgery skills; she handles all the household documents.",
+      "choices": ["Elena forged this line", "Test the ballpoint ink", "Check security footage for document tampering", "Continue investigating"],
+      "transitions": {
+        "Elena forged this line": "forgery_confirmed",
+        "Test the ballpoint ink": "ink_test",
+        "Check security footage for document tampering": "document_footage",
+        "Continue investigating": "crime_scene"
+      }
+    },
+    "final_confrontation": {
+      "description": "Your phone buzzes one final time: 'Elena Richardson just pulled into the parking garage. She's heading for the elevator.' You have minutes to make a decision. The evidence points to a calculated murder disguised as a crime of passion. Elena poisoned her husband's coffee, staged the break-in, framed Miranda and Martinez, and is about to walk into this building pretending to be the grieving widow. Martinez is willing to testify. Miranda is a witness. The forged letter and planted evidence tell the story. But Elena's family connections mean this case needs to be airtight.",
+      "choices": ["Arrest Elena in the lobby", "Gather more evidence first", "Confront her in the office", "Call for backup and wait"],
+      "transitions": {
+        "Arrest Elena in the lobby": "lobby_arrest",
+        "Gather more evidence first": "more_evidence",
+        "Confront her in the office": "office_confrontation",
+        "Call for backup and wait": "backup_ending"
+      }
+    },
+    "true_ending": {
+      "description": "As Elena Richardson steps off the elevator, her face a perfect mask of concern, you step forward with your badge. 'Mrs. Richardson. We have witnesses placing you at your husband's office at 11:35 PM, wearing Miranda Chen's coat. We have the forged addition to your husband's letter. We have your artificial sweetener in the poisoned coffee. And we have your blackmail texts to Jorge Martinez.' Her mask slips, just for a moment, revealing cold fury. 'You can't prove anything. My family will—' 'Your family will read about this in tomorrow's paper,' you interrupt. 'Elena Richardson, you're under arrest for the murder of David Richardson.' As the cuffs click, Martinez finally stops shaking. Miranda stops crying. Sometimes, the truth finds a way through the lies.",
+      "choices": ["Case closed"],
+      "transitions": {
+        "Case closed": "crime_scene"
+      }
+    }
+  }
+}'''
+
+# Demo workflow guide
+DEMO_WORKFLOW_GUIDE = """
+## LLM Improvement Loop Demo: Mystery Deepening Workflow
+
+This demo shows how to iteratively improve a game config using the Mystery Deepening workflow.
+
+### Starting Config
+- 7 states
+- Basic mystery structure
+- Short descriptions (8-15 words each)
+- 2 choices per state on average
+
+### Workflow Steps
+
+**Round 1: Environment Focus**
+- Click "1: environment" in Mystery Deepening column
+- Generate prompt → Copy to ChatGPT/Claude
+- LLM adds: environmental clues, sensory details, hidden objects
+- Result: 18 states, rich atmospheric descriptions
+
+**Round 2: Characters Focus**
+- Click "2: characters"
+- Generate prompt with Round 1 config
+- LLM adds: NPC motivations, dialogue revealing personality, relationships
+- Result: Character depth, suspicious behaviors, backstory hints
+
+**Round 3: Choices Focus**
+- Click "3: choices"
+- Generate prompt with Round 2 config
+- LLM adds: investigation options, different approaches, hidden paths
+- Result: 3-4 choices per state, multiple investigation strategies
+
+**Round 4: Tension Focus**
+- Click "4: tension"
+- Generate prompt with Round 3 config
+- LLM adds: time pressure, red herrings, dramatic reveals
+- Result: Heightened stakes, misleading clues, climactic moments
+
+### Metrics Progression (Example)
+| Round | States | Avg Choices | Avg Desc Length |
+|-------|--------|-------------|-----------------|
+| Start | 7      | 2.0         | 12 words        |
+| R1    | 18     | 2.8         | 45 words        |
+| R2    | 22     | 3.1         | 52 words        |
+| R3    | 25     | 3.6         | 55 words        |
+| R4    | 28     | 3.8         | 62 words        |
+
+### Tips
+1. Each round builds on previous improvements
+2. The prompt includes round context for continuity
+3. Use "Revert" if a round's changes don't work
+4. Export history to save your improvement journey
+"""
+
+if __name__ == "__main__":
+    import json
+
+    # Validate all rounds
+    rounds = [
+        ("Starter (R0)", DEMO_MYSTERY_STARTER),
+        ("Round 1 - Environment", DEMO_AFTER_ROUND_1),
+        ("Round 2 - Characters", DEMO_AFTER_ROUND_2),
+        ("Round 3 - Choices", DEMO_AFTER_ROUND_3),
+        ("Round 4 - Tension", DEMO_AFTER_ROUND_4),
+    ]
+
+    print("=== Demo Config Validation ===\n")
+    for name, config_str in rounds:
+        config = json.loads(config_str)
+        states = config.get('investigation', {})
+        total_choices = sum(len(s.get('choices', [])) for s in states.values())
+        avg_choices = total_choices / len(states) if states else 0
+        print(f"{name}: {len(states)} states, {avg_choices:.1f} avg choices")
+
+    print("\n" + DEMO_WORKFLOW_GUIDE)

demo_mystery_complete.json

@@ -0,0 +1,327 @@
+{
+  "investigation": {
+    "crime_scene": {
+      "description": "A dimly lit corner office on the 14th floor. Papers are scattered across the mahogany desk and floor - financial reports, all dated from last month. A broken window lets in cold night air, and you notice the glass shards fell inward, onto an expensive Persian rug now stained with what looks like coffee. A framed photo lies face-down near the overturned chair. On the desk, a half-eaten sandwich suggests Richardson left in a hurry - or was interrupted mid-meal. Your phone buzzes: 'URGENT - Richardson's wife just landed at the airport. ETA 45 minutes.' The clock is ticking.",
+      "choices": [
+        "Examine the desk carefully",
+        "Check the broken window",
+        "Look at the fallen photo",
+        "Search the floor for evidence",
+        "Leave and check the hallway"
+      ],
+      "transitions": {
+        "Examine the desk carefully": "desk_clue",
+        "Check the broken window": "window_clue",
+        "Look at the fallen photo": "photo_clue",
+        "Search the floor for evidence": "floor_search",
+        "Leave and check the hallway": "hallway"
+      }
+    },
+    "desk_clue": {
+      "description": "The desk has a half-written letter addressed to 'M' - the handwriting grows increasingly shaky toward the end, betraying Richardson's fear. An empty coffee cup sits beside it, a faint coral lipstick mark on the rim - Richardson's wife wears red, not coral. The desk drawer is slightly ajar, revealing a corner of what looks like a passport. A sticky note on the monitor reads 'MIRANDA CALLED - URGENT' in what looks like a secretary's handwriting. Wait - there's another note underneath: 'Elena knows. Tonight. Midnight.' Someone warned him, but he didn't run.",
+      "choices": [
+        "Read the letter",
+        "Check the drawer",
+        "Examine the coffee cup",
+        "Look at both sticky notes",
+        "Back to scene"
+      ],
+      "transitions": {
+        "Read the letter": "letter_reveal",
+        "Check the drawer": "drawer_contents",
+        "Examine the coffee cup": "coffee_clue",
+        "Look at both sticky notes": "sticky_notes_comparison",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "window_clue": {
+      "description": "Glass shards cover the inside of the windowsill and floor - definitely broken from outside. But something's wrong: the window latch is still locked from the inside. RED HERRING ALERT: Your gut says this is staged. On the exterior ledge, you spot a small piece of torn fabric caught on a nail, dark blue like a security uniform. But wait - security uniforms were switched to BLACK last month. This fabric is from an OLD uniform. Someone planted this.",
+      "choices": [
+        "Look outside carefully",
+        "Examine the planted fabric",
+        "Test the lock mechanism",
+        "Check for fingerprints",
+        "Back to scene"
+      ],
+      "transitions": {
+        "Look outside carefully": "outside_view",
+        "Examine the planted fabric": "fabric_clue",
+        "Test the lock mechanism": "lock_test",
+        "Check for fingerprints": "fingerprint_search",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "photo_clue": {
+      "description": "The frame's glass is cracked. The photo shows two men shaking hands at the company Christmas party 2019 - Richardson in an expensive suit, Martinez in his security uniform, both grinning like old friends. On the back, someone has written 'Partners in crime - Nov 2019' in feminine handwriting, with a small heart. The same coral lipstick has left a faint kiss mark in the corner. But here's what catches your eye: the photo has been recently handled - fresh fingerprints over old dust. Someone looked at this TONIGHT.",
+      "choices": [
+        "Keep the photo as evidence",
+        "Study the fresh fingerprints",
+        "Compare the lipstick shade",
+        "Check for hidden messages",
+        "Back to scene"
+      ],
+      "transitions": {
+        "Keep the photo as evidence": "evidence_collected",
+        "Study the fresh fingerprints": "fresh_prints",
+        "Compare the lipstick shade": "lipstick_comparison",
+        "Check for hidden messages": "hidden_message",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "floor_search": {
+      "description": "Crouching low, you scan the Persian rug and hardwood floor. Beneath the overturned chair, you find a crumpled receipt from a pharmacy dated today - Alprazolam prescription filled at 6:15 PM, patient name obscured by a coffee stain. Near the window, a single pearl earring catches the light. Elena Richardson was photographed wearing pearls at last month's gala. But pearls are common - is this really hers, or another planted clue?",
+      "choices": [
+        "Pocket the receipt - crucial evidence",
+        "Examine the earring skeptically",
+        "Check under the desk",
+        "Look for more planted evidence",
+        "Back to scene"
+      ],
+      "transitions": {
+        "Pocket the receipt - crucial evidence": "receipt_clue",
+        "Examine the earring skeptically": "earring_analysis",
+        "Check under the desk": "under_desk",
+        "Look for more planted evidence": "planted_evidence_search",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "letter_reveal": {
+      "description": "The letter reads: 'Dear M, I can't keep doing this. They're going to find out about the transfers, and when they do, neither of us will be safe. Elena is getting suspicious - she found the Cayman statements. I need to disappear, but I can't leave you behind. Meet me at the usual place at midnight. If I'm not there by 12:30, assume the worst and run. Don't trust Martinez anymore - he's been asking questions. All my love, R.' The writing stops mid-sentence. WAIT - the ink at the end is different. Someone ADDED that last line about Martinez. The original letter ended at 'run.'",
+      "choices": [
+        "Examine the different inks",
+        "Who is 'M'?",
+        "Why was Martinez's name added?",
+        "Continue investigating"
+      ],
+      "transitions": {
+        "Examine the different inks": "ink_analysis",
+        "Who is 'M'?": "m_mystery",
+        "Why was Martinez's name added?": "martinez_framed",
+        "Continue investigating": "crime_scene"
+      }
+    },
+    "drawer_contents": {
+      "description": "Inside the drawer: a passport with several recent stamps to the Cayman Islands - the last trip was three days ago. A burner phone with a cracked screen shows the last call was to 'M' at 11:47 PM - just fifteen minutes before the estimated incident. A sticky note reads 'CALL BEFORE FRIDAY - E knows' with 'E' underlined three times. Your phone buzzes again: 'Elena Richardson's car just passed the highway exit. 30 minutes.' You need to solve this before she arrives and lawyers up.",
+      "choices": [
+        "Grab the phone - check call history",
+        "Check the passport dates",
+        "Examine the 'E knows' note",
+        "Look for hidden compartments",
+        "Back to desk"
+      ],
+      "transitions": {
+        "Grab the phone - check call history": "phone_evidence",
+        "Check the passport dates": "passport_clue",
+        "Examine the 'E knows' note": "friday_deadline",
+        "Look for hidden compartments": "secret_compartment",
+        "Back to desk": "desk_clue"
+      }
+    },
+    "coffee_clue": {
+      "description": "The coral lipstick shade is distinctive - 'Sunset Kiss' by Luxe, sold exclusively at Nordstrom. Richardson's secretary Miranda wears this exact shade - you've seen her wear it. But so does ELENA RICHARDSON in her Instagram photos. The cup still has dregs at the bottom - the coffee smells bitter, with an underlying chemical note. There's a faint crystalline residue around the rim. TWIST: The residue isn't a sedative. Field test shows it's artificial sweetener - the expensive kind Elena uses for her diet. Miranda takes her coffee black.",
+      "choices": [
+        "This changes everything",
+        "Test the residue again",
+        "Photograph the evidence",
+        "Back to desk"
+      ],
+      "transitions": {
+        "This changes everything": "elena_revelation",
+        "Test the residue again": "residue_confirmation",
+        "Photograph the evidence": "evidence_photo",
+        "Back to desk": "desk_clue"
+      }
+    },
+    "hallway": {
+      "description": "The hallway is quiet, lit by flickering fluorescent lights. A security camera in the corner has a small red light - but you notice it's pointing at the wall, not the office door. Martinez approaches, his boots leaving muddy prints on the polished floor. His jaw is tight, eyes darting. 'Detective. Didn't expect you so soon.' His hand rests near his radio. Then he says something strange: 'Whatever they told you about me and Richardson - it's not the whole story. Elena's people got here first. I tried to warn him.' He looks genuinely scared.",
+      "choices": [
+        "What do you mean, Elena's people?",
+        "Check the security camera first",
+        "Examine his muddy boots",
+        "Ask about the warning",
+        "Return to office"
+      ],
+      "transitions": {
+        "What do you mean, Elena's people?": "elena_people",
+        "Check the security camera first": "camera_check",
+        "Examine his muddy boots": "boot_examination",
+        "Ask about the warning": "warning_details",
+        "Return to office": "crime_scene"
+      }
+    },
+    "camera_check": {
+      "description": "The camera has been manually rotated away from the office door. The adjustment screw is loose, recently turned - you can still see fresh scratches on the metal. Whoever did this knew exactly which camera to move. The timestamp log shows the adjustment happened at 11:42 PM. But here's the CRUCIAL DETAIL: there are TWO sets of scratches. Someone adjusted this camera TWICE. First at 11:42 PM, then again at 11:58 PM - after the incident. Someone came back to make sure it was still pointed away.",
+      "choices": [
+        "Check footage from other cameras",
+        "Who came back at 11:58?",
+        "Confront Martinez about timing",
+        "Back to hallway"
+      ],
+      "transitions": {
+        "Check footage from other cameras": "other_cameras",
+        "Who came back at 11:58?": "second_adjustment",
+        "Confront Martinez about timing": "timing_confrontation",
+        "Back to hallway": "hallway"
+      }
+    },
+    "guard_talk": {
+      "description": "'Evening, Detective.' Martinez's voice is steady but his hands aren't - they're shaking. His name tag reads 'Martinez, J.' His uniform is disheveled, with a small tear near his left sleeve. 'I heard nothing unusual tonight. Just doing my rounds.' He keeps glancing at his watch. It's 12:15 AM. Then he leans closer and whispers: 'The woman who came up at 11:35 - it wasn't Miranda. It was Elena. She was wearing Miranda's coat, but I recognized her perfume. Chanel No. 5. I didn't say anything because... her family...' He draws a finger across his throat.",
+      "choices": [
+        "Elena was HERE?",
+        "Tell me about her family",
+        "Why didn't you stop her?",
+        "You're lying to protect yourself"
+      ],
+      "transitions": {
+        "Elena was HERE?": "elena_presence",
+        "Tell me about her family": "family_connections",
+        "Why didn't you stop her?": "martinez_fear",
+        "You're lying to protect yourself": "martinez_defense"
+      }
+    },
+    "guard_pressed": {
+      "description": "'Look, I was on my rounds, okay?' Martinez's voice rises, then drops to a whisper. 'The 14th floor wasn't scheduled until midnight. But I went up early because Richardson texted me at 11:25 - said someone was coming, someone dangerous. When I got there at 11:40, I heard voices inside. A woman, screaming. Then silence. I... I hid. I'm not proud of it.' He shows you his phone - the text from Richardson reads: 'SHE FOUND OUT. Coming to office. Help me. Please.' Sent at 11:25 PM.",
+      "choices": [
+        "Who is 'she'?",
+        "Why did you hide?",
+        "Show me the rest of the texts",
+        "What happened after the silence?"
+      ],
+      "transitions": {
+        "Who is 'she'?": "she_identity",
+        "Why did you hide?": "hiding_reason",
+        "Show me the rest of the texts": "full_texts",
+        "What happened after the silence?": "aftermath"
+      }
+    },
+    "confrontation": {
+      "description": "Martinez breaks down completely. 'Fine! Yes, Richardson and I were together. For two years. But I didn't hurt him - I LOVED him.' Tears stream down his face. 'When I got to the office, he was already on the floor. The coffee cup was knocked over. A woman in Miranda's coat was climbing out the window - that's why there's fabric on the ledge. But the way she moved... it wasn't Miranda. It was Elena, I swear to God. She set this whole thing up to frame Miranda, frame me. She's been planning this for months.'",
+      "choices": [
+        "How do you know it was Elena?",
+        "Where is Richardson now?",
+        "What do you mean, planning for months?",
+        "You're under arrest"
+      ],
+      "transitions": {
+        "How do you know it was Elena?": "elena_identification",
+        "Where is Richardson now?": "richardson_fate",
+        "What do you mean, planning for months?": "long_con",
+        "You're under arrest": "arrest_martinez"
+      }
+    },
+    "photo_question": {
+      "description": "At the mention of the photo, Martinez's face changes from fear to realization. 'That photo... Elena found it last month. She came to me, showed it to me. Said she'd destroy both our careers unless I helped her.' He pulls out his phone, shows you a text thread. Elena Richardson: 'I know about you and my husband. Friday night. You will let me into the building after hours. You will turn off the camera. Or these photos go to HR, the board, and every news outlet in the city.' Dated three days ago.",
+      "choices": [
+        "She blackmailed you into helping",
+        "Did you know what she planned?",
+        "Why didn't you warn Richardson?",
+        "Show this to my captain"
+      ],
+      "transitions": {
+        "She blackmailed you into helping": "blackmail_reveal",
+        "Did you know what she planned?": "plan_knowledge",
+        "Why didn't you warn Richardson?": "warning_failure",
+        "Show this to my captain": "evidence_secured"
+      }
+    },
+    "accounts_info": {
+      "description": "'He was moving money - lots of it. Company funds to offshore accounts.' Martinez wipes his eyes. 'We were going to leave together, start fresh. But Elena found out about everything - the money AND us. She didn't just want a divorce. She wanted revenge.' He checks his watch nervously. 'Her family has connections to people who make problems disappear. The coffee, the staged break-in - this was a professional hit made to look like a crime of passion. And I...' His voice breaks. 'I let her in. God help me, I let her in.'",
+      "choices": [
+        "Where is Elena now?",
+        "The coffee was poisoned?",
+        "Who else helped her?",
+        "We need to find Richardson"
+      ],
+      "transitions": {
+        "Where is Elena now?": "elena_location",
+        "The coffee was poisoned?": "poison_confirmation",
+        "Who else helped her?": "accomplices",
+        "We need to find Richardson": "richardson_search"
+      }
+    },
+    "miranda_lead": {
+      "description": "You find Miranda Chen at her desk on the 12th floor, furiously packing a box. She freezes when she sees you. 'Detective! I was just... organizing.' Her coral lipstick is smeared, mascara running. 'I heard sirens. Is Mr. Richardson okay?' She's lying - her coat is hanging on the back of her chair, dry and clean. But someone wearing her coat was at the scene. On her desk, a resignation letter dated TODAY. She was planning to leave before any of this happened.",
+      "choices": [
+        "Where's your other coat, Miranda?",
+        "Who borrowed your coat tonight?",
+        "Why are you resigning?",
+        "Did you bring Richardson coffee tonight?"
+      ],
+      "transitions": {
+        "Where's your other coat, Miranda?": "coat_question",
+        "Who borrowed your coat tonight?": "coat_borrower",
+        "Why are you resigning?": "resignation_reason",
+        "Did you bring Richardson coffee tonight?": "coffee_denial"
+      }
+    },
+    "miranda_confession": {
+      "description": "'I didn't hurt him!' Miranda sobs. 'Yes, I brought him coffee at 11:40. Yes, I've been in love with him for three years. But when I got to his office, Elena was already there. She was wearing MY coat - must have taken it from my desk earlier. She told me to leave, that this was between her and her husband. I... I ran. I was scared.' She pulls out her phone. 'Look - I called 911 at 11:52 PM. Anonymously. That's how you got here so fast. I tried to help him, I swear.'",
+      "choices": [
+        "The 911 call - that was you?",
+        "What did you see Elena doing?",
+        "Why was she wearing your coat?",
+        "You're coming with me"
+      ],
+      "transitions": {
+        "The 911 call - that was you?": "911_confirmation",
+        "What did you see Elena doing?": "elena_actions",
+        "Why was she wearing your coat?": "coat_explanation",
+        "You're coming with me": "miranda_detained"
+      }
+    },
+    "miranda_coffee": {
+      "description": "'I always bring Mr. Richardson his evening coffee.' Miranda's hands shake as she grabs the edge of her desk. 'But tonight - tonight Elena intercepted me in the hallway. Took the cup right out of my hands. Said she wanted to make up with her husband, bring him coffee as a peace offering. I thought it was sweet.' Her face crumbles. 'Oh God. She put something in it, didn't she? She used MY cup, MY lipstick shade - she was setting me up from the start.'",
+      "choices": [
+        "Elena took the coffee from you?",
+        "She planned to frame you",
+        "What time was this?",
+        "I need you to come with me"
+      ],
+      "transitions": {
+        "Elena took the coffee from you?": "coffee_interception",
+        "She planned to frame you": "frame_job",
+        "What time was this?": "timeline_clarification",
+        "I need you to come with me": "miranda_witness"
+      }
+    },
+    "ink_analysis": {
+      "description": "Examining the letter under your UV light, the truth becomes clear. The original letter was written with Richardson's usual fountain pen - blue-black Montblanc ink. But the last line about Martinez was added with a cheap ballpoint, common office supply. Someone added that line to redirect suspicion toward Martinez and away from the real killer. The handwriting is close to Richardson's but not exact - slightly more angular. Elena Richardson is known for her perfect forgery skills; she handles all the household documents.",
+      "choices": [
+        "Elena forged this line",
+        "Test the ballpoint ink",
+        "Check security footage for document tampering",
+        "Continue investigating"
+      ],
+      "transitions": {
+        "Elena forged this line": "forgery_confirmed",
+        "Test the ballpoint ink": "ink_test",
+        "Check security footage for document tampering": "document_footage",
+        "Continue investigating": "crime_scene"
+      }
+    },
+    "final_confrontation": {
+      "description": "Your phone buzzes one final time: 'Elena Richardson just pulled into the parking garage. She's heading for the elevator.' You have minutes to make a decision. The evidence points to a calculated murder disguised as a crime of passion. Elena poisoned her husband's coffee, staged the break-in, framed Miranda and Martinez, and is about to walk into this building pretending to be the grieving widow. Martinez is willing to testify. Miranda is a witness. The forged letter and planted evidence tell the story. But Elena's family connections mean this case needs to be airtight.",
+      "choices": [
+        "Arrest Elena in the lobby",
+        "Gather more evidence first",
+        "Confront her in the office",
+        "Call for backup and wait"
+      ],
+      "transitions": {
+        "Arrest Elena in the lobby": "lobby_arrest",
+        "Gather more evidence first": "more_evidence",
+        "Confront her in the office": "office_confrontation",
+        "Call for backup and wait": "backup_ending"
+      }
+    },
+    "true_ending": {
+      "description": "As Elena Richardson steps off the elevator, her face a perfect mask of concern, you step forward with your badge. 'Mrs. Richardson. We have witnesses placing you at your husband's office at 11:35 PM, wearing Miranda Chen's coat. We have the forged addition to your husband's letter. We have your artificial sweetener in the poisoned coffee. And we have your blackmail texts to Jorge Martinez.' Her mask slips, just for a moment, revealing cold fury. 'You can't prove anything. My family will\u2014' 'Your family will read about this in tomorrow's paper,' you interrupt. 'Elena Richardson, you're under arrest for the murder of David Richardson.' As the cuffs click, Martinez finally stops shaking. Miranda stops crying. Sometimes, the truth finds a way through the lies.",
+      "choices": [
+        "Case closed"
+      ],
+      "transitions": {
+        "Case closed": "crime_scene"
+      }
+    }
+  }
+}

demo_mystery_starter.json

@@ -0,0 +1,81 @@
+{
+  "investigation": {
+    "crime_scene": {
+      "description": "A dimly lit office. Papers scattered everywhere. A broken window.",
+      "choices": [
+        "Examine the desk",
+        "Check the window",
+        "Leave"
+      ],
+      "transitions": {
+        "Examine the desk": "desk_clue",
+        "Check the window": "window_clue",
+        "Leave": "hallway"
+      }
+    },
+    "desk_clue": {
+      "description": "The desk has a half-written letter and an empty coffee cup.",
+      "choices": [
+        "Read the letter",
+        "Back to scene"
+      ],
+      "transitions": {
+        "Read the letter": "letter_reveal",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "window_clue": {
+      "description": "Glass shards on the inside. Someone broke in from outside.",
+      "choices": [
+        "Look outside",
+        "Back to scene"
+      ],
+      "transitions": {
+        "Look outside": "outside_view",
+        "Back to scene": "crime_scene"
+      }
+    },
+    "letter_reveal": {
+      "description": "The letter mentions a meeting tonight. It's unfinished.",
+      "choices": [
+        "Continue investigating"
+      ],
+      "transitions": {
+        "Continue investigating": "crime_scene"
+      }
+    },
+    "outside_view": {
+      "description": "Footprints in the mud lead toward the parking lot.",
+      "choices": [
+        "Follow the footprints",
+        "Back inside"
+      ],
+      "transitions": {
+        "Follow the footprints": "hallway",
+        "Back inside": "crime_scene"
+      }
+    },
+    "hallway": {
+      "description": "The hallway is quiet. A security guard approaches.",
+      "choices": [
+        "Talk to guard",
+        "Return to office"
+      ],
+      "transitions": {
+        "Talk to guard": "guard_talk",
+        "Return to office": "crime_scene"
+      }
+    },
+    "guard_talk": {
+      "description": "The guard says he heard nothing unusual tonight.",
+      "choices": [
+        "Press for details",
+        "Thank him and leave"
+      ],
+      "transitions": {
+        "Press for details": "guard_talk",
+        "Thank him and leave": "hallway"
+      }
+    }
+  }
+}

dnd_game_master_hfport/__init__.py

@@ -0,0 +1,34 @@
+"""
+D&D AI Game Master - Python Module for Hugging Face Integration
+
+A complete D&D 5e game master powered by Hugging Face language models.
+"""
+
+from .game_master import DnDGameMaster
+from .hf_integration import HuggingFaceGM, create_gm
+from .models.character import Character, create_blank_character, create_test_character
+from .models.scene import Scene, NPC, Lighting, TimeOfDay, NPCAttitude
+from .models.game_state import GameState, GamePhase, NarrativeEntry
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Main classes
+    "DnDGameMaster",
+    "HuggingFaceGM",
+    "create_gm",
+    # Character
+    "Character",
+    "create_blank_character",
+    "create_test_character",
+    # Scene
+    "Scene",
+    "NPC",
+    "Lighting",
+    "TimeOfDay",
+    "NPCAttitude",
+    # Game State
+    "GameState",
+    "GamePhase",
+    "NarrativeEntry",
+]

dnd_game_master_hfport/engine/__init__.py

@@ -0,0 +1,28 @@
+"""D&D 5e game engine - dice, checks, and modifiers."""
+
+from .dice import roll_dice, roll_d20, parse_dice_notation, DiceResult, RollMode
+from .checks import skill_check, attack_roll, CheckResult
+from .modifiers import (
+    get_ability_modifier,
+    get_proficiency_bonus,
+    get_skill_modifier,
+    SKILL_ABILITIES,
+)
+
+__all__ = [
+    # Dice
+    "roll_dice",
+    "roll_d20",
+    "parse_dice_notation",
+    "DiceResult",
+    "RollMode",
+    # Checks
+    "skill_check",
+    "attack_roll",
+    "CheckResult",
+    # Modifiers
+    "get_ability_modifier",
+    "get_proficiency_bonus",
+    "get_skill_modifier",
+    "SKILL_ABILITIES",
+]

dnd_game_master_hfport/engine/checks.py

@@ -0,0 +1,170 @@
+"""D&D 5e skill checks and attack rolls."""
+
+from dataclasses import dataclass
+from .dice import roll_d20, DiceResult, RollMode
+
+
+@dataclass
+class CheckResult:
+    """Result of a skill check or attack roll."""
+    roll: DiceResult
+    dc: int
+    success: bool
+    critical_success: bool
+    critical_failure: bool
+    margin: int  # How much above/below DC
+
+    def __str__(self) -> str:
+        result = "SUCCESS" if self.success else "FAILURE"
+        if self.critical_success:
+            result = "CRITICAL SUCCESS"
+        elif self.critical_failure:
+            result = "CRITICAL FAILURE"
+        return f"{self.roll} vs DC {self.dc}: {result} (margin: {self.margin:+d})"
+
+
+def skill_check(
+    modifier: int,
+    dc: int,
+    mode: RollMode = RollMode.NORMAL
+) -> CheckResult:
+    """
+    Perform a skill check against a DC.
+
+    Args:
+        modifier: Total skill modifier
+        dc: Difficulty Class to beat
+        mode: RollMode for advantage/disadvantage
+
+    Returns:
+        CheckResult with roll details and success/failure
+    """
+    roll = roll_d20(modifier, mode)
+
+    is_nat_20 = roll.natural_roll == 20
+    is_nat_1 = roll.natural_roll == 1
+
+    # In 5e, natural 20/1 on skill checks aren't auto-success/fail RAW,
+    # but many tables play that way. We'll use that common house rule.
+    success = roll.total >= dc or is_nat_20
+    if is_nat_1:
+        success = False
+
+    return CheckResult(
+        roll=roll,
+        dc=dc,
+        success=success,
+        critical_success=is_nat_20,
+        critical_failure=is_nat_1,
+        margin=roll.total - dc
+    )
+
+
+def attack_roll(
+    attack_bonus: int,
+    target_ac: int,
+    mode: RollMode = RollMode.NORMAL
+) -> CheckResult:
+    """
+    Perform an attack roll against AC.
+
+    Args:
+        attack_bonus: Total attack bonus
+        target_ac: Target's Armor Class
+        mode: RollMode for advantage/disadvantage
+
+    Returns:
+        CheckResult with roll details and hit/miss
+    """
+    roll = roll_d20(attack_bonus, mode)
+
+    is_nat_20 = roll.natural_roll == 20
+    is_nat_1 = roll.natural_roll == 1
+
+    # Natural 20 always hits, natural 1 always misses (RAW for attacks)
+    if is_nat_20:
+        success = True
+    elif is_nat_1:
+        success = False
+    else:
+        success = roll.total >= target_ac
+
+    return CheckResult(
+        roll=roll,
+        dc=target_ac,
+        success=success,
+        critical_success=is_nat_20,
+        critical_failure=is_nat_1,
+        margin=roll.total - target_ac
+    )
+
+
+def saving_throw(
+    modifier: int,
+    dc: int,
+    mode: RollMode = RollMode.NORMAL
+) -> CheckResult:
+    """
+    Perform a saving throw against a DC.
+
+    Args:
+        modifier: Total saving throw modifier
+        dc: Difficulty Class to beat
+        mode: RollMode for advantage/disadvantage
+
+    Returns:
+        CheckResult with roll details and success/failure
+    """
+    # Saving throws work like skill checks
+    return skill_check(modifier, dc, mode)
+
+
+def contested_check(
+    modifier1: int,
+    modifier2: int,
+    mode1: RollMode = RollMode.NORMAL,
+    mode2: RollMode = RollMode.NORMAL
+) -> tuple[CheckResult, CheckResult, int]:
+    """
+    Perform a contested check between two parties.
+
+    Args:
+        modifier1: First party's modifier
+        modifier2: Second party's modifier
+        mode1: First party's roll mode
+        mode2: Second party's roll mode
+
+    Returns:
+        Tuple of (party1_result, party2_result, winner)
+        winner: 1 if party1 wins, 2 if party2 wins, 0 if tie
+    """
+    roll1 = roll_d20(modifier1, mode1)
+    roll2 = roll_d20(modifier2, mode2)
+
+    # Use each other's total as the DC
+    result1 = CheckResult(
+        roll=roll1,
+        dc=roll2.total,
+        success=roll1.total >= roll2.total,
+        critical_success=roll1.natural_roll == 20,
+        critical_failure=roll1.natural_roll == 1,
+        margin=roll1.total - roll2.total
+    )
+
+    result2 = CheckResult(
+        roll=roll2,
+        dc=roll1.total,
+        success=roll2.total > roll1.total,  # Tie goes to party1
+        critical_success=roll2.natural_roll == 20,
+        critical_failure=roll2.natural_roll == 1,
+        margin=roll2.total - roll1.total
+    )
+
+    if roll1.total > roll2.total:
+        winner = 1
+    elif roll2.total > roll1.total:
+        winner = 2
+    else:
+        winner = 0  # Tie
+
+    return result1, result2, winner

dnd_game_master_hfport/engine/dice.py

@@ -0,0 +1,136 @@
+"""Dice rolling system for D&D 5e."""
+
+import random
+import re
+from dataclasses import dataclass
+from typing import List, Tuple
+from enum import Enum
+
+
+class RollMode(Enum):
+    """Roll modes for advantage/disadvantage."""
+    NORMAL = "normal"
+    ADVANTAGE = "advantage"
+    DISADVANTAGE = "disadvantage"
+
+
+@dataclass
+class DiceResult:
+    """Result of a dice roll."""
+    notation: str
+    rolls: List[int]
+    modifier: int
+    total: int
+    natural_roll: int  # For d20s, the die result before modifiers
+
+    def __str__(self) -> str:
+        rolls_str = ", ".join(str(r) for r in self.rolls)
+        if self.modifier >= 0:
+            return f"{self.notation}: [{rolls_str}] + {self.modifier} = {self.total}"
+        else:
+            return f"{self.notation}: [{rolls_str}] - {abs(self.modifier)} = {self.total}"
+
+
+def parse_dice_notation(notation: str) -> Tuple[int, int, int]:
+    """
+    Parse dice notation like '2d6+3' into (count, sides, modifier).
+
+    Args:
+        notation: Dice notation string (e.g., "2d6+3", "d20", "4d8-2")
+
+    Returns:
+        Tuple of (count, sides, modifier)
+
+    Raises:
+        ValueError: If notation is invalid
+    """
+    pattern = r'^(\d*)d(\d+)([+-]\d+)?$'
+    match = re.match(pattern, notation.lower().strip())
+
+    if not match:
+        raise ValueError(f"Invalid dice notation: {notation}")
+
+    count = int(match.group(1)) if match.group(1) else 1
+    sides = int(match.group(2))
+    modifier = int(match.group(3)) if match.group(3) else 0
+
+    return count, sides, modifier
+
+
+def roll_dice(notation: str, mode: RollMode = RollMode.NORMAL) -> DiceResult:
+    """
+    Roll dice with optional advantage/disadvantage.
+
+    Args:
+        notation: Dice notation string (e.g., "2d6+3")
+        mode: RollMode for advantage/disadvantage
+
+    Returns:
+        DiceResult with roll details
+    """
+    count, sides, modifier = parse_dice_notation(notation)
+
+    if mode == RollMode.NORMAL:
+        rolls = [random.randint(1, sides) for _ in range(count)]
+        natural = sum(rolls)
+    elif mode == RollMode.ADVANTAGE:
+        roll1 = [random.randint(1, sides) for _ in range(count)]
+        roll2 = [random.randint(1, sides) for _ in range(count)]
+        if sum(roll1) >= sum(roll2):
+            rolls = roll1
+        else:
+            rolls = roll2
+        natural = sum(rolls)
+    else:  # DISADVANTAGE
+        roll1 = [random.randint(1, sides) for _ in range(count)]
+        roll2 = [random.randint(1, sides) for _ in range(count)]
+        if sum(roll1) <= sum(roll2):
+            rolls = roll1
+        else:
+            rolls = roll2
+        natural = sum(rolls)
+
+    return DiceResult(
+        notation=notation,
+        rolls=rolls,
+        modifier=modifier,
+        total=sum(rolls) + modifier,
+        natural_roll=natural
+    )
+
+
+def roll_d20(modifier: int = 0, mode: RollMode = RollMode.NORMAL) -> DiceResult:
+    """
+    Convenience function for d20 rolls.
+
+    Args:
+        modifier: Modifier to add to the roll
+        mode: RollMode for advantage/disadvantage
+
+    Returns:
+        DiceResult with roll details
+    """
+    result = roll_dice("1d20", mode)
+    result.modifier = modifier
+    result.total = result.natural_roll + modifier
+    return result
+
+
+def roll_damage(notation: str, critical: bool = False) -> DiceResult:
+    """
+    Roll damage dice, doubling on critical hits.
+
+    Args:
+        notation: Damage dice notation (e.g., "2d6+3")
+        critical: If True, double the dice (not modifier)
+
+    Returns:
+        DiceResult with damage details
+    """
+    count, sides, modifier = parse_dice_notation(notation)
+
+    if critical:
+        count *= 2
+        notation = f"{count}d{sides}{'+' if modifier >= 0 else ''}{modifier}"
+
+    return roll_dice(notation)

dnd_game_master_hfport/engine/modifiers.py

@@ -0,0 +1,168 @@
+"""D&D 5e ability modifiers and proficiency calculations."""
+
+from typing import Dict
+
+# Skill to ability mapping (D&D 5e)
+SKILL_ABILITIES: Dict[str, str] = {
+    "acrobatics": "dexterity",
+    "animal_handling": "wisdom",
+    "arcana": "intelligence",
+    "athletics": "strength",
+    "deception": "charisma",
+    "history": "intelligence",
+    "insight": "wisdom",
+    "intimidation": "charisma",
+    "investigation": "intelligence",
+    "medicine": "wisdom",
+    "nature": "intelligence",
+    "perception": "wisdom",
+    "performance": "charisma",
+    "persuasion": "charisma",
+    "religion": "intelligence",
+    "sleight_of_hand": "dexterity",
+    "stealth": "dexterity",
+    "survival": "wisdom",
+}
+
+# Alternate names mapping
+SKILL_ALIASES: Dict[str, str] = {
+    "animal handling": "animal_handling",
+    "sleight of hand": "sleight_of_hand",
+}
+
+
+def normalize_skill_name(skill: str) -> str:
+    """Normalize skill name to standard format."""
+    normalized = skill.lower().strip()
+    return SKILL_ALIASES.get(normalized, normalized.replace(" ", "_"))
+
+
+def get_ability_modifier(score: int) -> int:
+    """
+    Calculate ability modifier from ability score.
+
+    Args:
+        score: Ability score (typically 1-30)
+
+    Returns:
+        Ability modifier (score - 10) // 2
+    """
+    return (score - 10) // 2
+
+
+def get_proficiency_bonus(level: int) -> int:
+    """
+    Get proficiency bonus based on character level.
+
+    Args:
+        level: Character level (1-20)
+
+    Returns:
+        Proficiency bonus (2-6)
+    """
+    if level < 1:
+        return 2
+    return 2 + (level - 1) // 4
+
+
+def get_skill_modifier(
+    ability_scores: Dict[str, int],
+    skill: str,
+    level: int,
+    is_proficient: bool = False,
+    has_expertise: bool = False
+) -> int:
+    """
+    Calculate total skill check modifier.
+
+    Args:
+        ability_scores: Dict mapping ability names to scores
+        skill: Skill name (e.g., "stealth", "perception")
+        level: Character level
+        is_proficient: Whether character is proficient in this skill
+        has_expertise: Whether character has expertise (double proficiency)
+
+    Returns:
+        Total modifier for skill checks
+    """
+    normalized_skill = normalize_skill_name(skill)
+    ability = SKILL_ABILITIES.get(normalized_skill, "strength")
+    base_mod = get_ability_modifier(ability_scores.get(ability, 10))
+
+    if has_expertise:
+        return base_mod + (get_proficiency_bonus(level) * 2)
+    elif is_proficient:
+        return base_mod + get_proficiency_bonus(level)
+    return base_mod
+
+
+def get_saving_throw_modifier(
+    ability_scores: Dict[str, int],
+    ability: str,
+    level: int,
+    is_proficient: bool = False
+) -> int:
+    """
+    Calculate saving throw modifier.
+
+    Args:
+        ability_scores: Dict mapping ability names to scores
+        ability: Ability name (e.g., "dexterity", "wisdom")
+        level: Character level
+        is_proficient: Whether character is proficient in this save
+
+    Returns:
+        Total modifier for saving throws
+    """
+    base_mod = get_ability_modifier(ability_scores.get(ability.lower(), 10))
+
+    if is_proficient:
+        return base_mod + get_proficiency_bonus(level)
+    return base_mod
+
+
+def get_attack_bonus(
+    ability_scores: Dict[str, int],
+    ability: str,
+    level: int,
+    is_proficient: bool = True
+) -> int:
+    """
+    Calculate attack bonus.
+
+    Args:
+        ability_scores: Dict mapping ability names to scores
+        ability: Ability used for attack (usually "strength" or "dexterity")
+        level: Character level
+        is_proficient: Whether character is proficient with the weapon
+
+    Returns:
+        Attack bonus
+    """
+    base_mod = get_ability_modifier(ability_scores.get(ability.lower(), 10))
+
+    if is_proficient:
+        return base_mod + get_proficiency_bonus(level)
+    return base_mod
+
+
+def get_spell_save_dc(
+    ability_scores: Dict[str, int],
+    spellcasting_ability: str,
+    level: int
+) -> int:
+    """
+    Calculate spell save DC.
+
+    Args:
+        ability_scores: Dict mapping ability names to scores
+        spellcasting_ability: The spellcasting ability (e.g., "intelligence")
+        level: Character level
+
+    Returns:
+        Spell save DC (8 + proficiency + ability modifier)
+    """
+    ability_mod = get_ability_modifier(
+        ability_scores.get(spellcasting_ability.lower(), 10)
+    )
+    return 8 + get_proficiency_bonus(level) + ability_mod

dnd_game_master_hfport/example.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""
+Example usage of the D&D AI Game Master module.
+
+Run with:
+    python -m dnd_game_master.example
+
+Or:
+    python example.py
+"""
+
+import os
+from dnd_game_master import (
+    DnDGameMaster,
+    Character,
+    Scene,
+    create_test_character,
+)
+from dnd_game_master.models.scene import (
+    Lighting,
+    TimeOfDay,
+    NPC,
+    NPCAttitude,
+    create_tavern_scene,
+)
+from dnd_game_master.game_master import run_game_loop
+
+
+def main():
+    """Run the D&D Game Master example."""
+
+    # Get API token from environment or prompt
+    api_token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGINGFACE_TOKEN")
+
+    if not api_token:
+        print("=" * 60)
+        print("D&D AI Game Master - Setup")
+        print("=" * 60)
+        print("\nNo HF_TOKEN environment variable found.")
+        print("Get your free token at: https://huggingface.co/settings/tokens")
+        api_token = input("\nEnter your Hugging Face API token: ").strip()
+
+        if not api_token:
+            print("\nNo token provided. Exiting.")
+            return
+
+    print("\nInitializing Game Master...")
+
+    # Create the Game Master with Hugging Face
+    gm = DnDGameMaster(
+        model_id="mistralai/Mistral-7B-Instruct-v0.3",
+        api_token=api_token,
+        use_local_model=False,  # Set True to load model locally
+    )
+
+    # Use test character or create custom one
+    print("\nWould you like to:")
+    print("1. Use the pre-made character (Kira the Rogue)")
+    print("2. Create a quick custom character")
+
+    choice = input("\nChoice (1/2): ").strip()
+
+    if choice == "2":
+        name = input("Character name: ").strip() or "Adventurer"
+        print("\nClasses: Fighter, Rogue, Wizard, Cleric, Ranger, Paladin")
+        char_class = input("Class: ").strip() or "Fighter"
+        print("\nRaces: Human, Elf, Dwarf, Halfling, Half-Elf, Tiefling")
+        race = input("Race: ").strip() or "Human"
+
+        character = Character(
+            name=name,
+            race=race,
+            character_class=char_class,
+            level=3,
+            strength=14,
+            dexterity=14,
+            constitution=14,
+            intelligence=12,
+            wisdom=12,
+            charisma=12,
+            max_hp=25,
+            current_hp=25,
+            armor_class=15,
+            proficient_skills=["perception", "athletics", "intimidation"],
+        )
+    else:
+        character = create_test_character()
+
+    # Create starting scene
+    scene = create_tavern_scene()
+
+    # Run the game loop
+    run_game_loop(
+        gm=gm,
+        character=character,
+        scene=scene,
+        adventure_name="The Dusty Tankard Mystery",
+    )
+
+
+def quick_demo():
+    """Run a quick non-interactive demo."""
+
+    api_token = os.environ.get("HF_TOKEN")
+    if not api_token:
+        print("Set HF_TOKEN environment variable to run demo")
+        return
+
+    print("Initializing Game Master...")
+    gm = DnDGameMaster(api_token=api_token)
+
+    character = create_test_character()
+    scene = create_tavern_scene()
+
+    gm.start_adventure(character, scene, "Demo Adventure")
+
+    # Simulate a few actions
+    actions = [
+        "I look around the tavern, trying to spot anything unusual.",
+        "I approach the hooded stranger in the corner.",
+        "I try to pickpocket the stranger.",
+    ]
+
+    for action in actions:
+        print(f"\n> {action}")
+        result = gm.process_player_action(action)
+
+        if result["type"] == "needs_roll":
+            print(f"\n{result['narration']}")
+            print(f"[Rolling {result['skill']} DC {result['dc']}...]")
+
+            roll_result = gm.execute_roll()
+            roll = roll_result["roll"]
+            print(f"Rolled: {roll['natural']} + {roll['modifier']} = {roll['total']}")
+            print(f"Result: {'Success!' if roll_result['success'] else 'Failure...'}")
+            print(f"\n{roll_result['narration']}")
+        else:
+            print(f"\n{result['narration']}")
+
+        print("-" * 40)
+
+
+if __name__ == "__main__":
+    import sys
+
+    if "--demo" in sys.argv:
+        quick_demo()
+    else:
+        main()

dnd_game_master_hfport/game_master.py

@@ -0,0 +1,462 @@
+"""Main D&D Game Master orchestrator."""
+
+from typing import Optional, Dict, Any, List
+from .hf_integration import HuggingFaceGM, create_gm
+from .models.character import Character, create_blank_character
+from .models.scene import Scene, Lighting, TimeOfDay
+from .models.game_state import GameState, GamePhase
+from .engine.dice import roll_d20, roll_dice, RollMode
+from .engine.checks import skill_check, attack_roll
+from .engine.modifiers import get_skill_modifier, get_ability_modifier
+from .prompts.gm_prompts import (
+    build_gm_system_prompt,
+    build_scene_context,
+    build_roll_outcome_prompt,
+    build_scene_extraction_prompt,
+)
+
+
+class DnDGameMaster:
+    """
+    Main Game Master class that orchestrates the D&D experience.
+
+    Integrates Hugging Face models for narrative generation with
+    D&D 5e game mechanics.
+
+    Example:
+        >>> gm = DnDGameMaster(api_token="hf_...")
+        >>> gm.start_adventure(character, scene)
+        >>> result = gm.process_player_action("I search the room")
+        >>> if result["type"] == "needs_roll":
+        ...     roll_result = gm.execute_roll()
+    """
+
+    def __init__(
+        self,
+        model_id: str = "mistralai/Mistral-7B-Instruct-v0.3",
+        api_token: Optional[str] = None,
+        use_local_model: bool = False,
+        device: str = "auto",
+    ):
+        """
+        Initialize the D&D Game Master.
+
+        Args:
+            model_id: Hugging Face model to use for narrative generation
+            api_token: HF API token (or set HF_TOKEN environment variable)
+            use_local_model: If True, load model locally instead of using API
+            device: Device for local inference ("auto", "cuda", "cpu", "mps")
+        """
+        self.gm = create_gm(
+            model_id=model_id,
+            api_token=api_token,
+            local=use_local_model,
+            device=device,
+        )
+        self.state = GameState()
+        self.system_prompt = build_gm_system_prompt()
+        self.pending_roll: Optional[Dict[str, Any]] = None
+
+    def set_character(self, character: Character):
+        """Set the active player character."""
+        self.state.character = character
+        self.state.phase = GamePhase.PLAYING
+
+    def set_scene(self, scene: Scene):
+        """Set the current scene."""
+        self.state.scene = scene
+        self.state.add_narrative("scene", scene.description)
+
+    def start_adventure(
+        self,
+        character: Character,
+        scene: Scene,
+        adventure_name: str = "",
+    ):
+        """
+        Begin a new adventure.
+
+        Args:
+            character: The player character
+            scene: The starting scene
+            adventure_name: Optional name for the adventure
+        """
+        self.state.start_adventure(character, scene, adventure_name)
+        self.pending_roll = None
+        print(f"\n{'='*60}")
+        print(f"Adventure: {adventure_name or 'A New Journey'}")
+        print(f"Character: {character.name}, {character.race} {character.character_class}")
+        print(f"{'='*60}")
+        print(f"\n{scene.description}\n")
+
+    def process_player_action(self, action: str) -> Dict[str, Any]:
+        """
+        Process a player's described action.
+
+        Args:
+            action: What the player wants to do (natural language)
+
+        Returns:
+            Dict with:
+            - type: "impossible" | "auto_success" | "auto_fail" | "needs_roll"
+            - narration: The narrative response
+            - skill: (if needs_roll) Skill to check
+            - dc: (if needs_roll) Difficulty class
+            - advantage/disadvantage: (if needs_roll) Roll mode
+            - suggestions: (if impossible) Alternative actions
+        """
+        if not self.state.character or not self.state.scene:
+            return {
+                "type": "error",
+                "narration": "No active character or scene. Use start_adventure() first.",
+            }
+
+        # Build context for the LLM
+        context = build_scene_context(self.state.character, self.state.scene)
+
+        # Get GM decision
+        decision = self.gm.get_gm_decision(
+            player_action=action,
+            system_prompt=self.system_prompt,
+            context=context,
+            conversation_history=self.state.get_recent_messages(),
+        )
+
+        # Log the interaction
+        self.state.add_message("user", action)
+        self.state.add_narrative("player", action)
+
+        # Handle based on decision type
+        decision_type = decision.get("decision", "auto_success")
+        narration = decision.get("narration", "")
+
+        if decision_type == "needs_roll":
+            # Store pending roll info
+            self.pending_roll = {
+                "action": action,
+                "skill": decision.get("skill", "perception"),
+                "dc": decision.get("dc", 15),
+                "advantage": decision.get("advantage", False),
+                "disadvantage": decision.get("disadvantage", False),
+            }
+
+            self.state.add_narrative(
+                "roll_request",
+                f"Roll {self.pending_roll['skill'].title()} (DC {self.pending_roll['dc']})",
+                skill=self.pending_roll["skill"],
+                dc=self.pending_roll["dc"],
+            )
+
+            return {
+                "type": "needs_roll",
+                "skill": self.pending_roll["skill"],
+                "dc": self.pending_roll["dc"],
+                "advantage": self.pending_roll["advantage"],
+                "disadvantage": self.pending_roll["disadvantage"],
+                "narration": narration,
+            }
+
+        # Auto-resolved (success, fail, or impossible)
+        self.state.add_message("assistant", narration)
+        self.state.add_narrative("gm_response", narration)
+
+        result = {
+            "type": decision_type,
+            "narration": narration,
+        }
+
+        if decision_type == "impossible":
+            result["suggestions"] = decision.get("suggestions", [])
+            result["reason"] = decision.get("reason", "")
+
+        return result
+
+    def execute_roll(self, manual_roll: Optional[int] = None) -> Dict[str, Any]:
+        """
+        Execute a pending skill check roll.
+
+        Args:
+            manual_roll: Optional manual d20 result (for physical dice)
+
+        Returns:
+            Dict with:
+            - roll: Roll details (natural, modifier, total, dc)
+            - success: Whether the check succeeded
+            - critical_success/critical_failure: If natural 20/1
+            - narration: Outcome narration
+        """
+        if not self.pending_roll:
+            return {"error": "No pending roll to execute"}
+
+        roll_info = self.pending_roll
+        character = self.state.character
+
+        # Calculate modifier
+        modifier = get_skill_modifier(
+            ability_scores=character.get_ability_scores(),
+            skill=roll_info["skill"],
+            level=character.level,
+            is_proficient=character.is_proficient(roll_info["skill"]),
+            has_expertise=character.has_expertise(roll_info["skill"]),
+        )
+
+        # Determine roll mode
+        mode = RollMode.NORMAL
+        if roll_info["advantage"]:
+            mode = RollMode.ADVANTAGE
+        elif roll_info["disadvantage"]:
+            mode = RollMode.DISADVANTAGE
+
+        # Roll the dice
+        if manual_roll is not None:
+            # Use manual roll
+            natural = manual_roll
+            total = natural + modifier
+            success = total >= roll_info["dc"] or natural == 20
+            if natural == 1:
+                success = False
+            critical_success = natural == 20
+            critical_failure = natural == 1
+        else:
+            # Automatic roll
+            result = skill_check(modifier, roll_info["dc"], mode)
+            natural = result.roll.natural_roll
+            total = result.roll.total
+            success = result.success
+            critical_success = result.critical_success
+            critical_failure = result.critical_failure
+
+        # Build outcome prompt
+        outcome_prompt = build_roll_outcome_prompt(
+            action=roll_info["action"],
+            skill=roll_info["skill"],
+            roll_total=total,
+            dc=roll_info["dc"],
+            success=success,
+            critical=critical_success or critical_failure,
+            natural_roll=natural,
+        )
+
+        # Get outcome narration from LLM
+        outcome = self.gm.narrate_outcome(outcome_prompt, self.system_prompt)
+        narration = outcome.get("narration", "The action resolves...")
+
+        # Log the roll and outcome
+        roll_summary = (
+            f"{roll_info['skill'].title()}: {natural} + {modifier} = {total} "
+            f"vs DC {roll_info['dc']} - {'SUCCESS' if success else 'FAILURE'}"
+        )
+        self.state.add_narrative("roll", roll_summary)
+        self.state.add_narrative("gm_response", narration)
+        self.state.add_message("assistant", narration)
+
+        # Check for location change
+        if outcome.get("location_changed"):
+            new_location = outcome.get("new_location", "Unknown")
+            new_description = outcome.get("new_description", "")
+            self.state.scene.location = new_location
+            self.state.scene.description = new_description
+
+        # Clear pending roll
+        self.pending_roll = None
+
+        return {
+            "roll": {
+                "natural": natural,
+                "modifier": modifier,
+                "total": total,
+                "dc": roll_info["dc"],
+                "skill": roll_info["skill"],
+            },
+            "success": success,
+            "critical_success": critical_success,
+            "critical_failure": critical_failure,
+            "margin": total - roll_info["dc"],
+            "narration": narration,
+        }
+
+    def quick_roll(self, skill: str, dc: int) -> Dict[str, Any]:
+        """
+        Perform a quick skill check without LLM narration.
+
+        Args:
+            skill: Skill name
+            dc: Difficulty class
+
+        Returns:
+            Roll result dictionary
+        """
+        if not self.state.character:
+            return {"error": "No active character"}
+
+        modifier = get_skill_modifier(
+            ability_scores=self.state.character.get_ability_scores(),
+            skill=skill,
+            level=self.state.character.level,
+            is_proficient=self.state.character.is_proficient(skill),
+            has_expertise=self.state.character.has_expertise(skill),
+        )
+
+        result = skill_check(modifier, dc)
+
+        return {
+            "roll": {
+                "natural": result.roll.natural_roll,
+                "modifier": modifier,
+                "total": result.roll.total,
+                "dc": dc,
+                "skill": skill,
+            },
+            "success": result.success,
+            "critical_success": result.critical_success,
+            "critical_failure": result.critical_failure,
+            "margin": result.margin,
+        }
+
+    def roll_initiative(self) -> Dict[str, Any]:
+        """Roll initiative for the current character."""
+        if not self.state.character:
+            return {"error": "No active character"}
+
+        dex_mod = get_ability_modifier(self.state.character.dexterity)
+        init_bonus = dex_mod + self.state.character.initiative_bonus
+
+        roll = roll_d20(init_bonus)
+
+        return {
+            "natural": roll.natural_roll,
+            "modifier": init_bonus,
+            "total": roll.total,
+        }
+
+    def roll_damage(self, notation: str, critical: bool = False) -> Dict[str, Any]:
+        """
+        Roll damage dice.
+
+        Args:
+            notation: Dice notation (e.g., "2d6+3")
+            critical: If True, double the dice
+
+        Returns:
+            Damage roll result
+        """
+        from .engine.dice import roll_damage
+        result = roll_damage(notation, critical)
+
+        return {
+            "notation": notation,
+            "rolls": result.rolls,
+            "modifier": result.modifier,
+            "total": result.total,
+            "critical": critical,
+        }
+
+    def get_narrative_history(self, max_entries: int = 50) -> str:
+        """Get formatted narrative history."""
+        return self.state.get_recent_context(max_entries)
+
+    def get_character_summary(self) -> str:
+        """Get current character summary."""
+        if not self.state.character:
+            return "No active character"
+        return self.state.character.summary()
+
+    def get_scene_summary(self) -> str:
+        """Get current scene summary."""
+        if not self.state.scene:
+            return "No active scene"
+        return self.state.scene.to_context_string()
+
+    def save_game(self, filepath: str):
+        """Save current game state to file."""
+        self.state.save_to_file(filepath)
+        print(f"Game saved to {filepath}")
+
+    def load_game(self, filepath: str):
+        """Load game state from file."""
+        self.state = GameState.load_from_file(filepath)
+        print(f"Game loaded from {filepath}")
+        print(f"Character: {self.state.character.name if self.state.character else 'None'}")
+        print(f"Location: {self.state.scene.location if self.state.scene else 'None'}")
+
+
+def run_game_loop(
+    gm: DnDGameMaster,
+    character: Character,
+    scene: Scene,
+    adventure_name: str = "Adventure",
+):
+    """
+    Run an interactive game loop in the terminal.
+
+    Args:
+        gm: Initialized DnDGameMaster
+        character: Player character
+        scene: Starting scene
+        adventure_name: Name of the adventure
+    """
+    gm.start_adventure(character, scene, adventure_name)
+
+    print("\nCommands: 'quit' to exit, 'stats' for character, 'look' for scene")
+    print("-" * 60)
+
+    while True:
+        try:
+            action = input("\n> What do you do? ").strip()
+        except (KeyboardInterrupt, EOFError):
+            print("\n\nFarewell, adventurer!")
+            break
+
+        if not action:
+            continue
+
+        if action.lower() in ['quit', 'exit', 'q']:
+            print("\nFarewell, adventurer!")
+            break
+
+        if action.lower() == 'stats':
+            print(f"\n{gm.get_character_summary()}")
+            continue
+
+        if action.lower() in ['look', 'scene']:
+            print(f"\n{gm.get_scene_summary()}")
+            continue
+
+        if action.lower() == 'save':
+            gm.save_game("savegame.json")
+            continue
+
+        # Process the action
+        result = gm.process_player_action(action)
+
+        if result.get("type") == "needs_roll":
+            print(f"\n{result.get('narration', '')}")
+            print(f"\n>>> Roll {result['skill'].title()} (DC {result['dc']})")
+
+            input("Press Enter to roll...")
+
+            roll_result = gm.execute_roll()
+            roll = roll_result["roll"]
+
+            print(f"\n[{roll['natural']}] + {roll['modifier']} = {roll['total']} vs DC {roll['dc']}")
+
+            if roll_result["critical_success"]:
+                print("*** CRITICAL SUCCESS! ***")
+            elif roll_result["critical_failure"]:
+                print("*** CRITICAL FAILURE! ***")
+            elif roll_result["success"]:
+                print("Success!")
+            else:
+                print("Failure...")
+
+            print(f"\n{roll_result['narration']}")
+
+        elif result.get("type") == "impossible":
+            print(f"\n{result.get('narration', 'That is not possible.')}")
+            if result.get("suggestions"):
+                print("\nYou might try:")
+                for s in result["suggestions"]:
+                    print(f"  - {s}")
+
+        else:
+            print(f"\n{result.get('narration', '')}")

dnd_game_master_hfport/gradio_app.py

@@ -0,0 +1,289 @@
+#!/usr/bin/env python3
+"""
+Gradio web interface for D&D AI Game Master.
+
+For Hugging Face Spaces deployment or local web interface.
+
+Run with:
+    python -m dnd_game_master.gradio_app
+
+Or deploy to Hugging Face Spaces.
+"""
+
+import os
+
+try:
+    import gradio as gr
+    HAS_GRADIO = True
+except ImportError:
+    HAS_GRADIO = False
+    print("Gradio not installed. Install with: pip install gradio")
+
+from dnd_game_master import DnDGameMaster, Character, Scene
+from dnd_game_master.models.scene import Lighting, TimeOfDay, NPC, NPCAttitude
+
+
+# Global game instance
+game_instance = None
+
+
+def initialize_game(
+    character_name: str,
+    character_class: str,
+    character_race: str,
+    api_token: str,
+) -> str:
+    """Initialize a new game session."""
+    global game_instance
+
+    if not api_token:
+        return "Please provide a Hugging Face API token."
+
+    try:
+        # Create character
+        character = Character(
+            name=character_name or "Adventurer",
+            race=character_race or "Human",
+            character_class=character_class or "Fighter",
+            level=1,
+            strength=14,
+            dexterity=14,
+            constitution=14,
+            intelligence=12,
+            wisdom=12,
+            charisma=12,
+            max_hp=12,
+            current_hp=12,
+            armor_class=14,
+            proficient_skills=["perception", "athletics"],
+        )
+
+        # Create starting scene
+        scene = Scene(
+            location="The Dusty Tankard Tavern",
+            description=(
+                "You push open the weathered oak door and step into the warmth of "
+                "The Dusty Tankard. The tavern is dimly lit by flickering candles and "
+                "a crackling fireplace. The smell of ale and roasted meat fills the air. "
+                "A few patrons sit at scattered tables, speaking in hushed tones. "
+                "Behind the bar, a stern-faced woman polishes a mug, her eyes following you."
+            ),
+            lighting=Lighting.DIM,
+            time_of_day=TimeOfDay.EVENING,
+            npcs=[
+                NPC("Mira the Bartender", "A stern woman with knowing eyes", NPCAttitude.NEUTRAL),
+                NPC("Hooded Stranger", "Sits alone in the corner, face hidden", NPCAttitude.UNFRIENDLY),
+            ],
+            objects=["Notice board", "Crackling fireplace", "Locked cellar door"],
+        )
+
+        # Initialize game master
+        game_instance = DnDGameMaster(api_token=api_token)
+        game_instance.start_adventure(character, scene, "The Dusty Tankard Mystery")
+
+        return f"""Adventure Started!
+
+You are {character.name}, a {character.race} {character.character_class}.
+
+---
+
+{scene.description}
+
+---
+
+What do you do?"""
+
+    except Exception as e:
+        return f"Error initializing game: {str(e)}"
+
+
+def process_action(action: str, history: list) -> tuple:
+    """Process a player action and return the response."""
+    global game_instance
+
+    if not game_instance:
+        return history + [[action, "Please initialize the game first!"]], ""
+
+    if not action.strip():
+        return history, ""
+
+    try:
+        result = game_instance.process_player_action(action)
+
+        if result.get("type") == "needs_roll":
+            # Auto-execute the roll
+            narration = result.get("narration", "")
+            roll_result = game_instance.execute_roll()
+
+            roll = roll_result["roll"]
+            roll_text = f"[{roll['natural']}] + {roll['modifier']} = {roll['total']} vs DC {roll['dc']}"
+
+            if roll_result["critical_success"]:
+                roll_text += " - CRITICAL SUCCESS!"
+            elif roll_result["critical_failure"]:
+                roll_text += " - CRITICAL FAILURE!"
+            elif roll_result["success"]:
+                roll_text += " - Success!"
+            else:
+                roll_text += " - Failure..."
+
+            response = f"{narration}\n\n**Roll {result['skill'].title()}:** {roll_text}\n\n{roll_result['narration']}"
+
+        elif result.get("type") == "impossible":
+            response = result.get("narration", "That is not possible.")
+            if result.get("suggestions"):
+                response += "\n\n**You might try:**\n"
+                for s in result["suggestions"]:
+                    response += f"- {s}\n"
+        else:
+            response = result.get("narration", "...")
+
+        return history + [[action, response]], ""
+
+    except Exception as e:
+        return history + [[action, f"Error: {str(e)}"]], ""
+
+
+def get_character_info() -> str:
+    """Get current character information."""
+    global game_instance
+    if not game_instance or not game_instance.state.character:
+        return "No active character"
+    return game_instance.get_character_summary()
+
+
+def get_scene_info() -> str:
+    """Get current scene information."""
+    global game_instance
+    if not game_instance or not game_instance.state.scene:
+        return "No active scene"
+    return game_instance.get_scene_summary()
+
+
+def create_interface():
+    """Create the Gradio interface."""
+
+    with gr.Blocks(title="D&D AI Game Master", theme=gr.themes.Soft()) as demo:
+        gr.Markdown("""
+        # D&D AI Game Master
+
+        An AI-powered Dungeons & Dragons Game Master using Hugging Face models.
+
+        ---
+        """)
+
+        with gr.Tab("Setup"):
+            gr.Markdown("### Character Creation")
+
+            with gr.Row():
+                name_input = gr.Textbox(
+                    label="Character Name",
+                    placeholder="Enter your character's name",
+                    value="Adventurer"
+                )
+                class_input = gr.Dropdown(
+                    choices=["Fighter", "Rogue", "Wizard", "Cleric", "Ranger", "Paladin", "Bard"],
+                    label="Class",
+                    value="Fighter"
+                )
+                race_input = gr.Dropdown(
+                    choices=["Human", "Elf", "Dwarf", "Halfling", "Half-Elf", "Tiefling", "Dragonborn"],
+                    label="Race",
+                    value="Human"
+                )
+
+            token_input = gr.Textbox(
+                label="Hugging Face API Token",
+                placeholder="hf_...",
+                type="password",
+                info="Get your free token at huggingface.co/settings/tokens"
+            )
+
+            start_btn = gr.Button("Start Adventure", variant="primary")
+            setup_output = gr.Markdown()
+
+            start_btn.click(
+                initialize_game,
+                inputs=[name_input, class_input, race_input, token_input],
+                outputs=setup_output
+            )
+
+        with gr.Tab("Play"):
+            chatbot = gr.Chatbot(
+                label="Adventure",
+                height=400,
+                show_copy_button=True,
+            )
+
+            with gr.Row():
+                action_input = gr.Textbox(
+                    label="What do you do?",
+                    placeholder="Describe your action...",
+                    scale=4
+                )
+                submit_btn = gr.Button("Submit", variant="primary", scale=1)
+
+            submit_btn.click(
+                process_action,
+                inputs=[action_input, chatbot],
+                outputs=[chatbot, action_input]
+            )
+            action_input.submit(
+                process_action,
+                inputs=[action_input, chatbot],
+                outputs=[chatbot, action_input]
+            )
+
+        with gr.Tab("Status"):
+            with gr.Row():
+                with gr.Column():
+                    gr.Markdown("### Character")
+                    char_info = gr.Textbox(
+                        label="Character Stats",
+                        lines=6,
+                        interactive=False
+                    )
+                    refresh_char_btn = gr.Button("Refresh")
+                    refresh_char_btn.click(get_character_info, outputs=char_info)
+
+                with gr.Column():
+                    gr.Markdown("### Current Scene")
+                    scene_info = gr.Textbox(
+                        label="Scene Details",
+                        lines=6,
+                        interactive=False
+                    )
+                    refresh_scene_btn = gr.Button("Refresh")
+                    refresh_scene_btn.click(get_scene_info, outputs=scene_info)
+
+        gr.Markdown("""
+        ---
+        **Tips:**
+        - Describe your actions naturally: "I search the room for hidden doors"
+        - The GM will decide if you need to roll dice
+        - Use the Status tab to check your character and surroundings
+        """)
+
+    return demo
+
+
+def main():
+    """Launch the Gradio app."""
+    if not HAS_GRADIO:
+        print("Please install gradio: pip install gradio")
+        return
+
+    demo = create_interface()
+
+    # Get port from environment (for Spaces) or use default
+    port = int(os.environ.get("PORT", 7860))
+
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=port,
+        share=False,  # Set True for public link
+    )
+
+
+if __name__ == "__main__":
+    main()

dnd_game_master_hfport/hf_integration.py

@@ -0,0 +1,395 @@
+"""Hugging Face integration for the D&D Game Master."""
+
+from typing import List, Dict, Optional, Any, Union
+import json
+import re
+import os
+
+# Support multiple import methods
+try:
+    from transformers import pipeline, AutoModelForCausalLM, AutoTokenizer
+    HAS_TRANSFORMERS = True
+except ImportError:
+    HAS_TRANSFORMERS = False
+
+try:
+    from huggingface_hub import InferenceClient
+    HAS_HF_HUB = True
+except ImportError:
+    HAS_HF_HUB = False
+
+
+class HuggingFaceGM:
+    """Hugging Face-powered Game Master for D&D."""
+
+    # Recommended models for narrative generation
+    RECOMMENDED_MODELS = {
+        "mistralai/Mistral-7B-Instruct-v0.3": {
+            "name": "Mistral 7B Instruct",
+            "size": "7B",
+            "description": "Good balance of speed and quality",
+            "speed": "fast",
+        },
+        "meta-llama/Llama-3.2-3B-Instruct": {
+            "name": "Llama 3.2 3B",
+            "size": "3B",
+            "description": "Fast responses, good for quick gameplay",
+            "speed": "very_fast",
+        },
+        "google/gemma-2-9b-it": {
+            "name": "Gemma 2 9B",
+            "size": "9B",
+            "description": "High quality narrative generation",
+            "speed": "medium",
+        },
+        "HuggingFaceH4/zephyr-7b-beta": {
+            "name": "Zephyr 7B",
+            "size": "7B",
+            "description": "Strong instruction following",
+            "speed": "fast",
+        },
+        "microsoft/Phi-3-mini-4k-instruct": {
+            "name": "Phi-3 Mini",
+            "size": "3.8B",
+            "description": "Compact but capable",
+            "speed": "very_fast",
+        },
+    }
+
+    def __init__(
+        self,
+        model_id: str = "mistralai/Mistral-7B-Instruct-v0.3",
+        use_api: bool = True,
+        api_token: Optional[str] = None,
+        device: str = "auto",
+    ):
+        """
+        Initialize the Hugging Face Game Master.
+
+        Args:
+            model_id: Hugging Face model ID
+            use_api: If True, use Inference API. If False, load model locally.
+            api_token: Hugging Face API token (required for API, optional for local)
+            device: Device for local inference ("auto", "cuda", "cpu", "mps")
+        """
+        self.model_id = model_id
+        self.use_api = use_api
+        self.api_token = api_token or os.environ.get("HF_TOKEN") or os.environ.get("HUGGINGFACE_TOKEN")
+        self.device = device
+
+        # Model and tokenizer for local inference
+        self.model = None
+        self.tokenizer = None
+        self.generator = None
+        self.client = None
+
+        if use_api:
+            self._init_api_client()
+        else:
+            self._init_local_model()
+
+    def _init_api_client(self):
+        """Initialize the Hugging Face Inference API client."""
+        if not HAS_HF_HUB:
+            raise ImportError(
+                "huggingface_hub is required for API inference. "
+                "Install with: pip install huggingface_hub"
+            )
+
+        self.client = InferenceClient(
+            model=self.model_id,
+            token=self.api_token,
+        )
+        print(f"Initialized HF Inference API with model: {self.model_id}")
+
+    def _init_local_model(self):
+        """Load model locally for inference."""
+        if not HAS_TRANSFORMERS:
+            raise ImportError(
+                "transformers and torch are required for local inference. "
+                "Install with: pip install transformers torch"
+            )
+
+        print(f"Loading model {self.model_id}... This may take a few minutes.")
+
+        self.tokenizer = AutoTokenizer.from_pretrained(
+            self.model_id,
+            token=self.api_token,
+        )
+
+        self.model = AutoModelForCausalLM.from_pretrained(
+            self.model_id,
+            device_map=self.device,
+            torch_dtype="auto",
+            token=self.api_token,
+        )
+
+        self.generator = pipeline(
+            "text-generation",
+            model=self.model,
+            tokenizer=self.tokenizer,
+        )
+
+        print(f"Model loaded successfully on device: {self.device}")
+
+    def chat(
+        self,
+        messages: List[Dict[str, str]],
+        max_tokens: int = 1024,
+        temperature: float = 0.8,
+        top_p: float = 0.95,
+    ) -> str:
+        """
+        Send a chat request to the model.
+
+        Args:
+            messages: List of {"role": "system/user/assistant", "content": "..."}
+            max_tokens: Maximum tokens to generate
+            temperature: Sampling temperature (higher = more creative)
+            top_p: Nucleus sampling parameter
+
+        Returns:
+            Generated text response
+        """
+        if self.use_api:
+            return self._chat_api(messages, max_tokens, temperature, top_p)
+        else:
+            return self._chat_local(messages, max_tokens, temperature, top_p)
+
+    def _chat_api(
+        self,
+        messages: List[Dict[str, str]],
+        max_tokens: int,
+        temperature: float,
+        top_p: float,
+    ) -> str:
+        """Use Hugging Face Inference API."""
+        try:
+            response = self.client.chat_completion(
+                messages=messages,
+                max_tokens=max_tokens,
+                temperature=temperature,
+                top_p=top_p,
+            )
+            return response.choices[0].message.content
+        except Exception as e:
+            print(f"API Error: {e}")
+            raise RuntimeError(f"Failed to get response from HF API: {e}")
+
+    def _chat_local(
+        self,
+        messages: List[Dict[str, str]],
+        max_tokens: int,
+        temperature: float,
+        top_p: float,
+    ) -> str:
+        """Use local model inference."""
+        # Format messages using the tokenizer's chat template if available
+        if hasattr(self.tokenizer, 'apply_chat_template'):
+            prompt = self.tokenizer.apply_chat_template(
+                messages,
+                tokenize=False,
+                add_generation_prompt=True
+            )
+        else:
+            prompt = self._format_messages_fallback(messages)
+
+        outputs = self.generator(
+            prompt,
+            max_new_tokens=max_tokens,
+            temperature=temperature,
+            top_p=top_p,
+            do_sample=True,
+            pad_token_id=self.tokenizer.eos_token_id,
+        )
+
+        generated = outputs[0]["generated_text"]
+
+        # Extract only the new generation (after the prompt)
+        if generated.startswith(prompt):
+            response = generated[len(prompt):].strip()
+        else:
+            # Try to find where the response starts
+            response = generated.strip()
+
+        return response
+
+    def _format_messages_fallback(self, messages: List[Dict[str, str]]) -> str:
+        """Fallback message formatting for models without chat templates."""
+        parts = []
+        for msg in messages:
+            role = msg["role"].upper()
+            content = msg["content"]
+            if role == "SYSTEM":
+                parts.append(f"### System:\n{content}")
+            elif role == "USER":
+                parts.append(f"### User:\n{content}")
+            elif role == "ASSISTANT":
+                parts.append(f"### Assistant:\n{content}")
+        parts.append("### Assistant:\n")
+        return "\n\n".join(parts)
+
+    def parse_json_response(self, response: str) -> Dict[str, Any]:
+        """
+        Parse JSON from the model response.
+
+        Handles various formats including markdown code blocks.
+
+        Args:
+            response: Raw model response
+
+        Returns:
+            Parsed JSON dictionary
+        """
+        # Remove markdown code blocks if present
+        cleaned = response.strip()
+
+        # Try to extract JSON from markdown code block
+        json_block_match = re.search(r'```(?:json)?\s*([\s\S]*?)```', cleaned)
+        if json_block_match:
+            cleaned = json_block_match.group(1).strip()
+
+        # Try to find JSON object boundaries
+        json_match = re.search(r'\{[\s\S]*\}', cleaned)
+        if json_match:
+            try:
+                return json.loads(json_match.group())
+            except json.JSONDecodeError:
+                pass
+
+        # Try parsing the whole thing
+        try:
+            return json.loads(cleaned)
+        except json.JSONDecodeError:
+            pass
+
+        # Fallback: treat as pure narration
+        return {
+            "decision": "auto_success",
+            "narration": response.strip(),
+            "parse_error": True,
+            "raw_response": response,
+        }
+
+    def get_gm_decision(
+        self,
+        player_action: str,
+        system_prompt: str,
+        context: str,
+        conversation_history: Optional[List[Dict[str, str]]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Get the GM's decision for a player action.
+
+        Args:
+            player_action: What the player wants to do
+            system_prompt: The GM system prompt
+            context: Current scene/character context
+            conversation_history: Previous conversation messages
+
+        Returns:
+            Parsed GM decision dictionary with keys like:
+            - decision: "impossible" | "auto_success" | "auto_fail" | "needs_roll"
+            - narration: The narrative text
+            - skill: (if needs_roll) The skill to check
+            - dc: (if needs_roll) The difficulty class
+        """
+        messages = [{"role": "system", "content": system_prompt}]
+
+        if conversation_history:
+            messages.extend(conversation_history[-10:])  # Limit context
+
+        user_message = f"{context}\n\n---\n\nPlayer action: {player_action}"
+        messages.append({"role": "user", "content": user_message})
+
+        response = self.chat(messages)
+        return self.parse_json_response(response)
+
+    def narrate_outcome(
+        self,
+        outcome_prompt: str,
+        system_prompt: str,
+    ) -> Dict[str, Any]:
+        """
+        Get narration for a roll outcome.
+
+        Args:
+            outcome_prompt: The outcome prompt with roll results
+            system_prompt: The GM system prompt
+
+        Returns:
+            Parsed response with narration and any scene updates
+        """
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": outcome_prompt},
+        ]
+
+        response = self.chat(messages)
+        return self.parse_json_response(response)
+
+    def extract_scene(
+        self,
+        extraction_prompt: str,
+    ) -> Dict[str, Any]:
+        """
+        Extract scene details from narrative.
+
+        Args:
+            extraction_prompt: The scene extraction prompt
+
+        Returns:
+            Parsed scene data
+        """
+        messages = [{"role": "user", "content": extraction_prompt}]
+        response = self.chat(messages, max_tokens=512)
+        return self.parse_json_response(response)
+
+    @classmethod
+    def list_recommended_models(cls) -> List[Dict[str, str]]:
+        """Get list of recommended models with descriptions."""
+        return [
+            {"id": model_id, **info}
+            for model_id, info in cls.RECOMMENDED_MODELS.items()
+        ]
+
+
+def create_gm(
+    model_id: str = "mistralai/Mistral-7B-Instruct-v0.3",
+    api_token: Optional[str] = None,
+    local: bool = False,
+    device: str = "auto",
+) -> HuggingFaceGM:
+    """
+    Create a Hugging Face Game Master instance.
+
+    This is a convenience function for quick setup.
+
+    Args:
+        model_id: Hugging Face model ID
+        api_token: Your HF API token (or set HF_TOKEN env var)
+        local: If True, load model locally instead of using API
+        device: Device for local inference ("auto", "cuda", "cpu", "mps")
+
+    Returns:
+        HuggingFaceGM instance ready for use
+
+    Example:
+        >>> gm = create_gm(api_token="hf_...")
+        >>> response = gm.chat([{"role": "user", "content": "Hello!"}])
+    """
+    return HuggingFaceGM(
+        model_id=model_id,
+        use_api=not local,
+        api_token=api_token,
+        device=device,
+    )
+
+
+# For backwards compatibility and simpler imports
+__all__ = [
+    "HuggingFaceGM",
+    "create_gm",
+    "HAS_TRANSFORMERS",
+    "HAS_HF_HUB",
+]

dnd_game_master_hfport/models/__init__.py

@@ -0,0 +1,22 @@
+"""Data models for D&D game state."""
+
+from .character import Character, create_blank_character, create_test_character
+from .scene import Scene, NPC, Lighting, TimeOfDay, NPCAttitude
+from .game_state import GameState, GamePhase, NarrativeEntry
+
+__all__ = [
+    # Character
+    "Character",
+    "create_blank_character",
+    "create_test_character",
+    # Scene
+    "Scene",
+    "NPC",
+    "Lighting",
+    "TimeOfDay",
+    "NPCAttitude",
+    # Game State
+    "GameState",
+    "GamePhase",
+    "NarrativeEntry",
+]

dnd_game_master_hfport/models/character.py

@@ -0,0 +1,344 @@
+"""Character data model for D&D 5e."""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+
+@dataclass
+class Character:
+    """A D&D 5e player character."""
+
+    # Basic info
+    name: str
+    race: str
+    character_class: str
+    level: int = 1
+    background: str = ""
+    alignment: str = "Neutral"
+
+    # Ability scores
+    strength: int = 10
+    dexterity: int = 10
+    constitution: int = 10
+    intelligence: int = 10
+    wisdom: int = 10
+    charisma: int = 10
+
+    # Combat stats
+    max_hp: int = 10
+    current_hp: int = 10
+    temp_hp: int = 0
+    armor_class: int = 10
+    speed: int = 30
+    initiative_bonus: int = 0
+
+    # Proficiencies
+    proficient_skills: List[str] = field(default_factory=list)
+    expertise_skills: List[str] = field(default_factory=list)
+    proficient_saves: List[str] = field(default_factory=list)
+
+    # Equipment and features
+    equipment: List[str] = field(default_factory=list)
+    features: List[str] = field(default_factory=list)
+
+    # Status
+    conditions: List[str] = field(default_factory=list)
+    death_saves_success: int = 0
+    death_saves_failure: int = 0
+
+    def get_ability_scores(self) -> Dict[str, int]:
+        """Get all ability scores as a dictionary."""
+        return {
+            "strength": self.strength,
+            "dexterity": self.dexterity,
+            "constitution": self.constitution,
+            "intelligence": self.intelligence,
+            "wisdom": self.wisdom,
+            "charisma": self.charisma,
+        }
+
+    def is_proficient(self, skill: str) -> bool:
+        """Check if character is proficient in a skill."""
+        normalized = skill.lower().replace(" ", "_")
+        return normalized in [
+            s.lower().replace(" ", "_") for s in self.proficient_skills
+        ]
+
+    def has_expertise(self, skill: str) -> bool:
+        """Check if character has expertise in a skill."""
+        normalized = skill.lower().replace(" ", "_")
+        return normalized in [
+            s.lower().replace(" ", "_") for s in self.expertise_skills
+        ]
+
+    def is_save_proficient(self, ability: str) -> bool:
+        """Check if character is proficient in a saving throw."""
+        return ability.lower() in [s.lower() for s in self.proficient_saves]
+
+    def take_damage(self, amount: int) -> int:
+        """
+        Apply damage to the character.
+
+        Args:
+            amount: Damage amount
+
+        Returns:
+            Actual damage taken after temp HP
+        """
+        # Temp HP absorbs damage first
+        if self.temp_hp > 0:
+            if amount <= self.temp_hp:
+                self.temp_hp -= amount
+                return 0
+            else:
+                amount -= self.temp_hp
+                self.temp_hp = 0
+
+        self.current_hp = max(0, self.current_hp - amount)
+        return amount
+
+    def heal(self, amount: int) -> int:
+        """
+        Heal the character.
+
+        Args:
+            amount: Healing amount
+
+        Returns:
+            Actual HP restored
+        """
+        old_hp = self.current_hp
+        self.current_hp = min(self.max_hp, self.current_hp + amount)
+        return self.current_hp - old_hp
+
+    def is_unconscious(self) -> bool:
+        """Check if character is at 0 HP."""
+        return self.current_hp <= 0
+
+    def is_dead(self) -> bool:
+        """Check if character has failed 3 death saves."""
+        return self.death_saves_failure >= 3
+
+    def is_stable(self) -> bool:
+        """Check if character has succeeded 3 death saves."""
+        return self.death_saves_success >= 3
+
+    def add_condition(self, condition: str):
+        """Add a condition to the character."""
+        if condition.lower() not in [c.lower() for c in self.conditions]:
+            self.conditions.append(condition)
+
+    def remove_condition(self, condition: str):
+        """Remove a condition from the character."""
+        self.conditions = [
+            c for c in self.conditions if c.lower() != condition.lower()
+        ]
+
+    def has_condition(self, condition: str) -> bool:
+        """Check if character has a condition."""
+        return condition.lower() in [c.lower() for c in self.conditions]
+
+    def to_dict(self) -> Dict:
+        """Convert character to dictionary for serialization."""
+        return {
+            "name": self.name,
+            "race": self.race,
+            "character_class": self.character_class,
+            "level": self.level,
+            "background": self.background,
+            "alignment": self.alignment,
+            "ability_scores": self.get_ability_scores(),
+            "max_hp": self.max_hp,
+            "current_hp": self.current_hp,
+            "temp_hp": self.temp_hp,
+            "armor_class": self.armor_class,
+            "speed": self.speed,
+            "proficient_skills": self.proficient_skills,
+            "expertise_skills": self.expertise_skills,
+            "proficient_saves": self.proficient_saves,
+            "equipment": self.equipment,
+            "features": self.features,
+            "conditions": self.conditions,
+        }
+
+    def summary(self) -> str:
+        """Get a brief character summary."""
+        return (
+            f"{self.name}, Level {self.level} {self.race} {self.character_class}\n"
+            f"HP: {self.current_hp}/{self.max_hp} | AC: {self.armor_class}\n"
+            f"STR: {self.strength} DEX: {self.dexterity} CON: {self.constitution}\n"
+            f"INT: {self.intelligence} WIS: {self.wisdom} CHA: {self.charisma}"
+        )
+
+
+def create_blank_character(name: str = "Adventurer") -> Character:
+    """Create a blank character with default stats."""
+    return Character(
+        name=name,
+        race="Human",
+        character_class="Fighter",
+        level=1,
+    )
+
+
+def create_test_character() -> Character:
+    """Create a pre-built test character (Kira the Rogue)."""
+    return Character(
+        name="Kira",
+        race="Half-Elf",
+        character_class="Rogue",
+        level=3,
+        background="Criminal",
+        alignment="Chaotic Good",
+        strength=10,
+        dexterity=16,
+        constitution=12,
+        intelligence=14,
+        wisdom=10,
+        charisma=14,
+        max_hp=21,
+        current_hp=21,
+        armor_class=14,
+        speed=30,
+        proficient_skills=[
+            "stealth", "perception", "deception",
+            "sleight_of_hand", "acrobatics", "investigation"
+        ],
+        expertise_skills=["stealth", "sleight_of_hand"],
+        proficient_saves=["dexterity", "intelligence"],
+        equipment=[
+            "Shortsword", "Shortbow", "Leather Armor",
+            "Thieves' Tools", "Burglar's Pack"
+        ],
+        features=["Sneak Attack (2d6)", "Cunning Action", "Expertise"],
+    )
+
+
+def create_fighter_character() -> Character:
+    """Create a pre-built Fighter character (Thorin the Dwarf)."""
+    return Character(
+        name="Thorin",
+        race="Dwarf",
+        character_class="Fighter",
+        level=3,
+        background="Soldier",
+        alignment="Lawful Good",
+        strength=16,
+        dexterity=12,
+        constitution=16,
+        intelligence=10,
+        wisdom=12,
+        charisma=8,
+        max_hp=31,
+        current_hp=31,
+        armor_class=18,
+        speed=25,
+        proficient_skills=["athletics", "intimidation", "perception", "survival"],
+        expertise_skills=[],
+        proficient_saves=["strength", "constitution"],
+        equipment=[
+            "Longsword", "Shield", "Chain Mail",
+            "Handaxe (2)", "Explorer's Pack"
+        ],
+        features=["Fighting Style (Defense)", "Second Wind", "Action Surge"],
+    )
+
+
+def create_wizard_character() -> Character:
+    """Create a pre-built Wizard character (Elara the Elf)."""
+    return Character(
+        name="Elara",
+        race="High Elf",
+        character_class="Wizard",
+        level=3,
+        background="Sage",
+        alignment="Neutral Good",
+        strength=8,
+        dexterity=14,
+        constitution=12,
+        intelligence=17,
+        wisdom=13,
+        charisma=10,
+        max_hp=17,
+        current_hp=17,
+        armor_class=12,
+        speed=30,
+        proficient_skills=["arcana", "history", "investigation", "insight"],
+        expertise_skills=[],
+        proficient_saves=["intelligence", "wisdom"],
+        equipment=[
+            "Quarterstaff", "Spellbook", "Component Pouch",
+            "Scholar's Pack", "Dagger"
+        ],
+        features=["Arcane Recovery", "Evocation Savant", "Sculpt Spells"],
+    )
+
+
+def create_cleric_character() -> Character:
+    """Create a pre-built Cleric character (Brother Marcus)."""
+    return Character(
+        name="Brother Marcus",
+        race="Human",
+        character_class="Cleric",
+        level=3,
+        background="Acolyte",
+        alignment="Lawful Good",
+        strength=14,
+        dexterity=10,
+        constitution=14,
+        intelligence=10,
+        wisdom=16,
+        charisma=12,
+        max_hp=24,
+        current_hp=24,
+        armor_class=18,
+        speed=30,
+        proficient_skills=["medicine", "religion", "insight", "persuasion"],
+        expertise_skills=[],
+        proficient_saves=["wisdom", "charisma"],
+        equipment=[
+            "Mace", "Shield", "Chain Mail",
+            "Holy Symbol", "Priest's Pack"
+        ],
+        features=["Spellcasting", "Channel Divinity", "Turn Undead"],
+    )
+
+
+def create_ranger_character() -> Character:
+    """Create a pre-built Ranger character (Sylvan the Wood Elf)."""
+    return Character(
+        name="Sylvan",
+        race="Wood Elf",
+        character_class="Ranger",
+        level=3,
+        background="Outlander",
+        alignment="Neutral Good",
+        strength=12,
+        dexterity=16,
+        constitution=14,
+        intelligence=10,
+        wisdom=14,
+        charisma=10,
+        max_hp=28,
+        current_hp=28,
+        armor_class=15,
+        speed=35,
+        proficient_skills=["nature", "survival", "stealth", "perception", "animal_handling"],
+        expertise_skills=[],
+        proficient_saves=["strength", "dexterity"],
+        equipment=[
+            "Longbow", "Shortsword (2)", "Studded Leather",
+            "Explorer's Pack", "Quiver (20 arrows)"
+        ],
+        features=["Favored Enemy (Beasts)", "Natural Explorer (Forest)", "Fighting Style (Archery)"],
+    )
+
+
+# Dictionary of all preset characters
+PRESET_CHARACTERS = {
+    "Kira (Rogue)": create_test_character,
+    "Thorin (Fighter)": create_fighter_character,
+    "Elara (Wizard)": create_wizard_character,
+    "Brother Marcus (Cleric)": create_cleric_character,
+    "Sylvan (Ranger)": create_ranger_character,
+}

dnd_game_master_hfport/models/game_state.py

@@ -0,0 +1,288 @@
+"""Game state management for D&D sessions."""
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict, Any
+from enum import Enum
+from datetime import datetime
+from .character import Character
+from .scene import Scene
+
+
+class GamePhase(Enum):
+    """Current phase of the game."""
+    SETUP = "setup"
+    ADVENTURE_SELECTION = "adventure_selection"
+    CHARACTER_CREATION = "character_creation"
+    PLAYING = "playing"
+    COMBAT = "combat"
+    PAUSED = "paused"
+    ENDED = "ended"
+
+
+class NarrativeType(Enum):
+    """Types of narrative entries."""
+    SCENE = "scene"
+    PLAYER = "player"
+    GM_RESPONSE = "gm_response"
+    NPC = "npc"
+    ROLL = "roll"
+    ROLL_REQUEST = "roll_request"
+    ROLL_OUTCOME = "roll_outcome"
+    DAMAGE = "damage"
+    SYSTEM = "system"
+
+
+@dataclass
+class NarrativeEntry:
+    """A single entry in the narrative log."""
+    entry_type: str
+    content: str
+    timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "entry_type": self.entry_type,
+            "content": self.content,
+            "timestamp": self.timestamp,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "NarrativeEntry":
+        """Create from dictionary."""
+        return cls(
+            entry_type=data.get("entry_type", "system"),
+            content=data.get("content", ""),
+            timestamp=data.get("timestamp", datetime.now().isoformat()),
+            metadata=data.get("metadata", {}),
+        )
+
+
+@dataclass
+class CombatState:
+    """State for combat encounters."""
+    is_active: bool = False
+    round_number: int = 0
+    turn_order: List[str] = field(default_factory=list)
+    current_turn_index: int = 0
+    combatants: Dict[str, Dict[str, Any]] = field(default_factory=dict)
+
+    def start_combat(self, initiative_order: List[tuple]):
+        """
+        Start combat with initiative order.
+
+        Args:
+            initiative_order: List of (name, initiative_roll) tuples
+        """
+        self.is_active = True
+        self.round_number = 1
+        self.current_turn_index = 0
+
+        # Sort by initiative (descending)
+        sorted_order = sorted(initiative_order, key=lambda x: x[1], reverse=True)
+        self.turn_order = [name for name, _ in sorted_order]
+
+        # Initialize combatant tracking
+        for name, initiative in sorted_order:
+            self.combatants[name] = {
+                "initiative": initiative,
+                "conditions": [],
+                "has_acted": False,
+            }
+
+    def next_turn(self) -> Optional[str]:
+        """Advance to next combatant's turn."""
+        if not self.is_active:
+            return None
+
+        # Mark current combatant as having acted
+        current = self.get_current_combatant()
+        if current and current in self.combatants:
+            self.combatants[current]["has_acted"] = True
+
+        # Move to next
+        self.current_turn_index += 1
+
+        # Check for new round
+        if self.current_turn_index >= len(self.turn_order):
+            self.current_turn_index = 0
+            self.round_number += 1
+            # Reset has_acted for all
+            for combatant in self.combatants.values():
+                combatant["has_acted"] = False
+
+        return self.get_current_combatant()
+
+    def get_current_combatant(self) -> Optional[str]:
+        """Get the name of the current combatant."""
+        if not self.turn_order or self.current_turn_index >= len(self.turn_order):
+            return None
+        return self.turn_order[self.current_turn_index]
+
+    def remove_combatant(self, name: str):
+        """Remove a combatant (defeated, fled, etc.)."""
+        if name in self.turn_order:
+            idx = self.turn_order.index(name)
+            self.turn_order.remove(name)
+            if idx < self.current_turn_index:
+                self.current_turn_index -= 1
+        if name in self.combatants:
+            del self.combatants[name]
+
+    def end_combat(self):
+        """End the combat encounter."""
+        self.is_active = False
+        self.round_number = 0
+        self.turn_order = []
+        self.current_turn_index = 0
+        self.combatants = {}
+
+
+@dataclass
+class GameState:
+    """Complete game state for a D&D session."""
+    # Session info
+    session_id: str = ""
+    session_name: str = "New Adventure"
+    created_at: str = field(default_factory=lambda: datetime.now().isoformat())
+
+    # Game phase
+    phase: GamePhase = GamePhase.SETUP
+
+    # Character and scene
+    character: Optional[Character] = None
+    scene: Optional[Scene] = None
+
+    # Combat
+    combat: CombatState = field(default_factory=CombatState)
+
+    # Narrative history
+    narrative_history: List[NarrativeEntry] = field(default_factory=list)
+
+    # LLM conversation history (for context)
+    conversation_history: List[Dict[str, str]] = field(default_factory=list)
+
+    # Adventure metadata
+    adventure_name: str = ""
+    adventure_description: str = ""
+
+    def add_narrative(
+        self,
+        entry_type: str,
+        content: str,
+        **metadata
+    ) -> NarrativeEntry:
+        """Add a narrative entry to the history."""
+        entry = NarrativeEntry(
+            entry_type=entry_type,
+            content=content,
+            metadata=metadata
+        )
+        self.narrative_history.append(entry)
+        return entry
+
+    def add_message(self, role: str, content: str):
+        """Add a message to the LLM conversation history."""
+        self.conversation_history.append({
+            "role": role,
+            "content": content
+        })
+
+    def get_recent_context(self, max_entries: int = 10) -> str:
+        """Get recent narrative for context building."""
+        recent = self.narrative_history[-max_entries:]
+        return "\n".join([
+            f"[{e.entry_type.upper()}] {e.content}"
+            for e in recent
+        ])
+
+    def get_recent_messages(self, max_messages: int = 20) -> List[Dict[str, str]]:
+        """Get recent conversation messages for LLM context."""
+        return self.conversation_history[-max_messages:]
+
+    def clear_conversation(self):
+        """Clear conversation history (but keep narrative)."""
+        self.conversation_history = []
+
+    def start_adventure(
+        self,
+        character: Character,
+        scene: Scene,
+        adventure_name: str = "",
+    ):
+        """Initialize a new adventure."""
+        self.character = character
+        self.scene = scene
+        self.adventure_name = adventure_name
+        self.phase = GamePhase.PLAYING
+        self.narrative_history = []
+        self.conversation_history = []
+
+        # Add initial scene to narrative
+        self.add_narrative("scene", scene.description)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize game state to dictionary."""
+        return {
+            "session_id": self.session_id,
+            "session_name": self.session_name,
+            "created_at": self.created_at,
+            "phase": self.phase.value,
+            "character": self.character.to_dict() if self.character else None,
+            "scene": self.scene.to_dict() if self.scene else None,
+            "narrative_history": [e.to_dict() for e in self.narrative_history],
+            "adventure_name": self.adventure_name,
+            "adventure_description": self.adventure_description,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "GameState":
+        """Deserialize game state from dictionary."""
+        state = cls(
+            session_id=data.get("session_id", ""),
+            session_name=data.get("session_name", "New Adventure"),
+            created_at=data.get("created_at", datetime.now().isoformat()),
+            phase=GamePhase(data.get("phase", "setup")),
+            adventure_name=data.get("adventure_name", ""),
+            adventure_description=data.get("adventure_description", ""),
+        )
+
+        # Load character if present
+        if data.get("character"):
+            from .character import Character
+            char_data = data["character"]
+            state.character = Character(
+                name=char_data.get("name", "Adventurer"),
+                race=char_data.get("race", "Human"),
+                character_class=char_data.get("character_class", "Fighter"),
+                level=char_data.get("level", 1),
+                # Add other fields as needed
+            )
+
+        # Load scene if present
+        if data.get("scene"):
+            state.scene = Scene.from_dict(data["scene"])
+
+        # Load narrative history
+        state.narrative_history = [
+            NarrativeEntry.from_dict(e)
+            for e in data.get("narrative_history", [])
+        ]
+
+        return state
+
+    def save_to_file(self, filepath: str):
+        """Save game state to a JSON file."""
+        import json
+        with open(filepath, 'w') as f:
+            json.dump(self.to_dict(), f, indent=2)
+
+    @classmethod
+    def load_from_file(cls, filepath: str) -> "GameState":
+        """Load game state from a JSON file."""
+        import json
+        with open(filepath, 'r') as f:
+            data = json.load(f)
+        return cls.from_dict(data)

dnd_game_master_hfport/models/scene.py

@@ -0,0 +1,235 @@
+"""Scene and environment data models for D&D."""
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict, Any
+from enum import Enum
+
+
+class TimeOfDay(Enum):
+    """Time of day for scene atmosphere."""
+    DAWN = "dawn"
+    MORNING = "morning"
+    MIDDAY = "midday"
+    AFTERNOON = "afternoon"
+    DUSK = "dusk"
+    EVENING = "evening"
+    NIGHT = "night"
+
+
+class Lighting(Enum):
+    """Lighting conditions affecting visibility."""
+    BRIGHT = "bright"
+    DIM = "dim"
+    DARK = "dark"
+
+
+class NPCAttitude(Enum):
+    """NPC disposition toward the party."""
+    HOSTILE = "hostile"
+    UNFRIENDLY = "unfriendly"
+    NEUTRAL = "neutral"
+    FRIENDLY = "friendly"
+    HELPFUL = "helpful"
+
+
+@dataclass
+class NPC:
+    """A non-player character in the scene."""
+    name: str
+    description: str = ""
+    attitude: NPCAttitude = NPCAttitude.NEUTRAL
+    notes: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "attitude": self.attitude.value,
+            "notes": self.notes,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "NPC":
+        """Create NPC from dictionary."""
+        return cls(
+            name=data.get("name", "Unknown"),
+            description=data.get("description", ""),
+            attitude=NPCAttitude(data.get("attitude", "neutral")),
+            notes=data.get("notes", ""),
+        )
+
+
+@dataclass
+class Scene:
+    """Current scene/location in the game world."""
+    location: str
+    description: str
+    lighting: Lighting = Lighting.BRIGHT
+    time_of_day: TimeOfDay = TimeOfDay.MIDDAY
+    npcs: List[NPC] = field(default_factory=list)
+    objects: List[str] = field(default_factory=list)
+    exits: List[str] = field(default_factory=list)
+    notes: str = ""
+
+    def to_context_string(self) -> str:
+        """Format scene as context for the LLM."""
+        parts = [
+            f"Location: {self.location}",
+            f"Time: {self.time_of_day.value.title()}, {self.lighting.value} lighting",
+            f"Description: {self.description}",
+        ]
+
+        if self.npcs:
+            npc_list = ", ".join([
+                f"{n.name} ({n.attitude.value})" for n in self.npcs
+            ])
+            parts.append(f"NPCs present: {npc_list}")
+
+        if self.objects:
+            parts.append(f"Notable objects: {', '.join(self.objects)}")
+
+        if self.exits:
+            parts.append(f"Exits: {', '.join(self.exits)}")
+
+        return "\n".join(parts)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "location": self.location,
+            "description": self.description,
+            "lighting": self.lighting.value,
+            "time_of_day": self.time_of_day.value,
+            "npcs": [npc.to_dict() for npc in self.npcs],
+            "objects": self.objects,
+            "exits": self.exits,
+            "notes": self.notes,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Scene":
+        """Create Scene from dictionary."""
+        npcs = [NPC.from_dict(n) for n in data.get("npcs", [])]
+        return cls(
+            location=data.get("location", "Unknown"),
+            description=data.get("description", ""),
+            lighting=Lighting(data.get("lighting", "bright")),
+            time_of_day=TimeOfDay(data.get("time_of_day", "midday")),
+            npcs=npcs,
+            objects=data.get("objects", []),
+            exits=data.get("exits", []),
+            notes=data.get("notes", ""),
+        )
+
+    def add_npc(self, npc: NPC):
+        """Add an NPC to the scene."""
+        self.npcs.append(npc)
+
+    def remove_npc(self, name: str):
+        """Remove an NPC by name."""
+        self.npcs = [n for n in self.npcs if n.name.lower() != name.lower()]
+
+    def get_npc(self, name: str) -> Optional[NPC]:
+        """Get an NPC by name."""
+        for npc in self.npcs:
+            if npc.name.lower() == name.lower():
+                return npc
+        return None
+
+    def add_object(self, obj: str):
+        """Add a notable object to the scene."""
+        if obj not in self.objects:
+            self.objects.append(obj)
+
+    def remove_object(self, obj: str):
+        """Remove an object from the scene."""
+        self.objects = [o for o in self.objects if o.lower() != obj.lower()]
+
+    def update_lighting(self, lighting: Lighting):
+        """Update scene lighting."""
+        self.lighting = lighting
+
+    def advance_time(self):
+        """Advance to the next time of day."""
+        times = list(TimeOfDay)
+        current_idx = times.index(self.time_of_day)
+        next_idx = (current_idx + 1) % len(times)
+        self.time_of_day = times[next_idx]
+
+
+# Premade adventure scenes
+def create_tavern_scene() -> Scene:
+    """Create a classic tavern starting scene."""
+    return Scene(
+        location="The Dusty Tankard Tavern",
+        description=(
+            "A dimly lit tavern filled with the murmur of hushed conversations. "
+            "Wooden beams creak overhead, and the smell of ale and roasted meat "
+            "hangs thick in the air. A crackling fireplace provides warmth against "
+            "the chill outside."
+        ),
+        lighting=Lighting.DIM,
+        time_of_day=TimeOfDay.EVENING,
+        npcs=[
+            NPC(
+                "Mira the Bartender",
+                "A stern woman with knowing eyes and calloused hands",
+                NPCAttitude.NEUTRAL
+            ),
+            NPC(
+                "Hooded Stranger",
+                "Sits alone in the corner, nursing a drink",
+                NPCAttitude.UNFRIENDLY
+            ),
+        ],
+        objects=["Notice board", "Crackling fireplace", "Locked cellar door"],
+        exits=["Front door to the street", "Back door to the alley", "Stairs to rooms above"],
+    )
+
+
+def create_dungeon_entrance_scene() -> Scene:
+    """Create a dungeon entrance scene."""
+    return Scene(
+        location="Ancient Crypt Entrance",
+        description=(
+            "Crumbling stone steps descend into darkness. The air grows cold and "
+            "damp as you approach the weathered entrance. Faded runes are carved "
+            "into the archway, their meaning long forgotten. A foul smell drifts "
+            "up from below."
+        ),
+        lighting=Lighting.DIM,
+        time_of_day=TimeOfDay.AFTERNOON,
+        npcs=[],
+        objects=[
+            "Faded warning runes", "Scattered bones", "Rusty iron gate",
+            "Extinguished torch sconces"
+        ],
+        exits=["Stone steps descending into darkness", "Forest path back to town"],
+    )
+
+
+def create_forest_clearing_scene() -> Scene:
+    """Create a forest clearing scene."""
+    return Scene(
+        location="Moonlit Forest Clearing",
+        description=(
+            "Silver moonlight filters through the canopy, illuminating a small "
+            "clearing in the ancient forest. Fireflies dance among the ferns, "
+            "and the distant hoot of an owl echoes through the trees. A moss-covered "
+            "stone circle stands at the center."
+        ),
+        lighting=Lighting.DIM,
+        time_of_day=TimeOfDay.NIGHT,
+        npcs=[],
+        objects=["Ancient stone circle", "Fairy ring of mushrooms", "Clear spring"],
+        exits=["Overgrown path north", "Game trail east", "Dense thicket west"],
+    )
+
+
+# Dictionary of all preset scenes
+PRESET_SCENES = {
+    "The Dusty Tankard (Tavern)": create_tavern_scene,
+    "Ancient Crypt Entrance (Dungeon)": create_dungeon_entrance_scene,
+    "Moonlit Forest Clearing": create_forest_clearing_scene,
+}

dnd_game_master_hfport/prompts/__init__.py

@@ -0,0 +1,19 @@
+"""System prompts for the D&D Game Master LLM."""
+
+from .gm_prompts import (
+    build_gm_system_prompt,
+    build_scene_context,
+    build_roll_outcome_prompt,
+    build_scene_extraction_prompt,
+    build_combat_prompt,
+    GM_PERSONALITY,
+)
+
+__all__ = [
+    "build_gm_system_prompt",
+    "build_scene_context",
+    "build_roll_outcome_prompt",
+    "build_scene_extraction_prompt",
+    "build_combat_prompt",
+    "GM_PERSONALITY",
+]

dnd_game_master_hfport/prompts/gm_prompts.py

@@ -0,0 +1,288 @@
+"""Prompt templates for the D&D Game Master LLM."""
+
+from typing import Optional
+from ..models.character import Character
+from ..models.scene import Scene
+
+
+# Base GM personality and rules
+GM_PERSONALITY = """You are an expert Dungeons & Dragons 5th Edition Game Master with decades of experience running immersive campaigns. Your storytelling is vivid and engaging, bringing scenes to life with sensory details. You are fair but challenging, creating tension while respecting player agency.
+
+Your core principles:
+- Describe environments with rich sensory details (sights, sounds, smells)
+- Give NPCs distinct personalities and motivations
+- Maintain internal world consistency
+- Reward creative problem-solving
+- Apply D&D 5e rules accurately
+- Keep the narrative moving forward
+- Balance challenge with fun"""
+
+
+def build_gm_system_prompt() -> str:
+    """Build the main GM system prompt for action adjudication."""
+    return f"""{GM_PERSONALITY}
+
+## Your Role
+When a player describes an action, you must decide how to resolve it and respond with a JSON object.
+
+## Decision Types
+- "impossible": The action cannot physically happen or breaks world logic
+- "auto_success": Trivial action that any adventurer could accomplish
+- "auto_fail": Action that would certainly fail regardless of luck
+- "needs_roll": Outcome is uncertain and requires a skill check
+
+## Response Format
+You MUST respond with valid JSON only, in this exact structure:
+
+For needs_roll:
+{{
+    "decision": "needs_roll",
+    "skill": "stealth",
+    "dc": 15,
+    "advantage": false,
+    "disadvantage": false,
+    "narration": "Brief setup for what happens as you attempt this...",
+    "reason": "Why this requires a roll"
+}}
+
+For auto_success:
+{{
+    "decision": "auto_success",
+    "narration": "Vivid description of what happens as you succeed...",
+    "reason": "Why this automatically succeeds"
+}}
+
+For auto_fail:
+{{
+    "decision": "auto_fail",
+    "narration": "Description of why this fails...",
+    "reason": "Why this cannot succeed"
+}}
+
+For impossible:
+{{
+    "decision": "impossible",
+    "narration": "Explanation of why this cannot be attempted...",
+    "reason": "Why this is impossible",
+    "suggestions": ["alternative action 1", "alternative action 2"]
+}}
+
+## Skill Check Guidelines
+Common DCs:
+- DC 5: Very easy (climb a knotted rope)
+- DC 10: Easy (hear an approaching guard)
+- DC 15: Medium (pick a typical lock)
+- DC 20: Hard (leap across a 20-foot chasm)
+- DC 25: Very hard (pick an amazing lock)
+- DC 30: Nearly impossible (leap across a 30-foot chasm)
+
+Match skills to actions:
+- Stealth: Moving quietly, hiding
+- Perception: Noticing things, searching
+- Investigation: Deducing, examining closely
+- Persuasion: Convincing through charm
+- Deception: Lying convincingly
+- Intimidation: Threatening, coercing
+- Athletics: Climbing, jumping, swimming
+- Acrobatics: Balance, tumbling, dodging
+- Sleight of Hand: Pickpocketing, hiding objects
+- Insight: Reading intentions, detecting lies
+
+IMPORTANT: Respond with JSON only. No markdown, no explanation outside the JSON."""
+
+
+def build_scene_context(character: Character, scene: Scene) -> str:
+    """Build context string with current scene and character info."""
+    context_parts = [
+        "=== CURRENT SCENE ===",
+        scene.to_context_string(),
+        "",
+        "=== ACTIVE CHARACTER ===",
+        f"Name: {character.name}",
+        f"Race/Class: {character.race} {character.character_class} (Level {character.level})",
+        f"HP: {character.current_hp}/{character.max_hp} | AC: {character.armor_class}",
+    ]
+
+    if character.conditions:
+        context_parts.append(f"Conditions: {', '.join(character.conditions)}")
+
+    return "\n".join(context_parts)
+
+
+def build_roll_outcome_prompt(
+    action: str,
+    skill: str,
+    roll_total: int,
+    dc: int,
+    success: bool,
+    critical: bool = False,
+    natural_roll: int = 0,
+) -> str:
+    """Build prompt for narrating roll outcomes."""
+    if critical and success:
+        result = "CRITICAL SUCCESS (Natural 20)"
+    elif critical and not success:
+        result = "CRITICAL FAILURE (Natural 1)"
+    elif success:
+        result = "SUCCESS"
+    else:
+        result = "FAILURE"
+
+    margin = roll_total - dc
+    margin_str = f"+{margin}" if margin >= 0 else str(margin)
+
+    return f"""The player attempted: "{action}"
+
+Skill check: {skill.title()}
+Roll: {natural_roll} + modifier = {roll_total} vs DC {dc} (margin: {margin_str})
+Result: {result}
+
+Narrate the outcome vividly, describing what happens based on the result. Be specific and cinematic.
+{"The critical success should feel especially rewarding and impactful." if critical and success else ""}
+{"The critical failure should have dramatic (but not campaign-ending) consequences." if critical and not success else ""}
+
+After narrating, if the scene has changed significantly, note the new scene state.
+
+Respond with JSON:
+{{
+    "narration": "Your vivid narration of what happens...",
+    "location_changed": false,
+    "new_location": null,
+    "new_description": null,
+    "npcs_changed": [],
+    "objects_changed": []
+}}"""
+
+
+def build_scene_extraction_prompt(narrative: str) -> str:
+    """Build prompt for extracting scene details from narrative."""
+    return f"""Analyze this narrative and extract the current scene details:
+
+---
+{narrative}
+---
+
+Extract and respond with JSON:
+{{
+    "location": "Name of the current location",
+    "description": "Detailed description of the scene (2-3 sentences)",
+    "lighting": "bright" | "dim" | "dark",
+    "time_of_day": "dawn" | "morning" | "midday" | "afternoon" | "dusk" | "evening" | "night",
+    "npcs": [
+        {{"name": "NPC name", "description": "Brief description", "attitude": "hostile" | "unfriendly" | "neutral" | "friendly" | "helpful"}}
+    ],
+    "objects": ["notable object 1", "notable object 2"],
+    "exits": ["exit 1", "exit 2"]
+}}
+
+Only include NPCs and objects that are clearly present in the narrative. If unsure, omit them."""
+
+
+def build_combat_prompt(
+    combatants: list,
+    current_turn: str,
+    round_number: int,
+    scene_context: str,
+) -> str:
+    """Build prompt for combat encounters."""
+    combatant_list = "\n".join([
+        f"- {c['name']}: HP {c.get('hp', '?')}, AC {c.get('ac', '?')}"
+        for c in combatants
+    ])
+
+    return f"""{GM_PERSONALITY}
+
+## COMBAT ENCOUNTER
+Round: {round_number}
+Current Turn: {current_turn}
+
+### Combatants:
+{combatant_list}
+
+### Scene:
+{scene_context}
+
+When describing combat actions:
+1. Be visceral and exciting
+2. Describe the physical action vividly
+3. React to hits and misses dramatically
+4. Track positioning and tactics
+5. Give enemies personality in their fighting style
+
+For enemy turns, describe their action and respond with:
+{{
+    "action": "attack" | "spell" | "ability" | "movement" | "other",
+    "target": "target name",
+    "narration": "Description of what they do",
+    "attack_roll": null,  // For attacks: the roll to make
+    "damage_roll": null,  // For damage: the dice to roll
+    "save_dc": null,      // For saves: the DC
+    "save_type": null     // For saves: which save
+}}"""
+
+
+def build_npc_dialogue_prompt(
+    npc_name: str,
+    npc_description: str,
+    npc_attitude: str,
+    player_said: str,
+    context: str,
+) -> str:
+    """Build prompt for NPC dialogue responses."""
+    return f"""You are roleplaying as {npc_name}.
+
+Description: {npc_description}
+Attitude toward party: {npc_attitude}
+
+Context:
+{context}
+
+The player says: "{player_said}"
+
+Respond in character as {npc_name}. Stay true to their personality and attitude.
+Consider:
+- Their current mood and disposition
+- What they know vs. don't know
+- Their goals and motivations
+- Their speech patterns and mannerisms
+
+Respond with JSON:
+{{
+    "dialogue": "What {npc_name} says in response",
+    "action": "Optional physical action or expression",
+    "attitude_change": null  // or "more_friendly" / "more_hostile" if attitude shifts
+}}"""
+
+
+def build_exploration_prompt(
+    action: str,
+    scene: Scene,
+    character: Character,
+) -> str:
+    """Build prompt for exploration and investigation actions."""
+    return f"""{GM_PERSONALITY}
+
+The player is exploring and wants to: {action}
+
+Current Scene:
+{scene.to_context_string()}
+
+Character:
+{character.name} - {character.race} {character.character_class} (Level {character.level})
+
+Describe what they discover or experience. If they're searching or investigating:
+- Reward thoroughness with details
+- Hide secrets behind appropriate skill checks
+- Connect discoveries to the larger world/story
+- Foreshadow dangers or opportunities
+
+If no roll is needed, describe what they find directly. If a roll would reveal more, ask for one.
+
+Respond with JSON:
+{{
+    "decision": "auto_success" | "needs_roll",
+    "skill": "perception",  // if needs_roll
+    "dc": 12,              // if needs_roll
+    "narration": "What they discover or experience...",
+    "hidden_info": "Additional info revealed on success"  // if needs_roll
+}}"""

dnd_game_master_hfport/requirements.txt

@@ -0,0 +1,17 @@
+# D&D AI Game Master - Python Dependencies
+
+# Required for Hugging Face Inference API
+huggingface_hub>=0.20.0
+
+# Required for local model inference (optional)
+transformers>=4.40.0
+torch>=2.0.0
+
+# Optional: for faster inference on NVIDIA GPUs
+# accelerate>=0.27.0
+
+# Optional: for quantized models (reduced memory)
+# bitsandbytes>=0.42.0
+
+# Optional: for Gradio web interface
+# gradio>=4.0.0

dnd_scenarios.py

@@ -0,0 +1,229 @@
+"""D&D Adventure scenario data and sequence generation.
+
+This module provides:
+- DND_ENCOUNTERS: Dictionary of encounter templates by type
+- generate_dnd_sequence: Function to generate adventure sequences
+"""
+
+import json
+import random
+
+# Encounter templates organized by type
+DND_ENCOUNTERS = {
+    "combat": [
+        ("Goblin Ambush", "A band of goblin raiders springs from hiding, blocking the path ahead", ["Goblin", "Goblin Boss"]),
+        ("Wolf Pack Hunt", "Hungry wolves circle the party, eyes gleaming in the darkness", ["Wolf", "Dire Wolf"]),
+        ("Orc War Party", "War drums echo as an orc raiding party charges forward", ["Orc", "Orc War Chief"]),
+        ("Undead Rising", "The ground trembles as skeletal warriors claw their way to the surface", ["Skeleton", "Zombie"]),
+        ("Bandit Roadblock", "Rough-looking bandits demand toll or blood", ["Bandit", "Bandit Captain"]),
+        ("Giant Spider Lair", "Webs glisten in the torchlight as massive spiders descend", ["Giant Spider", "Phase Spider"]),
+        ("Troll Bridge", "A massive troll guards the only crossing, demanding tribute", ["Troll"]),
+        ("Dragon Wyrmling", "A young dragon defends its growing hoard with fierce determination", ["Dragon Wyrmling"]),
+        ("Cultist Ritual", "Robed figures chant around a dark altar, summoning something terrible", ["Cultist", "Cult Fanatic"]),
+        ("Elemental Fury", "An elemental creature of pure destructive force bars the way", ["Fire Elemental", "Earth Elemental"]),
+    ],
+    "social": [
+        ("Tavern Rumors", "Locals share whispered tales over ale in a dimly lit tavern", ["Commoner", "Noble"]),
+        ("Noble's Request", "A wealthy patron offers gold for a dangerous task", ["Noble", "Knight"]),
+        ("Merchant Dispute", "Two traders argue over goods, seeking an arbiter", ["Merchant", "Guard"]),
+        ("Temple Audience", "A high priest offers guidance... for a price", ["Priest", "Acolyte"]),
+        ("Guild Meeting", "The local guild has work, but demands loyalty first", ["Guild Master", "Apprentice"]),
+        ("Royal Court", "The party gains audience with local nobility", ["King", "Advisor"]),
+        ("Mysterious Stranger", "A hooded figure offers cryptic warnings and hidden knowledge", ["Spy", "Assassin"]),
+        ("Festival Celebration", "The town celebrates, but something lurks beneath the merriment", ["Commoner", "Entertainer"]),
+    ],
+    "exploration": [
+        ("Ancient Ruins", "Crumbling stone walls hint at a civilization long forgotten", ["trap", "puzzle"]),
+        ("Dark Cave", "The cave mouth yawns before you, promising secrets in the darkness", ["hazard", "treasure"]),
+        ("Haunted Manor", "The abandoned estate creaks and groans with supernatural presence", ["ghost", "trap"]),
+        ("Underground River", "A subterranean waterway offers passage deeper into the earth", ["hazard", "discovery"]),
+        ("Forest Clearing", "Fey magic permeates this impossibly perfect glade", ["fey", "mystery"]),
+        ("Mountain Pass", "Treacherous cliffs and howling winds test every step", ["hazard", "environmental"]),
+        ("Sunken Temple", "Flooded chambers hide ancient treasures and guardians", ["trap", "treasure"]),
+        ("Wizard's Tower", "Arcane energy crackles through abandoned magical laboratories", ["magic", "puzzle"]),
+    ],
+    "puzzle": [
+        ("The Riddle Door", "Ancient text poses a riddle - only the wise may pass", ["intelligence", "lore"]),
+        ("Pressure Plates", "The floor is a grid of stone plates, some safe, some deadly", ["dexterity", "perception"]),
+        ("Mirror Maze", "Reflections shift and change, hiding the true path", ["wisdom", "investigation"]),
+        ("Elemental Locks", "Four elements must be combined in the correct order", ["arcana", "elements"]),
+        ("Ancestor's Trial", "Spirits of the past judge worth through tests of virtue", ["charisma", "history"]),
+        ("Clockwork Mechanism", "Gears and levers control something vital within", ["intelligence", "mechanics"]),
+        ("Symbol Sequence", "Ancient symbols must be activated in the prophesied order", ["religion", "arcana"]),
+        ("Weight Balance", "Treasures and counterweights must be perfectly balanced", ["wisdom", "mathematics"]),
+    ],
+    "boss": [
+        ("Dragon's Lair", "The great wyrm awakens, fire building in its throat", ["Adult Dragon"]),
+        ("Lich's Sanctum", "The undead sorcerer rises from its throne of bones", ["Lich"]),
+        ("Beholder's Den", "Multiple eyes swivel toward you, each crackling with deadly magic", ["Beholder"]),
+        ("Giant King", "The massive ruler of giants hefts a weapon the size of a tree", ["Giant King"]),
+        ("Vampire Lord", "The ancient vampire regards you with cold, eternal hunger", ["Vampire"]),
+        ("Mind Flayer Colony", "Alien intellects probe your mind as tentacled horrors advance", ["Mind Flayer"]),
+        ("Demon Portal", "A rift to the Abyss spews forth a demon of terrible power", ["Demon Lord"]),
+        ("Corrupted Paladin", "Once a hero, now fallen to darkness and seeking to spread it", ["Death Knight"]),
+    ],
+}
+
+# Difficulty modifiers
+DIFFICULTY_LEVELS = {
+    "easy": {
+        "adjective": "manageable",
+        "enemies": "few",
+        "treasure": "modest",
+    },
+    "medium": {
+        "adjective": "challenging",
+        "enemies": "several",
+        "treasure": "valuable",
+    },
+    "hard": {
+        "adjective": "dangerous",
+        "enemies": "many",
+        "treasure": "significant",
+    },
+    "deadly": {
+        "adjective": "deadly",
+        "enemies": "overwhelming",
+        "treasure": "legendary",
+    },
+}
+
+# Location flavors
+LOCATIONS = [
+    "dungeon depths", "ancient forest", "mountain fortress", "coastal caves",
+    "desert tomb", "frozen tundra", "volcanic lair", "feywild crossing",
+    "shadowfell edge", "planar rift", "underwater ruins", "floating citadel",
+]
+
+
+def generate_dnd_sequence(encounter_count, difficulty, include_combat, include_social,
+                          include_exploration, include_puzzle, include_boss,
+                          force_boss_end=True):
+    """Generate a D&D adventure sequence.
+
+    Args:
+        encounter_count: Number of encounters (3-10)
+        difficulty: One of 'easy', 'medium', 'hard', 'deadly'
+        include_combat: Include combat encounters
+        include_social: Include social encounters
+        include_exploration: Include exploration encounters
+        include_puzzle: Include puzzle encounters
+        include_boss: Include boss encounters
+        force_boss_end: Force sequence to end with a boss fight
+
+    Returns:
+        Tuple of (list_output, json_output, prompts_output)
+    """
+    difficulty_info = DIFFICULTY_LEVELS.get(difficulty, DIFFICULTY_LEVELS["medium"])
+    location = random.choice(LOCATIONS)
+
+    # Build available encounters pool
+    available = []
+    if include_combat:
+        available.extend([(e[0], e[1], "combat", e[2]) for e in DND_ENCOUNTERS["combat"]])
+    if include_social:
+        available.extend([(e[0], e[1], "social", e[2]) for e in DND_ENCOUNTERS["social"]])
+    if include_exploration:
+        available.extend([(e[0], e[1], "exploration", e[2]) for e in DND_ENCOUNTERS["exploration"]])
+    if include_puzzle:
+        available.extend([(e[0], e[1], "puzzle", e[2]) for e in DND_ENCOUNTERS["puzzle"]])
+
+    if not available and not include_boss:
+        return "Select at least one encounter type!", "{}", ""
+
+    sequence = []
+
+    # Reserve boss for end if requested
+    boss_encounter = None
+    if force_boss_end and include_boss:
+        boss_encounter = random.choice(DND_ENCOUNTERS["boss"])
+        encounter_count -= 1
+
+    # Fill with random encounters
+    random.shuffle(available)
+    for enc in available[:encounter_count]:
+        sequence.append(enc)
+
+    # Add boss at end
+    if boss_encounter:
+        sequence.append((boss_encounter[0], boss_encounter[1], "boss", boss_encounter[2]))
+
+    if not sequence:
+        return "No encounters available!", "{}", ""
+
+    # Format as list
+    list_output = f"## D&D Adventure in the {location.title()}\n"
+    list_output += f"**Difficulty:** {difficulty.title()} ({difficulty_info['adjective']})\n\n"
+
+    for i, (name, desc, enc_type, extras) in enumerate(sequence, 1):
+        extras_str = ", ".join(extras) if isinstance(extras, list) else str(extras)
+        list_output += f"**{i}. {name}** [{enc_type}]\n{desc}\n*Features: {extras_str}*\n\n"
+
+    # Format as config JSON
+    config = {"adventure": {}}
+    for i, (name, desc, enc_type, extras) in enumerate(sequence, 1):
+        state_name = name.lower().replace(" ", "_").replace("'", "").replace("-", "_")
+        current_state_id = f"encounter_{i}_{state_name}"
+
+        extras_str = ", ".join(extras) if isinstance(extras, list) else str(extras)
+
+        # Determine next state
+        if i < len(sequence):
+            next_name = sequence[i][0]
+            next_state_name = next_name.lower().replace(" ", "_").replace("'", "").replace("-", "_")
+            next_state_id = f"encounter_{i+1}_{next_state_name}"
+        else:
+            next_state_id = "adventure_complete"
+
+        # Create choices based on encounter type
+        if enc_type == "combat":
+            choices = ["Fight", "Attempt Diplomacy", "Try to Sneak Past"]
+        elif enc_type == "social":
+            choices = ["Engage in Conversation", "Observe Silently", "Make an Offer"]
+        elif enc_type == "exploration":
+            choices = ["Investigate Carefully", "Rush Forward", "Search for Traps"]
+        elif enc_type == "puzzle":
+            choices = ["Study the Puzzle", "Try a Solution", "Look for Clues"]
+        elif enc_type == "boss":
+            choices = ["Prepare for Battle", "Attempt Negotiation", "Launch Surprise Attack"]
+        else:
+            choices = ["Continue"]
+
+        # All choices lead to same next state for simplicity
+        transitions = {choice: next_state_id for choice in choices}
+
+        config["adventure"][current_state_id] = {
+            "description": f"[{enc_type.upper()} - {difficulty.upper()}] {desc}\n\nYou notice: {extras_str}",
+            "media_prompt": f"Fantasy RPG scene in {location}: {name} - {desc}, {difficulty_info['adjective']} atmosphere, featuring {extras_str}",
+            "choices": choices,
+            "transitions": transitions
+        }
+
+    # Add completion state
+    first_enc = sequence[0][0].lower().replace(" ", "_").replace("'", "").replace("-", "_")
+    config["adventure"]["adventure_complete"] = {
+        "description": f"Victory! The {location} has been conquered. {difficulty_info['treasure'].title()} treasures await the brave adventurers.",
+        "choices": ["Embark on New Adventure"],
+        "transitions": {
+            "Embark on New Adventure": f"encounter_1_{first_enc}"
+        }
+    }
+
+    json_output = json.dumps(config, indent=2)
+
+    # Format prompts
+    prompts_output = f"## D&D Adventure Prompts ({location.title()})\n\n"
+    for i, (name, desc, enc_type, extras) in enumerate(sequence, 1):
+        extras_str = ", ".join(extras) if isinstance(extras, list) else str(extras)
+        prompts_output += f"Fantasy RPG scene: {name} - {desc}, featuring {extras_str}\n"
+
+    return list_output, json_output, prompts_output
+
+
+# Quick test
+if __name__ == "__main__":
+    list_out, json_out, prompts_out = generate_dnd_sequence(
+        5, "medium", True, True, True, False, True
+    )
+    print(list_out)
+    print(json_out)

docs/hf_auth_integration_notes.md

@@ -0,0 +1,168 @@
+# HuggingFace Authentication Integration Notes
+
+## Purpose
+Allow users to save their Big RPG Scale entity databases to their own HuggingFace datasets (avoiding data collection concerns).
+
+## Requirements
+- Space-level OAuth configuration
+- User authentication via `gr.LoginButton()`
+- Save/load to user's own HF datasets
+
+## README.md Changes Required
+```yaml
+---
+title: GameConfigIdeaEditBrainstorm
+hf_oauth: true
+hf_oauth_scopes:
+  - read-repos
+  - write-repos
+---
+```
+
+## Gradio OAuth Integration
+
+### Login Button
+```python
+import gradio as gr
+
+with gr.Blocks() as demo:
+    gr.LoginButton(variant="huggingface", size="sm")
+```
+
+### Access User Profile
+```python
+def my_function(profile: gr.OAuthProfile | None):
+    if profile:
+        username = profile.username
+        # Can now save to user's repos
+    else:
+        return "Please log in first"
+```
+
+### Access User Token
+```python
+def save_to_user_dataset(
+    profile: gr.OAuthProfile | None,
+    token: gr.OAuthToken | None,
+    data: str
+):
+    if not profile or not token:
+        return "Login required"
+
+    # Use token.token for API calls
+```
+
+## Implementation Functions
+
+### Save Database
+```python
+from huggingface_hub import HfApi, create_repo
+
+def save_database_to_hf(
+    db: EntityDatabase,
+    profile: gr.OAuthProfile,
+    token: gr.OAuthToken,
+    dataset_name: str = "rpg-entity-database"
+) -> str:
+    username = profile.username
+    repo_id = f"{username}/{dataset_name}"
+
+    api = HfApi(token=token.token)
+
+    # Create repo if needed
+    create_repo(repo_id, repo_type="dataset", exist_ok=True, private=True)
+
+    # Export and upload
+    db_json = db.to_json()
+    api.upload_file(
+        path_or_fileobj=db_json.encode('utf-8'),
+        path_in_repo="entity_database.json",
+        repo_id=repo_id,
+        repo_type="dataset"
+    )
+
+    return f"Saved to: https://huggingface.co/datasets/{repo_id}"
+```
+
+### Load Database
+```python
+from huggingface_hub import hf_hub_download
+
+def load_database_from_hf(
+    db: EntityDatabase,
+    profile: gr.OAuthProfile,
+    token: gr.OAuthToken,
+    dataset_name: str = "rpg-entity-database"
+) -> str:
+    username = profile.username
+    repo_id = f"{username}/{dataset_name}"
+
+    file_path = hf_hub_download(
+        repo_id=repo_id,
+        filename="entity_database.json",
+        repo_type="dataset",
+        token=token.token
+    )
+
+    with open(file_path, 'r') as f:
+        json_str = f.read()
+
+    success, message = db.from_json(json_str)
+    return message
+```
+
+## UI Integration
+
+### Entity Database Tab Addition
+```python
+with gr.Row():
+    login_btn = gr.LoginButton(variant="huggingface", size="sm")
+    login_status = gr.Markdown("*Not logged in*")
+
+with gr.Accordion("Cloud Save/Load (HuggingFace)", open=False):
+    gr.Markdown("Save your entity database to your HuggingFace account.")
+
+    hf_dataset_name = gr.Textbox(
+        label="Dataset Name",
+        value="rpg-entity-database"
+    )
+
+    with gr.Row():
+        save_to_hf_btn = gr.Button("Save to HuggingFace", variant="primary")
+        load_from_hf_btn = gr.Button("Load from HuggingFace")
+
+    hf_status = gr.Markdown("")
+```
+
+## Graceful Degradation
+- All local features work without login
+- Show `gr.Info("Please log in...")` when save/load attempted without auth
+- Display current login status prominently
+
+## Alternative: CommitScheduler (Auto-Save)
+For session logging (like D&D GM event logs):
+```python
+from huggingface_hub import CommitScheduler
+
+scheduler = CommitScheduler(
+    folder_path="./user_data",
+    repo_id=f"{username}/game-sessions",
+    token=token.token,
+    private=True
+)
+```
+- Runs background thread, pushes every ~1 minute
+- Good for append-only data (logs, feedback)
+- Not ideal for frequently-updated files
+
+## Resources
+- [Gradio OAuth Docs](https://huggingface.co/docs/hub/spaces-oauth)
+- [Gradio OAuth Example Space](https://huggingface.co/spaces/gradio/oauth-example)
+- [HuggingFace Hub Upload Guide](https://huggingface.co/docs/huggingface_hub/guides/upload)
+- [Spaces Persistent Storage](https://huggingface.co/docs/hub/spaces-storage)
+
+## TODO
+- [ ] Test OAuth flow locally with `huggingface-cli login`
+- [ ] Decide on dataset structure (single JSON vs multiple files)
+- [ ] Consider versioning/backup strategy
+- [ ] Investigate Space-level persistent storage options

exporters/__init__.py

@@ -0,0 +1,97 @@
+"""Game Config IDE - Platform Exporters Package.
+
+This package provides exporters for converting game configs to various
+platforms and engines.
+
+Supported platforms:
+- Game Engines: GameMaker, Flutter
+- Narrative Engines: Twine, Ren'Py, Ink, Yarn Spinner
+- Game Platforms: Roblox, RPG Maker MZ, Minecraft, Papyrus (Skyrim/Fallout), VRChat
+- AR/XR Platforms: Snap Lens Studio, Meta Spark, 8th Wall, TikTok Effect House, Apple Reality
+- Interactive Fiction: Inform 7, Godot Dialogue Manager
+- Playable HTML: 2D Map, MovingDotSpace
+- Terminal: Python Terminal Game
+"""
+
+# Individual exporters
+from .gamemaker_exporter import export_to_gamemaker
+from .flutter_exporter import export_to_flutter
+from .twine_exporter import export_to_twine
+from .renpy_exporter import export_to_renpy
+from .ink_exporter import export_to_ink
+from .yarn_exporter import export_to_yarn
+from .roblox_exporter import export_to_roblox
+from .rpgmaker_exporter import export_to_rpgmaker
+from .terminal_exporter import export_to_terminal
+
+# AR/XR exporters
+from .ar_exporters import (
+    export_to_lensstudio,
+    export_to_metaspark,
+    export_to_8thwall,
+    export_to_tiktok,
+    export_to_reality
+)
+
+# Game platform exporters
+from .game_platform_exporters import (
+    export_to_minecraft,
+    export_to_papyrus,
+    export_to_vrchat
+)
+
+# Interactive fiction exporters
+from .fiction_exporters import (
+    export_to_inform7,
+    export_to_godot_dialogue
+)
+
+# HTML exporters
+from .html_exporters import (
+    export_to_2d_map,
+    export_to_movingdotspace
+)
+
+# PlayCanvas exporter (from root level)
+try:
+    from playcanvas_exporter import export_to_playcanvas, export_to_playcanvas_html
+except ImportError:
+    export_to_playcanvas = None
+    export_to_playcanvas_html = None
+
+# Router
+from .router import ConfigConversionforExporttoPlatform
+
+__all__ = [
+    # Individual exporters
+    'export_to_gamemaker',
+    'export_to_flutter',
+    'export_to_twine',
+    'export_to_renpy',
+    'export_to_ink',
+    'export_to_yarn',
+    'export_to_roblox',
+    'export_to_rpgmaker',
+    'export_to_terminal',
+    # AR/XR
+    'export_to_lensstudio',
+    'export_to_metaspark',
+    'export_to_8thwall',
+    'export_to_tiktok',
+    'export_to_reality',
+    # Game platforms
+    'export_to_minecraft',
+    'export_to_papyrus',
+    'export_to_vrchat',
+    # Fiction
+    'export_to_inform7',
+    'export_to_godot_dialogue',
+    # HTML
+    'export_to_2d_map',
+    'export_to_movingdotspace',
+    # PlayCanvas
+    'export_to_playcanvas',
+    'export_to_playcanvas_html',
+    # Router
+    'ConfigConversionforExporttoPlatform',
+]

exporters/ar_exporters.py

@@ -0,0 +1,843 @@
+"""AR/XR platform exporters for game configs.
+
+Includes exporters for:
+- Snap Lens Studio
+- Meta Spark AR (Instagram/Facebook)
+- 8th Wall WebAR
+- TikTok Effect House
+- Apple Reality Composer / visionOS
+"""
+
+import json
+
+
+def export_to_lensstudio(config_json):
+    """Export game config to Snap Lens Studio JavaScript format."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except json.JSONDecodeError as e:
+        return f"JSON Error: {str(e)}", ""
+
+    js_code = '''// Snap Lens Studio - Interactive Story Experience
+// Generated from Game Config IDE
+//
+// Setup in Lens Studio:
+// 1. Create a Script component
+// 2. Add @input bindings for UI elements
+// 3. Paste this code
+
+// @input Component.Text descriptionText {"label":"Description Text"}
+// @input Component.ScriptComponent[] choiceButtons {"label":"Choice Buttons"}
+// @input Asset.AudioTrackAsset[] audioTracks {"label":"Audio Tracks"}
+
+// Story States Configuration
+var STORY_STATES = {
+'''
+
+    first_state = None
+
+    # Generate states
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    state_name = f"{location_key}_{state_key}"
+                    if first_state is None:
+                        first_state = state_name
+
+                    description = state_data.get('description', 'No description').replace('"', '\\"').replace('\n', '\\n')
+                    choices = state_data.get('choices', [])
+                    transitions = state_data.get('transitions', {})
+                    media = state_data.get('media', {})
+
+                    js_code += f'    "{state_name}": {{\n'
+                    js_code += f'        description: "{description}",\n'
+                    js_code += f'        location: "{location_key}",\n'
+
+                    # Choices
+                    js_code += '        choices: ['
+                    if choices:
+                        js_code += ', '.join([f'"{c}"' for c in choices])
+                    js_code += '],\n'
+
+                    # Transitions
+                    js_code += '        transitions: {\n'
+                    if isinstance(transitions, dict):
+                        for choice, next_state in transitions.items():
+                            if next_state:
+                                if '_' not in next_state:
+                                    next_state = f"{location_key}_{next_state}"
+                                js_code += f'            "{choice}": "{next_state}",\n'
+                    js_code += '        },\n'
+
+                    # Media hints
+                    if media.get('image') or media.get('audio'):
+                        js_code += '        media: {\n'
+                        if media.get('image'):
+                            js_code += f'            image: "{media["image"]}",\n'
+                        if media.get('audio'):
+                            js_code += f'            audio: "{media["audio"]}",\n'
+                        js_code += '        },\n'
+
+                    js_code += '    },\n'
+
+    js_code += f'''}};
+
+var currentState = "{first_state or "start"}";
+
+// Initialize the story
+function initialize() {{
+    showState(currentState);
+}}
+
+// Display current state
+function showState(stateName) {{
+    var state = STORY_STATES[stateName];
+    if (!state) {{
+        print("State not found: " + stateName);
+        return;
+    }}
+
+    // Update description text
+    if (script.descriptionText) {{
+        script.descriptionText.text = state.description;
+    }}
+
+    // Update choice buttons
+    for (var i = 0; i < script.choiceButtons.length; i++) {{
+        var btn = script.choiceButtons[i];
+        if (i < state.choices.length) {{
+            btn.getSceneObject().enabled = true;
+            // Assuming button has a text child
+            var textComponent = btn.getSceneObject().getComponent("Component.Text");
+            if (textComponent) {{
+                textComponent.text = state.choices[i];
+            }}
+        }} else {{
+            btn.getSceneObject().enabled = false;
+        }}
+    }}
+
+    currentState = stateName;
+    print("Now at state: " + stateName);
+}}
+
+// Handle choice selection (call this from button tap events)
+function makeChoice(choiceIndex) {{
+    var state = STORY_STATES[currentState];
+    if (!state || choiceIndex >= state.choices.length) return;
+
+    var choiceText = state.choices[choiceIndex];
+    var nextState = state.transitions[choiceText];
+
+    if (nextState) {{
+        showState(nextState);
+    }} else {{
+        print("No transition for choice: " + choiceText);
+    }}
+}}
+
+// Reset to beginning
+function resetStory() {{
+    showState("{first_state or "start"}");
+}}
+
+// Export functions for external use
+script.api.makeChoice = makeChoice;
+script.api.resetStory = resetStory;
+script.api.getCurrentState = function() {{ return currentState; }};
+
+// Auto-initialize on start
+var onStartEvent = script.createEvent("OnStartEvent");
+onStartEvent.bind(initialize);
+'''
+
+    explanation = """Snap Lens Studio Export Generated!
+
+Setup Instructions:
+1. Download Lens Studio: https://lensstudio.snapchat.com/
+2. Create new project (World or Face lens)
+3. Add Script component to scene
+4. Paste this code
+5. Set up @input bindings in Inspector
+
+Required Scene Setup:
+- Text component for description (link to descriptionText)
+- Button objects with tap handlers (link to choiceButtons array)
+- Call script.api.makeChoice(0), makeChoice(1), etc. from buttons
+
+Button Tap Setup:
+1. Select button object
+2. Add "Interaction Component"
+3. On Tap event -> call Script.makeChoice(index)
+
+Testing:
+- Use Preview panel in Lens Studio
+- Send to Snapchat for device testing
+- Use Lens Studio's built-in simulator
+
+Publishing:
+- Submit via My Lenses portal
+- Review typically takes 1-3 days
+- 300M+ daily Snapchat AR users
+
+Tips:
+- Use World Tracking for immersive stories
+- Add 3D objects that appear with state changes
+- Use audio for atmosphere
+"""
+
+    return explanation, js_code
+
+
+def export_to_metaspark(config_json):
+    """Export game config to Meta Spark AR (Instagram/Facebook) format."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except json.JSONDecodeError as e:
+        return f"JSON Error: {str(e)}", ""
+
+    js_code = '''// Meta Spark AR - Interactive Story Effect
+// Generated from Game Config IDE
+//
+// Setup in Meta Spark Studio:
+// 1. Create new effect project
+// 2. Add Script to Assets
+// 3. Paste this code and connect to scene objects
+
+const Scene = require('Scene');
+const Diagnostics = require('Diagnostics');
+const Patches = require('Patches');
+const Time = require('Time');
+const Reactive = require('Reactive');
+
+// Story States Configuration
+const STORY_STATES = {
+'''
+
+    first_state = None
+
+    # Generate states
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    state_name = f"{location_key}_{state_key}"
+                    if first_state is None:
+                        first_state = state_name
+
+                    description = state_data.get('description', 'No description').replace('"', '\\"').replace('\n', '\\n')
+                    choices = state_data.get('choices', [])
+                    transitions = state_data.get('transitions', {})
+
+                    js_code += f'    "{state_name}": {{\n'
+                    js_code += f'        description: "{description}",\n'
+                    js_code += f'        location: "{location_key}",\n'
+                    js_code += '        choices: ['
+                    if choices:
+                        js_code += ', '.join([f'"{c}"' for c in choices])
+                    js_code += '],\n'
+                    js_code += '        transitions: {\n'
+                    if isinstance(transitions, dict):
+                        for choice, next_state in transitions.items():
+                            if next_state:
+                                if '_' not in next_state:
+                                    next_state = f"{location_key}_{next_state}"
+                                js_code += f'            "{choice}": "{next_state}",\n'
+                    js_code += '        }\n'
+                    js_code += '    },\n'
+
+    js_code += f'''}};
+
+let currentState = "{first_state or "start"}";
+
+(async function() {{
+    // Find scene objects (adjust names to match your scene)
+    const [descriptionText, choice1Btn, choice2Btn, choice3Btn] = await Promise.all([
+        Scene.root.findFirst('descriptionText'),
+        Scene.root.findFirst('choice1Button'),
+        Scene.root.findFirst('choice2Button'),
+        Scene.root.findFirst('choice3Button')
+    ]);
+
+    const choiceButtons = [choice1Btn, choice2Btn, choice3Btn].filter(b => b);
+
+    // Update UI with current state
+    function showState(stateName) {{
+        const state = STORY_STATES[stateName];
+        if (!state) {{
+            Diagnostics.log("State not found: " + stateName);
+            return;
+        }}
+
+        // Update description
+        if (descriptionText) {{
+            descriptionText.text = state.description;
+        }}
+
+        // Update choice buttons
+        choiceButtons.forEach((btn, i) => {{
+            if (btn) {{
+                const hasChoice = i < state.choices.length;
+                btn.hidden = Reactive.val(!hasChoice);
+                if (hasChoice && btn.findFirst) {{
+                    btn.findFirst('text').then(t => {{
+                        if (t) t.text = state.choices[i];
+                    }});
+                }}
+            }}
+        }});
+
+        currentState = stateName;
+        Diagnostics.log("State: " + stateName);
+
+        // Send to Patch Editor
+        Patches.inputs.setString('currentState', stateName);
+        Patches.inputs.setString('description', state.description);
+    }}
+
+    // Handle choice (connect via Patch Editor pulse inputs)
+    async function setupChoiceHandlers() {{
+        try {{
+            const choice1Pulse = await Patches.outputs.getPulse('choice1Selected');
+            const choice2Pulse = await Patches.outputs.getPulse('choice2Selected');
+            const choice3Pulse = await Patches.outputs.getPulse('choice3Selected');
+
+            choice1Pulse.subscribe(() => makeChoice(0));
+            choice2Pulse.subscribe(() => makeChoice(1));
+            choice3Pulse.subscribe(() => makeChoice(2));
+        }} catch(e) {{
+            Diagnostics.log("Patch outputs not connected: " + e);
+        }}
+    }}
+
+    function makeChoice(index) {{
+        const state = STORY_STATES[currentState];
+        if (!state || index >= state.choices.length) return;
+
+        const choiceText = state.choices[index];
+        const nextState = state.transitions[choiceText];
+
+        if (nextState) {{
+            showState(nextState);
+        }}
+    }}
+
+    // Initialize
+    showState(currentState);
+    setupChoiceHandlers();
+
+}})();
+'''
+
+    explanation = """Meta Spark AR Export Generated!
+
+Setup Instructions:
+1. Download Meta Spark Studio: https://spark.meta.com/
+2. Create new project (Target Tracker, World, or Face effect)
+3. Add Script asset and paste this code
+4. Create UI elements and name them to match script
+
+Scene Object Names:
+- descriptionText: Text object for story description
+- choice1Button, choice2Button, choice3Button: Button objects
+
+Patch Editor Integration:
+1. Open Patch Editor
+2. Create pulse outputs: choice1Selected, choice2Selected, choice3Selected
+3. Connect tap events to these pulses
+4. Script outputs: currentState, description (string)
+
+Testing:
+- Use device preview in Meta Spark
+- Send to Instagram app for testing
+- Test on both iOS and Android
+
+Publishing:
+- Submit via Meta Spark Hub
+- Publish to Instagram and/or Facebook
+- 600M+ Instagram AR filter users
+
+Tips:
+- Use Face Tracker for selfie-style stories
+- Use World Effects for immersive AR
+- Add 3D assets that change with states
+"""
+
+    return explanation, js_code
+
+
+def export_to_8thwall(config_json):
+    """Export game config to 8th Wall WebAR (A-Frame) format."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except json.JSONDecodeError as e:
+        return f"JSON Error: {str(e)}", ""
+
+    html_code = '''<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <title>AR Story Experience</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+
+    <!-- 8th Wall Web SDK (replace YOUR_APP_KEY) -->
+    <script src="https://apps.8thwall.com/xrweb?appKey=YOUR_APP_KEY"></script>
+
+    <!-- A-Frame -->
+    <script src="https://aframe.io/releases/1.4.0/aframe.min.js"></script>
+    <script src="https://cdn.8thwall.com/web/aframe/8frame-1.4.0.min.js"></script>
+
+    <style>
+        #story-ui {
+            position: fixed;
+            bottom: 20px;
+            left: 50%;
+            transform: translateX(-50%);
+            width: 90%;
+            max-width: 400px;
+            background: rgba(0,0,0,0.8);
+            border-radius: 15px;
+            padding: 20px;
+            color: white;
+            font-family: -apple-system, BlinkMacSystemFont, sans-serif;
+            z-index: 1000;
+        }
+        #story-description {
+            font-size: 16px;
+            margin-bottom: 15px;
+            line-height: 1.4;
+        }
+        .choice-btn {
+            display: block;
+            width: 100%;
+            padding: 12px;
+            margin: 8px 0;
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            border: none;
+            border-radius: 10px;
+            color: white;
+            font-size: 14px;
+            cursor: pointer;
+            transition: transform 0.2s;
+        }
+        .choice-btn:hover {
+            transform: scale(1.02);
+        }
+        .choice-btn:active {
+            transform: scale(0.98);
+        }
+        .hidden { display: none; }
+    </style>
+</head>
+<body>
+    <!-- A-Frame Scene -->
+    <a-scene
+        xrextras-gesture-detector
+        xrextras-almost-there
+        xrextras-loading
+        xrextras-runtime-error
+        renderer="colorManagement: true"
+        xrweb="disableWorldTracking: false">
+
+        <!-- Camera -->
+        <a-camera id="camera" position="0 1.6 0"></a-camera>
+
+        <!-- Story 3D Elements (add your own) -->
+        <a-entity id="story-3d-content" position="0 0 -3">
+            <a-text id="ar-title" value="AR Story" position="0 2 0" align="center" color="#FFF" width="4"></a-text>
+        </a-entity>
+
+    </a-scene>
+
+    <!-- Story UI Overlay -->
+    <div id="story-ui">
+        <div id="story-description">Loading story...</div>
+        <div id="choices-container"></div>
+    </div>
+
+    <script>
+    // Story States Configuration
+    const STORY_STATES = {
+'''
+
+    first_state = None
+
+    # Generate states
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    state_name = f"{location_key}_{state_key}"
+                    if first_state is None:
+                        first_state = state_name
+
+                    description = state_data.get('description', 'No description').replace('"', '\\"').replace('\n', '\\n')
+                    choices = state_data.get('choices', [])
+                    transitions = state_data.get('transitions', {})
+
+                    html_code += f'        "{state_name}": {{\n'
+                    html_code += f'            description: "{description}",\n'
+                    html_code += f'            location: "{location_key}",\n'
+                    html_code += '            choices: ['
+                    if choices:
+                        html_code += ', '.join([f'"{c}"' for c in choices])
+                    html_code += '],\n'
+                    html_code += '            transitions: {\n'
+                    if isinstance(transitions, dict):
+                        for choice, next_state in transitions.items():
+                            if next_state:
+                                if '_' not in next_state:
+                                    next_state = f"{location_key}_{next_state}"
+                                html_code += f'                "{choice}": "{next_state}",\n'
+                    html_code += '            }\n'
+                    html_code += '        },\n'
+
+    html_code += f'''    }};
+
+    let currentState = "{first_state or "start"}";
+
+    // DOM Elements
+    const descriptionEl = document.getElementById('story-description');
+    const choicesContainer = document.getElementById('choices-container');
+    const arTitle = document.getElementById('ar-title');
+
+    // Show state
+    function showState(stateName) {{
+        const state = STORY_STATES[stateName];
+        if (!state) {{
+            console.error("State not found:", stateName);
+            return;
+        }}
+
+        // Update UI
+        descriptionEl.textContent = state.description;
+
+        // Clear and create choice buttons
+        choicesContainer.innerHTML = '';
+        state.choices.forEach((choice, index) => {{
+            const btn = document.createElement('button');
+            btn.className = 'choice-btn';
+            btn.textContent = choice;
+            btn.onclick = () => makeChoice(index);
+            choicesContainer.appendChild(btn);
+        }});
+
+        // Update AR content (customize this!)
+        if (arTitle) {{
+            arTitle.setAttribute('value', state.location);
+        }}
+
+        currentState = stateName;
+        console.log("State:", stateName);
+    }}
+
+    // Handle choice
+    function makeChoice(index) {{
+        const state = STORY_STATES[currentState];
+        if (!state || index >= state.choices.length) return;
+
+        const choiceText = state.choices[index];
+        const nextState = state.transitions[choiceText];
+
+        if (nextState) {{
+            showState(nextState);
+        }}
+    }}
+
+    // Initialize when scene loads
+    document.querySelector('a-scene').addEventListener('loaded', () => {{
+        showState(currentState);
+    }});
+    </script>
+</body>
+</html>
+'''
+
+    explanation = """8th Wall WebAR Export Generated!
+
+Setup Instructions:
+1. Create account at https://www.8thwall.com/
+2. Create new Web project
+3. Get your App Key from dashboard
+4. Replace YOUR_APP_KEY in the HTML
+5. Upload to 8th Wall hosting or your own server
+
+Key Features:
+- Works in mobile browser (no app needed!)
+- A-Frame for 3D content
+- Responsive story UI overlay
+- World tracking enabled
+
+Customization:
+- Add 3D models in <a-entity> tags
+- Modify CSS for different UI styles
+- Add sounds with <a-sound> elements
+- Use xrextras components for AR features
+
+Testing:
+- Use 8th Wall's built-in hosting
+- Scan QR code on mobile device
+- Test on iOS Safari and Android Chrome
+
+Hosting Options:
+1. 8th Wall hosting (included with subscription)
+2. Your own HTTPS server
+3. GitHub Pages (free, needs HTTPS)
+
+Requirements:
+- 8th Wall subscription for App Key
+- HTTPS hosting (required for camera access)
+- Mobile device with camera
+
+Alternative (Free Testing):
+- Remove 8th Wall script
+- Use basic A-Frame only
+- Won't have advanced AR features
+
+Reach: 1B+ WebAR experiences served
+"""
+
+    return explanation, html_code
+
+
+def export_to_tiktok(config_json):
+    """Export game config to TikTok Effect House JavaScript format."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except json.JSONDecodeError as e:
+        return f"JSON Error: {str(e)}", ""
+
+    js_code = '''// TikTok Effect House - Interactive Story Effect
+// Generated from Game Config IDE
+//
+// Setup in Effect House:
+// 1. Create new project
+// 2. Add Visual Scripting or Script component
+// 3. Paste this code
+
+const Scene = require('Scene');
+const Time = require('Time');
+const Patches = require('Patches');
+const Diagnostics = require('Diagnostics');
+const TouchGestures = require('TouchGestures');
+
+const STORY_STATES = {
+'''
+
+    first_state = None
+
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    state_name = f"{location_key}_{state_key}"
+                    if first_state is None:
+                        first_state = state_name
+
+                    description = state_data.get('description', '').replace('"', '\\"').replace('\n', '\\n')
+                    choices = state_data.get('choices', [])
+                    transitions = state_data.get('transitions', {})
+
+                    js_code += f'    "{state_name}": {{\n'
+                    js_code += f'        description: "{description}",\n'
+                    js_code += '        choices: ['
+                    if choices:
+                        js_code += ', '.join([f'"{c}"' for c in choices])
+                    js_code += '],\n'
+                    js_code += '        transitions: {'
+                    if isinstance(transitions, dict):
+                        trans_items = []
+                        for choice, next_state in transitions.items():
+                            if next_state:
+                                if '_' not in next_state:
+                                    next_state = f"{location_key}_{next_state}"
+                                trans_items.append(f'"{choice}": "{next_state}"')
+                        js_code += ', '.join(trans_items)
+                    js_code += '}\n'
+                    js_code += '    },\n'
+
+    js_code += f'''}};
+
+let currentState = "{first_state or "start"}";
+let choiceIndex = 0;
+
+(async function() {{
+    const storyText = await Scene.root.findFirst('storyText');
+    const choiceTexts = await Promise.all([
+        Scene.root.findFirst('choice1'),
+        Scene.root.findFirst('choice2'),
+        Scene.root.findFirst('choice3')
+    ]);
+
+    function showState(stateName) {{
+        const state = STORY_STATES[stateName];
+        if (!state) return;
+        if (storyText) storyText.text = state.description;
+        choiceTexts.forEach((t, i) => {{
+            if (t) t.text = i < state.choices.length ? state.choices[i] : '';
+        }});
+        currentState = stateName;
+        choiceIndex = 0;
+        Diagnostics.log('State: ' + stateName);
+    }}
+
+    let lastTap = 0;
+    TouchGestures.onTap().subscribe(() => {{
+        const now = Date.now();
+        const state = STORY_STATES[currentState];
+        if (now - lastTap < 300 && state.choices.length > 0) {{
+            const next = state.transitions[state.choices[choiceIndex]];
+            if (next) showState(next);
+        }} else if (state.choices.length > 0) {{
+            choiceIndex = (choiceIndex + 1) % state.choices.length;
+            Patches.inputs.setScalar('currentChoice', choiceIndex);
+        }}
+        lastTap = now;
+    }});
+
+    showState(currentState);
+}})();
+'''
+
+    explanation = """TikTok Effect House Export Generated!
+
+Setup:
+1. Download Effect House: https://effecthouse.tiktok.com/
+2. Create new project
+3. Add Script component
+4. Paste this code
+
+Interaction:
+- Single tap: Cycle through choices
+- Double tap: Select current choice
+
+Scene Objects:
+- storyText: 2D Text for description
+- choice1, choice2, choice3: Choice text objects
+
+Testing:
+- Preview in Effect House
+- Send to TikTok app
+
+Publishing:
+- Submit via Effect House
+- 1B+ TikTok users reach
+"""
+
+    return explanation, js_code
+
+
+def export_to_reality(config_json):
+    """Export game config to Apple Reality Composer Pro / RealityKit Swift format."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except json.JSONDecodeError as e:
+        return f"JSON Error: {str(e)}", ""
+
+    swift_code = '''import SwiftUI
+import RealityKit
+
+// Story Adventure for visionOS / iOS AR
+// Generated from Game Config IDE
+
+struct StoryState: Identifiable {
+    let id: String
+    let description: String
+    let choices: [String]
+    let transitions: [String: String]
+}
+
+class StoryManager: ObservableObject {
+    @Published var currentStateId: String
+    let states: [String: StoryState]
+
+    init() {
+        var stateDict: [String: StoryState] = [:]
+'''
+
+    first_state = None
+
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    state_name = f"{location_key}_{state_key}"
+                    if first_state is None:
+                        first_state = state_name
+
+                    description = state_data.get('description', '').replace('"', '\\"')
+                    choices = state_data.get('choices', [])
+                    transitions = state_data.get('transitions', {})
+
+                    choices_str = ', '.join([f'"{c}"' for c in choices])
+                    trans_items = []
+                    if isinstance(transitions, dict):
+                        for choice, next_state in transitions.items():
+                            if next_state:
+                                if '_' not in next_state:
+                                    next_state = f"{location_key}_{next_state}"
+                                trans_items.append(f'"{choice}": "{next_state}"')
+
+                    swift_code += f'\n        stateDict["{state_name}"] = StoryState(id: "{state_name}", description: "{description}", choices: [{choices_str}], transitions: [{", ".join(trans_items)}])\n'
+
+    swift_code += f'''
+        self.states = stateDict
+        self.currentStateId = "{first_state or "start"}"
+    }}
+
+    var currentState: StoryState? {{ states[currentStateId] }}
+
+    func makeChoice(_ choice: String) {{
+        guard let next = currentState?.transitions[choice] else {{ return }}
+        currentStateId = next
+    }}
+}}
+
+struct StoryView: View {{
+    @StateObject private var manager = StoryManager()
+
+    var body: some View {{
+        VStack(spacing: 20) {{
+            if let state = manager.currentState {{
+                Text(state.description)
+                    .font(.title3)
+                    .padding()
+                ForEach(state.choices, id: \\.self) {{ choice in
+                    Button(choice) {{ manager.makeChoice(choice) }}
+                        .buttonStyle(.borderedProminent)
+                }}
+            }}
+        }}
+        .padding()
+    }}
+}}
+
+#Preview {{ StoryView() }}
+'''
+
+    explanation = """Apple Reality / visionOS Export Generated!
+
+Setup:
+1. Create visionOS or iOS project in Xcode 15+
+2. Add this Swift file
+3. Use StoryView in your app
+
+Requirements:
+- Xcode 15+
+- iOS 17+ / visionOS 1.0+
+- Swift 5.9+
+
+For Vision Pro:
+- Wrap in RealityView for spatial
+- Add 3D content per state
+
+Testing:
+- visionOS Simulator
+- iOS device with AR
+
+Distribution:
+- App Store
+"""
+
+    return explanation, swift_code

exporters/fiction_exporters.py

@@ -0,0 +1,140 @@
+"""Interactive fiction exporters for game configs.
+
+Includes exporters for:
+- Inform 7 natural language format
+- Godot Dialogue Manager format
+"""
+
+import json
+
+
+def export_to_inform7(config_json):
+    """Export game config to Inform 7 natural language format."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except json.JSONDecodeError as e:
+        return f"JSON Error: {str(e)}", ""
+
+    i7_code = '''"Story Adventure" by "Game Config IDE"
+
+'''
+
+    locations = {}
+    first_room = None
+
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            room_name = location_key.replace('_', ' ').title()
+            if first_room is None:
+                first_room = room_name
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    desc = state_data.get('description', f'You are in {room_name}.').replace('"', "'")
+                    locations[room_name] = desc
+                    break
+
+    for room_name, desc in locations.items():
+        i7_code += f'{room_name} is a room. "{desc}"\n\n'
+
+    if first_room:
+        i7_code += f"The player is in {first_room}.\n\n"
+
+    # Generate actions for choices
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    choices = state_data.get('choices', [])
+                    transitions = state_data.get('transitions', {})
+
+                    for choice in choices:
+                        action_name = choice.lower().replace(' ', '-')[:20]
+                        next_state = transitions.get(choice, '') if isinstance(transitions, dict) else ''
+
+                        i7_code += f'{action_name.replace("-", " ")}ing is an action applying to nothing.\n'
+                        i7_code += f'Understand "{choice.lower()}" as {action_name}ing.\n'
+                        i7_code += f'Carry out {action_name}ing: say "You chose: {choice}."\n\n'
+
+    explanation = """Inform 7 Interactive Fiction Export Generated!
+
+Setup:
+1. Download Inform 7: http://inform7.com/
+2. Create new project
+3. Paste code in Source panel
+4. Click "Go!" to compile
+
+Online Testing:
+- Borogove: https://borogove.app/
+
+Distribution:
+- Compile to .z8 or .gblorb
+- Upload to IFDB
+"""
+
+    return explanation, i7_code
+
+
+def export_to_godot_dialogue(config_json):
+    """Export game config to Godot Dialogue Manager format."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except json.JSONDecodeError as e:
+        return f"JSON Error: {str(e)}", ""
+
+    dialogue_code = '# Godot Dialogue Manager - story.dialogue\n\n'
+
+    first_title = None
+
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    title = f"{location_key}_{state_key}"
+                    if first_title is None:
+                        first_title = title
+
+                    description = state_data.get('description', '')
+                    choices = state_data.get('choices', [])
+                    transitions = state_data.get('transitions', {})
+
+                    dialogue_code += f"~ {title}\n"
+                    dialogue_code += f"{description}\n"
+
+                    if choices:
+                        for choice in choices:
+                            next_state = transitions.get(choice, '') if isinstance(transitions, dict) else ''
+                            if next_state:
+                                if '_' not in next_state:
+                                    next_state = f"{location_key}_{next_state}"
+                                dialogue_code += f"- {choice} => {next_state}\n"
+                            else:
+                                dialogue_code += f"- {choice} => END\n"
+                    else:
+                        dialogue_code += "=> END\n"
+
+                    dialogue_code += "\n"
+
+    explanation = f"""Godot Dialogue Manager Export Generated!
+
+Setup:
+1. Install "Dialogue Manager" addon from AssetLib
+2. Save as story.dialogue
+3. Use in GDScript:
+
+DialogueManager.show_dialogue_balloon(
+    preload("res://story.dialogue"),
+    "{first_title or "start"}"
+)
+
+Syntax:
+- ~ title : Node start
+- Text : Dialogue line
+- - Choice => target : Player choice
+- => END : End dialogue
+
+Requirements:
+- Godot 4.0+
+- Dialogue Manager addon
+"""
+
+    return explanation, dialogue_code

exporters/flutter_exporter.py

@@ -0,0 +1,124 @@
+"""Flutter/Dart exporter for game configs."""
+
+import json
+
+
+def export_to_flutter(config_json):
+    """Export config to Flutter/Dart code."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except:
+        return "Error: Invalid JSON", ""
+
+    dart = '''// Flutter Text Adventure Game
+// Add to your lib/main.dart or create lib/game_state.dart
+
+import 'package:flutter/material.dart';
+
+// ========== GAME CONFIG ==========
+final Map<String, Map<String, dynamic>> gameConfig = ''' + json.dumps(config, indent=2).replace('true', 'true').replace('false', 'false').replace('null', 'null') + ''';
+
+// ========== GAME STATE ==========
+class GameState extends ChangeNotifier {
+  String currentLocation = "''' + list(config.keys())[0] + '''";
+  String currentState = "''' + list(config[list(config.keys())[0]].keys())[0] + '''";
+  List<String> inventory = [];
+  int money = 0;
+  Map<String, bool> flags = {};
+
+  Map<String, dynamic>? get currentStateData {
+    return gameConfig[currentLocation]?[currentState];
+  }
+
+  String get description => currentStateData?['description'] ?? 'No description';
+
+  List<String> get choices =>
+      List<String>.from(currentStateData?['choices'] ?? []);
+
+  void makeChoice(int index) {
+    if (index < 0 || index >= choices.length) return;
+
+    String choice = choices[index];
+    var transitions = currentStateData?['transitions'] as Map<String, dynamic>?;
+
+    if (transitions != null && transitions.containsKey(choice)) {
+      String nextState = transitions[choice].toString();
+      if (nextState.contains('/')) {
+        var parts = nextState.split('/');
+        currentLocation = parts[0];
+        currentState = parts[1];
+      } else {
+        currentState = nextState;
+      }
+      notifyListeners();
+    }
+  }
+}
+
+// ========== GAME SCREEN WIDGET ==========
+class GameScreen extends StatelessWidget {
+  final GameState gameState;
+
+  const GameScreen({Key? key, required this.gameState}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return ListenableBuilder(
+      listenable: gameState,
+      builder: (context, child) {
+        return Scaffold(
+          appBar: AppBar(title: Text(gameState.currentLocation)),
+          body: Padding(
+            padding: const EdgeInsets.all(16.0),
+            child: Column(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              children: [
+                Text(
+                  gameState.description,
+                  style: Theme.of(context).textTheme.bodyLarge,
+                ),
+                const SizedBox(height: 24),
+                const Text('What do you do?',
+                    style: TextStyle(fontWeight: FontWeight.bold)),
+                const SizedBox(height: 8),
+                ...gameState.choices.asMap().entries.map((entry) {
+                  return Padding(
+                    padding: const EdgeInsets.symmetric(vertical: 4),
+                    child: ElevatedButton(
+                      onPressed: () => gameState.makeChoice(entry.key),
+                      child: Text(entry.value),
+                    ),
+                  );
+                }).toList(),
+              ],
+            ),
+          ),
+        );
+      },
+    );
+  }
+}
+
+// ========== MAIN APP ==========
+void main() {
+  runApp(MaterialApp(
+    home: GameScreen(gameState: GameState()),
+    theme: ThemeData.dark(),
+  ));
+}
+'''
+
+    explanation = """Flutter/Dart Export:
+
+1. Create new Flutter project: flutter create text_adventure
+2. Replace lib/main.dart with this code
+3. Run: flutter run
+
+Features:
+- Uses ChangeNotifier for state management
+- Responsive button-based choices
+- Dark theme by default
+
+For mobile: flutter build apk (Android) or flutter build ios"""
+
+    return explanation, dart

exporters/game_platform_exporters.py

@@ -0,0 +1,633 @@
+"""Game platform exporters for game configs.
+
+Includes exporters for:
+- Minecraft Datapack
+- Skyrim/Fallout 4 Papyrus
+- VRChat UdonSharp
+"""
+
+import json
+
+
+def export_to_minecraft(config_json):
+    """Export game config to Minecraft Datapack format (mcfunction + JSON)."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except json.JSONDecodeError as e:
+        return f"JSON Error: {str(e)}", ""
+
+    # Generate datapack structure as a combined output
+    output = '''# ========================================
+# MINECRAFT DATAPACK - Story Adventure
+# Generated from Game Config IDE
+# ========================================
+#
+# FOLDER STRUCTURE:
+# story_adventure/
+# ├── pack.mcmeta
+# ├── data/
+# │   └── story/
+# │       ├── functions/
+# │       │   ├── init.mcfunction
+# │       │   ├── tick.mcfunction
+# │       │   └── states/
+# │       │       └── [state].mcfunction
+# │       └── advancements/
+# │           └── root.json
+#
+# INSTALLATION:
+# 1. Create folder: .minecraft/saves/[world]/datapacks/story_adventure/
+# 2. Create the folder structure above
+# 3. Copy each file section below to the corresponding file
+# ========================================
+
+### FILE: pack.mcmeta ###
+{
+    "pack": {
+        "pack_format": 26,
+        "description": "Story Adventure - Interactive narrative datapack"
+    }
+}
+
+### FILE: data/story/functions/init.mcfunction ###
+# Initialize story system
+# Run once: /function story:init
+
+# Create scoreboard objectives
+scoreboard objectives add story_state dummy "Current State"
+scoreboard objectives add story_choice dummy "Player Choice"
+
+# Set initial state (0 = first state)
+scoreboard players set @a story_state 0
+scoreboard players set @a story_choice 0
+
+# Notify players
+tellraw @a {"text":"[Story] Adventure initialized! Use /trigger story_choice to make choices.","color":"gold"}
+
+# Enable trigger for choices
+scoreboard objectives add story_trigger trigger "Make Choice"
+scoreboard players enable @a story_trigger
+
+### FILE: data/story/functions/tick.mcfunction ###
+# Main tick function - checks for player choices
+# Add to tick.json or run periodically
+
+# Check if any player made a choice
+execute as @a[scores={story_trigger=1..}] run function story:process_choice
+scoreboard players set @a story_trigger 0
+scoreboard players enable @a story_trigger
+
+### FILE: data/story/functions/process_choice.mcfunction ###
+# Process player choice based on current state
+# Called when player uses /trigger story_trigger set [choice_number]
+
+'''
+
+    # Generate state functions
+    state_index = 0
+    state_map = {}  # Map state names to indices
+
+    # First pass: assign indices to states
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    state_name = f"{location_key}_{state_key}"
+                    state_map[state_name] = state_index
+                    state_index += 1
+
+    # Second pass: generate state functions
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    state_name = f"{location_key}_{state_key}"
+                    state_idx = state_map[state_name]
+                    description = state_data.get('description', 'No description').replace('"', '\\"')
+                    choices = state_data.get('choices', [])
+                    transitions = state_data.get('transitions', {})
+
+                    output += f"\n### FILE: data/story/functions/states/{state_name}.mcfunction ###\n"
+                    output += f"# State: {state_name} (index {state_idx})\n\n"
+
+                    # Display description
+                    output += f'tellraw @s {{"text":"\\n=== {location_key.upper()} ===\\n","color":"yellow","bold":true}}\n'
+                    output += f'tellraw @s {{"text":"{description}\\n","color":"white"}}\n'
+
+                    # Display choices
+                    if choices:
+                        output += f'tellraw @s {{"text":"\\nChoices:","color":"green"}}\n'
+                        for i, choice in enumerate(choices):
+                            choice_escaped = choice.replace('"', '\\"')
+                            output += f'tellraw @s {{"text":"[{i+1}] {choice_escaped}","color":"aqua","clickEvent":{{"action":"run_command","value":"/trigger story_trigger set {i+1}"}}}}\n'
+
+                    output += "\n"
+
+    # Generate process_choice logic
+    output += "\n### FILE: data/story/functions/process_choice.mcfunction (continued) ###\n"
+    output += "# Add state transition logic here\n\n"
+
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    state_name = f"{location_key}_{state_key}"
+                    state_idx = state_map[state_name]
+                    choices = state_data.get('choices', [])
+                    transitions = state_data.get('transitions', {})
+
+                    output += f"# From state: {state_name} ({state_idx})\n"
+                    for i, choice in enumerate(choices):
+                        next_state = transitions.get(choice, '') if isinstance(transitions, dict) else ''
+                        if next_state:
+                            if '_' not in next_state:
+                                next_state = f"{location_key}_{next_state}"
+                            if next_state in state_map:
+                                next_idx = state_map[next_state]
+                                output += f"execute as @s[scores={{story_state={state_idx},story_trigger={i+1}}}] run scoreboard players set @s story_state {next_idx}\n"
+                                output += f"execute as @s[scores={{story_state={next_idx}}}] run function story:states/{next_state}\n"
+
+    # Add start command
+    output += '''
+
+### FILE: data/story/functions/start.mcfunction ###
+# Start the story - run with /function story:start
+function story:init
+'''
+
+    first_state = list(state_map.keys())[0] if state_map else "start"
+    output += f"function story:states/{first_state}\n"
+
+    explanation = """Minecraft Datapack Export Generated!
+
+Installation:
+1. Navigate to: .minecraft/saves/[world]/datapacks/
+2. Create folder: story_adventure
+3. Create the folder structure shown above
+4. Copy each ### FILE: ### section to its file
+5. Run: /reload in-game
+
+Commands:
+- /function story:start - Begin the adventure
+- /function story:init - Reset/initialize
+- Click choices in chat or use /trigger story_trigger set [number]
+
+Requirements:
+- Minecraft Java Edition 1.20.4+
+- pack_format 26 (adjust for your version)
+- Command blocks enabled (for automation)
+
+Testing:
+- Use /reload after changes
+- Check /datapack list to verify loaded
+- Use F3+T to reload resources
+
+Multiplayer:
+- Each player has independent state
+- Uses scoreboards for tracking
+- Works on servers with datapacks enabled
+
+Customization:
+- Add sounds with /playsound
+- Add particles with /particle
+- Spawn entities for NPCs
+- Use /title for dramatic text
+"""
+
+    return explanation, output
+
+
+def export_to_papyrus(config_json):
+    """Export game config to Skyrim/Fallout 4 Papyrus script format."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except json.JSONDecodeError as e:
+        return f"JSON Error: {str(e)}", ""
+
+    psc_code = '''Scriptname StoryAdventure extends Quest
+{Story Adventure System - Generated from Game Config IDE}
+
+; ========================================
+; PROPERTIES - Set these in Creation Kit
+; ========================================
+Message Property StartMessage Auto
+{Initial message to show player}
+
+Message[] Property StateMessages Auto
+{Array of messages for each state - create in CK}
+
+GlobalVariable Property CurrentStateIndex Auto
+{Tracks current state - create GlobalVariable in CK}
+
+; ========================================
+; STATE DATA
+; ========================================
+
+'''
+
+    # Generate state data
+    states = []
+    state_index = 0
+    state_map = {}
+
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    state_name = f"{location_key}_{state_key}"
+                    state_map[state_name] = state_index
+                    states.append({
+                        'name': state_name,
+                        'index': state_index,
+                        'description': state_data.get('description', ''),
+                        'choices': state_data.get('choices', []),
+                        'transitions': state_data.get('transitions', {}),
+                        'location': location_key
+                    })
+                    state_index += 1
+
+    # Add state constants
+    for state in states:
+        psc_code += f"int Property STATE_{state['name'].upper()} = {state['index']} AutoReadOnly\n"
+
+    psc_code += f'''
+int Property TOTAL_STATES = {len(states)} AutoReadOnly
+
+; ========================================
+; FUNCTIONS
+; ========================================
+
+Function StartStory()
+    {{Begin the story from the first state}}
+    CurrentStateIndex.SetValue(0)
+    ShowCurrentState()
+EndFunction
+
+Function ShowCurrentState()
+    {{Display the current state's message and choices}}
+    int stateIdx = CurrentStateIndex.GetValueInt()
+
+    If stateIdx >= 0 && stateIdx < StateMessages.Length
+        int result = StateMessages[stateIdx].Show()
+        ProcessChoice(stateIdx, result)
+    EndIf
+EndFunction
+
+Function ProcessChoice(int fromState, int choiceIndex)
+    {{Handle the player's choice and transition to next state}}
+
+    int nextState = -1
+
+'''
+
+    # Generate choice processing
+    for state in states:
+        psc_code += f"    ; From {state['name']}\n"
+        psc_code += f"    If fromState == {state['index']}\n"
+
+        transitions = state['transitions']
+        choices = state['choices']
+
+        for i, choice in enumerate(choices):
+            next_state = transitions.get(choice, '') if isinstance(transitions, dict) else ''
+            if next_state:
+                if '_' not in next_state:
+                    next_state = f"{state['location']}_{next_state}"
+                if next_state in state_map:
+                    psc_code += f"        If choiceIndex == {i}\n"
+                    psc_code += f"            nextState = {state_map[next_state]} ; -> {next_state}\n"
+                    psc_code += f"        EndIf\n"
+
+        psc_code += f"    EndIf\n\n"
+
+    psc_code += '''
+    ; Transition to next state
+    If nextState >= 0
+        CurrentStateIndex.SetValue(nextState)
+        ShowCurrentState()
+    Else
+        Debug.Notification("Story: No valid transition")
+    EndIf
+EndFunction
+
+Function ResetStory()
+    {Reset to beginning}
+    CurrentStateIndex.SetValue(0)
+EndFunction
+
+; ========================================
+; CREATION KIT MESSAGE TEMPLATES
+; ========================================
+; Create these Message forms in Creation Kit:
+;
+'''
+
+    # Add message templates as comments
+    for state in states:
+        desc = state['description'][:100].replace('\n', ' ')
+        psc_code += f"; Message: {state['name']}_MSG\n"
+        psc_code += f";   Message Text: \"{desc}...\"\n"
+        psc_code += f";   Buttons:\n"
+        for i, choice in enumerate(state['choices']):
+            psc_code += f";     [{i}] {choice}\n"
+        psc_code += ";\n"
+
+    explanation = """Skyrim/Fallout 4 Papyrus Export Generated!
+
+Setup in Creation Kit:
+1. Create new Quest (or use existing)
+2. Attach this script to the Quest
+3. Create Message forms for each state (see bottom of script)
+4. Create GlobalVariable for CurrentStateIndex
+5. Link properties in Quest script properties
+
+Message Form Setup:
+- Create one Message per state
+- Add buttons matching the choices
+- Link to StateMessages array property
+
+Triggering the Story:
+- Call StartStory() from dialogue, trigger, or spell
+- Example: StoryQuest.StartStory()
+
+Testing:
+- Use console: cqf StoryQuest StartStory
+- Or create test spell/item
+
+Requirements:
+- Creation Kit (free with game)
+- Papyrus compiler
+- Basic CK knowledge
+
+Mod Distribution:
+- Package as .esp + .psc/.pex files
+- Upload to Nexus Mods
+- 10M+ active Skyrim modders
+"""
+
+    return explanation, psc_code
+
+
+def export_to_vrchat(config_json):
+    """Export game config to VRChat UdonSharp format."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except json.JSONDecodeError as e:
+        return f"JSON Error: {str(e)}", ""
+
+    cs_code = '''using UdonSharp;
+using UnityEngine;
+using UnityEngine.UI;
+using VRC.SDKBase;
+using VRC.Udon;
+using TMPro;
+
+/// <summary>
+/// VRChat Story Adventure System
+/// Generated from Game Config IDE
+///
+/// Setup:
+/// 1. Create UdonSharpProgramAsset
+/// 2. Attach to GameObject in world
+/// 3. Link UI elements in Inspector
+/// </summary>
+public class StoryAdventure : UdonSharpBehaviour
+{
+    [Header("UI References")]
+    [SerializeField] private TextMeshProUGUI descriptionText;
+    [SerializeField] private Button[] choiceButtons;
+    [SerializeField] private TextMeshProUGUI[] choiceButtonTexts;
+
+    [Header("Audio (Optional)")]
+    [SerializeField] private AudioSource audioSource;
+    [SerializeField] private AudioClip[] stateAudioClips;
+
+    [Header("Settings")]
+    [SerializeField] private bool syncAcrossPlayers = false;
+
+    // State tracking
+    [UdonSynced] private int currentStateIndex = 0;
+    private string currentStateName = "";
+
+    // ========================================
+    // STATE DATA
+    // ========================================
+
+'''
+
+    # Generate state data
+    states = []
+    state_index = 0
+    state_map = {}
+
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    state_name = f"{location_key}_{state_key}"
+                    state_map[state_name] = state_index
+                    states.append({
+                        'name': state_name,
+                        'index': state_index,
+                        'description': state_data.get('description', '').replace('"', '\\"').replace('\n', '\\n'),
+                        'choices': state_data.get('choices', []),
+                        'transitions': state_data.get('transitions', {}),
+                        'location': location_key
+                    })
+                    state_index += 1
+
+    # State name constants
+    for state in states:
+        cs_code += f'    private const int STATE_{state["name"].upper()} = {state["index"]};\n'
+
+    cs_code += f'''
+    private const int TOTAL_STATES = {len(states)};
+
+    // State descriptions
+    private string[] stateDescriptions = new string[]
+    {{
+'''
+
+    for state in states:
+        cs_code += f'        "{state["description"]}",\n'
+
+    cs_code += '''    };
+
+    // State choices (jagged array workaround for Udon)
+    private string[][] stateChoices;
+
+    // ========================================
+    // INITIALIZATION
+    // ========================================
+
+    void Start()
+    {
+        InitializeChoices();
+        ShowState(currentStateIndex);
+    }
+
+    private void InitializeChoices()
+    {
+        stateChoices = new string[TOTAL_STATES][];
+
+'''
+
+    for state in states:
+        choices_str = ', '.join([f'"{c}"' for c in state['choices']])
+        cs_code += f'        stateChoices[{state["index"]}] = new string[] {{ {choices_str} }};\n'
+
+    cs_code += '''    }
+
+    // ========================================
+    // STATE DISPLAY
+    // ========================================
+
+    private void ShowState(int stateIndex)
+    {
+        if (stateIndex < 0 || stateIndex >= TOTAL_STATES) return;
+
+        currentStateIndex = stateIndex;
+
+        // Update description
+        if (descriptionText != null)
+        {
+            descriptionText.text = stateDescriptions[stateIndex];
+        }
+
+        // Update choice buttons
+        string[] choices = stateChoices[stateIndex];
+        for (int i = 0; i < choiceButtons.Length; i++)
+        {
+            if (i < choices.Length)
+            {
+                choiceButtons[i].gameObject.SetActive(true);
+                if (choiceButtonTexts[i] != null)
+                {
+                    choiceButtonTexts[i].text = choices[i];
+                }
+            }
+            else
+            {
+                choiceButtons[i].gameObject.SetActive(false);
+            }
+        }
+
+        // Play audio if available
+        if (audioSource != null && stateIndex < stateAudioClips.Length && stateAudioClips[stateIndex] != null)
+        {
+            audioSource.PlayOneShot(stateAudioClips[stateIndex]);
+        }
+
+        // Sync if enabled
+        if (syncAcrossPlayers)
+        {
+            RequestSerialization();
+        }
+    }
+
+    // ========================================
+    // CHOICE HANDLING
+    // ========================================
+
+    // Call these from button OnClick events
+    public void OnChoice0() { ProcessChoice(0); }
+    public void OnChoice1() { ProcessChoice(1); }
+    public void OnChoice2() { ProcessChoice(2); }
+    public void OnChoice3() { ProcessChoice(3); }
+
+    private void ProcessChoice(int choiceIndex)
+    {
+        int nextState = GetNextState(currentStateIndex, choiceIndex);
+        if (nextState >= 0)
+        {
+            ShowState(nextState);
+        }
+    }
+
+    private int GetNextState(int fromState, int choiceIndex)
+    {
+'''
+
+    # Generate transition logic
+    for state in states:
+        cs_code += f"        // From: {state['name']}\n"
+        cs_code += f"        if (fromState == {state['index']})\n"
+        cs_code += "        {\n"
+
+        transitions = state['transitions']
+        choices = state['choices']
+
+        for i, choice in enumerate(choices):
+            next_state = transitions.get(choice, '') if isinstance(transitions, dict) else ''
+            if next_state:
+                if '_' not in next_state:
+                    next_state = f"{state['location']}_{next_state}"
+                if next_state in state_map:
+                    cs_code += f"            if (choiceIndex == {i}) return {state_map[next_state]}; // -> {next_state}\n"
+
+        cs_code += "        }\n\n"
+
+    cs_code += '''
+        return -1; // No valid transition
+    }
+
+    // ========================================
+    // PUBLIC API
+    // ========================================
+
+    public void ResetStory()
+    {
+        ShowState(0);
+    }
+
+    public override void OnDeserialization()
+    {
+        // Sync state when variable is updated
+        if (syncAcrossPlayers)
+        {
+            ShowState(currentStateIndex);
+        }
+    }
+}
+'''
+
+    explanation = """VRChat UdonSharp Export Generated!
+
+Setup in Unity:
+1. Create new UdonSharpProgramAsset
+2. Copy this code to the .cs file
+3. Create GameObject in scene
+4. Add UdonBehaviour component
+5. Link the UdonSharpProgramAsset
+6. Set up UI in Inspector
+
+UI Setup:
+- Canvas with TextMeshPro for description
+- Button array for choices (4 recommended)
+- Link to descriptionText, choiceButtons, choiceButtonTexts
+
+Button Events:
+- Button 0: OnClick -> UdonBehaviour.SendCustomEvent("OnChoice0")
+- Button 1: OnClick -> UdonBehaviour.SendCustomEvent("OnChoice1")
+- etc.
+
+Multiplayer Sync:
+- Enable syncAcrossPlayers for shared experience
+- Uses UdonSynced for state synchronization
+
+Requirements:
+- Unity 2019.4.31f1 (VRChat current)
+- VRChat SDK3 - Worlds
+- UdonSharp package
+
+Testing:
+- Use VRChat SDK control panel
+- Build & Test locally first
+- Check Udon console for errors
+
+Publishing:
+- Build and publish via VRChat SDK
+- 30K+ concurrent VR users
+"""
+
+    return explanation, cs_code

exporters/gamemaker_exporter.py

@@ -0,0 +1,103 @@
+"""GameMaker Studio 2 exporter for game configs."""
+
+import json
+
+
+def export_to_gamemaker(config_json):
+    """Export config to GameMaker GML script."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except:
+        return "Error: Invalid JSON", ""
+
+    gml = '''// GameMaker Studio 2 - Text Adventure Game
+// Create this in a persistent controller object
+
+// ========== GAME CONFIG ==========
+global.game_config = ds_map_create();
+'''
+
+    # Add states to config
+    for location, states in config.items():
+        for state_name, state_data in states.items():
+            state_key = f"{location}_{state_name}"
+            gml += f'\n// State: {state_key}\n'
+            gml += f'var state_{state_key} = ds_map_create();\n'
+            gml += f'ds_map_add(state_{state_key}, "description", "{state_data.get("description", "")[:100]}");\n'
+
+            choices = state_data.get("choices", [])
+            gml += f'var choices_{state_key} = ds_list_create();\n'
+            for choice in choices:
+                choice_escaped = str(choice).replace('"', '\\"')
+                gml += f'ds_list_add(choices_{state_key}, "{choice_escaped}");\n'
+            gml += f'ds_map_add_list(state_{state_key}, "choices", choices_{state_key});\n'
+            gml += f'ds_map_add_map(global.game_config, "{state_key}", state_{state_key});\n'
+
+    gml += '''
+// ========== GAME STATE ==========
+global.current_location = "''' + list(config.keys())[0] + '''";
+global.current_state = "''' + list(config[list(config.keys())[0]].keys())[0] + '''";
+global.inventory = ds_list_create();
+global.money = 0;
+
+// ========== GAME FUNCTIONS ==========
+function get_current_state() {
+    var state_key = global.current_location + "_" + global.current_state;
+    return ds_map_find_value(global.game_config, state_key);
+}
+
+function get_description() {
+    var state = get_current_state();
+    if (state != undefined) {
+        return ds_map_find_value(state, "description");
+    }
+    return "No description";
+}
+
+function get_choices() {
+    var state = get_current_state();
+    if (state != undefined) {
+        return ds_map_find_value(state, "choices");
+    }
+    return undefined;
+}
+
+function make_choice(choice_index) {
+    var choices = get_choices();
+    if (choices != undefined && choice_index < ds_list_size(choices)) {
+        // Handle transition logic here
+        show_debug_message("Choice made: " + ds_list_find_value(choices, choice_index));
+    }
+}
+
+// ========== DRAW EVENT (for obj_game_controller) ==========
+// In Draw GUI event:
+/*
+draw_set_font(fnt_game);
+draw_set_color(c_white);
+
+// Draw description
+draw_text_ext(50, 50, get_description(), 20, 700);
+
+// Draw choices
+var choices = get_choices();
+if (choices != undefined) {
+    for (var i = 0; i < ds_list_size(choices); i++) {
+        var choice_text = string(i + 1) + ". " + ds_list_find_value(choices, i);
+        draw_text(50, 200 + (i * 30), choice_text);
+    }
+}
+*/
+'''
+
+    explanation = """GameMaker Studio 2 Export:
+
+1. Create a new object: obj_game_controller
+2. Mark it as Persistent
+3. In Create event: paste the config and state code
+4. In Draw GUI event: use the drawing code
+5. In keyboard events: call make_choice() with player input
+
+The code uses ds_maps and ds_lists for state management."""
+
+    return explanation, gml

exporters/html_exporters.py

@@ -0,0 +1,596 @@
+"""HTML-based exporters for game configs.
+
+Includes exporters for:
+- 2D Map SVG visualization
+- MovingDotSpace interactive HTML game
+"""
+
+import json
+import os
+import math
+
+
+def export_to_2d_map(config_json):
+    """Export config to 2D map layout visualization."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except:
+        return "Error: Invalid JSON", ""
+
+    # Generate SVG map
+    locations = list(config.keys())
+    num_locations = len(locations)
+
+    svg_width = 800
+    svg_height = 600
+
+    svg = f'''<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {svg_width} {svg_height}">
+  <style>
+    .location {{ fill: #4a90d9; stroke: #2c5aa0; stroke-width: 2; }}
+    .location:hover {{ fill: #6ba3e0; }}
+    .label {{ font-family: Arial; font-size: 12px; fill: white; text-anchor: middle; }}
+    .connection {{ stroke: #666; stroke-width: 2; fill: none; }}
+  </style>
+  <rect width="100%" height="100%" fill="#1a1a2e"/>
+'''
+
+    # Calculate positions in a circle
+    center_x, center_y = svg_width // 2, svg_height // 2
+    radius = min(svg_width, svg_height) // 3
+
+    positions = {}
+    for i, location in enumerate(locations):
+        angle = (2 * math.pi * i) / num_locations - math.pi / 2
+        x = center_x + radius * math.cos(angle)
+        y = center_y + radius * math.sin(angle)
+        positions[location] = (x, y)
+
+    # Draw connections based on transitions
+    connections_drawn = set()
+    for location, states in config.items():
+        for state_name, state_data in states.items():
+            transitions = state_data.get("transitions", {})
+            for choice, target in transitions.items():
+                if isinstance(target, str) and "/" in target:
+                    target_loc = target.split("/")[0]
+                    if target_loc in positions:
+                        conn_key = tuple(sorted([location, target_loc]))
+                        if conn_key not in connections_drawn:
+                            x1, y1 = positions[location]
+                            x2, y2 = positions[target_loc]
+                            svg += f'  <line class="connection" x1="{x1}" y1="{y1}" x2="{x2}" y2="{y2}"/>\n'
+                            connections_drawn.add(conn_key)
+
+    # Draw location nodes
+    for location, (x, y) in positions.items():
+        num_states = len(config[location])
+        node_size = 30 + num_states * 5
+        svg += f'  <circle class="location" cx="{x}" cy="{y}" r="{node_size}"/>\n'
+        svg += f'  <text class="label" x="{x}" y="{y + 4}">{location}</text>\n'
+
+    svg += '</svg>'
+
+    # Also generate a text-based map
+    text_map = "=== 2D MAP LAYOUT ===\n\n"
+    text_map += "Locations and their states:\n"
+    for location, states in config.items():
+        text_map += f"\n[{location}]\n"
+        for state_name in states.keys():
+            text_map += f"  - {state_name}\n"
+
+    text_map += "\nConnections:\n"
+    for conn in connections_drawn:
+        text_map += f"  {conn[0]} <---> {conn[1]}\n"
+
+    explanation = """2D Map Export:
+
+The SVG shows your game's location layout:
+- Each circle is a location
+- Circle size = number of states in that location
+- Lines show connections between locations
+
+You can:
+1. Copy the SVG and open in a browser
+2. Use as a reference for level design
+3. Import into vector editors (Figma, Inkscape)"""
+
+    return explanation, svg
+
+
+def export_to_movingdotspace(config_json, autotravel=True):
+    """Export game config to a playable MovingDotSpace HTML file.
+
+    Converts the game config into an interactive 2D exploration game
+    where players use arrow keys to move and collide with targets to
+    trigger state-machine modals. Locations are locked until the player
+    transitions to them via game choices.
+
+    Args:
+        config_json: The game config JSON string or dict
+        autotravel: If True, teleport player to new locations on transition.
+                   If False, just unlock the location and player must walk there.
+    """
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except json.JSONDecodeError as e:
+        return f"JSON Error: {str(e)}", ""
+
+    # === EXTRACT STATS DATA FROM CONFIG ===
+    extracted_objectives = []
+    extracted_inventory = []
+    extracted_skills = []
+    starting_money = 1000  # Default
+
+    # Check for MovingDotSpace metadata (from Big RPG Scale export)
+    mds_meta = config.get("_movingdotspace_meta", {})
+    if mds_meta:
+        # Use metadata if available
+        extracted_inventory = mds_meta.get("inventory", [])
+        extracted_skills = mds_meta.get("skills", [])
+        extracted_objectives = mds_meta.get("objectives", [])
+        starting_money = mds_meta.get("startingMoney", 100)
+
+    # Also parse through config to find additional quests, items, skills, and money from on_enter effects
+    for location_key, location_data in config.items():
+        if location_key.startswith("_"):  # Skip metadata keys
+            continue
+        if not isinstance(location_data, dict):
+            continue
+
+        for state_key, state_data in location_data.items():
+            if not isinstance(state_data, dict):
+                continue
+
+            # Check on_enter effects for money and quests
+            on_enter = state_data.get("on_enter", {})
+            if isinstance(on_enter, dict):
+                # Extract starting money (override if found)
+                if "set_money" in on_enter:
+                    starting_money = on_enter["set_money"]
+
+                # Extract quests as objectives (add to existing)
+                if "start_mission" in on_enter:
+                    missions = on_enter["start_mission"]
+                    if isinstance(missions, list):
+                        for mission in missions:
+                            if not any(obj["id"] == mission for obj in extracted_objectives):
+                                extracted_objectives.append({
+                                    "id": mission.replace("_", " ").title(),
+                                    "name": f"Complete: {mission.replace('_', ' ').title()}",
+                                    "complete": False
+                                })
+                    elif isinstance(missions, str):
+                        if not any(obj["id"] == missions for obj in extracted_objectives):
+                            extracted_objectives.append({
+                                "id": missions.replace("_", " ").title(),
+                                "name": f"Complete: {missions.replace('_', ' ').title()}",
+                                "complete": False
+                            })
+
+                # Extract items added to inventory (add to existing)
+                if "add_item" in on_enter:
+                    items = on_enter["add_item"]
+                    if isinstance(items, list):
+                        for item in items:
+                            if isinstance(item, dict):
+                                extracted_inventory.append(item)
+                            elif isinstance(item, str):
+                                extracted_inventory.append({
+                                    "type": "item",
+                                    "name": item.replace("_", " ").title(),
+                                    "description": f"A {item.replace('_', ' ')}"
+                                })
+                    elif isinstance(items, str):
+                        extracted_inventory.append({
+                            "type": "item",
+                            "name": items.replace("_", " ").title(),
+                            "description": f"A {items.replace('_', ' ')}"
+                        })
+
+    # If no objectives found, add default exploration objective
+    if not extracted_objectives:
+        extracted_objectives.append({
+            "id": "Main",
+            "name": "Explore all locations",
+            "complete": False
+        })
+
+    # Generate targets from game config locations (exclude metadata and special UI locations)
+    # Special locations that are UI/menu states, not map targets:
+    # - game_start: intro state
+    # - inventory: player inventory UI
+    # - quest_journal: quest tracking UI
+    special_locations = {"_movingdotspace_meta", "game_start", "inventory", "quest_journal"}
+    targets = []
+    locations = [k for k in config.keys() if k not in special_locations and not k.startswith("_")]
+    first_location = locations[0] if locations else None
+
+    # Build a map of location keys to their display names for JS
+    location_map = {}
+
+    for i, location_key in enumerate(locations):
+        location_data = config[location_key]
+        display_name = location_key.replace("_", " ").title()
+        location_map[location_key] = display_name
+
+        # Calculate grid position (4 columns)
+        x = 150 + (i % 4) * 350
+        y = 150 + (i // 4) * 250
+
+        # Build modalStates from game config states
+        modal_states = {}
+        first_state = None
+
+        for state_key, state_data in location_data.items():
+            if not isinstance(state_data, dict):
+                continue
+
+            if first_state is None:
+                first_state = state_key
+
+            # Convert choices to items with actions
+            items = []
+            transitions = state_data.get("transitions", {})
+            for choice in state_data.get("choices", []):
+                # Get transition target for this choice
+                target_ref = transitions.get(choice, "close")
+
+                # Parse target reference - check if it's a cross-location transition
+                if isinstance(target_ref, str):
+                    if "/" in target_ref:
+                        # Format: "location/state" - check if location is different
+                        parts = target_ref.split("/", 1)
+                        target_location = parts[0]
+                        target_state = parts[1] if len(parts) > 1 else "arrive"
+
+                        if target_location != location_key:
+                            # Cross-location transition - mark with crossloc prefix
+                            action = f"crossloc:{target_ref}"
+                        else:
+                            # Same location - just use the state name
+                            action = target_state
+                    else:
+                        action = target_ref
+                else:
+                    action = "close"
+
+                items.append({
+                    "label": choice,
+                    "action": action
+                })
+
+            # Get image from media
+            media = state_data.get("media", {})
+            modal_img = media.get("image", "") if isinstance(media, dict) else ""
+
+            modal_states[state_key] = {
+                "title": state_key.replace("_", " ").title(),
+                "content": state_data.get("description", ""),
+                "items": items,
+                "consequences": [],
+                "modalimg": modal_img
+            }
+
+        # Create target with smmodal collision type
+        # Include locationKey for lock/unlock tracking
+        target = {
+            "name": display_name,
+            "locationKey": location_key,
+            "x": x,
+            "y": y,
+            "collisionType": "smmodal",
+            "modalStates": modal_states,
+            "locked": location_key != first_location  # Only first location unlocked
+        }
+        targets.append(target)
+
+    # Build the MovingDotSpace config structure with extracted stats
+    movingdot_config = {
+        "themes": {
+            "Exported Game": {
+                "background": "#2d3436",
+                "backgroundColor": "#2d3436",
+                "inventory": extracted_inventory,
+                "skills": extracted_skills,
+                "startingMoney": starting_money,
+                "autotravel": autotravel,
+                "persistentTargets": [],
+                "story": [{
+                    "part": 0,
+                    "objectives": extracted_objectives,
+                    "targets": targets
+                }],
+                "actions": {}
+            }
+        }
+    }
+
+    # Read the HTML template
+    template_path = os.path.join(os.path.dirname(__file__), "..", "MovingDotSpaceExport", "MovingDotSpaceStandalone.html")
+
+    try:
+        with open(template_path, 'r', encoding='utf-8') as f:
+            html_template = f.read()
+    except FileNotFoundError:
+        return "Error: MovingDotSpaceStandalone.html template not found", ""
+
+    # Convert config to JSON and create the initialization code
+    config_json_str = json.dumps(movingdot_config, indent=2)
+    location_map_json = json.dumps(location_map)
+
+    # Custom JS to handle location locking and cross-location transitions
+    autotravel_js = "true" if autotravel else "false"
+    init_code = f"""
+    // Auto-generated config from Game Config IDE
+    // This overrides the default themes after initial load
+    (function() {{
+      const exportedConfig = {config_json_str};
+      const locationMap = {location_map_json};
+
+      // Track unlocked locations
+      const unlockedLocations = new Set(['{first_location}']);
+
+      // Autotravel setting - if true, teleport to new locations; if false, just unlock them
+      let autotravelEnabled = {autotravel_js};
+
+      // Use setTimeout to ensure this runs after the default init()
+      setTimeout(function() {{
+        initMovingDotSpace(exportedConfig);
+
+        // Explicitly set stats from config after theme is loaded
+        const themeConfig = exportedConfig.themes['Exported Game'];
+        if (themeConfig) {{
+          // Set starting money
+          if (themeConfig.startingMoney !== undefined) {{
+            gameState.playerStats.money = themeConfig.startingMoney;
+          }}
+          // Ensure inventory is loaded
+          if (themeConfig.inventory && themeConfig.inventory.length > 0) {{
+            gameState.inventory = themeConfig.inventory;
+          }}
+          // Ensure skills are loaded
+          if (themeConfig.skills && themeConfig.skills.length > 0) {{
+            gameState.skills = themeConfig.skills;
+          }}
+          // Load objectives from story part 0 (they should already be there, but ensure)
+          const storyPart = themeConfig.story && themeConfig.story[0];
+          if (storyPart && storyPart.objectives) {{
+            gameState.objectives = storyPart.objectives;
+          }}
+          // Re-render stats to show updated values
+          renderStats();
+          console.log('Stats loaded:', {{
+            money: gameState.playerStats.money,
+            inventory: gameState.inventory.length,
+            skills: gameState.skills.length,
+            objectives: gameState.objectives.length
+          }});
+        }}
+
+        // Create autotravel toggle button
+        const controlsDiv = document.createElement('div');
+        controlsDiv.id = 'autotravel-controls';
+        controlsDiv.style.cssText = 'position: absolute; top: 10px; right: 10px; z-index: 1000; background: rgba(0,0,0,0.7); padding: 8px 12px; border-radius: 5px; color: white; font-size: 12px;';
+        controlsDiv.innerHTML = `
+          <label style="cursor: pointer; display: flex; align-items: center; gap: 6px;">
+            <input type="checkbox" id="autotravel-toggle" ${{autotravelEnabled ? 'checked' : ''}} style="cursor: pointer;">
+            <span>Autotravel</span>
+          </label>
+        `;
+        document.getElementById('game-container').appendChild(controlsDiv);
+
+        document.getElementById('autotravel-toggle').addEventListener('change', function(e) {{
+          autotravelEnabled = e.target.checked;
+          const status = autotravelEnabled ? 'ON - Will teleport to new locations' : 'OFF - Walk to unlocked locations manually';
+          elements.overlayText.textContent = 'Autotravel: ' + status;
+        }});
+
+        // Override the handleSMModalAction to support cross-location transitions
+        const originalHandleSMModalAction = window.handleSMModalAction || function() {{}};
+
+        window.handleSMModalActionCustom = function(item) {{
+          const action = item.action;
+
+          // Check for cross-location transition
+          if (action.startsWith('crossloc:')) {{
+            const fullRef = action.substring(9); // Remove "crossloc:"
+            const parts = fullRef.split('/');
+            const targetLocation = parts[0];
+            const targetState = parts[1];
+
+            // Unlock the target location
+            unlockedLocations.add(targetLocation);
+
+            // Update target visibility
+            updateTargetVisibility();
+
+            // Find the target element for that location
+            const targetData = gameState.targets.find(t => t.locationKey === targetLocation);
+            if (targetData) {{
+              // Close current modal first
+              closeSMModal();
+
+              if (autotravelEnabled) {{
+                // Autotravel ON: Teleport player near the target
+                gameState.dotPosition.x = targetData.x + 50;
+                gameState.dotPosition.y = targetData.y;
+                renderDot();
+
+                // After a brief delay, open the new location's modal at the target state
+                setTimeout(function() {{
+                  if (targetData.modalStates && targetData.modalStates[targetState]) {{
+                    gameState.currentSMModalStates = targetData.modalStates;
+                    gameState.currentSMModalState = targetState;
+                    gameState.isSMModalOpen = true;
+                    renderSMModalState();
+                    elements.smModal.classList.add('open');
+                  }}
+                }}, 300);
+              }} else {{
+                // Autotravel OFF: Just show message, player must walk there
+                const locationName = locationMap[targetLocation] || targetLocation;
+                elements.overlayText.textContent = `Unlocked: ${{locationName}}! Walk there using arrow keys.`;
+              }}
+            }}
+            return;
+          }}
+
+          // Check if action is a state transition within current modal
+          if (gameState.currentSMModalStates && gameState.currentSMModalStates[action]) {{
+            gameState.currentSMModalState = action;
+            renderSMModalState();
+          }} else if (action === 'close' || !gameState.currentSMModalStates) {{
+            // Explicit close or no modal states - just close
+            closeSMModal();
+          }} else {{
+            // Execute as action and close
+            executeAction(action);
+            closeSMModal();
+          }}
+        }};
+
+        // Override renderSMModalState to use our custom handler
+        const originalRenderSMModalState = window.renderSMModalState;
+        window.renderSMModalState = function() {{
+          const states = gameState.currentSMModalStates;
+          if (!states) {{
+            console.error("No modal states available");
+            return;
+          }}
+          const currentState = states[gameState.currentSMModalState];
+
+          if (!currentState) {{
+            console.error("State not found:", gameState.currentSMModalState);
+            return;
+          }}
+
+          elements.smModalTitle.textContent = currentState.title || '';
+          elements.smModalContent.textContent = currentState.content || '';
+
+          // Render actions with custom handler
+          elements.smModalActions.innerHTML = '';
+          (currentState.items || []).forEach(item => {{
+            const btn = document.createElement('button');
+            btn.textContent = item.label;
+            btn.addEventListener('click', () => handleSMModalActionCustom(item));
+            elements.smModalActions.appendChild(btn);
+          }});
+
+          // Handle image
+          if (currentState.modalimg) {{
+            elements.smModalImage.src = currentState.modalimg;
+            elements.smModalImage.style.display = 'block';
+          }} else {{
+            elements.smModalImage.style.display = 'none';
+          }}
+
+          // Execute consequences
+          (currentState.consequences || []).forEach(consequence => {{
+            executeAction(consequence);
+          }});
+        }};
+
+        // Function to update target visibility based on unlocked locations
+        function updateTargetVisibility() {{
+          const targetsContainer = document.getElementById('targets-container');
+          const targetElements = targetsContainer.querySelectorAll('.target');
+          const labelElements = targetsContainer.querySelectorAll('.target-label');
+
+          gameState.targets.forEach((target, index) => {{
+            const isUnlocked = unlockedLocations.has(target.locationKey);
+            target.locked = !isUnlocked;
+
+            // Find corresponding DOM elements
+            const targetEl = targetElements[index];
+            const labelEl = labelElements[index];
+
+            if (targetEl) {{
+              if (isUnlocked) {{
+                targetEl.style.backgroundColor = 'red';
+                targetEl.style.opacity = '1';
+                targetEl.style.pointerEvents = 'auto';
+              }} else {{
+                targetEl.style.backgroundColor = '#555';
+                targetEl.style.opacity = '0.4';
+              }}
+            }}
+            if (labelEl) {{
+              labelEl.style.opacity = isUnlocked ? '1' : '0.4';
+              if (!isUnlocked) {{
+                labelEl.textContent = target.name + ' (Locked)';
+              }} else {{
+                labelEl.textContent = target.name;
+              }}
+            }}
+          }});
+        }}
+
+        // Override handleCollision to check if location is unlocked
+        const originalHandleCollision = window.handleCollision;
+        window.handleCollision = function(target) {{
+          // Check if target is locked
+          if (target.locked) {{
+            elements.overlayText.textContent = 'This location is locked. Find a way to unlock it first!';
+            return;
+          }}
+          // Call original handler
+          originalHandleCollision(target);
+        }};
+
+        // Initial visibility update
+        setTimeout(updateTargetVisibility, 100);
+
+      }}, 50);
+    }})();
+    """
+
+    html_output = html_template.replace("/* CONFIG_PLACEHOLDER */", init_code)
+
+    # Build stats summary for explanation
+    stats_summary = []
+    if extracted_objectives:
+        stats_summary.append(f"{len(extracted_objectives)} objectives")
+    if extracted_inventory:
+        stats_summary.append(f"{len(extracted_inventory)} starting items")
+    stats_summary.append(f"{starting_money} starting gold")
+
+    autotravel_status = "ON (teleport to locations)" if autotravel else "OFF (walk manually)"
+
+    explanation = f"""MovingDotSpace Export:
+
+Created a playable 2D exploration game with {len(targets)} location targets.
+
+**Location Locking System:**
+- Only the first location ("{first_location}") is unlocked at start
+- Other locations appear grayed out with "(Locked)" label
+- When you select a choice that transitions to another location, it unlocks
+
+**Autotravel:** {autotravel_status}
+- Toggle checkbox in top-right corner to switch modes
+- ON: Automatically teleport to new locations when unlocked
+- OFF: Location unlocks but you must walk there with arrow keys
+
+**Stats Panel (bottom):**
+- {', '.join(stats_summary)}
+- Objectives extracted from quests/missions in your config
+- Inventory populated from on_enter add_item effects
+- Player stats with starting money from config
+
+**How to Play:**
+1. Save the HTML file and open in a browser
+2. Click the game area to focus it
+3. Use arrow keys to move the green dot
+4. Collide with red targets to trigger interactions
+5. Choose options that lead to new locations to unlock them
+6. Toggle autotravel checkbox to control movement style
+
+**Features:**
+- {len(targets)} interactive locations from your config
+- Progressive unlocking based on game choices
+- Cross-location transitions (e.g., "village/hub") handled automatically
+- State machine modals with your choices/transitions
+- Live stats panel with objectives, inventory, and player stats
+
+The HTML file is self-contained and can be shared directly."""
+
+    return explanation, html_output

exporters/ink_exporter.py

@@ -0,0 +1,86 @@
+"""Ink interactive fiction exporter for game configs."""
+
+import json
+
+
+def export_to_ink(config_json):
+    """Export game config to Ink interactive fiction format (.ink)."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except json.JSONDecodeError as e:
+        return f"JSON Error: {str(e)}", ""
+
+    ink_code = '''// Ink Interactive Story
+// Generated from Game Config IDE
+// Test at: https://www.inklestudios.com/ink/
+
+VAR current_location = ""
+
+'''
+
+    first_knot = None
+
+    # Generate knots (Ink's term for passages/labels)
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    knot_name = f"{location_key}_{state_key}"
+                    if first_knot is None:
+                        first_knot = knot_name
+
+                    description = state_data.get('description', 'No description')
+                    choices = state_data.get('choices', [])
+                    transitions = state_data.get('transitions', {})
+
+                    ink_code += f"=== {knot_name} ===\n"
+                    ink_code += f"~ current_location = \"{location_key}\"\n"
+                    ink_code += f"{description}\n\n"
+
+                    if choices:
+                        for choice in choices:
+                            next_state = transitions.get(choice, '') if isinstance(transitions, dict) else ''
+
+                            if next_state:
+                                if '_' not in next_state:
+                                    next_state = f"{location_key}_{next_state}"
+                                ink_code += f"* [{choice}] -> {next_state}\n"
+                            else:
+                                ink_code += f"* [{choice}]\n"
+                                ink_code += f"    You chose: {choice}\n"
+                                ink_code += f"    -> END\n"
+                    else:
+                        ink_code += "-> END\n"
+
+                    ink_code += "\n"
+
+    # Add start redirect at the top
+    if first_knot:
+        ink_code = f"-> {first_knot}\n\n" + ink_code
+
+    explanation = """Ink Interactive Fiction Export Generated!
+
+Setup Instructions:
+1. Install Inky editor: https://github.com/inkle/inky/releases
+2. Paste this code into Inky
+3. Click Play to test
+4. Export to JSON for game integration
+
+Online Testing:
+- Ink Playground: https://www.inklestudios.com/ink/
+- Paste code and click "Play"
+
+Integration Options:
+- Unity: Use ink-unity-integration package
+- Web: Use inkjs library
+- Godot: Use inkgd plugin
+
+Ink Syntax Reference:
+- === knot === : Named passage
+- * [choice] : Player choice
+- -> target : Redirect/jump
+- ~ var = value : Set variable
+- { condition: text } : Conditional text
+"""
+
+    return explanation, ink_code

exporters/renpy_exporter.py

@@ -0,0 +1,112 @@
+"""Ren'Py visual novel exporter for game configs."""
+
+import json
+
+
+def export_to_renpy(config_json):
+    """Export game config to Ren'Py visual novel format (.rpy)."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except json.JSONDecodeError as e:
+        return f"JSON Error: {str(e)}", ""
+
+    rpy_code = '''# Ren'Py Visual Novel Export
+# Generated from Game Config IDE
+
+init python:
+    # Game state tracking
+    game_flags = {}
+
+'''
+
+    # Track all labels for jump validation
+    all_labels = []
+    first_label = None
+
+    # First pass: collect all state names
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    label_name = f"{location_key}_{state_key}"
+                    all_labels.append(label_name)
+                    if first_label is None:
+                        first_label = label_name
+
+    # Add start label
+    rpy_code += f'''label start:
+    jump {first_label or "game_start"}
+
+'''
+
+    # Second pass: generate labels
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    label_name = f"{location_key}_{state_key}"
+                    description = state_data.get('description', 'No description').replace('"', '\\"')
+                    choices = state_data.get('choices', [])
+                    transitions = state_data.get('transitions', {})
+                    media = state_data.get('media', {})
+
+                    rpy_code += f"label {label_name}:\n"
+
+                    # Add scene/background if media exists
+                    if media.get('image'):
+                        img_name = media['image'].replace('saved_media/', '').replace('.', '_')
+                        rpy_code += f'    scene bg {img_name}\n'
+
+                    # Add description as narration
+                    rpy_code += f'    "{description}"\n\n'
+
+                    # Add choices menu
+                    if choices:
+                        rpy_code += "    menu:\n"
+                        for choice in choices:
+                            choice_escaped = choice.replace('"', '\\"')
+                            next_state = transitions.get(choice, '') if isinstance(transitions, dict) else ''
+
+                            rpy_code += f'        "{choice_escaped}":\n'
+
+                            if next_state:
+                                # Handle state references
+                                if '_' not in next_state:
+                                    next_state = f"{location_key}_{next_state}"
+                                if next_state in all_labels:
+                                    rpy_code += f'            jump {next_state}\n'
+                                else:
+                                    rpy_code += f'            # Target not found: {next_state}\n'
+                                    rpy_code += f'            "This path is not yet implemented."\n'
+                            else:
+                                rpy_code += f'            "You chose: {choice_escaped}"\n'
+                    else:
+                        rpy_code += "    return\n"
+
+                    rpy_code += "\n"
+
+    explanation = """Ren'Py Visual Novel Export Generated!
+
+Setup Instructions:
+1. Download Ren'Py from https://www.renpy.org/
+2. Create a new project
+3. Replace game/script.rpy with this code
+4. Add images to game/images/ folder
+5. Run the project
+
+Image Setup:
+- Place background images in game/images/
+- Name them to match the scene declarations
+- Supported formats: .png, .jpg, .webp
+
+Testing:
+- Use Ren'Py launcher to test
+- Press Shift+R to reload scripts
+- Use developer console for debugging
+
+Web Export:
+- Ren'Py can export to web (HTML5)
+- Use "Build Distributions" > "Web"
+"""
+
+    return explanation, rpy_code

exporters/roblox_exporter.py

@@ -0,0 +1,192 @@
+"""Roblox Lua exporter for game configs."""
+
+import json
+
+
+def export_to_roblox(config_json):
+    """Export game config to Roblox Lua format (ModuleScript + LocalScript)."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except json.JSONDecodeError as e:
+        return f"JSON Error: {str(e)}", ""
+
+    lua_code = '''--[[
+    Roblox Story System Export
+    Generated from Game Config IDE
+
+    Setup:
+    1. Create a ModuleScript in ReplicatedStorage named "StoryModule"
+    2. Paste this code
+    3. Create UI elements and connect to the module
+--]]
+
+local StoryModule = {}
+
+-- Story States Configuration
+StoryModule.States = {
+'''
+
+    first_state = None
+
+    # Generate states table
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    state_name = f"{location_key}_{state_key}"
+                    if first_state is None:
+                        first_state = state_name
+
+                    description = state_data.get('description', 'No description').replace('"', '\\"').replace('\n', '\\n')
+                    choices = state_data.get('choices', [])
+                    transitions = state_data.get('transitions', {})
+                    media = state_data.get('media', {})
+
+                    lua_code += f'    ["{state_name}"] = {{\n'
+                    lua_code += f'        Description = "{description}",\n'
+                    lua_code += f'        Location = "{location_key}",\n'
+
+                    # Choices array
+                    lua_code += '        Choices = {'
+                    if choices:
+                        choice_strs = [f'"{c}"' for c in choices]
+                        lua_code += ', '.join(choice_strs)
+                    lua_code += '},\n'
+
+                    # Transitions table
+                    lua_code += '        Transitions = {\n'
+                    if isinstance(transitions, dict):
+                        for choice, next_state in transitions.items():
+                            if next_state:
+                                if '_' not in next_state:
+                                    next_state = f"{location_key}_{next_state}"
+                                lua_code += f'            ["{choice}"] = "{next_state}",\n'
+                    lua_code += '        },\n'
+
+                    # Media table
+                    lua_code += '        Media = {\n'
+                    if media.get('image'):
+                        lua_code += f'            Image = "{media["image"]}",\n'
+                    if media.get('audio'):
+                        lua_code += f'            Audio = "{media["audio"]}",\n'
+                    lua_code += '        },\n'
+
+                    lua_code += '    },\n'
+
+    lua_code += f'''}}
+
+-- Starting state
+StoryModule.StartState = "{first_state or "start"}"
+
+-- Current state tracker
+local currentState = StoryModule.StartState
+
+-- Get current state data
+function StoryModule.GetCurrentState()
+    return StoryModule.States[currentState]
+end
+
+-- Get state by name
+function StoryModule.GetState(stateName)
+    return StoryModule.States[stateName]
+end
+
+-- Make a choice and transition to next state
+function StoryModule.MakeChoice(choiceText)
+    local state = StoryModule.States[currentState]
+    if state and state.Transitions[choiceText] then
+        currentState = state.Transitions[choiceText]
+        return true, StoryModule.States[currentState]
+    end
+    return false, nil
+end
+
+-- Reset to start
+function StoryModule.Reset()
+    currentState = StoryModule.StartState
+end
+
+-- Get all available choices for current state
+function StoryModule.GetChoices()
+    local state = StoryModule.States[currentState]
+    return state and state.Choices or {{}}
+end
+
+return StoryModule
+
+--[[
+    EXAMPLE LOCALSCRIPT (put in StarterPlayerScripts):
+
+    local ReplicatedStorage = game:GetService("ReplicatedStorage")
+    local StoryModule = require(ReplicatedStorage:WaitForChild("StoryModule"))
+    local Players = game:GetService("Players")
+    local player = Players.LocalPlayer
+    local playerGui = player:WaitForChild("PlayerGui")
+
+    -- Create simple UI
+    local screenGui = Instance.new("ScreenGui")
+    screenGui.Parent = playerGui
+
+    local descLabel = Instance.new("TextLabel")
+    descLabel.Size = UDim2.new(0.8, 0, 0.3, 0)
+    descLabel.Position = UDim2.new(0.1, 0, 0.1, 0)
+    descLabel.TextWrapped = true
+    descLabel.Parent = screenGui
+
+    local function updateUI()
+        local state = StoryModule.GetCurrentState()
+        descLabel.Text = state.Description
+
+        -- Clear old buttons
+        for _, child in pairs(screenGui:GetChildren()) do
+            if child:IsA("TextButton") then
+                child:Destroy()
+            end
+        end
+
+        -- Create choice buttons
+        for i, choice in ipairs(state.Choices) do
+            local btn = Instance.new("TextButton")
+            btn.Size = UDim2.new(0.3, 0, 0.08, 0)
+            btn.Position = UDim2.new(0.35, 0, 0.5 + (i-1) * 0.1, 0)
+            btn.Text = choice
+            btn.Parent = screenGui
+
+            btn.MouseButton1Click:Connect(function()
+                StoryModule.MakeChoice(choice)
+                updateUI()
+            end)
+        end
+    end
+
+    updateUI()
+--]]
+'''
+
+    explanation = """Roblox Lua Export Generated!
+
+Setup Instructions:
+1. Open Roblox Studio
+2. Create a ModuleScript in ReplicatedStorage named "StoryModule"
+3. Paste this code into the ModuleScript
+4. Create a LocalScript in StarterPlayerScripts for UI
+5. Use the example code at the bottom as a starting point
+
+Testing:
+- Use Play Solo (F5) to test
+- The example creates basic text UI
+- Customize with proper GUI elements
+
+API Reference:
+- StoryModule.GetCurrentState() : Get current state data
+- StoryModule.MakeChoice(choice) : Make a choice, returns success + new state
+- StoryModule.GetChoices() : Get available choices array
+- StoryModule.Reset() : Reset to start state
+
+Publishing:
+- Test in Studio first
+- Publish as Experience
+- Share via Roblox platform
+"""
+
+    return explanation, lua_code

exporters/router.py

@@ -0,0 +1,127 @@
+"""Router for config-to-platform exports.
+
+This module provides the main routing function that dispatches
+to the appropriate platform-specific exporter based on the
+platform identifier.
+"""
+
+import json
+
+# Import all exporters
+from .gamemaker_exporter import export_to_gamemaker
+from .flutter_exporter import export_to_flutter
+from .twine_exporter import export_to_twine
+from .renpy_exporter import export_to_renpy
+from .ink_exporter import export_to_ink
+from .yarn_exporter import export_to_yarn
+from .roblox_exporter import export_to_roblox
+from .rpgmaker_exporter import export_to_rpgmaker
+from .ar_exporters import (
+    export_to_lensstudio,
+    export_to_metaspark,
+    export_to_8thwall,
+    export_to_tiktok,
+    export_to_reality
+)
+from .game_platform_exporters import (
+    export_to_minecraft,
+    export_to_papyrus,
+    export_to_vrchat
+)
+from .fiction_exporters import (
+    export_to_inform7,
+    export_to_godot_dialogue
+)
+from .html_exporters import (
+    export_to_2d_map,
+    export_to_movingdotspace
+)
+from .terminal_exporter import export_to_terminal
+
+
+def ConfigConversionforExporttoPlatform(platform, config):
+    """Route config export to the appropriate platform-specific exporter.
+
+    Args:
+        platform: Platform identifier string (e.g., 'gamemaker', 'flutter', 'twine')
+        config: Game config JSON string or dict
+
+    Returns:
+        Tuple of (explanation, output_code)
+    """
+    FinalOutput = ""
+    FinalOutputExplanation = ""
+
+    # Import engine exporters from main module (these live in my_text_game_engine_attempt.py)
+    try:
+        from my_text_game_engine_attempt import (
+            export_to_playcanvas,
+            export_to_godot,
+            export_to_unreal
+        )
+        has_engine_exporters = True
+    except ImportError:
+        has_engine_exporters = False
+
+    if platform == "playcanvas" and has_engine_exporters:
+        FinalOutputExplanation, FinalOutput = export_to_playcanvas(config)
+    elif platform == "godot" and has_engine_exporters:
+        FinalOutputExplanation, FinalOutput = export_to_godot(config)
+    elif platform == "unreal" and has_engine_exporters:
+        FinalOutputExplanation, FinalOutput = export_to_unreal(config)
+    elif platform == "gamemaker":
+        FinalOutputExplanation, FinalOutput = export_to_gamemaker(config)
+    elif platform == "flutter":
+        FinalOutputExplanation, FinalOutput = export_to_flutter(config)
+    elif platform == "twine":
+        FinalOutputExplanation, FinalOutput = export_to_twine(config)
+    elif platform == "renpy":
+        FinalOutputExplanation, FinalOutput = export_to_renpy(config)
+    elif platform == "ink":
+        FinalOutputExplanation, FinalOutput = export_to_ink(config)
+    elif platform == "yarn":
+        FinalOutputExplanation, FinalOutput = export_to_yarn(config)
+    elif platform == "roblox":
+        FinalOutputExplanation, FinalOutput = export_to_roblox(config)
+    elif platform == "rpgmaker":
+        FinalOutputExplanation, FinalOutput = export_to_rpgmaker(config)
+    elif platform == "lensstudio":
+        FinalOutputExplanation, FinalOutput = export_to_lensstudio(config)
+    elif platform == "metaspark":
+        FinalOutputExplanation, FinalOutput = export_to_metaspark(config)
+    elif platform == "8thwall":
+        FinalOutputExplanation, FinalOutput = export_to_8thwall(config)
+    elif platform == "minecraft":
+        FinalOutputExplanation, FinalOutput = export_to_minecraft(config)
+    elif platform == "papyrus":
+        FinalOutputExplanation, FinalOutput = export_to_papyrus(config)
+    elif platform == "vrchat":
+        FinalOutputExplanation, FinalOutput = export_to_vrchat(config)
+    elif platform == "tiktok":
+        FinalOutputExplanation, FinalOutput = export_to_tiktok(config)
+    elif platform == "reality":
+        FinalOutputExplanation, FinalOutput = export_to_reality(config)
+    elif platform == "inform7":
+        FinalOutputExplanation, FinalOutput = export_to_inform7(config)
+    elif platform == "godot_dialogue":
+        FinalOutputExplanation, FinalOutput = export_to_godot_dialogue(config)
+    elif platform == "movingdotspace" or platform == "2d map related space":
+        FinalOutputExplanation, FinalOutput = export_to_movingdotspace(config)
+    elif platform == "terminal":
+        FinalOutputExplanation, FinalOutput = export_to_terminal(config)
+    elif platform == "existing game":
+        FinalOutput = """// Config for importing into existing game mod systems
+// Copy this JSON and use your game's import feature
+
+""" + (config if isinstance(config, str) else json.dumps(json.loads(config) if isinstance(config, str) else config, indent=2))
+        FinalOutputExplanation = """Existing Game Integration:
+
+Popular games with mod/custom content support:
+- Skyrim: Use Creation Kit, save as quest mod
+- GTA V: Use Script Hook V, convert to mission script
+- Sims 4: Use Mod Constructor, create story mod
+- Roblox: Use Roblox Studio, create experience
+
+The config JSON is provided above - convert it to your game's format."""
+
+    return FinalOutputExplanation, FinalOutput

exporters/rpgmaker_exporter.py

@@ -0,0 +1,247 @@
+"""RPG Maker MZ JavaScript plugin exporter for game configs."""
+
+import json
+
+
+def export_to_rpgmaker(config_json):
+    """Export game config to RPG Maker MZ JavaScript plugin format."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except json.JSONDecodeError as e:
+        return f"JSON Error: {str(e)}", ""
+
+    js_code = '''//=============================================================================
+// StoryAdventure.js - RPG Maker MZ Plugin
+// Generated from Game Config IDE
+//=============================================================================
+
+/*:
+ * @target MZ
+ * @plugindesc Story Adventure System - Branching narrative plugin
+ * @author Game Config IDE Export
+ *
+ * @command StartStory
+ * @text Start Story
+ * @desc Begin the story from the starting state
+ *
+ * @command ShowCurrentState
+ * @text Show Current State
+ * @desc Display the current state with choices
+ *
+ * @help
+ * This plugin provides a branching narrative system.
+ *
+ * Plugin Commands:
+ * - StartStory: Initialize and show first state
+ * - ShowCurrentState: Redisplay current state
+ *
+ * Script Calls:
+ * - $gameStory.setState("state_name")
+ * - $gameStory.makeChoice(index)
+ * - $gameStory.getCurrentState()
+ */
+
+(() => {
+    const pluginName = "StoryAdventure";
+
+    // Story States Data
+    const STORY_STATES = {
+'''
+
+    first_state = None
+
+    # Generate states
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    state_name = f"{location_key}_{state_key}"
+                    if first_state is None:
+                        first_state = state_name
+
+                    description = state_data.get('description', 'No description').replace('"', '\\"').replace('\n', '\\n')
+                    choices = state_data.get('choices', [])
+                    transitions = state_data.get('transitions', {})
+
+                    js_code += f'        "{state_name}": {{\n'
+                    js_code += f'            description: "{description}",\n'
+                    js_code += f'            location: "{location_key}",\n'
+
+                    # Choices array
+                    js_code += '            choices: ['
+                    if choices:
+                        choice_strs = [f'"{c}"' for c in choices]
+                        js_code += ', '.join(choice_strs)
+                    js_code += '],\n'
+
+                    # Transitions object
+                    js_code += '            transitions: {\n'
+                    if isinstance(transitions, dict):
+                        for choice, next_state in transitions.items():
+                            if next_state:
+                                if '_' not in next_state:
+                                    next_state = f"{location_key}_{next_state}"
+                                choice_escaped = choice.replace('"', '\\"')
+                                js_code += f'                "{choice_escaped}": "{next_state}",\n'
+                    js_code += '            }\n'
+                    js_code += '        },\n'
+
+    js_code += f'''    }};
+
+    const START_STATE = "{first_state or "start"}";
+
+    // Game Story Manager
+    class Game_Story {{
+        constructor() {{
+            this.initialize();
+        }}
+
+        initialize() {{
+            this._currentState = START_STATE;
+            this._visitedStates = [];
+        }}
+
+        getCurrentState() {{
+            return STORY_STATES[this._currentState];
+        }}
+
+        getStateName() {{
+            return this._currentState;
+        }}
+
+        setState(stateName) {{
+            if (STORY_STATES[stateName]) {{
+                this._currentState = stateName;
+                this._visitedStates.push(stateName);
+                return true;
+            }}
+            return false;
+        }}
+
+        makeChoice(choiceIndex) {{
+            const state = this.getCurrentState();
+            if (state && state.choices[choiceIndex]) {{
+                const choiceText = state.choices[choiceIndex];
+                const nextState = state.transitions[choiceText];
+                if (nextState) {{
+                    return this.setState(nextState);
+                }}
+            }}
+            return false;
+        }}
+
+        getChoices() {{
+            const state = this.getCurrentState();
+            return state ? state.choices : [];
+        }}
+
+        hasVisited(stateName) {{
+            return this._visitedStates.includes(stateName);
+        }}
+
+        reset() {{
+            this.initialize();
+        }}
+    }}
+
+    // Create global instance
+    window.$gameStory = null;
+
+    // Initialize on new game
+    const _DataManager_createGameObjects = DataManager.createGameObjects;
+    DataManager.createGameObjects = function() {{
+        _DataManager_createGameObjects.call(this);
+        $gameStory = new Game_Story();
+    }};
+
+    // Save story state
+    const _DataManager_makeSaveContents = DataManager.makeSaveContents;
+    DataManager.makeSaveContents = function() {{
+        const contents = _DataManager_makeSaveContents.call(this);
+        contents.story = {{
+            currentState: $gameStory._currentState,
+            visitedStates: $gameStory._visitedStates
+        }};
+        return contents;
+    }};
+
+    // Load story state
+    const _DataManager_extractSaveContents = DataManager.extractSaveContents;
+    DataManager.extractSaveContents = function(contents) {{
+        _DataManager_extractSaveContents.call(this, contents);
+        if (contents.story) {{
+            $gameStory._currentState = contents.story.currentState;
+            $gameStory._visitedStates = contents.story.visitedStates;
+        }}
+    }};
+
+    // Show story state as message with choices
+    function showStoryState() {{
+        const state = $gameStory.getCurrentState();
+        if (!state) return;
+
+        // Show description
+        $gameMessage.add(state.description);
+
+        // Set up choices if available
+        if (state.choices.length > 0) {{
+            $gameMessage.setChoices(state.choices, 0, -1);
+            $gameMessage.setChoiceCallback(n => {{
+                if (n >= 0) {{
+                    $gameStory.makeChoice(n);
+                    // Optionally auto-continue
+                    // showStoryState();
+                }}
+            }});
+        }}
+    }}
+
+    // Plugin Commands
+    PluginManager.registerCommand(pluginName, "StartStory", args => {{
+        $gameStory.reset();
+        showStoryState();
+    }});
+
+    PluginManager.registerCommand(pluginName, "ShowCurrentState", args => {{
+        showStoryState();
+    }});
+
+    // Export for script calls
+    window.Game_Story = Game_Story;
+    window.showStoryState = showStoryState;
+
+}})();
+'''
+
+    explanation = """RPG Maker MZ Plugin Export Generated!
+
+Setup Instructions:
+1. Save this as js/plugins/StoryAdventure.js
+2. Open RPG Maker MZ project
+3. Go to Plugin Manager (gear icon)
+4. Add "StoryAdventure" plugin
+5. Use Plugin Commands in events
+
+Plugin Commands:
+- StartStory: Begin from first state
+- ShowCurrentState: Show current state again
+
+Script Calls (in Event > Script):
+- $gameStory.setState("state_name")
+- $gameStory.makeChoice(0)  // choice index
+- $gameStory.getCurrentState()
+- $gameStory.getChoices()
+- $gameStory.hasVisited("state_name")
+- showStoryState()  // Show with message window
+
+Event Integration:
+- Use Conditional Branch to check states
+- Script: $gameStory.getStateName() === "village_start"
+- Combine with map transfers for location changes
+
+Saving:
+- Story progress auto-saves with game
+- Visited states tracked for conditionals
+"""
+
+    return explanation, js_code

exporters/terminal_exporter.py

@@ -0,0 +1,131 @@
+"""Python terminal game exporter for game configs."""
+
+import json
+
+
+def export_to_terminal(config_json):
+    """Export game config to standalone Python terminal game."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except json.JSONDecodeError as e:
+        return f"JSON Error: {str(e)}", ""
+
+    code = '''#!/usr/bin/env python3
+"""
+Auto-generated Terminal Text Adventure Game
+Run with: python game.py
+"""
+
+import json
+
+# Game configuration
+CONFIG = ''' + json.dumps(config, indent=2) + '''
+
+def get_state(location, state_name):
+    """Get state data from config."""
+    if location in CONFIG and state_name in CONFIG[location]:
+        return CONFIG[location][state_name]
+    return None
+
+def play_game():
+    """Main game loop."""
+    # Find starting location and state
+    current_location = list(CONFIG.keys())[0]
+    current_state = list(CONFIG[current_location].keys())[0]
+
+    inventory = []
+    flags = {}
+    money = 0
+
+    print("=" * 50)
+    print("TERMINAL TEXT ADVENTURE")
+    print("=" * 50)
+    print()
+
+    while True:
+        state = get_state(current_location, current_state)
+        if not state:
+            print(f"\\nGame Over - No state found: {current_location}/{current_state}")
+            break
+
+        # Display description
+        description = state.get("description", "No description")
+        print(f"\\n[{current_location.upper()} - {current_state}]")
+        print("-" * 40)
+        print(description)
+        print()
+
+        # Get choices
+        choices = state.get("choices", [])
+        if not choices:
+            print("\\n*** THE END ***")
+            break
+
+        # Display choices
+        print("What do you do?")
+        for i, choice in enumerate(choices, 1):
+            print(f"  {i}. {choice}")
+        print(f"  0. Quit game")
+
+        # Get player input
+        try:
+            choice_input = input("\\nEnter choice: ").strip()
+            if choice_input == "0":
+                print("\\nThanks for playing!")
+                break
+            choice_idx = int(choice_input) - 1
+            if 0 <= choice_idx < len(choices):
+                chosen = choices[choice_idx]
+                print(f"\\n> {chosen}")
+
+                # Handle transitions
+                transitions = state.get("transitions", {})
+                if chosen in transitions:
+                    next_state = transitions[chosen]
+                    if "/" in str(next_state):
+                        parts = next_state.split("/")
+                        current_location = parts[0]
+                        current_state = parts[1]
+                    else:
+                        current_state = next_state
+            else:
+                print("Invalid choice, try again.")
+        except ValueError:
+            print("Please enter a number.")
+        except KeyboardInterrupt:
+            print("\\n\\nGame interrupted. Goodbye!")
+            break
+
+if __name__ == "__main__":
+    play_game()
+'''
+
+    explanation = """Python Terminal Game Export Generated!
+
+How to Run:
+1. Save the code as 'game.py'
+2. Open terminal/command prompt
+3. Run: python game.py
+
+Requirements:
+- Python 3.6+
+- No external dependencies
+
+Features:
+- Text-based adventure gameplay
+- Choice-based navigation
+- State transitions from your config
+- Quit option (enter 0)
+
+Mobile Options:
+- Pydroid 3 (Android) - Run Python on phone
+- Pythonista (iOS) - Python IDE for iPhone/iPad
+- Replit Mobile - Cloud-based Python
+
+Web Hosting:
+- Replit.com - Host and share Python apps
+- PythonAnywhere - Free Python hosting
+- Google Colab - Run in browser (add input handling)
+"""
+
+    return explanation, code

exporters/twine_exporter.py

@@ -0,0 +1,127 @@
+"""Twine/SugarCube exporter for game configs."""
+
+import json
+
+
+def export_to_twine(config_json):
+    """Export game config to Twine/SugarCube HTML format."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except json.JSONDecodeError as e:
+        return f"JSON Error: {str(e)}", ""
+
+    # Build Twine passages
+    passages = []
+    first_passage = None
+
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    passage_name = f"{location_key}_{state_key}"
+                    if first_passage is None:
+                        first_passage = passage_name
+
+                    description = state_data.get('description', 'No description')
+                    choices = state_data.get('choices', [])
+                    transitions = state_data.get('transitions', {})
+
+                    # Build passage content
+                    content = f"{description}\n\n"
+
+                    # Add choices as links
+                    for choice in choices:
+                        if isinstance(transitions, dict):
+                            next_state = transitions.get(choice, '')
+                            if next_state:
+                                # Handle slash notation (location/state) -> convert to underscore
+                                if '/' in next_state:
+                                    next_state = next_state.replace('/', '_')
+                                # Handle state-only references (add current location prefix)
+                                elif '_' not in next_state or not any(next_state.startswith(loc) for loc in config.keys()):
+                                    # Check if it's just a state name within current location
+                                    if next_state in location_data:
+                                        next_state = f"{location_key}_{next_state}"
+                                content += f"[[{choice}|{next_state}]]\n"
+                            else:
+                                content += f"[[{choice}]]\n"
+                        else:
+                            content += f"[[{choice}]]\n"
+
+                    passages.append((passage_name, content.strip()))
+
+    # Generate Twine HTML
+    twine_html = f'''<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <title>Exported Story</title>
+    <style>
+        body {{ font-family: Georgia, serif; max-width: 600px; margin: 50px auto; padding: 20px; }}
+        .passage {{ margin-bottom: 20px; }}
+        a {{ color: #0066cc; text-decoration: none; display: block; margin: 10px 0; padding: 10px; background: #f0f0f0; border-radius: 5px; }}
+        a:hover {{ background: #e0e0e0; }}
+    </style>
+</head>
+<body>
+<div id="story">
+    <div id="current-passage"></div>
+</div>
+
+<script>
+const passages = {{
+'''
+
+    # Add passages as JavaScript object
+    for name, content in passages:
+        # Escape for JavaScript
+        escaped_content = content.replace('\\', '\\\\').replace("'", "\\'").replace('\n', '\\n')
+        twine_html += f"    '{name}': '{escaped_content}',\n"
+
+    twine_html += f'''}};
+
+let currentPassage = '{first_passage or "start"}';
+
+function showPassage(name) {{
+    const content = passages[name] || 'Passage not found: ' + name;
+    const container = document.getElementById('current-passage');
+
+    // Parse links [[text|target]] or [[text]]
+    let html = content.replace(/\\[\\[([^|\\]]+)\\|([^\\]]+)\\]\\]/g, '<a href="#" onclick="showPassage(\\'$2\\'); return false;">$1</a>');
+    html = html.replace(/\\[\\[([^\\]]+)\\]\\]/g, '<a href="#" onclick="showPassage(\\'$1\\'); return false;">$1</a>');
+    html = html.replace(/\\n/g, '<br>');
+
+    container.innerHTML = '<div class="passage">' + html + '</div>';
+    currentPassage = name;
+}}
+
+// Start the story
+showPassage(currentPassage);
+</script>
+</body>
+</html>'''
+
+    explanation = """Twine/Interactive Fiction Export Generated!
+
+Instructions:
+1. Save this as an .html file
+2. Open in any web browser to play
+3. Or import into Twine (twinery.org):
+   - Open Twine
+   - Import > From File
+   - Select the HTML file
+
+Alternative - Use Twinery.org online:
+1. Go to https://twinery.org/
+2. Click "Use it online"
+3. Create new story
+4. Copy passages manually or import HTML
+
+Features:
+- Self-contained HTML file
+- No dependencies required
+- Works offline
+- Easy to customize CSS
+"""
+
+    return explanation, twine_html

exporters/yarn_exporter.py

@@ -0,0 +1,108 @@
+"""Yarn Spinner dialogue exporter for game configs."""
+
+import json
+
+
+def export_to_yarn(config_json):
+    """Export game config to Yarn Spinner dialogue format (.yarn)."""
+    try:
+        config = json.loads(config_json) if isinstance(config_json, str) else config_json
+    except json.JSONDecodeError as e:
+        return f"JSON Error: {str(e)}", ""
+
+    yarn_code = '''title: Start
+tags:
+---
+<<jump {first_node}>>
+===
+
+'''
+
+    first_node = None
+    nodes = []
+
+    # Generate nodes
+    for location_key, location_data in config.items():
+        if isinstance(location_data, dict):
+            for state_key, state_data in location_data.items():
+                if isinstance(state_data, dict):
+                    node_name = f"{location_key}_{state_key}"
+                    if first_node is None:
+                        first_node = node_name
+
+                    description = state_data.get('description', 'No description')
+                    choices = state_data.get('choices', [])
+                    transitions = state_data.get('transitions', {})
+                    media = state_data.get('media', {})
+
+                    node_code = f"title: {node_name}\n"
+                    node_code += f"tags: location:{location_key}\n"
+                    node_code += "---\n"
+
+                    # Add media commands if present
+                    if media.get('image'):
+                        node_code += f"<<set_background \"{media['image']}\">>\n"
+                    if media.get('audio'):
+                        node_code += f"<<play_audio \"{media['audio']}\">>\n"
+
+                    # Add description
+                    node_code += f"{description}\n\n"
+
+                    # Add choices
+                    if choices:
+                        for choice in choices:
+                            next_state = transitions.get(choice, '') if isinstance(transitions, dict) else ''
+
+                            if next_state:
+                                if '_' not in next_state:
+                                    next_state = f"{location_key}_{next_state}"
+                                node_code += f"-> {choice}\n"
+                                node_code += f"    <<jump {next_state}>>\n"
+                            else:
+                                node_code += f"-> {choice}\n"
+                                node_code += f"    You selected: {choice}\n"
+                                node_code += f"    <<stop>>\n"
+                    else:
+                        node_code += "<<stop>>\n"
+
+                    node_code += "===\n\n"
+                    nodes.append(node_code)
+
+    # Replace placeholder in start node
+    yarn_code = yarn_code.replace("{first_node}", first_node or "Start")
+
+    # Add all nodes
+    yarn_code += "\n".join(nodes)
+
+    explanation = """Yarn Spinner Dialogue Export Generated!
+
+Setup Instructions:
+1. Install Yarn Spinner for Unity: https://yarnspinner.dev/
+2. Create a new .yarn file in your project
+3. Paste this code
+4. Add a Dialogue Runner component to your scene
+
+Online Testing:
+- Try Yarn Spinner: https://try.yarnspinner.dev/
+- Paste code and click "Run"
+
+Unity Integration:
+1. Import Yarn Spinner package from Unity Asset Store (free)
+2. Create YarnProject asset
+3. Add .yarn files to project
+4. Set up DialogueRunner with your UI
+
+Custom Commands (implement in C#):
+- <<set_background "image">> : Change background
+- <<play_audio "file">> : Play sound effect
+- <<stop>> : End dialogue
+
+Yarn Syntax Reference:
+- title: NodeName : Start of node
+- -> Choice text : Player option
+- <<jump NodeName>> : Go to node
+- <<set $var = value>> : Set variable
+- <<if $var>> ... <<endif>> : Conditional
+"""
+
+    return explanation, yarn_code

file_explorer_and_upload.py

@@ -16,7 +16,8 @@ os.makedirs(SAVE_DIR, exist_ok=True)
 SUPPORTED_EXTENSIONS = {
     "image": [".jpg", ".jpeg", ".png", ".gif", ".bmp", ".webp"],
     "audio": [".mp3", ".wav", ".ogg"],
-    "video": [".mp4", ".avi", ".mov", ".webm"]
+    "video": [".mp4", ".avi", ".mov", ".webm"],
+    "model3d": [".glb", ".gltf", ".obj"]
 }
 
 def save_file(file):
@@ -50,24 +51,61 @@ def save_file(file):
         return f"Error saving file: {str(e)}", gr.update(value=SAVE_DIR), gr.update()
 
 def view_file(file_path):
+    """View a file and return appropriate outputs for each media type.
+    Returns: (image, audio, video, message, model3d)
+    """
     if not file_path:
-        return None, None, None, "No file selected."
+        return None, None, None, "No file selected.", None
 
     try:
-        full_path = os.path.join(SAVE_DIR, file_path)
+        # FileExplorer returns relative path from root_dir, or could be full path
+        # Handle both cases
+        if os.path.isabs(file_path):
+            full_path = file_path
+        elif file_path.startswith(SAVE_DIR):
+            full_path = file_path
+        else:
+            full_path = os.path.join(SAVE_DIR, file_path)
+
+        # Normalize the path
+        full_path = os.path.normpath(full_path)
+
+        if not os.path.exists(full_path):
+            return None, None, None, f"File not found: {full_path}", None
+
         _, extension = os.path.splitext(full_path)
         extension = extension.lower()
 
         if extension in SUPPORTED_EXTENSIONS["image"]:
-            return Image.open(full_path), None, None, None
+            return Image.open(full_path), None, None, f"Viewing: {os.path.basename(full_path)}", None
         elif extension in SUPPORTED_EXTENSIONS["audio"]:
-            return None, full_path, None, None
+            return None, full_path, None, f"Viewing: {os.path.basename(full_path)}", None
         elif extension in SUPPORTED_EXTENSIONS["video"]:
-            return None, None, full_path, None
+            return None, None, full_path, f"Viewing: {os.path.basename(full_path)}", None
+        elif extension in SUPPORTED_EXTENSIONS["model3d"]:
+            return None, None, None, f"Viewing 3D: {os.path.basename(full_path)}", full_path
         else:
-            return None, None, None, f"Unsupported file type: {extension}"
+            return None, None, None, f"Unsupported file type: {extension}", None
+    except Exception as e:
+        return None, None, None, f"Error viewing file: {str(e)}", None
+
+
+def get_all_media_files():
+    """Get all media files from saved_media folder for use in dropdowns"""
+    try:
+        if not os.path.exists(SAVE_DIR):
+            return []
+        files = os.listdir(SAVE_DIR)
+        # Filter to only supported media files
+        media_files = []
+        for f in files:
+            ext = os.path.splitext(f)[1].lower()
+            if any(ext in exts for exts in SUPPORTED_EXTENSIONS.values()):
+                media_files.append(f)
+        return sorted(media_files)
     except Exception as e:
-        return None, None, None, f"Error viewing file: {str(e)}"
+        print(f"Error listing media files: {e}")
+        return []
 
 def refresh_file_explorer():
     files = os.listdir(SAVE_DIR)
@@ -81,6 +119,117 @@ def delete_file(file_path):
     else:
         return f"{file_path} does not exist."
 
+
+def delete_file_and_refresh(filename):
+    """Delete file and return updated dropdown choices"""
+    if not filename:
+        return gr.update(choices=get_all_media_files()), "No file selected"
+
+    full_path = os.path.join(SAVE_DIR, filename)
+    if os.path.exists(full_path):
+        os.remove(full_path)
+        return gr.update(choices=get_all_media_files(), value=None), f"Deleted: {filename}"
+    return gr.update(choices=get_all_media_files()), f"File not found: {filename}"
+
+
+def save_file_and_refresh(file):
+    """Save file and return updated dropdown choices for Browse tab"""
+    if file is None:
+        return "No file uploaded.", gr.update(), gr.update(value=None)
+
+    try:
+        original_filename = os.path.basename(file.name)
+        _, extension = os.path.splitext(original_filename)
+
+        if not any(extension.lower() in exts for exts in SUPPORTED_EXTENSIONS.values()):
+            return f"Unsupported file type: {extension}", gr.update(), gr.update()
+
+        base_name = os.path.splitext(original_filename)[0]
+        counter = 1
+        new_filename = f"{base_name}{extension}"
+        while os.path.exists(os.path.join(SAVE_DIR, new_filename)):
+            new_filename = f"{base_name}_{counter}{extension}"
+            counter += 1
+
+        dest_path = os.path.join(SAVE_DIR, new_filename)
+        shutil.copy2(file.name, dest_path)
+
+        # Return updated dropdown choices
+        return f"File saved: {new_filename}", gr.update(choices=get_all_media_files()), gr.update(value=None)
+    except Exception as e:
+        return f"Error saving file: {str(e)}", gr.update(), gr.update()
+
+def upload_file_or_bundle(file):
+    """
+    Unified upload handler that handles both media files and zip bundles.
+    Returns: (status, dropdown_update, file_input_clear, config_json, extracted_files)
+    """
+    if file is None:
+        return "No file uploaded.", gr.update(), gr.update(value=None), None, ""
+
+    try:
+        original_filename = os.path.basename(file.name)
+        _, extension = os.path.splitext(original_filename)
+        ext_lower = extension.lower()
+
+        # Check if it's a zip bundle
+        if ext_lower == ".zip":
+            try:
+                config, extracted_files = import_config_with_media(file.name)
+                config_json = json.dumps(config, indent=2)
+                files_str = "\n".join(extracted_files) if extracted_files else "No new files extracted (all already existed)"
+                status = f"Bundle imported! Config loaded, {len(extracted_files)} new media files extracted."
+                return (
+                    status,
+                    gr.update(choices=get_all_media_files()),
+                    gr.update(value=None),
+                    config_json,
+                    files_str
+                )
+            except FileNotFoundError as e:
+                return f"Error: {str(e)}", gr.update(), gr.update(), None, ""
+            except Exception as e:
+                return f"Error importing bundle: {str(e)}", gr.update(), gr.update(), None, ""
+
+        # Handle regular media files
+        if not any(ext_lower in exts for exts in SUPPORTED_EXTENSIONS.values()):
+            return f"Unsupported file type: {extension}", gr.update(), gr.update(), None, ""
+
+        base_name = os.path.splitext(original_filename)[0]
+        counter = 1
+        new_filename = f"{base_name}{extension}"
+        while os.path.exists(os.path.join(SAVE_DIR, new_filename)):
+            new_filename = f"{base_name}_{counter}{extension}"
+            counter += 1
+
+        dest_path = os.path.join(SAVE_DIR, new_filename)
+        shutil.copy2(file.name, dest_path)
+
+        return (
+            f"File saved: {new_filename}",
+            gr.update(choices=get_all_media_files()),
+            gr.update(value=None),
+            None,
+            ""
+        )
+    except Exception as e:
+        return f"Error: {str(e)}", gr.update(), gr.update(), None, ""
+
+
+def export_config_with_media_wrapper(config_json):
+    """Wrapper for export that provides status message along with the file"""
+    from my_text_game_engine_attempt import export_config_with_media
+    if not config_json or not config_json.strip():
+        return None, "Please paste a config JSON to export"
+    try:
+        zip_path = export_config_with_media(config_json)
+        return zip_path, f"Export successful! Bundle ready for download."
+    except json.JSONDecodeError as e:
+        return None, f"Invalid JSON: {str(e)}"
+    except Exception as e:
+        return None, f"Export failed: {str(e)}"
+
+
 def import_config_with_media(zip_path):
     global SAVE_DIR
     target_folder = SAVE_DIR
@@ -100,21 +249,27 @@ def import_config_with_media(zip_path):
         with zipfile.ZipFile(zip_path, 'r') as zip_ref:
             zip_ref.extractall(temp_dir)
         
-        # Load the config
+        # Load the config (check both config.json and game_config.json for compatibility)
         config_path = os.path.join(temp_dir, 'config.json')
+        alt_config_path = os.path.join(temp_dir, 'game_config.json')
+
         if os.path.exists(config_path):
             with open(config_path, 'r') as f:
                 config = json.load(f)
+        elif os.path.exists(alt_config_path):
+            with open(alt_config_path, 'r') as f:
+                config = json.load(f)
         else:
-            raise FileNotFoundError("config.json not found in the zip file")
+            raise FileNotFoundError("config.json (or game_config.json) not found in the zip file")
         
         # Create the target folder if it doesn't exist
         os.makedirs(target_folder, exist_ok=True)
         
         # Copy media files that don't already exist in the target folder
+        config_files = {'config.json', 'game_config.json'}
         for root, _, files in os.walk(temp_dir):
             for file in files:
-                if file != 'config.json':
+                if file not in config_files:
                     src_path = os.path.join(root, file)
                     dst_path = os.path.join(target_folder, file)
                     if not os.path.exists(dst_path):

film_scenarios.py

@@ -0,0 +1,206 @@
+"""Film scenario data and sequence generation.
+
+This module provides:
+- FILM_SCENARIOS: Dictionary of categorized film scenario templates
+- generate_scenario_sequence: Function to generate random sequences of scenarios
+"""
+
+import json
+import random
+
+FILM_SCENARIOS = {
+    "openings": [
+        ("Dawn Patrol", "Character wakes up, morning routine reveals personality/situation"),
+        ("The Arrival", "Protagonist enters new location for first time"),
+        ("In Medias Res", "Opens mid-action, audience catches up"),
+        ("The Funeral", "Character death sets story in motion, mourners gathered"),
+        ("Voiceover Reflection", "Older character narrates past events"),
+    ],
+    "tension": [
+        ("The Ticking Clock", "Countdown visible/mentioned, deadline approaching"),
+        ("Hiding in Plain Sight", "Character conceals identity among enemies"),
+        ("The Stakeout", "Characters wait and watch from vehicle/building"),
+        ("Parallel Editing Chase", "Cut between pursuer and pursued"),
+        ("The Interrogation", "Character questioned under pressure"),
+        ("Eavesdropping", "Character overhears crucial conversation"),
+        ("The Setup/Double-Cross", "Trusted ally reveals betrayal"),
+        ("Trapped in Enclosed Space", "Elevator, room, vehicle - no escape"),
+        ("The Hostage Situation", "Loved one held, demands made"),
+        ("Walking Into a Trap", "Audience knows danger character doesn't"),
+    ],
+    "action": [
+        ("The Standoff", "Multiple parties aim weapons, no one shoots first"),
+        ("The Bar Fight", "Violence erupts in drinking establishment"),
+        ("Car Chase Through City", "Vehicles weave through traffic, obstacles"),
+        ("Rooftop Confrontation", "Final battle on building top, city below"),
+        ("The Heist Execution", "Plan unfolds step by step with complications"),
+        ("Training Montage", "Character improves skills over compressed time"),
+        ("The Last Stand", "Outnumbered defenders hold position"),
+        ("One vs Many", "Single fighter takes on multiple opponents"),
+        ("The Duel", "Two opponents face off, formal or informal"),
+        ("Escape Sequence", "Character flees captivity/danger"),
+    ],
+    "emotional": [
+        ("The Confession", "Character admits truth - love, crime, secret"),
+        ("Deathbed Scene", "Dying character's final words/wishes"),
+        ("The Reunion", "Long-separated characters meet again"),
+        ("Breaking the News", "Character learns devastating information"),
+        ("The Sacrifice", "Character gives up something precious for others"),
+        ("Saying Goodbye", "Characters part ways, possibly forever"),
+        ("The Breakdown", "Character's composure finally cracks"),
+        ("Reconciliation", "Estranged characters make peace"),
+        ("The Proposal", "Marriage or significant commitment offered"),
+        ("Visiting the Grave", "Character speaks to deceased at burial site"),
+    ],
+    "discovery": [
+        ("Finding the Body", "Character discovers corpse"),
+        ("The Evidence Room", "Character finds proof of conspiracy/truth"),
+        ("Flashback Reveal", "Past event recontextualizes everything"),
+        ("The Twist Revealed", "Major plot revelation changes understanding"),
+        ("Reading the Letter/Document", "Written words deliver crucial info"),
+        ("Surveillance Footage", "Character watches recording of key event"),
+        ("The Photograph", "Image reveals connection or identity"),
+        ("Decoding the Message", "Cipher/puzzle solved, meaning clear"),
+    ],
+    "social": [
+        ("The Dinner Party", "Tension beneath polite social gathering"),
+        ("The Job Interview", "Character proves worth or fails to"),
+        ("Meeting the Parents", "Romantic partner meets family"),
+        ("The Courtroom", "Legal proceedings, testimony, verdict"),
+        ("Press Conference", "Public statement, reporters' questions"),
+        ("The Gala/Ball", "Formal event, everyone dressed up, intrigue"),
+        ("The Wake/Reception", "Social gathering after significant event"),
+    ],
+    "endings": [
+        ("Walking Into the Sunset", "Hero departs, back to camera, horizon ahead"),
+        ("The Circular Return", "Final scene mirrors opening, showing change"),
+        ("Freeze Frame", "Action stops, often with voiceover or text"),
+        ("The Bittersweet Victory", "Won but at great cost, hollow celebration"),
+        ("New Dawn", "Sun rises on changed world/character, hope restored"),
+        ("The Cliffhanger", "Unresolved tension, question left hanging"),
+        ("Where Are They Now", "Text/montage showing characters' futures"),
+        ("The Twist Ending", "Final revelation reframes entire story"),
+        ("Full Circle Reunion", "Characters gather one last time"),
+        ("The Long Walk Away", "Character leaves location, camera lingers"),
+        ("Passing the Torch", "Legacy/knowledge transferred to next generation"),
+        ("The Final Confrontation", "Last face-to-face with antagonist"),
+        ("Quiet Moment After Storm", "Calm after climax, processing events"),
+        ("The Sacrifice Payoff", "Earlier sacrifice proven worthwhile"),
+        ("Open Road/New Beginning", "Character sets off on next journey"),
+    ],
+}
+
+
+def generate_scenario_sequence(count, include_opening, include_tension, include_action,
+                               include_emotional, include_discovery, include_social, include_ending,
+                               force_opening, force_ending):
+    """Generate a random sequence of film scenarios.
+
+    Args:
+        count: Number of scenarios to generate
+        include_opening: Include opening scenarios
+        include_tension: Include tension scenarios
+        include_action: Include action scenarios
+        include_emotional: Include emotional scenarios
+        include_discovery: Include discovery scenarios
+        include_social: Include social scenarios
+        include_ending: Include ending scenarios
+        force_opening: Force sequence to start with an opening
+        force_ending: Force sequence to end with an ending
+
+    Returns:
+        Tuple of (list_output, json_output, prompts_output)
+    """
+    available = []
+    if include_opening:
+        available.extend([(s[0], s[1], "opening") for s in FILM_SCENARIOS["openings"]])
+    if include_tension:
+        available.extend([(s[0], s[1], "tension") for s in FILM_SCENARIOS["tension"]])
+    if include_action:
+        available.extend([(s[0], s[1], "action") for s in FILM_SCENARIOS["action"]])
+    if include_emotional:
+        available.extend([(s[0], s[1], "emotional") for s in FILM_SCENARIOS["emotional"]])
+    if include_discovery:
+        available.extend([(s[0], s[1], "discovery") for s in FILM_SCENARIOS["discovery"]])
+    if include_social:
+        available.extend([(s[0], s[1], "social") for s in FILM_SCENARIOS["social"]])
+    if include_ending:
+        available.extend([(s[0], s[1], "ending") for s in FILM_SCENARIOS["endings"]])
+
+    if not available:
+        return "Select at least one category!", "{}", ""
+
+    sequence = []
+
+    # Force opening if requested
+    if force_opening and include_opening:
+        opening = random.choice(FILM_SCENARIOS["openings"])
+        sequence.append((opening[0], opening[1], "opening"))
+        count -= 1
+
+    # Force ending if requested
+    ending_scene = None
+    if force_ending and include_ending:
+        ending_scene = random.choice(FILM_SCENARIOS["endings"])
+        count -= 1
+
+    # Fill middle with random selections
+    middle_available = [s for s in available if s[2] not in (["opening"] if force_opening else [])
+                        and s[2] not in (["ending"] if force_ending else [])]
+    if not middle_available:
+        middle_available = available
+
+    random.shuffle(middle_available)
+    sequence.extend(middle_available[:max(0, count)])
+
+    # Add ending at the end
+    if ending_scene:
+        sequence.append((ending_scene[0], ending_scene[1], "ending"))
+
+    # Format as list
+    list_output = "## Generated Sequence\n\n"
+    for i, (name, desc, cat) in enumerate(sequence, 1):
+        list_output += f"**{i}. {name}** [{cat}]\n{desc}\n\n"
+
+    # Format as config JSON (using correct engine format)
+    config = {"story_location": {}}
+    for i, (name, desc, cat) in enumerate(sequence, 1):
+        state_name = name.lower().replace(" ", "_").replace("/", "_").replace("-", "_")
+        current_state_id = f"scene_{i}_{state_name}"
+
+        # Determine next state
+        if i < len(sequence):
+            next_name = sequence[i][0]  # Get next scene's name
+            next_state_name = next_name.lower().replace(" ", "_").replace("/", "_").replace("-", "_")
+            next_state_id = f"scene_{i+1}_{next_state_name}"
+        else:
+            next_state_id = "ending"
+
+        # Use proper format: choices as list of strings, transitions as dict
+        config["story_location"][current_state_id] = {
+            "description": f"[{cat.upper()}] {desc}",
+            "media_prompt": f"Cinematic shot: {name} - {desc}",
+            "choices": ["Continue"],
+            "transitions": {
+                "Continue": next_state_id
+            }
+        }
+
+    # Add ending state
+    first_state_name = sequence[0][0].lower().replace(" ", "_").replace("/", "_").replace("-", "_")
+    config["story_location"]["ending"] = {
+        "description": "The story concludes here.",
+        "choices": ["Start Over"],
+        "transitions": {
+            "Start Over": f"scene_1_{first_state_name}"
+        }
+    }
+
+    json_output = json.dumps(config, indent=2)
+
+    # Format prompts only (for queue)
+    prompts_output = "## Video Prompts (copy to queue)\n\n"
+    for i, (name, desc, cat) in enumerate(sequence, 1):
+        prompts_output += f"Cinematic shot: {name} - {desc}\n"
+
+    return list_output, json_output, prompts_output

game_state.py

@@ -0,0 +1,377 @@
+"""
+GameState - Rich state tracking for game configs with logic gates.
+
+Provides comprehensive tracking beyond the basic Player class:
+- Inventory, money, knowledge (existing)
+- People met, locations discovered
+- Missions/quests (active, completed, failed)
+- Boolean flags and numeric counters
+- Choice history for analytics
+
+JSON-serializable for save/load functionality.
+"""
+
+from typing import Dict, List, Set, Any, Optional
+from dataclasses import dataclass, field
+import json
+import time
+
+
+@dataclass
+class GameState:
+    """
+    Comprehensive game state tracking.
+    All fields are JSON-serializable for save/load.
+    """
+
+    # ==================== Character Resources (from existing Player) ====================
+    inventory: List[str] = field(default_factory=list)
+    money: int = 0
+    knowledge: Dict[str, Any] = field(default_factory=dict)
+
+    # ==================== People/NPCs ====================
+    people_met: Set[str] = field(default_factory=set)
+    npc_reputation: Dict[str, int] = field(default_factory=dict)  # NPC -> affinity score
+
+    # ==================== Locations ====================
+    locations_visited: Set[str] = field(default_factory=set)
+    locations_discovered: Set[str] = field(default_factory=set)  # Known but not visited
+    current_location: str = ""
+    current_state: str = ""
+
+    # ==================== Missions/Quests ====================
+    missions_active: Dict[str, Dict] = field(default_factory=dict)  # id -> {status, progress, data}
+    missions_completed: Set[str] = field(default_factory=set)
+    missions_failed: Set[str] = field(default_factory=set)
+
+    # ==================== Flags (boolean switches) ====================
+    flags: Dict[str, bool] = field(default_factory=dict)
+
+    # ==================== Counters (numeric trackers) ====================
+    counters: Dict[str, int] = field(default_factory=dict)
+
+    # ==================== History Tracking ====================
+    choice_history: List[Dict] = field(default_factory=list)  # [{state, choice, timestamp}]
+    state_visit_counts: Dict[str, int] = field(default_factory=dict)
+
+    # ==================== Metadata ====================
+    game_start_time: float = field(default_factory=time.time)
+    total_choices_made: int = 0
+
+    # ==================== Item Methods ====================
+
+    def add_item(self, item: str) -> None:
+        """Add an item to inventory (no duplicates)."""
+        if item not in self.inventory:
+            self.inventory.append(item)
+
+    def add_items(self, items: List[str]) -> None:
+        """Add multiple items to inventory."""
+        for item in items:
+            self.add_item(item)
+
+    def remove_item(self, item: str) -> bool:
+        """Remove an item from inventory. Returns True if successful."""
+        if item in self.inventory:
+            self.inventory.remove(item)
+            return True
+        return False
+
+    def has_item(self, item: str) -> bool:
+        """Check if player has an item."""
+        return item in self.inventory
+
+    def item_count(self, item: str) -> int:
+        """Count occurrences of an item (for stackable items)."""
+        return self.inventory.count(item)
+
+    # ==================== Money Methods ====================
+
+    def add_money(self, amount: int) -> None:
+        """Add money to player's balance."""
+        self.money += amount
+
+    def remove_money(self, amount: int) -> bool:
+        """Remove money. Returns True if player had enough."""
+        if self.money >= amount:
+            self.money -= amount
+            return True
+        return False
+
+    def has_money(self, amount: int) -> bool:
+        """Check if player has at least this much money."""
+        return self.money >= amount
+
+    # ==================== People Methods ====================
+
+    def meet_person(self, person: str) -> None:
+        """Mark an NPC as met."""
+        self.people_met.add(person)
+
+    def has_met(self, person: str) -> bool:
+        """Check if player has met an NPC."""
+        return person in self.people_met
+
+    def adjust_reputation(self, npc: str, change: int) -> None:
+        """Adjust reputation with an NPC."""
+        self.npc_reputation[npc] = self.npc_reputation.get(npc, 0) + change
+
+    def get_reputation(self, npc: str) -> int:
+        """Get reputation with an NPC (default 0)."""
+        return self.npc_reputation.get(npc, 0)
+
+    # ==================== Location Methods ====================
+
+    def visit_location(self, location: str) -> None:
+        """Mark a location as visited."""
+        self.locations_visited.add(location)
+        self.locations_discovered.discard(location)  # No longer just discovered
+
+    def discover_location(self, location: str) -> None:
+        """Mark a location as discovered (but not visited)."""
+        if location not in self.locations_visited:
+            self.locations_discovered.add(location)
+
+    def has_visited(self, location: str) -> bool:
+        """Check if player has visited a location."""
+        return location in self.locations_visited
+
+    def has_discovered(self, location: str) -> bool:
+        """Check if player knows about a location (visited or discovered)."""
+        return location in self.locations_visited or location in self.locations_discovered
+
+    # ==================== Mission Methods ====================
+
+    def start_mission(self, mission_id: str, data: Dict = None) -> None:
+        """Start a new mission/quest."""
+        self.missions_active[mission_id] = data or {"status": "active", "progress": 0}
+
+    def update_mission(self, mission_id: str, updates: Dict) -> None:
+        """Update mission data."""
+        if mission_id in self.missions_active:
+            self.missions_active[mission_id].update(updates)
+
+    def complete_mission(self, mission_id: str) -> None:
+        """Mark a mission as completed."""
+        if mission_id in self.missions_active:
+            del self.missions_active[mission_id]
+        self.missions_completed.add(mission_id)
+
+    def fail_mission(self, mission_id: str) -> None:
+        """Mark a mission as failed."""
+        if mission_id in self.missions_active:
+            del self.missions_active[mission_id]
+        self.missions_failed.add(mission_id)
+
+    def is_mission_complete(self, mission_id: str) -> bool:
+        """Check if a mission is completed."""
+        return mission_id in self.missions_completed
+
+    def is_mission_active(self, mission_id: str) -> bool:
+        """Check if a mission is currently active."""
+        return mission_id in self.missions_active
+
+    def is_mission_failed(self, mission_id: str) -> bool:
+        """Check if a mission has failed."""
+        return mission_id in self.missions_failed
+
+    def get_mission_data(self, mission_id: str) -> Optional[Dict]:
+        """Get data for an active mission."""
+        return self.missions_active.get(mission_id)
+
+    # ==================== Flag Methods ====================
+
+    def set_flag(self, flag: str, value: bool = True) -> None:
+        """Set a boolean flag."""
+        self.flags[flag] = value
+
+    def clear_flag(self, flag: str) -> None:
+        """Clear (set to False) a flag."""
+        self.flags[flag] = False
+
+    def has_flag(self, flag: str) -> bool:
+        """Check if a flag is set (True)."""
+        return self.flags.get(flag, False)
+
+    def toggle_flag(self, flag: str) -> bool:
+        """Toggle a flag and return new value."""
+        new_value = not self.flags.get(flag, False)
+        self.flags[flag] = new_value
+        return new_value
+
+    # ==================== Counter Methods ====================
+
+    def set_counter(self, name: str, value: int) -> None:
+        """Set a counter to a specific value."""
+        self.counters[name] = value
+
+    def increment_counter(self, name: str, amount: int = 1) -> int:
+        """Increment a counter and return new value."""
+        self.counters[name] = self.counters.get(name, 0) + amount
+        return self.counters[name]
+
+    def decrement_counter(self, name: str, amount: int = 1) -> int:
+        """Decrement a counter and return new value."""
+        return self.increment_counter(name, -amount)
+
+    def get_counter(self, name: str, default: int = 0) -> int:
+        """Get a counter value."""
+        return self.counters.get(name, default)
+
+    # ==================== Knowledge Methods ====================
+
+    def update_knowledge(self, key: str, value: Any = True) -> None:
+        """Add or update knowledge."""
+        self.knowledge[key] = value
+
+    def has_knowledge(self, key: str) -> bool:
+        """Check if player has a knowledge entry."""
+        return key in self.knowledge
+
+    def get_knowledge(self, key: str, default: Any = None) -> Any:
+        """Get a knowledge value."""
+        return self.knowledge.get(key, default)
+
+    def remove_knowledge(self, key: str) -> None:
+        """Remove a knowledge entry."""
+        self.knowledge.pop(key, None)
+
+    # ==================== History Methods ====================
+
+    def record_choice(self, state: str, choice: str) -> None:
+        """Record a player choice for history tracking."""
+        self.choice_history.append({
+            "state": state,
+            "choice": choice,
+            "timestamp": time.time()
+        })
+        self.total_choices_made += 1
+        self.state_visit_counts[state] = self.state_visit_counts.get(state, 0) + 1
+
+    def get_visit_count(self, state: str) -> int:
+        """Get number of times a state was visited."""
+        return self.state_visit_counts.get(state, 0)
+
+    def get_last_choices(self, n: int = 5) -> List[Dict]:
+        """Get the last N choices made."""
+        return self.choice_history[-n:] if self.choice_history else []
+
+    # ==================== Serialization ====================
+
+    def to_dict(self) -> Dict:
+        """Convert to JSON-serializable dict for saving."""
+        return {
+            "inventory": self.inventory,
+            "money": self.money,
+            "knowledge": self.knowledge,
+            "people_met": list(self.people_met),
+            "npc_reputation": self.npc_reputation,
+            "locations_visited": list(self.locations_visited),
+            "locations_discovered": list(self.locations_discovered),
+            "current_location": self.current_location,
+            "current_state": self.current_state,
+            "missions_active": self.missions_active,
+            "missions_completed": list(self.missions_completed),
+            "missions_failed": list(self.missions_failed),
+            "flags": self.flags,
+            "counters": self.counters,
+            "choice_history": self.choice_history,
+            "state_visit_counts": self.state_visit_counts,
+            "game_start_time": self.game_start_time,
+            "total_choices_made": self.total_choices_made
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict) -> 'GameState':
+        """Reconstruct GameState from dict (for loading saves)."""
+        state = cls()
+        state.inventory = data.get("inventory", [])
+        state.money = data.get("money", 0)
+        state.knowledge = data.get("knowledge", {})
+        state.people_met = set(data.get("people_met", []))
+        state.npc_reputation = data.get("npc_reputation", {})
+        state.locations_visited = set(data.get("locations_visited", []))
+        state.locations_discovered = set(data.get("locations_discovered", []))
+        state.current_location = data.get("current_location", "")
+        state.current_state = data.get("current_state", "")
+        state.missions_active = data.get("missions_active", {})
+        state.missions_completed = set(data.get("missions_completed", []))
+        state.missions_failed = set(data.get("missions_failed", []))
+        state.flags = data.get("flags", {})
+        state.counters = data.get("counters", {})
+        state.choice_history = data.get("choice_history", [])
+        state.state_visit_counts = data.get("state_visit_counts", {})
+        state.game_start_time = data.get("game_start_time", time.time())
+        state.total_choices_made = data.get("total_choices_made", 0)
+        return state
+
+    def to_json(self) -> str:
+        """Serialize to JSON string."""
+        return json.dumps(self.to_dict(), indent=2)
+
+    @classmethod
+    def from_json(cls, json_str: str) -> 'GameState':
+        """Deserialize from JSON string."""
+        return cls.from_dict(json.loads(json_str))
+
+    def reset(self) -> None:
+        """Reset state to initial values (for new game)."""
+        self.inventory.clear()
+        self.money = 0
+        self.knowledge.clear()
+        self.people_met.clear()
+        self.npc_reputation.clear()
+        self.locations_visited.clear()
+        self.locations_discovered.clear()
+        self.current_location = ""
+        self.current_state = ""
+        self.missions_active.clear()
+        self.missions_completed.clear()
+        self.missions_failed.clear()
+        self.flags.clear()
+        self.counters.clear()
+        self.choice_history.clear()
+        self.state_visit_counts.clear()
+        self.game_start_time = time.time()
+        self.total_choices_made = 0
+
+
+class Player:
+    """
+    Backwards-compatible Player class that wraps GameState.
+    Existing configs using lambda consequences will continue to work.
+    """
+
+    def __init__(self, game_state: GameState = None):
+        self._state = game_state or GameState()
+
+    # Existing API (unchanged for backwards compatibility)
+    @property
+    def inventory(self) -> List[str]:
+        return self._state.inventory
+
+    @property
+    def money(self) -> int:
+        return self._state.money
+
+    @money.setter
+    def money(self, value: int):
+        self._state.money = value
+
+    @property
+    def knowledge(self) -> Dict[str, Any]:
+        return self._state.knowledge
+
+    def add_item(self, item: str) -> None:
+        self._state.add_item(item)
+
+    def has_item(self, item: str) -> bool:
+        return self._state.has_item(item)
+
+    def update_knowledge(self, topic: str) -> None:
+        self._state.update_knowledge(topic, True)
+
+    # NEW: Expose full state for advanced usage
+    @property
+    def game_state(self) -> GameState:
+        return self._state