docs/DEBUG_SCENARIO_IMPLEMENTATION.md

Debug Scenario Feature - Implementation Summary

✅ Completed

What Was Built

A debug mode system for manual testing of combat scenarios in the Gradio web interface.

Implementation Details

1. Debug Scenarios Defined (web/app_gradio.py lines 70-81)

DEBUG_SCENARIOS = [
    ("Random Start", None, [], []),
    ("Goblin Fight", "Goblin Cave Entrance", ["Goblin"], []),
    ("Goblin with Treasure", "Goblin Cave Entrance", ["Goblin"], ["Hidden Chest"]),
    ("Wolf Pack", "Dark Forest Clearing", ["Wolf", "Wolf"], []),
    ("Skeleton Guardian", "Ancient Ruins", ["Skeleton"], ["Ancient Sword"]),
    ("Dragon Encounter", "Dragon's Lair Approach", ["Young Red Dragon"], ["Dragon Hoard"]),
    ("Safe Inn", "The Prancing Pony Inn", ["Innkeeper Butterbur"], ["Healing Potion"]),
    ("Shopping District", "The Market Square", ["Merchant", "Blacksmith"], []),
]

2. UI Dropdown Added (web/app_gradio.py lines 1117-1124)

• Dropdown appears after character selection
• Only visible when settings.DEBUG_MODE = True
• Populated with scenario names from DEBUG_SCENARIOS list
• Clear label: "🧪 Debug Scenario (Optional)"

3. Routing Function Created (web/app_gradio.py lines 379-470)

• load_character_with_debug() intelligently routes to normal or debug loading
• If scenario selected: Loads character at specific location with pre-spawned NPCs/items
• If no scenario: Normal character load with random location
• Sets GM context with full character stats
• Returns welcome message with scenario info

4. Load Button Updated (web/app_gradio.py line 1367)

• Now accepts both character and scenario inputs
• Passes both to load_character_with_debug() function
• Outputs: character sheet, message input, chat history, character image

5. Documentation Created

• docs/DEBUG_MODE.md - Full documentation (3669 chars)
  • How to enable debug mode
  • Complete scenario list with purposes
  • Implementation details
  • Adding new scenarios
  • Use cases (combat testing, NPC hallucination testing, etc.)
• README.md - Added debug mode section
  • Quick overview in Commands Reference section
  • Links to full documentation

Files Modified

1. web/app_gradio.py

   • Added DEBUG_SCENARIOS list (8 scenarios)
   • Added debug_scenario_dropdown UI component
   • Replaced load_debug_scenario() with load_character_with_debug() wrapper
   • Updated load_btn.click() to use new wrapper with 2 inputs

2. dnd_rag_system/config/settings.py

   • Temporarily set DEBUG_MODE = True for testing
   • Reverted to DEBUG_MODE = False (must be manually enabled)

3. README.md

   • Added "🧪 Debug Mode - Testing Scenarios" section
   • Documented enable steps, features, and scenarios
   • Linked to full documentation

Files Created

1. docs/DEBUG_MODE.md - Comprehensive debug mode documentation
2. docs/DEBUG_SCENARIO_IMPLEMENTATION.md - This summary file

How to Use

For End Users

1. Enable debug mode: Edit dnd_rag_system/config/settings.py, set DEBUG_MODE = True
2. Start Gradio: python web/app_gradio.py
3. Open browser: http://localhost:7860
4. Select character (Thorin or Elara)
5. Select debug scenario from dropdown (or leave blank for random start)
6. Click "Load Character"
7. Game starts in specific scenario with NPCs/items pre-spawned

For Developers - Adding Scenarios

Edit DEBUG_SCENARIOS in web/app_gradio.py:

DEBUG_SCENARIOS = [
    ...
    ("My Test Scenario", "Location Name", ["NPC1", "NPC2"], ["Item1"]),
]

Format: (scenario_name, location_name, npcs_list, items_list)

Testing Status

✅ Syntax Check: Python compilation successful ✅ Unit Tests: All tests pass (location extraction, NPC filtering) ✅ Gradio Startup: App starts successfully with debug mode enabled ✅ UI Visibility: Dropdown only visible when DEBUG_MODE = True ✅ Code Review: Clean implementation, no duplication

Use Cases

This feature addresses the request for manual testing capabilities:

1. Combat Testing - Quickly test specific monster encounters without RNG
2. Location Bug Testing - Verify location doesn't teleport during combat
3. NPC Hallucination Testing - Test GM uses correct monster names (e.g., spawns Goblin, says "Goblin" not "Wolf")
4. Shop System Testing - Instant access to merchant NPCs
5. Regression Testing - Verify bug fixes work in controlled scenarios

Next Steps (Optional)

Future enhancements could include:

• Load/save custom scenarios from JSON files
• Multi-step scripted scenarios (spawn enemy after 3 turns)
• HP/gold overrides for edge case testing
• Scenario victory conditions
• Character state presets (wounded, low on spells, etc.)

Related Context

This feature completes the work interrupted in the previous session:

• Previous: DEBUG_SCENARIOS defined, load_debug_scenario() started
• This Session: UI integrated, routing logic completed, fully documented
• Bug Fixes: Works alongside location extraction and NPC hallucination filtering

Summary

Status: ✅ COMPLETE

The debug scenario feature is fully implemented, tested, and documented. Users can now enable DEBUG_MODE to access predefined test scenarios via a dropdown in the Gradio UI. The feature integrates seamlessly with existing character loading and does not affect normal gameplay when disabled.