Feature Extensions API (#8410)

pixijs · Jun 20, 2022 · b98acb1 · b98acb1
1 parent 03f8b02
commit b98acb1
Show file tree

Hide file tree

Showing 77 changed files with 654 additions and 188 deletions.
diff --git a/bundles/pixi.js-legacy/src/index.ts b/bundles/pixi.js-legacy/src/index.ts
@@ -1,4 +1,4 @@
-import { AccessibilityManager, InteractionManager } from 'pixi.js';
+import { extensions } from 'pixi.js';
 import { CanvasRenderer, canvasUtils } from '@pixi/canvas-renderer';
 import { CanvasMeshRenderer } from '@pixi/canvas-mesh';
 import { CanvasGraphicsRenderer } from '@pixi/canvas-graphics';
@@ -10,13 +10,13 @@ import '@pixi/canvas-particle-container';
 import '@pixi/canvas-display';
 import '@pixi/canvas-text';
 
-CanvasRenderer.registerPlugin('accessibility', AccessibilityManager);
-CanvasRenderer.registerPlugin('extract', CanvasExtract);
-CanvasRenderer.registerPlugin('graphics', CanvasGraphicsRenderer);
-CanvasRenderer.registerPlugin('interaction', InteractionManager);
-CanvasRenderer.registerPlugin('mesh', CanvasMeshRenderer);
-CanvasRenderer.registerPlugin('prepare', CanvasPrepare);
-CanvasRenderer.registerPlugin('sprite', CanvasSpriteRenderer);
+extensions.add(
+    CanvasExtract,
+    CanvasGraphicsRenderer,
+    CanvasMeshRenderer,
+    CanvasPrepare,
+    CanvasSpriteRenderer
+);
 
 // Export ES for those importing specifically by name,
 // e.g., `import {autoDetectRenderer} from 'pixi.js-legacy'`

diff --git a/bundles/pixi.js/src/index.ts b/bundles/pixi.js/src/index.ts
@@ -3,10 +3,9 @@ import '@pixi/polyfill';
 import * as utils from '@pixi/utils';
 import { AccessibilityManager } from '@pixi/accessibility';
 import { InteractionManager } from '@pixi/interaction';
-import { Application } from '@pixi/app';
-import { Renderer, BatchRenderer } from '@pixi/core';
+import { BatchRenderer, extensions } from '@pixi/core';
 import { Extract } from '@pixi/extract';
-import { Loader, AppLoaderPlugin } from '@pixi/loaders';
+import { AppLoaderPlugin } from '@pixi/loaders';
 import { CompressedTextureLoader, DDSLoader, KTXLoader } from '@pixi/compressed-textures';
 import { ParticleRenderer } from '@pixi/particle-container';
 import { Prepare } from '@pixi/prepare';
@@ -24,25 +23,27 @@ import '@pixi/mixin-cache-as-bitmap';
 import '@pixi/mixin-get-child-by-name';
 import '@pixi/mixin-get-global-position';
 
-// Install renderer plugins
-Renderer.registerPlugin('accessibility', AccessibilityManager);
-Renderer.registerPlugin('extract', Extract);
-Renderer.registerPlugin('interaction', InteractionManager);
-Renderer.registerPlugin('particle', ParticleRenderer);
-Renderer.registerPlugin('prepare', Prepare);
-Renderer.registerPlugin('batch', BatchRenderer);
-Renderer.registerPlugin('tilingSprite', TilingSpriteRenderer);
+extensions.add(
+    // Install renderer plugins
+    AccessibilityManager,
+    Extract,
+    InteractionManager,
+    ParticleRenderer,
+    Prepare,
+    BatchRenderer,
+    TilingSpriteRenderer,
 
-// Install loader plugins
-Loader.registerPlugin(BitmapFontLoader);
-Loader.registerPlugin(CompressedTextureLoader);
-Loader.registerPlugin(DDSLoader);
-Loader.registerPlugin(KTXLoader);
-Loader.registerPlugin(SpritesheetLoader);
+    // Install loader plugins
+    BitmapFontLoader,
+    CompressedTextureLoader,
+    DDSLoader,
+    KTXLoader,
+    SpritesheetLoader,
 
-// Install application plugins
-Application.registerPlugin(TickerPlugin);
-Application.registerPlugin(AppLoaderPlugin);
+    // Install application plugins
+    TickerPlugin,
+    AppLoaderPlugin
+);
 
 /**
  * String of the current PIXI version.

diff --git a/packages/accessibility/README.md b/packages/accessibility/README.md
@@ -10,7 +10,7 @@ npm install @pixi/accessibility
 
 ```js
 import { AccessibilityManager } from '@pixi/accessibility';
-import { Renderer } from '@pixi/core';
+import { extensions } from '@pixi/core';
 
-Renderer.registerPlugin('accessibility', AccessibilityManager);
+extensions.add(AccessibilityManager);
 ```
diff --git a/packages/accessibility/src/AccessibilityManager.ts b/packages/accessibility/src/AccessibilityManager.ts
@@ -4,7 +4,7 @@ import { accessibleTarget } from './accessibleTarget';
 
 import type { Rectangle } from '@pixi/math';
 import type { Container } from '@pixi/display';
-import type { Renderer, AbstractRenderer } from '@pixi/core';
+import { Renderer, AbstractRenderer, ExtensionMetadata, ExtensionType } from '@pixi/core';
 import type { IAccessibleHTMLElement } from './accessibleTarget';
 
 // add some extra variables to the container..
@@ -35,6 +35,15 @@ const DIV_HOOK_ZINDEX = 2;
  */
 export class AccessibilityManager
 {
+    /** @ignore */
+    static extension: ExtensionMetadata = {
+        name: 'accessibility',
+        type: [
+            ExtensionType.RendererPlugin,
+            ExtensionType.CanvasRendererPlugin,
+        ],
+    };
+
     /** Setting this to true will visually show the divs. */
     public debug = false;
 

diff --git a/packages/accessibility/test/AccessibilityManager.tests.ts b/packages/accessibility/test/AccessibilityManager.tests.ts
@@ -1,7 +1,7 @@
 import { AccessibilityManager } from '@pixi/accessibility';
 import { CanvasRenderer } from '@pixi/canvas-renderer';
 import { DisplayObject, Container } from '@pixi/display';
-import { Renderer } from '@pixi/core';
+import { extensions, Renderer } from '@pixi/core';
 import { isMobile } from '@pixi/utils';
 import { expect } from 'chai';
 
@@ -22,12 +22,14 @@ describe('AccessibilityManager', () =>
 
     it('should be plugin for renderer', () =>
     {
-        CanvasRenderer.registerPlugin('accessibility', AccessibilityManager);
+        extensions.add(AccessibilityManager);
 
         const renderer = new CanvasRenderer();
 
         expect(renderer.plugins.accessibility).to.be.instanceof(AccessibilityManager);
         renderer.destroy();
+
+        extensions.remove(AccessibilityManager);
     });
 
     it('should remove touch hook when destroyed', () =>

diff --git a/packages/app/README.md b/packages/app/README.md
@@ -17,7 +17,7 @@ document.body.appendChild(app.view);
 
 ### Plugins
 
-PixiJS provides a few plugins to add features to the Application. These can be installed from the following packages. Use `Application.registerPlugin` to use these plugins. _Note: if you are using pixi.js or pixi.js-legacy bundles, this is unnecessary since plugins are installed automatically by default._
+PixiJS provides a few plugins to add features to the Application. These can be installed from the following packages. Use `extensions.add` to use these plugins. _Note: if you are using pixi.js or pixi.js-legacy bundles, this is unnecessary since plugins are installed automatically by default._
 
 * **LoaderPlugin** from `@pixi/loaders`
 * **TickerPlugin** from `@pixi/ticker`
diff --git a/packages/app/src/Application.ts b/packages/app/src/Application.ts
@@ -1,14 +1,14 @@
 import { Container } from '@pixi/display';
-import { autoDetectRenderer } from '@pixi/core';
+import { autoDetectRenderer, extensions, ExtensionType } from '@pixi/core';
 
 import type { Rectangle } from '@pixi/math';
 import type { Renderer, IRendererOptionsAuto, AbstractRenderer } from '@pixi/core';
 import type { IDestroyOptions } from '@pixi/display';
+import { deprecation } from '@pixi/utils';
 
 /**
  * Any plugin that's usable for Application should contain these methods.
  * @memberof PIXI
- * @see {@link PIXI.Application.registerPlugin}
  */
 export interface IApplicationPlugin
 {
@@ -47,7 +47,7 @@ export interface Application extends GlobalMixins.Application {}
 export class Application
 {
     /** Collection of installed plugins. */
-    private static _plugins: IApplicationPlugin[] = [];
+    static _plugins: IApplicationPlugin[] = [];
 
     /**
      * The root display container that's rendered.
@@ -111,13 +111,20 @@ export class Application
     }
 
     /**
-     * Register a middleware plugin for the application
+     * Use the {@link PIXI.extensions.add} API to register plugins.
+     * @deprecated since 6.5.0
      * @static
      * @param {PIXI.IApplicationPlugin} plugin - Plugin being installed
      */
     static registerPlugin(plugin: IApplicationPlugin): void
     {
-        Application._plugins.push(plugin);
+        // #if _DEBUG
+        deprecation('6.5.0', 'Application.registerPlugin() is deprecated, use extensions.add()');
+        // #endif
+        extensions.add({
+            type: ExtensionType.Application,
+            ref: plugin,
+        });
     }
 
     /** Render the current stage. */
@@ -177,3 +184,28 @@ export class Application
         this.renderer = null;
     }
 }
+
+extensions.handle(
+    ExtensionType.Application,
+    (extension) =>
+    {
+        const plugins = Application._plugins;
+        const plugin = extension.ref as unknown as IApplicationPlugin;
+
+        if (!plugins.includes(plugin))
+        {
+            plugins.push(plugin);
+        }
+    },
+    (extension) =>
+    {
+        const plugins = Application._plugins;
+        const plugin = extension.ref as unknown as IApplicationPlugin;
+        const index = plugins.indexOf(plugin);
+
+        if (index !== -1)
+        {
+            plugins.splice(index, 1);
+        }
+    }
+);
diff --git a/packages/app/src/ResizePlugin.ts b/packages/app/src/ResizePlugin.ts
@@ -1,5 +1,5 @@
 import type { CanvasRenderer } from '@pixi/canvas-renderer';
-import type { Renderer } from '@pixi/core';
+import { ExtensionMetadata, ExtensionType, Renderer } from '@pixi/core';
 import type { IApplicationOptions } from './Application';
 
 /**
@@ -9,6 +9,9 @@ import type { IApplicationOptions } from './Application';
  */
 export class ResizePlugin
 {
+    /** @ignore */
+    static extension: ExtensionMetadata = ExtensionType.Application;
+
     public static resizeTo: Window | HTMLElement;
     public static resize: () => void;
     public static renderer: Renderer | CanvasRenderer;

diff --git a/packages/app/src/index.ts b/packages/app/src/index.ts
@@ -1,6 +1,6 @@
-import { Application } from './Application';
 import { ResizePlugin } from './ResizePlugin';
+import { extensions } from '@pixi/core';
 
-Application.registerPlugin(ResizePlugin);
+extensions.add(ResizePlugin);
 
 export * from './Application';
diff --git a/packages/app/test/Application.tests.ts b/packages/app/test/Application.tests.ts
@@ -1,4 +1,5 @@
 import { Application } from '@pixi/app';
+import { extensions, ExtensionType } from '@pixi/core';
 import { Container } from '@pixi/display';
 import { skipHello } from '@pixi/utils';
 import { expect } from 'chai';
@@ -28,8 +29,9 @@ describe('Application', () =>
             init: sinon.spy(),
             destroy: sinon.spy(),
         };
+        const extension = { type: ExtensionType.Application, ref: plugin };
 
-        Application.registerPlugin(plugin);
+        extensions.add(extension);
 
         const app = new Application();
 
@@ -38,7 +40,7 @@ describe('Application', () =>
         expect(plugin.init).to.be.calledOnce;
         expect(plugin.destroy).to.be.calledOnce;
 
-        Application['_plugins'].pop();
+        extensions.remove(extension);
     });
 
     it('should remove canvas when destroyed', () =>

diff --git a/packages/basis/README.md b/packages/basis/README.md
@@ -12,7 +12,7 @@ npm install @pixi/core
 
 ```js
 import { BasisLoader } from '@pixi/basis';
-import { Loader } from '@pixi/loaders';
+import { extensions } from '@pixi/core';
 
-Loader.registerPlugin(BasisLoader);
+extensions.add(BasisLoader);
 ```
diff --git a/packages/basis/src/BasisLoader.ts b/packages/basis/src/BasisLoader.ts
@@ -1,5 +1,5 @@
 import { TYPES, MIPMAP_MODES, ALPHA_MODES, FORMATS } from '@pixi/constants';
-import { BaseTexture, BufferResource, Texture } from '@pixi/core';
+import { BaseTexture, BufferResource, ExtensionMetadata, ExtensionType, Texture } from '@pixi/core';
 import { CompressedTextureResource, INTERNAL_FORMATS } from '@pixi/compressed-textures';
 import {
     BASIS_FORMATS,
@@ -64,6 +64,9 @@ LoaderResource.setExtensionXhrType('basis', LoaderResource.XHR_RESPONSE_TYPE.BUF
  */
 export class BasisLoader
 {
+    /** @ignore */
+    static extension: ExtensionMetadata = ExtensionType.Loader;
+
     private static basisBinding: BasisBinding;
     private static defaultRGBFormat: { basisFormat: BASIS_FORMATS, textureFormat: INTERNAL_FORMATS | TYPES };
     private static defaultRGBAFormat: { basisFormat: BASIS_FORMATS, textureFormat: INTERNAL_FORMATS | TYPES };

diff --git a/packages/basis/src/index.ts b/packages/basis/src/index.ts
@@ -1,8 +1,7 @@
-import { Loader } from '@pixi/loaders';
+import { extensions } from '@pixi/core';
 import { BasisLoader } from './BasisLoader';
 
 export * from './Basis';
 export * from './BasisLoader';
 
-// parse any BASIS supercompressed files into textures
-Loader.registerPlugin(BasisLoader);
+extensions.add(BasisLoader);
diff --git a/packages/canvas-extract/README.md b/packages/canvas-extract/README.md
@@ -9,8 +9,8 @@ npm install @pixi/canvas-extract
 ## Usage
 
 ```js
+import { extensions } from '@pixi/core';
 import { CanvasExtract } from '@pixi/canvas-extract';
-import { CanvasRenderer } from '@pixi/canvas-renderer';
 
-CanvasRenderer.registerPlugin('extract', CanvasExtract);
+extensions.add(CanvasExtract);
 ```
diff --git a/packages/canvas-extract/src/CanvasExtract.ts b/packages/canvas-extract/src/CanvasExtract.ts
@@ -1,4 +1,4 @@
-import { RenderTexture } from '@pixi/core';
+import { ExtensionMetadata, ExtensionType, RenderTexture } from '@pixi/core';
 import { CanvasRenderTarget } from '@pixi/utils';
 import { Rectangle } from '@pixi/math';
 import { CanvasRenderer } from '@pixi/canvas-renderer';
@@ -16,6 +16,12 @@ const TEMP_RECT = new Rectangle();
  */
 export class CanvasExtract
 {
+    /** @ignore */
+    static extension: ExtensionMetadata = {
+        name: 'extract',
+        type: ExtensionType.CanvasRendererPlugin,
+    };
+
     /** A reference to the current renderer */
     public renderer: CanvasRenderer;
 

diff --git a/packages/canvas-extract/test/CanvasExtract.tests.ts b/packages/canvas-extract/test/CanvasExtract.tests.ts
@@ -3,7 +3,7 @@ import { CanvasRenderer } from '@pixi/canvas-renderer';
 import { Sprite } from '@pixi/sprite';
 import { expect } from 'chai';
 import { skipHello } from '@pixi/utils';
-import { Texture, RenderTexture } from '@pixi/core';
+import { Texture, RenderTexture, extensions } from '@pixi/core';
 import { CanvasSpriteRenderer } from '@pixi/canvas-sprite';
 
 import '@pixi/canvas-display';
@@ -12,11 +12,8 @@ skipHello();
 
 describe('CanvasExtract', () =>
 {
-    before(() =>
-    {
-        CanvasRenderer.registerPlugin('extract', CanvasExtract);
-        CanvasRenderer.registerPlugin('sprite', CanvasSpriteRenderer);
-    });
+    before(() => extensions.add(CanvasExtract, CanvasSpriteRenderer));
+    after(() => extensions.remove(CanvasExtract, CanvasSpriteRenderer));
 
     it('should access extract on renderer', () =>
     {

diff --git a/packages/canvas-graphics/README.md b/packages/canvas-graphics/README.md
@@ -10,7 +10,7 @@ npm install @pixi/canvas-graphics
 
 ```js
 import { CanvasGraphicsRenderer } from '@pixi/canvas-graphics';
-import { CanvasRenderer } from '@pixi/canvas-renderer';
+import { extensions } from '@pixi/core';
 
-CanvasRenderer.registerPlugin('graphics', CanvasGraphicsRenderer);
+extensions.add(CanvasGraphicsRenderer);
 ```