21539417834

Committed 31 Jan 2026 05:22AM UTC coverage: 88.61% (-0.1%) from 88.757%

Build # 21539417834

Build Type

Pull #3670

github

Committed by

web-flow

Commit Message

Merge 7773440cb into 8cba88917

Pull Request Pull Request #3670: feat: Implement Plugin System

Coverage Stats

5402 of 7377 branches covered (73.23%)

17 of 47 new or added lines in 4 files covered. (36.17%)

86 existing lines in 4 files now uncovered.

14882 of 16795 relevant lines covered (88.61%)

24427.76 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

0.0

/src/engine/plugin.ts

import type { Engine, EngineOptions } from './engine';
import type { ExcaliburGraphicsContext, ExcaliburGraphicsContextOptions } from './graphics';
import type { Scene } from './scene';

// TODO should these support async flows???

/**
 *
 * An Excalibur plugin packages up changes to excalibur in a convenient package such as
 * * Custom config intercepting and implementation
 * * Engine initialization customization
 * * Graphics Context configuration including
 *   * Custom RendererPlugins
 *   * Custom PostProcessors
 * * Scene customization including default ECS Systems, Components
 */
export abstract class Plugin {
  /**
   * Unique name of the plugin
   */
  name: string;
  /**
   * Plugin priority determines the order they're run, lower is first, higher is last, default is 0
   */
  priority: number = 0;

  /**
   * Perform any async loading
   */
  async onLoad?(): Promise<void> {
    return await Promise.resolve();
  }

  /**
   * Perform any extras when load complete
   */
  async onLoadComplete?(): Promise<void> {
    return await Promise.resolve();
  }

  /**
   * Optionally intercept and mutate the {@param options} passed into the Engine, and modify the engine
   */
  onEnginePreConfig?(engine: Engine, options: EngineOptions): void;

  /**
   * Optionally intercept and mutate the {@param options} passed into the Engine, and modify the engine
   */
  onEnginePostConfig?(engine: Engine, options: EngineOptions): void;

  /**
   * Optinally intercept the engine and modify before initialize
   */
  onEnginePreInitialize?(engine: Engine): void;

  /**
   * Optionally intercept the engine and modify after initialize
   */
  onEnginePostInitialize?(engine: Engine): void;

  /**
   * Optionally intercept the grpahics context before configuration and modify either the context or options
   */
  onGraphicsPreConfig?(context: ExcaliburGraphicsContext, options: ExcaliburGraphicsContextOptions): void;

  /**
   * Optionally intercept the grpahics context after configuration and modify either the context or options
   */
  onGraphicsPostConfig?(context: ExcaliburGraphicsContext, options: ExcaliburGraphicsContextOptions): void;

  /**
   * Optionally intercetp the graphics context and modify before initialize
   */
  onGraphicsPreInitialize?(context: ExcaliburGraphicsContext): void;

  /**
   * Optionally intercetp the graphics context and modify after initialize
   */
  onGraphicsPostInitialize?(context: ExcaliburGraphicsContext): void;

  /**
   * Optionally intercept a scene and modify before initialize
   */
  onScenePreInitialize?(scene: Scene): void;

  /**
   * Optionally intercept a scene and modify after initialize
   */
  onScenePostInitialize?(scene: Scene): void;

  /**
   * Optinally perform any cleanup necessary when the engine is disposed
   */
  dispose?(): void;
}

1	import type { Engine, EngineOptions } from './engine';
2	import type { ExcaliburGraphicsContext, ExcaliburGraphicsContextOptions } from './graphics';
3	import type { Scene } from './scene';
4
5	// TODO should these support async flows???
6
7	/**
8	*
9	* An Excalibur plugin packages up changes to excalibur in a convenient package such as
10	* * Custom config intercepting and implementation
11	* * Engine initialization customization
12	* * Graphics Context configuration including
13	* * Custom RendererPlugins
14	* * Custom PostProcessors
15	* * Scene customization including default ECS Systems, Components
16	*/
17	export abstract class Plugin {
18	/**
19	* Unique name of the plugin
20	*/
21	name: string;
22	/**
23	* Plugin priority determines the order they're run, lower is first, higher is last, default is 0
24	*/
NEW 25	priority: number = 0;	×
26
27	/**
28	* Perform any async loading
29	*/
30	async onLoad?(): Promise<void> {
NEW 31	return await Promise.resolve();	×
32	}
33
34	/**
35	* Perform any extras when load complete
36	*/
37	async onLoadComplete?(): Promise<void> {
NEW 38	return await Promise.resolve();	×
39	}
40
41	/**
42	* Optionally intercept and mutate the {@param options} passed into the Engine, and modify the engine
43	*/
44	onEnginePreConfig?(engine: Engine, options: EngineOptions): void;
45
46	/**
47	* Optionally intercept and mutate the {@param options} passed into the Engine, and modify the engine
48	*/
49	onEnginePostConfig?(engine: Engine, options: EngineOptions): void;
50
51	/**
52	* Optinally intercept the engine and modify before initialize
53	*/
54	onEnginePreInitialize?(engine: Engine): void;
55
56	/**
57	* Optionally intercept the engine and modify after initialize
58	*/
59	onEnginePostInitialize?(engine: Engine): void;
60
61	/**
62	* Optionally intercept the grpahics context before configuration and modify either the context or options
63	*/
64	onGraphicsPreConfig?(context: ExcaliburGraphicsContext, options: ExcaliburGraphicsContextOptions): void;
65
66	/**
67	* Optionally intercept the grpahics context after configuration and modify either the context or options
68	*/
69	onGraphicsPostConfig?(context: ExcaliburGraphicsContext, options: ExcaliburGraphicsContextOptions): void;
70
71	/**
72	* Optionally intercetp the graphics context and modify before initialize
73	*/
74	onGraphicsPreInitialize?(context: ExcaliburGraphicsContext): void;
75
76	/**
77	* Optionally intercetp the graphics context and modify after initialize
78	*/
79	onGraphicsPostInitialize?(context: ExcaliburGraphicsContext): void;
80
81	/**
82	* Optionally intercept a scene and modify before initialize
83	*/
84	onScenePreInitialize?(scene: Scene): void;
85
86	/**
87	* Optionally intercept a scene and modify after initialize
88	*/
89	onScenePostInitialize?(scene: Scene): void;
90
91	/**
92	* Optinally perform any cleanup necessary when the engine is disposed
93	*/
94	dispose?(): void;
95	}

excaliburjs / Excalibur / 21539417834

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous