Battle Animations & Timing

Battle Animations & Timing Guide

Description

This guide ensures that all battle animations (Entry, Attack hits, Fainting, Switching) maintain the authentic G/S feel by respecting specific sequence timings and CSS class interactions.

Animation Framework Overview

The project uses a data-driven, registry-based animation system spread across three files in js/anim/:

• AnimFramework (anim_framework.js) — The engine. Registers and plays named animation sequences. Contains the SVG shape library, formation patterns, and sprite movement presets.
• registry/ — Directory containing modular animation definitions (registered on load):
  • core.js: Basic type effects (fx-fire, etc.), recovery, status, and system animations.
  • elemental.js: Fire, Water, Electric, Grass, and Ice moves.
  • physical.js: Normal, Fighting, Flying, and Poison moves.
  • nature.js: Ground and Rock moves.
  • steel.js: Steel and Metal-themed moves.
  • mystic.js: Psychic, Ghost, Dark, Dragon, and multi-elemental moves.
• BattleAnims (animations.js) — High-level API the rest of the codebase calls. Delegates to the framework.

[!IMPORTANT] Check the Directory First: Always check docs/ANIMATION_DIRECTORY.json before implementing a new animation to avoid duplicates. Since this file is large, do not read the whole file. Instead, use the grep_search tool to search for the specific elemental type (e.g. "FIRE": {) and only read the relevant section. If you add a new animation, you must manually update this JSON file in the appropriate type category.

How Move Animations are Triggered

When a move deals damage, the pipeline automatically checks for a registered animation:

resolveSingleHit → applyDamage(target, amount, type, moveName)
  → triggerHitAnim(target, type, moveName)
    ① Check (Pre-Anim): Are conditions valid? (Substitute, Status, Type Immunity)
        → If invalid, log "But it failed!" and STOP.
    ② Check: AnimFramework.has(moveName)  → e.g. 'flamethrower'
    ③ Check: AnimFramework.has('fx-'+type) → e.g. 'fx-fire'
    ④ Fallback: classic inline (screen flash + sprite shake)

Move names are auto-normalized: 'FLAMETHROWER' → 'flamethrower', 'ICE BEAM' → 'ice-beam'.

The skipAnim Pattern

If a unique move in MOVE_DEX plays its own animation in onHit (e.g. Explosion), its internal moveData should set skipAnim: true to prevent the pipeline from replaying it.

const moveData = { name: 'EXPLOSION', type: 'normal', power: 250, category: 'physical', skipAnim: true };

Available Step Types (20 total)

Audio & Control

Visual Effects (Scene-level)

Sprite Effects

Projectiles & Particles

Shapes & Overlays

Developer Experience: Autocomplete & Types

The project includes a robust JSDoc-based type system in js/types.js and a jsconfig.json file. This provides full IntelliSense for animation sequences in VS Code.

How to use:

When calling AnimFramework.register(name, steps), the steps array is automatically typed.

• As you type { type: '...' }, VS Code will suggest all 20+ available step types.
• Once a type is chosen, VS Code will suggest the specific parameters (e.g. sound for sfx, preset for spriteMove).

Key Types:

• AnimStep: Defines the required/optional fields for every animation step.
• AnimationEngine: Typed interface for AnimFramework.
• BattleEngine: Typed interface for the main Battle orchestrator.

SVG Shape Library

13 built-in 8-bit pixel-art shapes available for overlay, formation, and stream steps:

Formation Patterns

Predefined point layouts for the formation step. Each is an array of {x, y} offsets from the target's center.

Custom formations — pass your own points array:

{ type: 'formation', target: 'defender',
    points: [{x:0,y:-10}, {x:-10,y:0}, {x:10,y:0}, {x:0,y:10}],
    particleSize: 6, color: '#ff0000', duration: 500
}

Sprite Movement Presets

The spriteMove step provides quick-access movement templates. Direction is automatically adjusted for player vs. enemy side.

Content truncated.