Combat Session Foundation & Initiative System

[FirebrickRed]

Summary

Core combat infrastructure: session management, initiative rolling, turn order tracking via scoreboard, and combatant management. Foundation for all other combat features.

Phase: MVP Combat System
Systems: Combat System, Scoreboard, Entity System

Prerequisites

• Unified Entity System Foundation #72 - Unified Entity System Foundation (completed)
• Native Villager Trade GUI Shop System #75 - Shop System uses similar entity lookup patterns (completed)

Goals

• Combat session state management (combatants, turn order, round counter, active turn)
• Initiative calculation with proper bonuses (DEX mod + features like Jack of All Trades)
• Surprise round handling
• Scoreboard-based initiative display
• Multiple ways to add combatants
• Mid-combat combatant management

Commands

Starting Combat

# Begin combat setup mode
/combat start
> Combat session started. Add combatants with /combat add

# Add specific player or entity by name
/combat add Alice
/combat add goblin_chief
> Added Alice to combat
> Added Goblin Chief to combat

# Add all entities/players within radius
/combat add --radius 30
> Added 3 combatants within 30 blocks

# Add by group (stub for #79 - Entity Group Management)
/combat add --group kobold_warband
> [Future: Group support pending #79]

# Mark combatant as surprised (skips first turn)
/combat surprise goblin_chief
> Goblin Chief marked as surprised (will skip Round 1)

# Remove combatant
/combat remove Alice
> Removed Alice from combat

Rolling Initiative

# Lock in combatants and roll initiative
/rollforinitiative
> Rolling initiative...
> ━━━━━━━━━━━━━━━━━━━━━━━
> 1. Alice (19) - DEX +3
> 2. Bob (15) - DEX +2
> 3. Goblin Chief (12) [SURPRISED]
> 4. Kobold Scout (8)
> ━━━━━━━━━━━━━━━━━━━━━━━
> Round 1 begins! It's Alice's turn.

# Manually adjust initiative (DM fixing mistakes)
/combat initiative goblin_chief set 20
> Goblin Chief initiative: 12 → 20
> Turn order updated.

Mid-Combat Management

# Add combatant after combat started
/combat add reinforcement_goblin
> Added Reinforcement Goblin to combat (initiative: 14)

# View current combat state
/combat status
> Round 2 | Current Turn: Bob
> Combatants: 4 | Surprised: 0

Initiative Calculation

// Base calculation
int initiative = dexterityModifier;

// Jack of All Trades (Bard 2+): Add half proficiency to non-proficient checks
if (hasJackOfAllTrades && !hasFeat("Alert") && !hasExpertise("Initiative")) {
    initiative += proficiencyBonus / 2;
}

// Other bonuses (Alert feat, etc.) - future enhancement

Tie-Breaking Rules

• Default (MVP): Higher initiative bonus wins
• Future Config: Options for DEX score, roll-off, DM decides

Scoreboard Display

━━━ INITIATIVE ━━━
→ 19 Alice        ← Current turn indicator
  15 Bob
  12 ??? [S]      ← Hidden enemy, Surprised
  8  Kobold Scout
━━━━━━━━━━━━━━━━━━
Round: 1

Entity Name Collision Handling

• Internally track by UUID (entities) or Player UUID (players)
• Display uses instance name or custom name
• If duplicate names, append number: "Goblin", "Goblin (2)"

Surprised Mechanic

• Surprised combatants are marked with [S] on scoreboard
• On their first turn: "Goblin Chief is surprised and loses their turn!"
• Surprise cleared after Round 1

Data Structures

public class CombatSession {
    private UUID sessionId;
    private List<Combatant> combatants;  // Sorted by initiative
    private int currentTurnIndex;
    private int roundNumber;
    private boolean isActive;
    
    // Combatant can be Player or DndEntityInstance
}

public class Combatant {
    private UUID id;  // Player UUID or Entity UUID
    private String displayName;
    private int initiative;
    private int initiativeBonus;
    private boolean isSurprised;
    private boolean isHidden;  // For #102
    private CombatantType type;  // PLAYER, ENTITY
}

Future Enhancements (Not MVP)

• Config for tie-breaking rules
• Reaction tracking
• Lair actions on specific initiative counts
• Legendary actions

Related Issues

• Entity Group Management System #79 - Entity Group Management (for group adds)
• Entity HP Tracking & Damage System #82 - Entity HP Tracking (combat requires HP)
• Entity Combat Initiative Integration #83 - Entity Initiative Config (YAML-based initiative modifiers)
• Turn Management & Action Economy #98 - Turn Management (depends on this)

[FirebrickRed]

Completed in fc228a2

Implemented Features

Combat Session Management:

• CombatSession class with full state tracking (combatants, turn order, round counter)
• Combatant class supporting both Players and DndEntityInstances
• Session registry for future multi-combat support

Commands:

Command	Description
/combat start	Begin combat setup mode
/combat add <target> [--hidden]	Add player or entity by name
/combat add --radius <blocks>	Add nearby combatants
/combat remove <target>	Remove from combat
/combat surprise <target>	Mark as surprised
/combat rollforinitiative	Roll initiative and start combat
/combat initiative <target> set <val>	Override initiative
/combat nextturn	Advance to next turn
/combat endturn [target]	End turn (defaults to current)
/combat turn <target>	Jump to specific combatant
/combat reveal/hide <entity>	Toggle hidden status
/combat status	View combat state
/combat end	End combat session

Initiative System:

• DEX modifier + Jack of All Trades (Bard 2+)
• Tie-breaking by initiative bonus
• Scoreboard shows actual initiative values as red numbers

Surprise Rounds:

• Surprised combatants marked with [S] on scoreboard
• Skip their turn in Round 1 with announcement

Hidden Enemies (#102):

• --hidden flag when adding entities
• DM sees real names, players see "???"
• Separate DM/player messages for all announcements

Quality of Life:

• Names with spaces: balin the smith
• Quoted names: "balin the smith"
• Duplicate handling: Wolf → Wolf TICKET-001: Implement Player Choice Handler #1, Wolf TICKET-002: Implement Ability Allocation Handler #2 (rebuilds on remove)
• Tab completion for all subcommands

Files Added

• combat/CombatSession.java - Session state and scoreboard
• combat/Combatant.java - Player/entity representation
• combat/CombatCommand.java - Main /combat handler
• combat/RollForInitiativeCommand.java - Legacy command support