PIXI-Group (#2478)

src/foundry/client/config.d.ts

@@ -1789,7 +1789,9 @@ declare global {
         [key: string]: LayerDefinition;
       }
 
-      interface GroupDefinition<GroupClass extends CanvasGroupConstructor = CanvasGroupConstructor> {
+      interface GroupDefinition<
+        GroupClass extends ToSpriteConstructor<CanvasGroupConstructor> = ToSpriteConstructor<CanvasGroupConstructor>,
+      > {
         groupClass: GroupClass;
         parent: string;
       }
@@ -1893,6 +1895,10 @@ interface CanvasGroupConstructor extends PixiContainerConstructor {
 
   /**
    * The name of this canvas group
+   * @remarks Not used in EffectsCanvasGroup in v11
    */
-  groupName: string;
+  groupName?: string;
 }
+
+type ToSpriteConstructor<Class extends new (sprite?: SpriteMesh) => any> = Pick<Class, keyof Class> &
+  (new (sprite: SpriteMesh) => InstanceType<Class>);

src/foundry/client/pixi/core/containers/base-canvas-group.d.ts

@@ -34,7 +34,7 @@ declare global {
    * @param ContainerClass - The parent Container class being mixed.
    * @returns A ContainerClass subclass mixed with BaseCanvasMixin features.
    */
-  function BaseCanvasMixin<BaseClass extends typeof PIXI.Container>(
+  function BaseCanvasMixin<BaseClass extends AnyConstructor<typeof PIXI.Container>>(
     ContainerClass: BaseClass,
   ): Mixin<typeof BaseCanvasMixinClass, BaseClass>;
 }

src/foundry/client/pixi/groups/effects.d.ts

@@ -1,29 +1,166 @@
-/**
- * A container group which contains visual effects rendered above the primary group.
- */
-declare class EffectsCanvasGroup extends PIXI.Container {
-  constructor();
+export {};
 
-  walls: WallsLayer;
+type CanvasBackgroundAlterationEffects = unknown;
 
-  lighting: LightingLayer;
+type CanvasIlluminationEffects = unknown;
 
-  weather: WeatherLayer;
+type CanvasColorationEffects = unknown;
 
-  sight: SightLayer;
-
-  /** @defaultValue `true` */
-  sortableChildren: boolean;
+type CanvasVisibility = unknown;
 
+declare global {
   /**
-   * The name of this canvas group
-   * @defaultValue `"effects"`
+   * A container group which contains visual effects rendered above the primary group.
    */
-  static groupName: string;
+  class EffectsCanvasGroup extends PIXI.Container {
+    constructor();
 
-  /**
-   * Create the member layers of the scene container
-   * @internal
-   */
-  protected _createLayers(): void;
+    /**
+     * The current global light source.
+     */
+    globalLightSource: GlobalLightSource;
+
+    /**
+     * Whether to currently animate light sources.
+     */
+    animateLightSources: boolean;
+
+    /**
+     * Whether to currently animate vision sources.
+     */
+    animateVisionSources: boolean;
+
+    /**
+     * A mapping of light sources which are active within the rendered Scene.
+     */
+    lightSources: Collection<LightSource>;
+
+    /**
+     * A Collection of vision sources which are currently active within the rendered Scene.
+     */
+    visionSources: Collection<VisionSource>;
+
+    /**
+     * A set of vision mask filters used in visual effects group
+     */
+    visualEffectsMaskingFilters: Set<VisualEffectsMaskingFilter>;
+
+    /**
+     * A layer of background alteration effects which change the appearance of the primary group render texture.
+     */
+    background: CanvasBackgroundAlterationEffects;
+
+    /**
+     * A layer which adds illumination-based effects to the scene.
+     */
+    illumination: CanvasIlluminationEffects;
+
+    /**
+     * A layer which adds color-based effects to the scene.
+     */
+    coloration: CanvasColorationEffects;
+
+    /**
+     * A layer which controls the current visibility of the scene.
+     */
+    visibility: CanvasVisibility;
+
+    /**
+     * Clear all effects containers and animated sources.
+     */
+    clearEffects(): void;
+
+    /**
+     * Draw the component layers of the canvas group.
+     */
+    draw(): Promise<void>;
+
+    /**
+     * Actions to take when the darkness level is changed
+     * @param darkness - The new darkness level
+     * @param prior    - The prior darkness level
+     * @internal
+     */
+    _onDarknessChange(darkness: number, prior: number): void;
+
+    /**
+     * Initialize LightSource objects for all AmbientLightDocument instances which exist within the active Scene.
+     */
+    initializeLightSources(): void;
+
+    /**
+     * Update the global light source which provides global illumination to the Scene.
+     * @param options - Options which modify how the source is updated
+     */
+    updateGlobalLightSource(options: {
+      /**
+       * Defer updating perception to manually update it later
+       * @defaultValue `false`
+       */
+      defer: boolean;
+    }): void;
+
+    /**
+     * Refresh the state and uniforms of all LightSource objects.
+     */
+    refreshLightSources(): boolean;
+
+    /**
+     * Refresh the state and uniforms of all VisionSource objects.
+     */
+    refreshVisionSources(): boolean;
+
+    /**
+     * Refresh the active display of lighting.
+     */
+    refreshLighting(): boolean;
+
+    /**
+     * Perform a deconstruction workflow for this canvas group when the canvas is retired.
+     */
+    tearDown(): Promise<void>;
+
+    /**
+     * Activate vision masking for visual effects
+     * @param enabled - Whether to enable or disable vision masking
+     *                  (default: `true`)
+     */
+    toggleMaskingFilters(enabled: boolean): void;
+
+    /**
+     * Activate post-processing effects for a certain effects channel.
+     * @param filterMode          - The filter mode to target.
+     * @param postProcessingModes - The post-processing modes to apply to this filter.
+     * @param uniforms            - The uniforms to update.
+     */
+    activatePostProcessingFilters(
+      filterMode: VisualEffectsMaskingFilter.FilterMode,
+      postProcessingModes: VisualEffectsMaskingFilter.PostProcessModes,
+      uniforms: AbstractBaseShader.Uniforms,
+    ): void;
+
+    /**
+     * Reset post-processing modes on all Visual Effects masking filters.
+     */
+    resetPostProcessingFilters(): void;
+
+    /**
+     * Activate light source animation for AmbientLight objects within this layer
+     */
+    activateAnimation(): void;
+
+    /**
+     * Deactivate light source animation for AmbientLight objects within this layer
+     */
+    deactivateAnimation(): void;
+
+    /**
+     * Animate a smooth transition of the darkness overlay to a target value.
+     * Only begin animating if another animation is not already in progress.
+     * @param target   - The target darkness level between 0 and 1
+     * @param duration - The desired animation time in milliseconds. Default is 10 seconds
+     * @returns A Promise which resolves once the animation is complete
+     */
+    animateDarkness(target: number, duration: number): Promise<unknown>;
+  }
 }

src/foundry/client/pixi/groups/environment.d.ts

@@ -0,0 +1,20 @@
+export {};
+
+declare global {
+  /**
+   * A container group which contains the primary canvas group and the effects canvas group.
+   */
+  class EnvironmentCanvasGroup extends BaseCanvasMixin(PIXI.Container) {
+    /**
+     * @defaultValue `"environment"`
+     */
+    static override groupName: string;
+
+    /**
+     * @defaultValue `false`
+     */
+    static override tearDownChildren: boolean;
+
+    override draw(): Promise<void>;
+  }
+}

src/foundry/client/pixi/groups/hidden.d.ts

@@ -0,0 +1,37 @@
+import type { EventMode } from "pixi.js";
+
+export {};
+
+declare global {
+  /**
+   * A specialized canvas group for rendering hidden containers before all others (like masks).
+   */
+  class HiddenCanvasGroup extends BaseCanvasMixin(PIXI.Container) {
+    /**
+     * @defaultValue `"none"`
+     */
+    override eventMode: EventMode;
+
+    /**
+     * The container which hold masks.
+     */
+    masks: PIXI.Container;
+
+    /**
+     * @defaultValue `"hidden"`
+     */
+    static override groupName: string;
+
+    /**
+     * Add a mask to this group.
+     * @param name          - Name of the mask.
+     * @param displayObject - Display object to add.
+     * @param position      - Position of the mask.
+     */
+    addMask(name: string, displayObject: PIXI.DisplayObject, position?: number | undefined): void;
+
+    override draw(): Promise<void>;
+
+    override tearDown(): Promise<void>;
+  }
+}

src/foundry/client/pixi/groups/index.d.ts

@@ -1,3 +1,7 @@
 import "./effects";
+import "./environment";
+import "./hidden";
 import "./interface";
+import "./overlay";
 import "./primary";
+import "./rendered";

src/foundry/client/pixi/groups/interface.d.ts

@@ -1,27 +1,72 @@
-/**
- * A container group which displays interface elements rendered above other canvas groups.
- */
-declare class InterfaceCanvasGroup extends PIXI.Container {
-  constructor();
+export {};
 
-  sounds: SoundsLayer;
+declare global {
+  /**
+   * A container group which displays interface elements rendered above other canvas groups.
+   */
+  class InterfaceCanvasGroup extends BaseCanvasMixin(PIXI.Container) {
+    /**
+     * @defaultValue `"interface"`
+     */
+    static override groupName: string;
 
-  notes: NotesLayer;
+    /**
+     * Draw the canvas group and all its component layers.
+     */
+    override draw(): Promise<void>;
 
-  controls: ControlsLayer;
+    /**
+     * Display scrolling status text originating from this ObjectHUD container.
+     * @param origin  - An origin point where the text should first emerge
+     * @param content - The text content to display
+     * @param options - Options which customize the text animation
+     * @returns - The created PreciseText object which is scrolling
+     */
+    createScrollingText(
+      origin: Point,
+      content: string,
+      options?: {
+        /**
+         * The duration of the scrolling effect in milliseconds
+         * @defaultValue `2000`
+         */
+        duration?: number;
 
-  /** @defaultValue `true` */
-  sortableChildren: boolean;
+        /**
+         * The distance in pixels that the scrolling text should travel
+         * @defaultValue (2 * text.width)
+         */
+        distance?: number;
 
-  /**
-   * The name of this canvas group
-   * @defaultValue `"interface"`
-   */
-  static groupName: string;
+        /**
+         * The original anchor point where the text appears
+         */
+        anchor: foundry.CONST.TEXT_ANCHOR_POINTS;
 
-  /**
-   * Create the member layers of the scene container
-   * @internal
-   */
-  protected _createLayers(): void;
+        /**
+         * The direction in which the text scrolls
+         */
+        direction: foundry.CONST.TEXT_ANCHOR_POINTS;
+
+        /**
+         * An amount of randomization between [0, 1] applied to the initial position
+         * @defaultValue `0`
+         */
+        jitter: number;
+
+        /**
+         * Additional parameters of PIXI.TextStyle which are applied to the text
+         */
+        textStyle: InexactPartial<PIXI.ITextStyle>;
+      },
+    ): Promise<PreciseText | null>;
+
+    /**
+     * @deprecated since v11, will be removed in v13
+     * @remarks "InterfaceCanvasGroup.reverseMaskfilter is deprecated.
+     * Please create your own ReverseMaskFilter, or instead of attaching the filter to each of your objects extend the
+     * already masked GridLayer with a container for these objects, which is much better for performance."
+     */
+    get reverseMaskfilter(): ReverseMaskFilter;
+  }
 }

src/foundry/client/pixi/groups/overlay.d.ts

@@ -0,0 +1,18 @@
+export {};
+
+declare global {
+  /**
+   * A container group which is not bound to the stage world transform.
+   */
+  class OverlayCanvasGroup extends BaseCanvasMixin(UnboundContainer) {
+    /**
+     * @defaultValue `"overlay"`
+     */
+    static override groupName: string;
+
+    /**
+     * @defaultValue `false`
+     */
+    static override tearDownChildren: boolean;
+  }
+}