Pictuary Battle Engine

A standalone, testable battle system for the Pictuary game, implementing the battle mechanics defined in battle_system_design.md.

Overview

This battle engine provides a complete turn-based combat system implementing EVERYTHING from battle_system_design.md:

Type effectiveness based on Pictuary's photography-themed types (Beast, Bug, Aquatic, Flora, Mineral, Space, Machina, Structure, Culture, Cuisine)
Composable effects system with 10 different effect types
Advanced damage formulas (standard, recoil, drain, fixed, percentage)
Mechanic override system for special abilities that modify core game mechanics
Trigger-based special abilities with 18 different trigger events
Status effects with chance-based application and turn-end processing
Field effects with stackable/non-stackable variants
PP manipulation system (drain, restore, disable)
Counter moves and priority modification
Conditional effects with 25+ different conditions
Extreme risk-reward moves as defined in the design document
Comprehensive test coverage (116 tests across 7 test files)

Architecture

Core Components

BattleEngine.ts - Main battle orchestration and logic
types.ts - Type definitions for all battle system interfaces
test-data.ts - Example Piclets and moves for testing
*.test.ts - Comprehensive test suites

Key Features

Battle State Management
- Turn-based execution with proper phase handling
- Action priority system (priority → speed → random)
- Win condition checking and battle end logic
- Field effects tracking and processing
Advanced Damage System
- Standard damage: Traditional attack vs defense calculation with type effectiveness and STAB
- Recoil damage: Self-harm after dealing damage (e.g., 25% recoil)
- Drain damage: Heal user for portion of damage dealt (e.g., 50% drain)
- Fixed damage: Exact damage amounts regardless of stats
- Percentage damage: Damage based on target's max HP percentage
- Type effectiveness calculations with dual-type support
- STAB (Same Type Attack Bonus)
- Accuracy checks with move-specific accuracy values
Comprehensive Effect System
- damage: 5 different damage formulas with conditional scaling
- modifyStats: Stat changes (increase/decrease/greatly_increase/greatly_decrease)
- applyStatus: Status effects with configurable chance percentages
- heal: Healing with amounts (small/medium/large/full) or percentage/fixed formulas
- manipulatePP: PP drain, restore, or disable targeting specific moves
- fieldEffect: Battlefield modifications affecting all combatants
- counter: Delayed damage reflection based on incoming attack types
- priority: Dynamic priority modification for moves
- removeStatus: Cure specific status conditions
- mechanicOverride: Fundamental game mechanic modifications
Status Effects
- Poison/Burn: Turn-end damage (1/8 max HP)
- Paralysis/Sleep/Freeze: Action prevention
- Confusion: Self-targeting chance
- Chance-based application: Configurable success rates (e.g., 30% freeze chance)
- Status immunity: Abilities can grant immunity to specific statuses
- Status removal: Moves and abilities can cure conditions
Special Ability System
- 18 Trigger Events: onDamageTaken, onSwitchIn, endOfTurn, onLowHP, etc.
- Conditional triggers: Abilities activate based on HP thresholds, weather, status
- Multiple effects per trigger: Complex abilities with layered effects
- Mechanic overrides: Abilities that fundamentally change game rules
Field Effects
- Global effects: Affect entire battlefield
- Side effects: Affect one player's side only
- Stackable/Non-stackable: Configurable effect layering
- Duration tracking: Effects expire after set number of turns
Move Flags System
- Combat flags: contact, bite, punch, sound, explosive, draining, ground
- Priority flags: priority, lowPriority
- Mechanic flags: charging, recharge, multiHit, twoTurn, sacrifice, gambling
- Interaction flags: reflectable, snatchable, copyable, protectable, bypassProtect
- Flag immunity/weakness: Abilities can modify interactions with flagged moves

Usage

Basic Battle Setup

import { BattleEngine } from './BattleEngine';
import { STELLAR_WOLF, TOXIC_CRAWLER } from './test-data';

// Create a new battle
const battle = new BattleEngine(STELLAR_WOLF, TOXIC_CRAWLER);

// Execute a turn
const playerAction = { type: 'move', piclet: 'player', moveIndex: 0 };
const opponentAction = { type: 'move', piclet: 'opponent', moveIndex: 1 };

battle.executeActions(playerAction, opponentAction);

// Check battle state
console.log(battle.getState());
console.log(battle.getLog());
console.log(battle.isGameOver(), battle.getWinner());

Creating Custom Piclets

import { PicletDefinition, Move, PicletType, AttackType } from './types';

const customMove: Move = {
  name: "Thunder Strike",
  type: AttackType.SPACE,
  power: 80,
  accuracy: 90,
  pp: 10,
  priority: 0,
  flags: ['explosive'],
  effects: [
    {
      type: 'damage',
      target: 'opponent',
      amount: 'strong'
    },
    {
      type: 'applyStatus',
      target: 'opponent',
      status: 'paralyze',
      condition: 'ifLucky50'
    }
  ]
};

const customPiclet: PicletDefinition = {
  name: "Storm Guardian",
  description: "A cosmic entity that commands lightning",
  tier: 'high',
  primaryType: PicletType.SPACE,
  baseStats: { hp: 120, attack: 100, defense: 90, speed: 85 },
  nature: "Bold",
  specialAbility: {
    name: "Lightning Rod",
    description: "Draws electric attacks and boosts power"
  },
  movepool: [customMove, /* other moves */]
};

Testing

The battle engine includes comprehensive test coverage:

# Run all battle engine tests
npm test src/lib/battle-engine/

# Run specific test file
npm test src/lib/battle-engine/BattleEngine.test.ts

# Run with UI
npm run test:ui

Test Categories

Unit Tests (BattleEngine.test.ts)
- Battle initialization
- Basic battle flow
- Damage calculations
- Status effects
- Stat modifications
- Healing effects
- Conditional effects
- Battle end conditions
- Move accuracy
- Action priority
Integration Tests (integration.test.ts)
- Complete battle scenarios
- Multi-turn battles with complex interactions
- Performance and stability tests
- Edge cases

Design Principles

Following the battle system design document:

Simple JSON Schema - Moves are defined with conceptual effect levels (weak/normal/strong/extreme) rather than specific numeric values
Composable Effects - Multiple effects per move with conditional triggers
Bold and Dramatic - Effects can be powerful with interesting tradeoffs
Type-Driven - Photography-themed types with meaningful interactions
Special Abilities - Passive traits that transform gameplay

Integration with Main App

This module is designed to be eventually imported into the main Svelte app:

// In Battle.svelte
import { BattleEngine } from '$lib/battle-engine/BattleEngine';
import type { PicletDefinition } from '$lib/battle-engine/types';

// Convert PicletInstance to PicletDefinition format
// Initialize battle engine
// Replace existing battle logic

Future Enhancements

Planned features following the design document:

Special ability trigger system
Field effects and weather
Counter moves and priority manipulation
PP manipulation effects
Multi-target moves
Switch actions and party management
Critical hit calculations
More complex conditional effects
Battle replay system

Performance Notes

Battle state is immutable (deep-cloned on getState())
Efficient type effectiveness lookup using enums
Minimal memory allocation during battle execution
Tested for battles up to 100+ turns without performance issues