Foundry Virtual Tabletop - API Documentation - Version 14
    Preparing search index...

    Class CanvasShakeEffect

    A lightweight screen/object shake utility.

    CanvasShakeEffect applies a smooth, time-based positional jitter to a target PIXI.DisplayObject by offsetting its x and y coordinates relative to a captured reference point. The shake motion is produced using two independent foundry.canvas.animation.SmoothNoise generators (one per axis) to avoid harsh, frame-to-frame randomness and provide a more natural camera-like shake.

    The effect runs for CanvasShakeEffect#duration milliseconds, with a linearly decaying amplitude from CanvasShakeEffect#maxDisplacement down to zero. After the active shake window ends, the target smoothly returns to its reference point using CanvasShakeEffect#returnSpeed as a per-tick interpolation factor.

    If multiple shake instances target the same object, the newest shake replaces the currently active one using a smooth transition, and the target returns to its original pre-shake position once shaking completes. Important: Changes of x and y from external sources outside of CanvasShakeEffect are taken into account.

    Safety/termination conditions:

    // Shake a target for 6 seconds with a 20px peak amplitude
    const shake = new foundry.canvas.animation.CanvasShakeEffect({
      target: canvas.stage,
      duration: 6000,
      maxDisplacement: 20,
      smoothness: 0.6,
      returnSpeed: 0.15,
      invalidateMasks: true
    });
    await shake.play();

    // Use a custom ticker and a deterministic time offset
    const shake = new foundry.canvas.animation.CanvasShakeEffect({
      target: someContainer,
      seed: 12345,
      ticker: myTicker
    });
    shake.play();
    Index

    Constructors

    constructor

    Properties

    duration maxDisplacement randomOffset returnSpeed smoothness TAKEOVER_DURATION_MS

    Accessors

    playing

    Methods

    play stop

    Constructors

    • Create a new CanvasShakeEffect

      Parameters

      • options: {
            duration?: number;
            invalidateMasks?: boolean;
            maxDisplacement?: number;
            returnSpeed?: number;
            seed?: number | null;
            smoothness?: number;
            target?: DisplayObject;
            ticker?: Ticker | null;
        }
        • Optionalduration?: number

          Total shake duration in MS.

        • OptionalinvalidateMasks?: boolean

          Should hidden canvas group masks be invalidated each frame?

        • OptionalmaxDisplacement?: number

          Maximum displacement in pixels.

        • OptionalreturnSpeed?: number

          "Return to origin" lerp factor per tick in the range [0, 1].

        • Optionalseed?: number | null

          Optional seed used to derive a deterministic time offset.

        • Optionalsmoothness?: number

          Smoothness in the range [0, 1]. Higher is smoother.

        • Optionaltarget?: DisplayObject

          The target PIXI display object to shake. Defaults to canvas.stage

        • Optionalticker?: Ticker | null

          Optional PIXI ticker. Defaults to foundry.canvas.animation.CanvasAnimation.ticker.

      Returns CanvasShakeEffect

    Properties

    duration: number

    Total shake duration in MS. After this duration elapses, the effect transitions into a return-to-origin phase.

    maxDisplacement: number

    Maximum displacement in pixels during the shake. This value is used as the target maximum offset along each axis.

    randomOffset: number

    The deterministic time offset derived from CanvasShakeEffect#seed. Applied to the elapsed time before generating noise.

    returnSpeed: number

    Return-to-origin interpolation factor per tick, in the range [0, 1]. Higher values restore the target to its reference point more quickly.

    smoothness: number

    Smoothness parameter in the range [0, 1]. Higher values produce smoother, lower-frequency motion.

    TAKEOVER_DURATION_MS: number = 150

    Duration in ms of the smooth takeover transition when a new shake replaces an active shake.

    Accessors

    • get playing(): boolean

      Whether the shake effect is currently active.

      Returns boolean

    Methods

    • Start the shake effect. Registers a ticker callback and returns a promise that resolves once the effect ends. If the effect is already playing, returns the existing promise (or a resolved one as a fallback).

      Returns Promise<void>

      A promise that resolves when the effect completes or is stopped.

    • Stop the shake effect immediately. Removes the ticker callback, optionally snaps the target back to its base position, and resolves the active promise.

      Parameters

      • Optionaloptions: { release?: boolean; snap?: boolean } = {}
        • Optionalrelease?: boolean

          Release the target shake state if no other shake is active.

        • Optionalsnap?: boolean

          Snap the target back to its base position.

      Returns void

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods