Battleground Design Document

1. Purpose

The Battleground component serves as the visual and functional environment for turn-based battles, mimicking classic JRPG systems. It is designed to be a modular and extensible system that can support various battle scenarios, enemy types, and player configurations.

2. Core Functionality

• Turn-Based Combat: Implements a turn-based battle system where players and enemies alternate turns to perform actions.
• Action Handling: Manages and processes battle actions such as attack, defend, use item, and run.
• Animation Management: Triggers and synchronizes animations for various battle events, including attacks, hits, victories, and defeats.
• State Management: Maintains the battle state, including character health, status effects, and turn order.
• UI Integration: Provides a user interface for displaying battle information, selecting actions, and viewing animations.

3. Layout and Visual Design

• Arena: The main visual area where the battle takes place. It includes backgrounds, character sprites, and animation effects.
• Character Display: Visual representation of player and enemy characters, including health bars, status icons, and names.
• Action Menu: A menu that displays available actions for the current player's turn.
• Dialog Boxes: Earthbound-style dialog boxes for displaying battle messages, such as attack results, status updates, and victory/defeat messages.

4. Technical Design

4.1. Component Structure

• Battleground Component: The main Vue component that orchestrates the battle. It manages the battle state, renders the UI, and handles user input.
• Character Components: Reusable components for displaying character sprites, health bars, and status information.
• Animation Components: Components or CSS classes for triggering and managing animations. We will leverage GSAP (GreenSock Animation Platform) for creating smooth and performant animations. GSAP will handle character movements, attack effects, and UI transitions.
• Battle Service: A service or utility module that contains the core battle logic, including turn management, action processing, and state updates.

4.2. Data Model

• Character Object: Represents a player or enemy character with properties such as:
  • id: Unique identifier
  • name: Character name
  • health: Current health points
  • maxHealth: Maximum health points
  • attack: Attack power
  • defense: Defense power
  • magicAttack: Magic attack power
  • magicDefense: Magic defense power
  • speed: Determines turn order
  • sprite: Path to the character's sprite image
  • animations: Object containing animation definitions. These definitions will be GSAP timelines or tweens that control the character's visual behavior during battle events.
• Battle State Object: Represents the current state of the battle with properties such as:
  • turnOrder: Array of character IDs in the current turn order
  • currentPlayerId: ID of the character whose turn it is
  • enemies: Array of enemy character objects
  • players: Array of player character objects
  • active: Boolean indicating whether the battle is active

4.3. Key Methods

• initBattle(): Initializes the battle state, sets up the turn order, and loads character data.
• handleAction(action): Processes a battle action, updates the battle state, and triggers animations.
• performEnemyTurn(): Executes the enemy's turn, selects an action, and applies it to the player.
• defeatEnemy(enemy): Handles the defeat of an enemy, triggers victory animations, and updates the battle state.
• enterBattle(): Initializes the battle background.
• initBackground(): Sets up the initial background.

5. Rules and Mechanics

• Turn Order: Determined by the speed stat of each character.
• Actions: Players and enemies can perform various actions during their turn, such as:
  • Attack: Deals physical damage to the target.
  • Defend: Reduces incoming damage.
  • Use Item: Consumes an item to restore health, apply buffs, or inflict status effects.
  • Run: Attempts to escape the battle (success rate depends on character speed and enemy stats).
• Damage Calculation: Damage is calculated based on the attacker's attack power, the defender's defense power, and a random factor.
• Status Effects: Characters can be affected by status effects such as poison, paralysis, and sleep, which can alter their stats or prevent them from acting.
• Victory/Defeat Conditions: The battle ends when all enemies are defeated or all players are defeated.

6. Future Enhancements

• Multi-Enemy/Player Support: Extend the battleground to support multiple enemies and players.
• Advanced AI: Implement more sophisticated AI for enemies, including decision-making based on character stats, status effects, and battle conditions.
• Special Abilities: Add support for special abilities and spells with unique effects and animations.
• Interactive Environments: Introduce interactive elements to the battleground, such as destructible objects or environmental hazards.
• Party System: Implement a party system where players can switch between characters during battle.

7. Battleground States

7.1. Initial State

• The battle begins with the initBattle() method, which sets up the initial conditions.
• Character data is loaded, and the turn order is determined.
• The background music starts, and the initial animations play.

7.2. Active State

• During the active state, players and enemies take turns performing actions.
• The handleAction() method processes each action, updating the battle state and triggering animations.
• The UI displays available actions and battle information.

7.3. Victory State

• The victory state is triggered when all enemies are defeated.
• Victory animations play, and the player receives rewards.
• The battle ends, and the player returns to the game world.

7.4. Defeat State

• The defeat state is triggered when all players are defeated.
• Defeat animations play, and the player may face penalties.
• The battle ends, and the player may be returned to a previous save point.

8. Animations

We will use GSAP for all animations to ensure smooth and performant visual effects.

8.1. Attack Animations

• Visual effects that accompany attack actions, such as sword swings, energy blasts, and magical projectiles. GSAP will be used to animate these effects, synchronizing them with sound effects and damage calculations.

8.2. Hit Animations

• Visual effects that indicate a character has been hit, such as flashing sprites, impact particles, and screen shake. GSAP will control these animations to convey the force and impact of the attack.

8.3. Victory Animations

• Celebratory animations that play when the player wins the battle, such as character poses, fireworks, and victory dances. GSAP will be used to create dynamic and exciting victory animations.

8.4. Defeat Animations

• Animations that play when the player loses the battle, such as collapsing sprites, fading effects, and mournful music. GSAP will control these animations to convey a sense of loss and disappointment.