Skip to main content

​
Display Animations

This guide explains how to display animations in RPG-JS. There are three common types of animations you can create and display:
  1. Spritesheet Animations - Using image spritesheets with the built-in animation system
  2. Custom Component Animations - Creating your own Canvas Engine components for complex effects
  3. CanvasEngine FX Animations - Using the prebuilt Fx component animation for particle effects
If one server-side gameplay moment should trigger several client visuals at once, such as a flash, sound, hit text, and component animation, use Client Visuals to group those primitives on the client and send only one compact server event.

​
Spritesheet Animations

See also: Spritesheets Guide for comprehensive information about spritesheets, including dynamic spritesheet resolution.

​
1. Creating the Animation Spritesheet

First, you need to create an animation spritesheet and add it to your module’s spritesheets configuration.

​
Using AnimationSpritesheetPreset

The easiest way is to use the built-in AnimationSpritesheetPreset helper: 
import { Presets } from "@rpgjs/client";

// In your client module configuration
spritesheets: [
  {
    id: "explosion",
    width: 1024,
    height: 1024,
    image: "explosion.png",
    ...Presets.AnimationSpritesheetPreset(4, 4), // 4x4 grid = 16 frames
  }
]
The AnimationSpritesheetPreset(framesWidth, framesHeight) automatically generates frame coordinates for a grid-based spritesheet. For example, AnimationSpritesheetPreset(4, 4) creates 16 frames arranged in a 4x4 grid.

​
Manual Spritesheet Configuration

You can also manually configure your spritesheet: 
spritesheets: [
  {
    id: "custom-animation",
    image: "my-animation.png",
    width: 512,
    height: 512,
    framesWidth: 8,
    framesHeight: 2,
    textures: {
      default: {
        animations: () => [
          [
            { time: 0, frameX: 0, frameY: 0 },
            { time: 100, frameX: 1, frameY: 0 },
            { time: 200, frameX: 2, frameY: 0 },
            // ... more frames
          ]
        ],
      }
    }
  }
]

​
2. Displaying Spritesheet Animations

​
On a Player

Use the showAnimation method on a player instance: 
/**
 * Display an animation on a player
 * @param graphic - The spritesheet ID
 * @param animationName - Animation name (default: 'default')
 * @param replaceGraphic - Whether to replace the player's graphic (default: false)
 */
player.showAnimation(graphic: string, animationName: string = 'default', replaceGraphic: boolean = false)
Examples: 
// Show explosion animation on player
player.showAnimation("explosion");

// Show specific animation from spritesheet
player.showAnimation("spell-effects", "fireball");

// Replace player graphic with animation
player.showAnimation("transformation", "default", true);

​
On a Map

Use the showAnimation method on a map instance: 
/**
 * Display an animation at a specific position on the map
 * @param position - The x, y coordinates where to display the animation
 * @param graphic - The spritesheet ID
 * @param animationName - Animation name (default: 'default')
 */
map.showAnimation(position: { x: number, y: number }, graphic: string, animationName: string = 'default')
Examples: 
// Show explosion at specific coordinates
map.showAnimation({ x: 100, y: 200 }, "explosion");

// Show spell effect at player position
const playerPos = { x: player.x, y: player.y };
map.showAnimation(playerPos, "spell-effects", "lightning");

​
Custom Component Animations

For more complex animations with custom logic, you can create Canvas Engine components.
There are two different prop shapes in the client rendering pipeline:
  • scene components loaded with provideLoadMap() receive data and params
  • component animations rendered with showComponentAnimation() receive their props directly (x, y, onFinish, and your custom params)
The examples below are for componentAnimations, not for custom map scene components.

​
1. Creating a Custom Animation Component

Create a Canvas Engine component file (e.g., ExplosionComponent.ce): 
<Sprite sheet x y anchor={0.5} scale alpha={opacity} />

<script>
  import { animatedSignal, mount, tick } from "canvasengine";
  import { inject, RpgClientEngine } from "@rpgjs/client";

  // Get props passed to the component animation
  const { 
    x, 
    y, 
    onFinish,     // Required: callback to remove animation when done
    intensity,    // Custom parameter
    color,        // Custom parameter
    duration      // Custom parameter with default value
  } = defineProps({
    duration: {
      default: 1000
    },
    intensity: {
      default: 1
    },
    color: {
      default: 'white'
    }
  });

  const client = inject(RpgClientEngine);

  // Animation properties
  const scale = animatedSignal(0.1, { duration: duration() });
  const opacity = animatedSignal(1, { duration: duration() });

  // Setup spritesheet
  const sheet = {
    definition: client.getSpriteSheet('explosion'),
    playing: 'default'
  };

  // Start animation on mount
  mount(() => {
    scale.set(intensity() * 2);
    opacity.set(0);
  });

  // Handle animation completion
  let elapsedTime = 0;
  tick(({ deltaTime }) => {
    elapsedTime += deltaTime;
    
    if (elapsedTime >= duration()) {
      if (onFinish) {
        onFinish(); // This removes the animation
      }
    }
  });
</script>
This direct prop shape matches how component animations are rendered in draw-map.ce: 
<componentAnimation.component ...animation />
By contrast, custom map scene components are mounted from canvas.ce with a data object: 
<sceneComponent() data={map().data} params={map().params} />

​
2. Registering the Component Animation

Add your component to the module configuration: 
import ExplosionComponent from "./components/ExplosionComponent.ce";
import { RpgClient, defineModule } from "@rpgjs/client";

export default defineModule<RpgClient>({
  componentAnimations: [
    {
      id: "explosion",
      component: ExplosionComponent
    }
  ]
});

​
3. Using the Prebuilt FX Component

RPGJS includes a ready-to-use component animation wrapper for the CanvasEngine Fx preset system. Register it like any other component animation: 
import { RpgClient, defineModule, PrebuiltComponentAnimations } from "@rpgjs/client";

export default defineModule<RpgClient>({
  componentAnimations: [
    {
      id: "explosion",
      component: PrebuiltComponentAnimations.Fx
    },
    {
      id: "heal",
      component: PrebuiltComponentAnimations.Fx
    }
  ]
});
Then call it with showComponentAnimation() and pass CanvasEngine Fx props: 
map.showComponentAnimation("explosion", { x: 300, y: 200 }, {
  name: "explosionSmall",
  scale: 1.2,
  zIndex: 1000
});

player.showComponentAnimation("heal", {
  name: "healPulse",
  scale: 0.8
});
Useful built-in Fx names include hitSpark, slashSpark, impactBurst, smokePuff, dustStep, dashDust, magicBurst, healPulse, pickup, levelUp, and explosionSmall. For looped FX, pass displayDuration to tell RPGJS when to remove the temporary component: 
player.showComponentAnimation("aura", {
  name: "magicBurst",
  loop: true,
  displayDuration: 1200
});
You can also pass a custom CanvasEngine preset object from client-side code. When triggering an animation from the server, keep params serializable; register a client wrapper component if the preset uses functions, Pixi textures, or other client-only objects.

​
4. Displaying Custom Component Animations

​
On a Player

Use the showComponentAnimation method. On a client sprite, it returns a promise that resolves when the component animation calls onFinish. 
/**
 * Display a component animation on a player
 * @param id - The component animation ID
 * @param params - Parameters to pass to the component
 */
sprite.showComponentAnimation(id: string, params: any): Promise<void>
Examples: 
// Basic explosion on player
await sprite.showComponentAnimation("explosion", {});

// Explosion with custom parameters
await sprite.showComponentAnimation("explosion", {
  intensity: 2.5,
  color: "red",
  duration: 1500
});

// Hit indicator with damage text
await sprite.showComponentAnimation("hit", {
  text: "150",
  color: "red"
});

// Heal animation
await sprite.showComponentAnimation("heal", {
  amount: 50,
  color: "green"
});
For a spritesheet animation on the same sprite, use showAnimation(): 
await sprite.showAnimation("explosion", "default")
Server-side methods such as player.showComponentAnimation() and map.showComponentAnimation() only send the animation request to clients and remain fire-and-forget.

​
On a Map

Use the showComponentAnimation method on the map: 
/**
 * Display a component animation at a specific position
 * @param id - The component animation ID
 * @param position - The x, y coordinates
 * @param params - Parameters to pass to the component
 */
map.showComponentAnimation(id: string, position: { x: number, y: number }, params: any)
Examples: 
// Explosion at specific location
map.showComponentAnimation("explosion", { x: 300, y: 400 }, {
  intensity: 3,
  duration: 2000
});

// Area effect at multiple positions
const positions = [
  { x: 100, y: 100 },
  { x: 150, y: 120 },
  { x: 200, y: 140 }
];

positions.forEach(pos => {
  map.showComponentAnimation("sparkle", pos, {
    color: "gold",
    size: 0.8
  });
});

​
Best Practices

​
1. Animation Performance

  • Keep spritesheet sizes reasonable (max 2048x2048)
  • Limit the number of simultaneous animations
  • Use onFinish callback to properly clean up component animations

​
2. Parameter Validation

Always provide default values for component parameters: 
const { 
  duration,
  intensity 
} = defineProps({
  duration: { default: 1000 },
  intensity: { default: 1 }
});

​
3. Memory Management

Component animations are automatically cleaned up when onFinish is called. Always call this callback when your animation completes: 
// In your component animation
tick(({ deltaTime }) => {
  elapsedTime += deltaTime;
  
  if (elapsedTime >= duration()) {
    if (onFinish) {
      onFinish(); // Essential for cleanup
    }
  }
});