Skip to content

COMBAT_QUICKSTART.md

Latest commit

 

History

History
175 lines (136 loc) · 4.55 KB

COMBAT_QUICKSTART.md

File metadata and controls

175 lines (136 loc) · 4.55 KB

Combat System - Quick Start Guide

What Was Built

A complete turn-based combat system for pattern-weaver with:

  • Player character with stats and XP progression
  • Three enemy types (Slime, Wolf, Goblin) with varying difficulty
  • Damage calculations with variance (hidden formula)
  • Win/lose/flee conditions
  • Action queue and combat log
  • All formulas internal (player only sees "You dealt 15 damage")

File Locations

C:/Users/decro/pattern-weaver/src/
├── entities/
│   ├── Player.js                    // Player character (100 HP, 10 ATK, 5 DEF, 50 MP)
│   └── Enemy.js                     // Enemy types with AI (Slime/Wolf/Goblin)
└── systems/
    ├── CombatSystem.js              // Core combat engine
    ├── CombatSystem.test.mjs        // Test suite (verified working)
    └── COMBAT_INTEGRATION_GUIDE.md  // Detailed documentation

Quick Usage

import { CombatSystem } from './systems/CombatSystem.js';
import { Enemy } from './entities/Enemy.js';

// Create and start combat
const combat = new CombatSystem();
const enemy = new Enemy('wolf');
combat.initCombat(enemy);

// Player takes turn
combat.executePlayerAction('attack');
// → Automatic: damage calculated, enemy turn executed, result checked

// Check current state
console.log(combat.getState());
// {
//   combatActive: true,
//   currentTurn: 'player',
//   result: null,
//   playerStatus: { hp: 98, attack: 10, defense: 5, ... },
//   enemyStatus: { hp: 42, name: 'Wolf', ... }
// }

// Get log entries
combat.getLog(5).forEach(log => {
  console.log(`Turn ${log.turn}: ${log.message}`);
});

// Check result when combat ends
if (!combat.combatActive) {
  console.log(combat.getResultMessage()); // "You defeated Wolf and gained 20 XP!"
}

Combat Flow

1. Player chooses action (attack/defend/flee)
2. Player action executes
   └─ Check: Did enemy die? → Win
3. Enemy AI chooses action (80% attack, 20% defend)
4. Enemy action executes
   └─ Check: Did player die? → Lose
5. Repeat step 1-4 until combat ends

Damage Formula (Internal)

baseDamage = attacker.attack - (defender.defense * 0.5)
minDamage = Math.max(1, baseDamage)    // Never less than 1
variance = 0.9 + Math.random() * 0.2   // 90-110% random
finalDamage = Math.floor(minDamage * variance)

Player sees: "You dealt 15 damage" (formula hidden)

Enemy Stats

Type HP ATK DEF XP
Slime 30 6 1 10
Wolf 50 12 3 20
Goblin 45 9 2 30

Actions Available

Attack

  • Deal damage = your attack power - (enemy defense * 0.5)
  • Variance: ±10%
  • Minimum: 1 damage

Defend

  • Reduce next incoming attack by 50%
  • Stacks with passive defense
  • Example: Enemy deals 10 → You take 5 (50%) → With defend: 2.5 (75%)

Flee

  • 50% chance to escape combat
  • On failure: Enemy gets free turn
  • No penalty otherwise

Player Leveling

- Start: Level 1, 100 HP, 10 ATK, 5 DEF, 50 MP
- Level up every 100 XP gained
- On level up: +2 ATK, +1 DEF, +20 maxHP, +10 maxMP

Integrating with CombatScene

See src/scenes/CombatScene.example.js for a complete Phaser 3 implementation example.

Key points:

  1. Create CombatSystem in scene's create()
  2. Call getAvailableActions() to enable buttons
  3. Call executePlayerAction(action) on user input
  4. Call getState() and getLog() to update UI
  5. Listen to combatActive to detect end

Testing

All systems tested and verified:

cd C:/Users/decro/pattern-weaver
node src/systems/CombatSystem.test.mjs

Tests cover: ✓ Initialization ✓ Enemy variations ✓ Damage variance (90-110%) ✓ Full combat simulation ✓ Defend mechanics ✓ Flee (50% success) ✓ XP and leveling ✓ Defense mitigation ✓ Combat state ✓ Available actions

All PASSED!

Key Design Notes

  1. All formulas are internal - Player only sees friendly messages
  2. Automatic progression - Enemy turns execute immediately
  3. No softlock - Minimum 1 damage prevents infinite cycles
  4. Simple AI - Enemy uses basic 80/20 attack/defend strategy
  5. XP at victory - Only awarded on successful defeat
  6. Defense stacking - Passive + active multiply (e.g., 25% + 50% = 75% reduced)

What's Not Included (Optional Enhancements)

  • Skills/special abilities
  • Items or consumables
  • Status effects (poison, stun, etc.)
  • Energy/resource costs for actions
  • Difficulty scaling
  • Enemy loot drops
  • Combat animations/graphics

These can be added by extending the core system!

Ready to integrate into your CombatScene!