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

Type	Parameters	Description
sfx	sound, wait?	Play a sound effect
cry	cry?, target?('attacker'/'defender'), wait?	Play a Pokémon cry
wait	ms	Pause execution
callback	fn(ctx)	Run arbitrary async function
parallel	steps: [...]	Run multiple steps concurrently
sequence	steps: [...]	Run multiple steps in order. Essential for nesting inside parallel

Visual Effects (Scene-level)

Type	Parameters	Description
screenFx	class, duration	Apply CSS class to scene (auto-removes). Uses classes like fx-fire, fx-water, etc.
flash	color, duration, opacity?, parent?	Full-scene color overlay that fades out
tilt	angle, duration	Rotate the battle scene and spring back. Great for heavy impacts
bgColor	color, duration	Temporarily flash the background to a solid color (e.g. dark for Ghost moves)
invert	target('scene'|'attacker'|'defender'), duration	Invert colors of the entire scene or a single sprite
wave	intensity, duration, speed	Wavy screen distortion using skew transforms. Psychic/Confusion vibe
cssClass	el, class, duration, persist?	Toggle any CSS class on any element

Sprite Effects

Type	Parameters	Description
spriteShake	target, duration, flipped?, skipIfInvisible?	Shake + flicker a sprite (the classic "hit" reaction)
spriteSilhouette	target, color, hold?, duration, follow?	Solid-color silhouette. Follows sprite moves by default.
spriteGhost	target, color, hold?, duration	Stationary silhouette snapshot (ghosting effect).
spriteWave	target, intensity, duration, speed	Wiggle/distortion on a specific sprite.
spriteMove	target, preset OR x,y,duration,easing	Move a sprite with preset templates or custom coordinates
spriteMetallic	target, duration, color?	Applies a grayscale metallic filter to the sprite and animates a shiny gradient wipe across it. Supports 'gold'/'bronze' tints.
move	el, x, y, duration, easing?, reset?	Translate any arbitrary DOM element

Projectiles & Particles

Type	Parameters	Description
stream	from, to, count, interval, spread, travelTime, size, color, outline?, scaleStart?, scaleEnd?, fade?, svgShape?	Continuous particle flow. Core system for fire, ice, water moves. Supports SVG shapes as particles
beam	from, to, className?, duration, width, height, beamStyles?	Single projectile from → to
volley	from, to, count, interval, travelTime, projectile: {width, height, styles}	Rapid-fire pixel projectiles (e.g. Pin Missile)
particles	position, count, spread, className?, duration, particleStyles?	Burst of impact particles at a position

Shapes & Overlays

Type	Parameters	Description
overlay	target, shape, color, outline?, width, height, duration, animation, count?, spread?	Render an SVG shape on top of a target with entrance animation
formation	target, pattern|points, particleSize, color, outline?, shape?, duration, stagger?	Spawn particles arranged in a predefined pattern (e.g. Fire Blast 大 kanji)
orbit	target, shape, radiusX, radiusY, count, speed, duration, color, outline?, yOffset?	Rotate shapes in an elliptical path around a target. Simulates depth with z-index and scaling.
spawn	parent?, className, styles?, tag?, text?, duration, waitAfter?	Create a temporary DOM element

---

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:

Shape	Use Case
lightning	Thunderbolt striking down
fire	Flame particles, fire overlays
water	Water drop effects
leaf	Grass/nature moves
star	Impact sparks, sparkle effects
claw	Slash / claw attack overlays
fist	Fighting-type punch impacts
skull	Ghost-type effects
spiral	Psychic / confusion effects
bird	Flying-type movements / Confusion
duck	Confusion effect
rock	Ground/Rock type impacts
sparkle	Healing / Status restore effects
music	Sing / Sonic moves
heart	Attract / Charm effects
eye	Glare / Mean Look effects
bubble	Water / Sleep effects
zzz	Sleep status
drop	Sweat drop / Splash
shield	Protect / Defense effects
wall	Reflect / Light Screen
anger	Anger point / frustration vein pop
jaw-top	Upper set of fangs
jaw-bottom	Lower set of fangs
bite	(Deprecated) Combined biting teeth
kick	High Jump Kick / kicking attacks
poison	Toxic sludge drop, poison attacks
snow	Hail / Blizzard snowflakes
gust	Whirlwind / hurricane tornadoes
spike	Spikes / caltrop hazards

---

Formation Patterns

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

Pattern	Shape	Best For
fireBlast	大 kanji	Fire Blast's iconic symbol
cross	+ shape	Cross-shaped impacts
ring	○ circle	Encircling effects
xShape	✕ shape	X-shaped hits

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.

Preset	Motion	Duration	Best For
lunge	Forward toward opponent, back	240ms	Physical attacks (Tackle, Slash)
dodge	Quick sidestep away	160ms	Evasion, Agility
jump	Hop up and down	240ms	Bounce, aerial moves
recoil	Push backward	300ms	Take-down, recoil damage
charge	Rush forward aggressively	400ms	Hyper Beam charge, Skull Bash
slam	Up then slam down	310ms	Body Slam, Earthquake
float	Gentle rise and

---

Content truncated.