Explain Command System

Overview

The Explain Command System provides a way for players to understand the mechanics behind their dice rolls without actually making the roll. It reuses existing command logic but changes the output format to focus on educational explanations rather than random results.

This system follows the architectural patterns established in the Attack Roll and Ability Check systems, leveraging the same pipeline structure but with a modified output formatter that explains dice expressions and modifiers instead of showing roll results.

Command Usage

!explain <command> [arguments...]

• command: The base command to explain (required)
• attack - Explains attack mechanics for a weapon

• Future commands: check, cast, etc.

• All arguments after the command are passed to the underlying command system.

Examples:

!explain attack                  # Explains available attacks
!explain attack longsword        # Explains longsword attack mechanics
!explain attack longsword 2H     # Explains two-handed longsword mechanics
!explain attack dagger backstab  # Explains backstab mechanics with a dagger

System Components

Core Architecture

The Explain system uses a wrapper pattern that:

1. Intercepts commands and adds an explain: true flag
2. Reuses existing command parsing and validation
3. Follows the normal execution pipeline but formats results differently
4. Provides detailed breakdowns of modifiers and their sources

This approach ensures that explanations always match actual game mechanics and stay in sync when rules change.

ExplainCommand

Responsibility: Processes the !explain command from Discord

• Implements the Stingbatbot.Commands.Command behavior
• Parses the first argument to determine which command to explain
• Routes to appropriate command with explain: true option
• Registered in the Command Registry for bot access
• Uses standard command pattern for error handling and responses

Key Functions: - name/0: Returns "explain" as the command name - description/0: Provides a description of the command - usage/0: Provides usage instructions - execute/2: Main function that handles command routing - extract_args/1: Extracts command and options from arguments

RollFormatter Extension

Rather than creating a separate formatter, the RollFormatter module is extended with pattern matching for explanation mode:

# Format roll with explanation mode
def format_roll(%RollResult{} = result, %{explain: true}) do
  # Format as explanation instead of roll results
  # ...
end

# Existing format_roll implementation
def format_roll(%RollResult{} = result) do
  # ...
end

This ensures that explanations maintain the same style and structure as actual roll results, while focusing on the mechanics instead of randomized outcomes.

Command Modifications

Each supported command requires minor modifications to handle the explain flag:

AttackCommand

The format_single_weapon_attack/2 function is updated to check for explain: true in options and pass this to the formatter:

def format_single_weapon_attack(attack, opts) do
  roll_result = AttackRoll.roll(attack, opts)
  RollFormatter.format_roll(roll_result, opts)
end

The rest of the AttackCommand logic remains unchanged, allowing for complete reuse of weapon lookup, option parsing, and roll mechanics.

Roll Pipeline Enhancements

To ensure complete explanations, the roll pipeline is enhanced to track all modifications:

1. Source Tracking: Each modifier records its source for explanation
2. Dice Mechanics Changes: Modifications that change dice (not just modifiers) are documented
3. Option Effects: The impact of each command option is clearly recorded

For example, the versatile weapon handler is enhanced to add a damage modifier entry that explains the dice change:

# When a versatile weapon is used two-handed
modified_attack = %{attack | 
  damage_modifiers: [
    %{source: "Versatile (Two-Handed)", value: 0} | attack.damage_modifiers
  ]
}

Similar enhancements ensure that all mechanics can be properly explained.

Example Output

Weapon Attack Explanation

📝 Gund's Longsword Attack (2H) - Explanation

Attack Roll Formula: 1d20+5
• Base attack bonus: +5
  → +2 from STR modifier
  → +2 from weapon mastery
  → +1 from magic weapon bonus

Damage Formula: 1d10+3
• Base weapon: 1d8 damage
• Versatile (Two-Handed): Using d10 instead of d8
• Damage modifier: +3
  → +2 from STR modifier
  → +1 from magic weapon bonus

Backstab Explanation

📝 Nyx's Dagger Attack (backstab) - Explanation

Attack Roll Formula: 1d20+4
• Base attack bonus: +4
  → +3 from DEX modifier
  → +1 from magic weapon bonus

Damage Formula: 2d4+4
• Base weapon: 1d4 damage
• Backstab: 1 extra weapon die (1d4)
• Damage modifier: +4
  → +3 from DEX modifier
  → +1 from magic weapon bonus

For a higher level thief with BackstabIncrease:

📝 Kakkrig's Dagger Attack (backstab) - Explanation

Attack Roll Formula: 1d20+4
• Base attack bonus: +4
  → +3 from DEX modifier
  → +1 from magic weapon bonus

Damage Formula: 8d4+4
• Base weapon: 1d4 damage
• Backstab: 6 extra weapon dice (based on level 11)
• BackstabIncrease: 1 extra weapon die
• Damage modifier: +4
  → +3 from DEX modifier
  → +1 from magic weapon bonus

Implementation Plan

1. Create the ExplainCommand module to handle the !explain command
2. Update RollFormatter to support explanation mode
3. Enhance AttackCommand to pass the explain flag to the formatter
4. Improve roll pipelines to track all source information
5. Add tests to ensure explanations match actual roll mechanics
6. Update documentation

Future Extensions

The Explain system is designed to support additional commands as they are implemented:

• !explain check - Explaining ability check mechanics
• !explain cast - Explaining spell casting mechanics
• !explain save - Explaining saving throw mechanics

Each new command will follow the same pattern of reusing existing mechanics but with enhanced explanation formatting.

Benefits

The Explain command system provides several key benefits:

1. Educational Tool: Helps new players understand game mechanics
2. Transparency: Makes it clear how bonuses and modifiers work
3. Debugging Aid: Assists DMs in verifying that mechanics are working correctly
4. Planning Tool: Allows players to understand potential outcomes before rolling
5. Consistency: Ensures explanations always match actual game mechanics