القائمة
Guide for maintaining and adding new battle animations, focusing on specific sequence timing (Entry, Hits, Faints) and the data-driven Animation Framework.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Guide for adding new moves, items, or mechanics to the modular Pokemon Battle system.
Learn how to use the DialogManager system to display text, ask questions, and manage user interactions in the game.
Guide for creating new screens and managing transitions using the ScreenManager framework.
Guidelines for maintaining visual consistency across the UI, based on the Summary Screen reference.
Guide for maintaining the modular structure, script order, and global module patterns.
| name | Battle Animations & Timing |
| description | Guide for maintaining and adding new battle animations, focusing on specific sequence timing (Entry, Hits, Faints) and the data-driven Animation Framework. |
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.
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.jsonbefore implementing a new animation to avoid duplicates. Since this file is large, do not read the whole file. Instead, use thegrep_searchtool 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.
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'.
skipAnim PatternIf 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 };
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
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.
When calling AnimFramework.register(name, steps), the steps array is automatically typed.
{ type: '...' }, VS Code will suggest all 20+ available step types.sound for sfx, preset for spriteMove).AnimStep: Defines the required/optional fields for every animation step.AnimationEngine: Typed interface for AnimFramework.BattleEngine: Typed interface for the main Battle orchestrator.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 |
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
}
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 fall | 600ms | Levitate, Fly |
shake | Rapid vibration in place | 250ms | Charging up, rage trembling |
Usage:
{ type: 'spriteMove', target: 'attacker', preset: 'lunge' }
HUD animations (HP drain and XP gain) are handled in js/ui/ui.js but are data-driven via weights and durations in js/data/settings.js. Tuning these values allows for fine-grained control over the "feel" and "prestige" of battle progress.
ANIM_HUD ConfigurationLocated in js/data/settings.js, this object centralizes all behavior for bars:
| Parameter | Default | Effect |
|---|---|---|
HP_BASE_DURATION | 1200 | ms for a 100% HP bar change. |
HP_ZONE_RED_MULT | 1.8 | Slowdown multiplier when health is below 20%. |
HP_SMALL_HIT_MULT | 4.0 | Extra slowdown for hits dealing < 15% damage. |
HP_TAIL_UNITS | 3 | The number of final HP digits that "crawl" slowly. |
HP_TAIL_MS_PER_UNIT | 800 | ms per digit during the tail crawl. |
HP_EASE_POWER | 4 | Power for the ease-out curve (Higher = sharper slowdown). |
XP_BASE_DURATION | 2500 | ms for a full 100% XP fill (higher = more prestige). |
XP_TICK_RATE | 60 | ms between sound ticks during growth. |
XP_PITCH_START | 400 | Starting frequency (Hz) for the tick sound. |
XP_PITCH_SCALE | 600 | Total Hz rise for a 100% bar fill. |
XP_LEVEL_PITCH_BONUS | 100 | Frequency boost (Hz) added to both start and end each time a level is gained in a sequence. |
You can register a function instead of an array. The function receives the resolved context (attacker, defender, etc.) and must return an array of steps. This allows for logic-based animations (e.g. fewer particles for weak moves).
```javascript
const createDrainAnim = (intensity) => {
return [
{ type: 'sfx', sound: 'grass' },
// ... logic to adjust particle count based on intensity
];
};
AnimFramework.register('absorb', createDrainAnim('low'));
AnimFramework.register('giga-drain', createDrainAnim('high'));
For animations that require direct DOM manipulation (e.g., hiding a sprite for "Fly" or "Dig"), use the callback step type.
{ type: 'callback', fn: ctx => {
// Direct access to DOM elements
ctx.attackerSprite.style.opacity = '0';
ctx.scene.style.filter = 'grayscale(100%)';
}}
js/anim/registry/ (e.g., elemental.js for Fire moves).AnimFramework.register() call with 8-bit style:AnimFramework.register('fire-blast', [
{ type: 'sfx', sound: 'fire' },
{ type: 'spriteMove', target: 'attacker', preset: 'lunge' },
{ type: 'stream', from: 'attacker', to: 'defender',
count: 15, interval: 25, spread: 12, travelTime: 350,
size: 6, color: '#ff4500', outline: '#8b0000',
scaleStart: 0.6, scaleEnd: 2.0, svgShape: 'fire'
},
{ type: 'sfx', sound: 'fire' },
{ type: 'parallel', steps: [
{ type: 'flash', color: '#ff4500', duration: 300, opacity: 0.3 },
{ type: 'screenFx', class: 'fx-fire', duration: 700 },
{ type: 'spriteShake', target: 'defender', duration: 500 },
{ type: 'formation', target: 'defender', pattern: 'fireBlast',
shape: 'fire', particleSize: 8,
color: '#ff4500', outline: '#8b0000',
duration: 500, stagger: 25
}
]}
]);
Displays a shape directly on the target's position. Useful for physical strikes, shields, flashes, or elemental bursts.
{
type: 'overlay',
target: 'defender', // 'attacker', 'defender', 'scene'
shape: 'claw', // SVG name
color: '#ffffff',
outline: '#000000',
width: 60, height: 60,
duration: 300,
animation: 'strike', // 'strike', 'slam', 'grow', 'fade', 'crunch'
count: 3, // number of instances (e.g. 3 scratches)
spread: 20, // pixel variance
stagger: 100 // ms delay between each shape spawning
}
strike: Slides down into position (good for slashes).slam: Drops from above and scales up (impact moves).grow: Scales from 0 to 1 (shields, bursts).fade: Opacity 0 to 1 (ghostly effects).crunch: Special mode that alternates jaw-top and jaw-bottom shapes to meet in the middle (bite moves). Best used with count: 2 and stagger: 0.slash: Fast diagonal movement (top-left to bottom-right). Perfect for claw and sword-like attacks.AnimFramework.register() instead of writing inline DOM logic.parallel: Combine screen-level effects with sprite-level effects.