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

    Interface ParticleGeneratorConfiguration

    interface ParticleGeneratorConfiguration {
        alpha?: ParticleGeneratorValue;
        anchor?: ParticleGeneratorAnchor;
        anchorOffset?: IPointData | null;
        anchorPoint?: ParticleGeneratorAnchorPoint;
        area?: ParticleGeneratorArea | null;
        behavior?: ParticleGeneratorBehavior | ParticleGeneratorBehaviorId | null;
        blend?: BLEND_MODES;
        blur?:
            | number
            | { intensity: number; quality?: number }
            | { enabled: boolean; intensity: number; quality?: number }
            | null;
        bounds?: ParticleGeneratorRectangle | null;
        clip?: boolean | ParticleGeneratorRectangle | ParticleGeneratorClipOptions;
        constraintArea?:
            | "world"
            | "view"
            | ParticleGeneratorRectangle
            | "budget"
            | null;
        constraintMode?: ParticleGeneratorConstraintMode
        | null;
        container?: Container<DisplayObject>;
        count?: number;
        debug?: boolean | ParticleGeneratorDebugOptions | null;
        drift?: { enabled: boolean; intensity: number };
        elevation?: number;
        fade?: ParticleGeneratorFadeOptions;
        follow?: ParticleGeneratorFollowOptions;
        initial?: number;
        lifetime?: ParticleGeneratorRange;
        manual?: boolean | null;
        mask?: BaseShapeData | DisplayObject | IShape | null;
        mode?: ParticleGeneratorMode;
        newlyVisible?: boolean;
        onDeath?: ParticleGeneratorDeathCallback | null;
        onSpawn?: ParticleGeneratorParticleCallback | null;
        onTick?: ParticleGeneratorTickCallback | null;
        onUpdate?: ParticleGeneratorParticleCallback | null;
        orbit?: ParticleGeneratorOrbitOptions;
        particleAnchor?: IPointData | null;
        perFrame?: number;
        positionTest?: ParticleGeneratorPositionTest | null;
        probability?: number;
        randomizeAgeInPadding?: boolean;
        restitution?: number;
        rotation?: ParticleGeneratorRotationOptions;
        sampleMode?: ParticleGeneratorAreaSampleMode;
        scale?: ParticleGeneratorValue;
        shaderClass?: typeof BaseSamplerShader | null;
        sort?: number;
        spawnRate?: number;
        textures?: (string | Texture<Resource>)[];
        ticker?: Ticker;
        tint?: ParticleGeneratorColorValue;
        velocity?: ParticleGeneratorVelocityOptions | null;
        viewPadding?: number;
    }
    Index

    Properties

    alpha? anchor? anchorOffset? anchorPoint? area? behavior? blend? blur? bounds? clip? constraintArea? constraintMode? container? count? debug? drift? elevation? fade? follow? initial? lifetime? manual? mask? mode? newlyVisible? onDeath? onSpawn? onTick? onUpdate? orbit? particleAnchor? perFrame? positionTest? probability? randomizeAgeInPadding? restitution? rotation? sampleMode? scale? shaderClass? sort? spawnRate? textures? ticker? tint? velocity? viewPadding?

    Properties

    alpha?: ParticleGeneratorValue

    The alpha value for particles.

    anchor?: ParticleGeneratorAnchor

    An optional anchor used to attach areas and behaviors.

    anchorOffset?: IPointData | null

    A fixed offset (scene pixels) applied to the anchor.

    anchorPoint?: ParticleGeneratorAnchorPoint

    Which point to use when anchoring.

    area?: ParticleGeneratorArea | null

    The default spawn area in "effect" mode (scene coordinates).

    behavior?: ParticleGeneratorBehavior | ParticleGeneratorBehaviorId | null

    Optional behavior.

    blend?: BLEND_MODES

    The blend mode used to render particles.

    blur?:
        | number
        | { intensity: number; quality?: number }
        | { enabled: boolean; intensity: number; quality?: number }
        | null

    An optional blur filter applied to the internal container.

    bounds?: ParticleGeneratorRectangle | null

    Optional generator bounds in scene coordinates. This is used for coordinate conversion, viewport clamping, and optional clipping. Defaults to the current Scene dimensions.

    clip?: boolean | ParticleGeneratorRectangle | ParticleGeneratorClipOptions

    Clip (=> mask) configuration. Use true for default clipping. If no clip rectangle is provided and ParticleGeneratorConfiguration#area is a foundry.data.BaseShapeData, that shape is used.

    constraintArea?: "world" | "view" | ParticleGeneratorRectangle | "budget" | null

    The constraint area.

    • "budget": the padded viewport rectangle.
    • "view": the unpadded viewport rectangle.
    • "world": the generator bounds.
    • Rectangle: a custom rectangle in scene coordinates. If null, defaults to "budget" in ambient mode when constraintMode is not "none".
    constraintMode?: ParticleGeneratorConstraintMode | null

    How to handle particles leaving the constraint area. If null, defaults to "kill" in ambient mode and "none" in effect mode.

    container?: Container<DisplayObject>

    The parent container which receives the internal particle container. Defaults to canvas.primary.

    count?: number

    The target particle count.

    • In "ambient" mode, this is the maximum for the full bounds and is scaled by visible area.
    • In "effect" mode, this is the absolute target.
    debug?: boolean | ParticleGeneratorDebugOptions | null

    Optional debugging helpers.

    drift?: { enabled: boolean; intensity: number }

    Optional random drift configuration.

    elevation?: number

    The elevation for the particle container.

    fade?: ParticleGeneratorFadeOptions

    Fade envelope configuration.

    follow?: ParticleGeneratorFollowOptions

    Follow behavior options.

    initial?: number

    The initial proportion (0..1) of the computed target particle count to spawn on start.

    lifetime?: ParticleGeneratorRange

    The particle lifetime in milliseconds.

    manual?: boolean | null

    If true, particles are never spawned automatically. If null, defaults to true in "effect" mode unless spawnRate is explicitly configured and false in "ambient" mode. Legacy perFrame does not change the default.

    mask?: BaseShapeData | DisplayObject | IShape | null

    An explicit mask for the particle container. Accepts either a pre-built PIXI.DisplayObject, a PIXI shape, or a foundry.data.BaseShapeData which is drawn into a PIXI.Graphics. Presence implies masking is desired, and this mask takes precedence over clip.

    mode?: ParticleGeneratorMode

    The runtime mode.

    • "ambient": maintains a stable density in the visible region (viewport-based budget).
    • "effect": spawns in a defined area; particles are lifetime-driven unless constrained.
    newlyVisible?: boolean

    If true, prioritize spawning particles in newly-visible areas when the view changes (pan/zoom).

    onDeath?: ParticleGeneratorDeathCallback | null

    An optional callback called when a particle is recycled.

    onSpawn?: ParticleGeneratorParticleCallback | null

    An optional callback called after the particle has been placed and configured. This is a handy place to attach custom per-particle data for batch shaders.

    onTick?: ParticleGeneratorTickCallback | null

    An optional callback called per frame (not per particle!).

    onUpdate?: ParticleGeneratorParticleCallback | null

    An optional callback called each frame for each live particle, after position, rotation, tint, and alpha have been computed.

    orbit?: ParticleGeneratorOrbitOptions

    Orbit behavior options.

    particleAnchor?: IPointData | null

    Optional sprite anchor override for particle textures. If null, each texture's defaultAnchor is used.

    perFrame?: number

    Deprecated since v14. Use spawnRate instead. If spawnRate is omitted or null, this legacy per-frame value is converted using the Pixi ticker target frame rate.

    positionTest?: ParticleGeneratorPositionTest | null

    An optional spawn validator. The function is invoked as (x, y, {generator, particle}) and must return true if the location is valid. Coordinates are scene coordinates in pixels. The generator evaluates a single candidate position per spawn attempt.

    probability?: number

    The chance (0..1) that a spawn attempt actually creates a particle.

    randomizeAgeInPadding?: boolean

    If true, particles spawned in padded regions can start partially through their lifetime.

    restitution?: number

    Bounce restitution factor (0..1) used when constraintMode is "bounce".

    rotation?: ParticleGeneratorRotationOptions

    Rotation configuration for particles.

    sampleMode?: ParticleGeneratorAreaSampleMode

    Which part of the spawn area to sample.

    scale?: ParticleGeneratorValue

    The scale value for particles.

    shaderClass?: typeof BaseSamplerShader | null

    Optional shader class used to render particles. Defaults to BaseSamplerShader. Batchable shaders are the fast path for sustained effects. ParticleGenerator creates plain SpriteMesh instances, so shaders which require foundry.canvas.primary.PrimarySpriteMesh occlusion or depth data are not supported.

    sort?: number

    The sorting key for the particle container.

    spawnRate?: number

    The maximum number of particles that may be spawned per second (auto-spawn mode).

    textures?: (string | Texture<Resource>)[]

    The particle texture sources. Each entry may be a PIXI.Texture or a string path usable by foundry.canvas.getTexture/PIXI.Texture.from.

    ticker?: Ticker

    The ticker used to drive the update loop. Defaults to CanvasAnimation.ticker.

    tint?: ParticleGeneratorColorValue

    The tint color for particles.

    velocity?: ParticleGeneratorVelocityOptions | null

    The particle velocity in pixels per second.

    viewPadding?: number

    A proportion (0..1+) of extra area around the visible region used for spawning. For example, 0.2 extends the spawn region by 20% in each dimension.

    Settings

    Member Visibility

    On This Page

    Properties