Scenario Documentation & Examples

[FirebrickRed]

Summary

Create comprehensive, heavily-commented example combat scenarios that DMs can copy and modify. Includes inline documentation for formations, conditional events, and combat integration.

Phase: 4 - DM Tools (Documentation)
Systems: Encounter System, Documentation

Prerequisites

• Pre-Planned Combat Scenario System #81 - Pre-Planned Combat Scenario System (MUST be completed first)

Goals

• Create 5+ example scenarios with extensive comments
• Explain formation types with visual diagrams
• Document conditional events system
• Party-size scaling examples
• Tips for customization
• Copy-paste ready templates

Example Structure

# ============================================
# TOWN GUARDS ATTEMPT ARREST
# ============================================
# Usage: /dmencounter spawn town_guard_arrest
#
# When to use:
#   - Players angered town authorities
#   - Guards sent to arrest party
#   - Pre-configured combat encounter
#
# What happens:
#   - Guards spawn in surround formation
#   - Combat initiative starts
#   - All guards share one initiative (group)
#   - Captain has own initiative
# ============================================

id: town_guard_arrest
name: "Town Guard Arrest Attempt"
description: "Guards attempt to arrest the party"

# SPAWN CONFIGURATION
spawn:
  # Regular guards (4 total)
  - id: town_guard
    count: 4
    formation: surround  # Circle around party
    # Formation: Forms ring around party center
    # Visual:     G
    #          G  P  G
    #             G
    # (P = party, G = guard)
    
    group_initiative: true  # All 4 share one initiative
    random_names: true  # Pick from town_guard name pool
    
  # Guard captain (leader)
  - id: guard_captain
    count: 1
    custom_name: "Captain Thorne"
    location: back  # Behind the guards
    # Captain stands behind the line
    
    group_initiative: false  # Has own initiative

# EFFECTS ON SPAWN
on_spawn:
  - type: message
    text: "\"By order of the magistrate, you are under arrest!\""
    speaker: "Captain Thorne"
    
  - type: combat_start
    # Triggers initiative tracker (Issue #83)

# CONDITIONAL EVENTS (Future)
# These trigger based on combat events
conditions:
  # If captain defeated, guards flee
  - trigger: entity_defeated
    entity: guard_captain
    effects:
      - type: message
        text: "\"The captain is down! Retreat!\""
      - type: entity_action
        action: flee
        targets: [town_guard]
        # All town_guard entities run away

# ============================================
# FORMATION TYPES EXPLAINED:
# ============================================
# surround - Circle around party center
# line     - Straight line facing party
# flanking - Split to sides of party
# back     - Behind other entities
# scattered - Random positions
# ============================================

# ============================================
# TIPS FOR DMs:
# ============================================
# - Adjust guard count based on party size
# - Change formation for different tactics
# - Add conditional events for roleplay
# - Copy and modify for different scenarios
# ============================================

Example Files to Create

1. town_guard_arrest.yml - Guard combat
2. kobold_ambush.yml - Ambush scenario
3. dragon_boss_fight.yml - Solo boss with phases
4. bandit_camp_assault.yml - Multiple enemy types
5. rescue_mission.yml - Friendly NPCs to protect

Location

DMContent/
└── Scenarios/
    └── examples/  # Documented examples
        ├── town_guard_arrest.yml
        ├── kobold_ambush.yml
        ├── dragon_boss_fight.yml
        ├── bandit_camp_assault.yml
        └── rescue_mission.yml

Formation Visual Diagrams

Include ASCII art in comments:

# surround formation:
#     G
#  G  P  G
#     G

# line formation:
#  G G G G
#    P P

# flanking formation:
#  G     G
#    P P
#  G     G

Next Steps

After completing this issue:

• DMs can reference examples when creating scenarios
• Complements Issue Encounter Table Documentation & Examples #86 (Encounter Documentation)

Related Issues

• Pre-Planned Combat Scenario System #81 - Pre-Planned Scenario System (prerequisite)
• Encounter Table Documentation & Examples #86 - Encounter Documentation (similar docs)
• Entity Combat Initiative Integration #83 - Combat Initiative (used by scenarios)