Turn Management & Action Economy

[FirebrickRed]

Summary

Manage combat turns, track action economy (actions, bonus actions, movement), display turn information, and handle turn advancement. Includes movement tracking with soft enforcement and visual glow indicator for active turn.

Phase: MVP Combat System
Systems: Combat System, Action Economy, Movement Tracking

Prerequisites

• Combat Session Foundation & Initiative System #97 - Combat Session Foundation & Initiative System

Goals

• Turn advancement and tracking
• Glow effect on active combatant (visual turn indicator)
• Action economy per turn (1 Action, 1 Bonus Action, Movement)
• Movement tracking with soft enforcement (1 block = 5ft)
• Visual movement range indicator (particles)
• Turn start announcements with hover text
• Position undo for movement mistakes
• Combat ending and cleanup

Commands

Turn Management

# Advance to next combatant's turn
/combat nextturn
> Bob's turn ends.
> [Bob's glow removed]
> ━━━━━━━━━━━━━━━━━━━━━━━
> It's Goblin Chief's turn!
> [Goblin Chief now glowing]
> • 1 Action
> • 1 Bonus Action  
> • 30 ft movement
> ━━━━━━━━━━━━━━━━━━━━━━━

# Force-end a specific combatant's turn (DM override)
/combat endturn Alice
> Alice's turn ended by DM.
> [Alice's glow removed]

# Jump to specific combatant (out of order)
/combat turn Bob
> Jumping to Bob's turn (out of order).
> [Previous combatant's glow removed, Bob now glowing]

# End combat session
/combat end
> Combat ended. Final stats:
> - Rounds: 4
> - Combatants remaining: 3
> [All glows removed, scoreboard cleared]

Movement

# Undo movement (return to turn-start position)
/combat movement undo
> Returned to turn-start position. (30 ft movement restored)

# Check remaining movement
/combat movement
> You have 15/30 ft movement remaining.

Active Turn Glow Effect

Implementation

// When turn starts - apply glow
private void applyTurnGlow(Combatant combatant) {
    if (combatant.isPlayer()) {
        Player player = combatant.getPlayer();
        player.setGlowing(true);
    } else {
        // Entity glow via armor stand or associated entity
        Entity entity = combatant.getEntity();
        entity.setGlowing(true);
    }
}

// When turn ends - remove glow
private void removeTurnGlow(Combatant combatant) {
    if (combatant.isPlayer()) {
        combatant.getPlayer().setGlowing(false);
    } else {
        combatant.getEntity().setGlowing(false);
    }
}

// On turn transition
private void transitionTurn(Combatant previous, Combatant next) {
    if (previous != null) {
        removeTurnGlow(previous);
    }
    applyTurnGlow(next);
    announceTurnStart(next);
}

Glow Color (Future Enhancement)

// Default Minecraft glow is white/team color
// Could use scoreboard teams to set glow colors:
// - Green glow for players
// - Red glow for enemies
// - Yellow glow for neutral

Team activeTeam = scoreboard.registerNewTeam("active_turn");
activeTeam.setColor(NamedTextColor.GOLD);
activeTeam.addEntry(combatant.getName());

Entity Glow Considerations

// DndEntityInstance uses ArmorStand - need to glow the visible entity
// Option 1: Glow the armor stand itself
armorStand.setGlowing(true);

// Option 2: If armor stand has passenger (mob), glow that
if (armorStand.getPassengers().size() > 0) {
    armorStand.getPassengers().get(0).setGlowing(true);
}

// Option 3: Spawn temporary glowing marker
// (if armor stand glow doesn't look good)

Turn Start Announcement

For Players

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
It's Alice's turn! ✨ [Alice is now glowing]
• 1 Action [HOVER: Attack, Cast Spell, Dash, Disengage, Dodge, Help, Hide, Ready, Search, Use Object]
• 1 Bonus Action [HOVER: Cunning Action, Offhand Attack, Bonus Action Spells]
• 30 ft movement
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Reminder: Alice is Prone, Poisoned

Hover text shows available actions based on:

• Standard actions (Attack, Cast Spell, Dash, etc.)
• Class features (Cunning Action, etc.)
• Equipped items
• Prepared spells with casting time "1 action"

For Entities (DM View)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DM: It's Goblin Chief's turn ✨
[Uses scoreboard display name for hidden enemies]
• 1 Action
• 1 Bonus Action
• 30 ft movement
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Movement Tracking

Soft Enforcement

// Track movement per turn
int movementUsed = 0;
int maxMovement = combatant.getSpeed();  // From CharacterSheet or DndEntityInstance

// On player move event
int blocksMoved = calculateDistance(oldPos, newPos);
int feetMoved = blocksMoved * 5;
movementUsed += feetMoved;

if (movementUsed > maxMovement) {
    player.sendMessage("⚠ Warning: You've exceeded your movement! (" + movementUsed + "/" + maxMovement + " ft)");
    // Soft enforcement: warn but allow
}

Movement Range Particles

// Show max movement range as particle circle
int radiusBlocks = maxMovement / 5;
// Display particle ring at ground level showing movement boundary
// Toggle-able in future via config

Position Tracking

// Store turn-start position for undo
Location turnStartPosition;

// On turn start
turnStartPosition = player.getLocation();

// On /combat movement undo
player.teleport(turnStartPosition);
movementUsed = 0;

Action Economy Display

Scoreboard Integration

━━━ INITIATIVE ━━━
→ 19 Alice [A][B][25ft]  ← Glowing in-game
  15 Bob
  12 Goblin Chief
━━━━━━━━━━━━━━━━━━

[A] = Action available
[B] = Bonus Action available
[25ft] = Movement remaining

Or action bar display:

Action: ✓ | Bonus: ✓ | Movement: 25/30 ft

Round Advancement

// When all combatants have acted
if (currentTurnIndex >= combatants.size() - 1) {
    roundNumber++;
    currentTurnIndex = 0;
    broadcast("━━━ Round " + roundNumber + " ━━━");
    
    // Clear surprised status after Round 1
    if (roundNumber == 2) {
        clearAllSurprisedStatus();
    }
}

Condition Reminders

On turn start, remind player of active conditions:

Reminder: Alice is Prone, Poisoned
[HOVER: Prone - disadvantage on attacks, attackers within 5ft have advantage]

Auto-Save Combat State

// Periodically save combat state for crash recovery
// Save to: plugins/jkvttplugin/CombatSessions/active_session.yml

combat_session:
  round: 3
  current_turn: 1
  combatants:
    - uuid: "player-uuid-1"
      name: "Alice"
      initiative: 19
      action_used: false
      bonus_used: true
      movement_used: 15
      turn_start_position: [100, 64, 200]

Edge Cases

• Player disconnects mid-turn → Remove glow, skip their turn, mark as "disconnected"
• Player rejoins → Restore to combat with saved state (no glow until their turn)
• All enemies dead → Prompt DM to end combat
• All players unconscious → Combat continues (death saves)
• Combat ends → Remove all glows

Future Enhancements (Not MVP)

• Config for movement enforcement level (none/soft/hard)
• Config for glow colors by team
• Dash action doubles movement
• Difficult terrain (half movement)
• Reactions (opportunity attacks)
• Ready action holding

Related Issues

• Combat Session Foundation & Initiative System #97 - Combat Foundation (prerequisite)
• Attack Roll System #99 - Attack Roll System (uses action)
• Damage & Healing System #100 - Damage System (uses action)
• Death Saves & Unconscious State #101 - Death Saves (unconscious turn handling)
• Condition Tracking & Display #103 - Condition Tracking (condition reminders)

[FirebrickRed]

Completed in commit f7ae858. Implemented turn state tracking, action economy (action/bonus/reaction), VTT-style movement with backtracking, player freeze off-turn, glow effects, DM possession movement integration, and player self-use commands.