excalibur 0.33.0-alpha.99 → 1.1.0-alpha.310

package/build/{dist → esm/src/engine}/graphics/context/excalibur-graphics-context-2d-canvas.d.ts

@@ -1,8 +1,9 @@
-import type { ExcaliburGraphicsContext, LineGraphicsOptions, PointGraphicsOptions, ExcaliburGraphicsContextOptions, DebugDraw, HTMLImageSource } from './excalibur-graphics-context';
+import type { ExcaliburGraphicsContext, LineGraphicsOptions, PointGraphicsOptions, ExcaliburGraphicsContextOptions, DebugDraw, DebugTextOptions, HTMLImageSource } from './excalibur-graphics-context';
 import type { Vector } from '../../math/vector';
 import { Color } from '../../color';
 import type { Resolution } from '../../screen';
 import type { PostProcessor } from '../post-processor/post-processor';
+import type { RendererPlugin } from './renderer';
 import { AffineMatrix } from '../../math/affine-matrix';
 import type { Material, MaterialOptions } from './material';
 declare class ExcaliburGraphicsContext2DCanvasDebug implements DebugDraw {
@@ -20,17 +21,22 @@ declare class ExcaliburGraphicsContext2DCanvasDebug implements DebugDraw {
     drawLine(start: Vector, end: Vector, lineOptions?: LineGraphicsOptions): void;
     drawPoint(point: Vector, pointOptions?: PointGraphicsOptions): void;
     drawCircle(pos: Vector, radius: number, color: Color, stroke?: Color, thickness?: number): void;
-    drawText(text: string, pos: Vector): void;
+    drawText(text: string, pos: Vector, options?: DebugTextOptions): void;
+    measureText(text: string, scale?: number): {
+        width: number;
+        height: number;
+    };
 }
 export interface ExcaliburGraphicsContext2DOptions extends ExcaliburGraphicsContextOptions {
     context?: CanvasRenderingContext2D;
 }
 export declare class ExcaliburGraphicsContext2DCanvas implements ExcaliburGraphicsContext {
+    private _ctx;
     /**
      * Meant for internal use only. Access the internal context at your own risk and no guarantees this will exist in the future.
      * @internal
      */
-    __ctx: CanvasRenderingContext2D;
+    get __ctx(): CanvasRenderingContext2D;
     get width(): number;
     get height(): number;
     /**
@@ -102,6 +108,10 @@ export declare class ExcaliburGraphicsContext2DCanvas implements ExcaliburGraphi
     removePostProcessor(_postprocessor: PostProcessor): void;
     clearPostProcessors(): void;
     updatePostProcessors(elapsed: number): void;
+    register<T extends RendererPlugin>(_renderer: T): void;
+    lazyRegister<TRenderer extends RendererPlugin>(_type: TRenderer['type'], _renderer: () => TRenderer): void;
+    get(_rendererName: string): RendererPlugin | null;
+    draw<TRenderer extends RendererPlugin>(_rendererName: TRenderer['type'], ..._args: Parameters<TRenderer['draw']>): void;
     beginDrawLifecycle(): void;
     endDrawLifecycle(): void;
     set material(material: Material | undefined | null);

package/build/{dist → esm/src/engine}/graphics/context/excalibur-graphics-context-webgl.d.ts

@@ -1,15 +1,17 @@
-import type { ExcaliburGraphicsContext, LineGraphicsOptions, RectGraphicsOptions, PointGraphicsOptions, ExcaliburGraphicsContextOptions, DebugDraw, HTMLImageSource } from './excalibur-graphics-context';
+import type { ExcaliburGraphicsContext, LineGraphicsOptions, RectGraphicsOptions, PointGraphicsOptions, ExcaliburGraphicsContextOptions, DebugDraw, DebugTextOptions, HTMLImageSource } from './excalibur-graphics-context';
 import { Matrix } from '../../math/matrix';
 import { TransformStack } from './transform-stack';
 import type { Vector } from '../../math/vector';
 import { Color } from '../../color';
 import { StateStack } from './state-stack';
 import type { Resolution } from '../../screen';
+import { Framebuffer } from './framebuffer';
+import { VertexBuffer } from './vertex-buffer';
 import type { PostProcessor } from '../post-processor/post-processor';
 import { TextureLoader } from './texture-loader';
 import type { RendererPlugin } from './renderer';
 import type { AffineMatrix } from '../../math/affine-matrix';
-import type { MaterialOptions } from './material';
+import type { MaterialOptionsWithoutContext } from './material';
 import { Material } from './material';
 import type { ShaderOptions } from './shader';
 import { Shader } from './shader';
@@ -57,7 +59,11 @@ declare class ExcaliburGraphicsContextWebGLDebug implements DebugDraw {
      *
      * Debugging draws are independent of scale/zoom
      */
-    drawText(text: string, pos: Vector): void;
+    drawText(text: string, pos: Vector, options?: DebugTextOptions): void;
+    measureText(text: string, scale?: number): {
+        width: number;
+        height: number;
+    };
 }
 export interface WebGLGraphicsContextInfo {
     transform: TransformStack;
@@ -85,8 +91,9 @@ export declare class ExcaliburGraphicsContextWebGL implements ExcaliburGraphicsC
     private _drawCallIndex;
     private _drawCalls;
     private _renderTarget;
-    private _msaaTarget;
+    private _msaaTarget?;
     private _postProcessTargets;
+    private _drawTarget;
     private _screenRenderer;
     private _postprocessors;
     /**
@@ -116,7 +123,10 @@ export declare class ExcaliburGraphicsContextWebGL implements ExcaliburGraphicsC
     uvPadding: number;
     backgroundColor: Color;
     textureLoader: TextureLoader;
+    private _materials;
     materialScreenTexture: WebGLTexture | null;
+    private _onGraphicsPreInitialize?;
+    private _onGraphicsPostInitialize?;
     get z(): number;
     set z(value: number);
     get opacity(): number;
@@ -126,6 +136,20 @@ export declare class ExcaliburGraphicsContextWebGL implements ExcaliburGraphicsC
     get width(): number;
     get height(): number;
     get ortho(): Matrix;
+    /**
+     * The {@apilink Framebuffer} the current frame is being drawn into.
+     *
+     * Useful as an explicit destination when compositing custom shader passes into the frame,
+     * for example `pass.draw(myFramebuffer, ctx.drawTarget)`.
+     */
+    get drawTarget(): Framebuffer;
+    private _screenQuadBuffer;
+    /**
+     * Shared static clip-space quad (interleaved [x, y, u, v] * 6 vertices) used by every
+     * {@apilink ShaderPass} on this context, meant for internal use only.
+     * @internal
+     */
+    get __screenQuadBuffer(): VertexBuffer;
     /**
      * Checks the underlying webgl implementation if the requested internal resolution is supported
      * @param dim
@@ -141,7 +165,7 @@ export declare class ExcaliburGraphicsContextWebGL implements ExcaliburGraphicsC
     private _init;
     register<T extends RendererPlugin>(renderer: T): void;
     lazyRegister<TRenderer extends RendererPlugin>(type: TRenderer['type'], renderer: () => TRenderer): void;
-    get(rendererName: string): RendererPlugin | undefined;
+    get(rendererName: string): RendererPlugin | null;
     private _currentRenderer;
     private _isCurrentRenderer;
     beginDrawLifecycle(): void;
@@ -175,12 +199,25 @@ export declare class ExcaliburGraphicsContextWebGL implements ExcaliburGraphicsC
     updatePostProcessors(elapsed: number): void;
     set material(material: Material | null | undefined);
     get material(): Material | null | undefined;
+    /**
+     * Registers a material with this context so it can be enumerated with {@apilink ExcaliburGraphicsContextWebGL.materials},
+     * called automatically by the {@apilink Material} constructor.
+     *
+     * Materials are held weakly and do not prevent garbage collection.
+     */
+    registerMaterial(material: Material): void;
+    /**
+     * Returns all live materials created against this context, useful for debugging and tooling.
+     *
+     * Materials are held weakly; materials that have been garbage collected are pruned on access.
+     */
+    get materials(): Material[];
     /**
      * Creates and initializes the material which compiles the internal shader
      * @param options
      * @returns Material
      */
-    createMaterial(options: Omit<MaterialOptions, 'graphicsContext'>): Material;
+    createMaterial(options: MaterialOptionsWithoutContext): Material;
     createShader(options: Omit<ShaderOptions, 'graphicsContext'>): Shader;
     clear(): void;
     /**

package/build/{dist → esm/src/engine}/graphics/context/excalibur-graphics-context.d.ts

@@ -4,6 +4,7 @@ import type { Resolution } from '../../screen';
 import type { PostProcessor } from '../post-processor/post-processor';
 import type { AffineMatrix } from '../../math/affine-matrix';
 import type { Material, MaterialOptions } from './material';
+import type { RendererPlugin } from './renderer';
 import { ImageFiltering } from '../filtering';
 export type HTMLImageSource = HTMLImageElement | HTMLCanvasElement;
 export interface AntialiasOptions {
@@ -104,6 +105,43 @@ export interface ExcaliburGraphicsContextOptions {
      * Feature flag that enables draw sorting will removed in v0.29
      */
     useDrawSorting?: boolean;
+    /**
+     * Hook called before the graphics context is configured. Use to modify options before
+     * the WebGL context is created. Called at the start of the constructor.
+     *
+     * Called internally by Excalibur to forward plugin hooks.
+     * @param context The graphics context being constructed
+     * @param options The graphics context options (mutable)
+     * @internal
+     */
+    onGraphicsPreConfig?: (context: ExcaliburGraphicsContext, options: ExcaliburGraphicsContextOptions) => void;
+    /**
+     * Hook called after the graphics context is configured but before initialization.
+     * Called after the WebGL context is created and configuration properties are set.
+     *
+     * Called internally by Excalibur to forward plugin hooks.
+     * @param context The graphics context being constructed
+     * @param options The graphics context options
+     * @internal
+     */
+    onGraphicsPostConfig?: (context: ExcaliburGraphicsContext, options: ExcaliburGraphicsContextOptions) => void;
+    /**
+     * Hook called before the graphics context's internal initialization (renderers, render targets).
+     *
+     * Called internally by Excalibur to forward plugin hooks.
+     * @param context The graphics context being initialized
+     * @internal
+     */
+    onGraphicsPreInitialize?: (context: ExcaliburGraphicsContext) => void;
+    /**
+     * Hook called after the graphics context's internal initialization is complete.
+     * This is where plugins typically register custom renderers and post-processors.
+     *
+     * Called internally by Excalibur to forward plugin hooks.
+     * @param context The initialized graphics context
+     * @internal
+     */
+    onGraphicsPostInitialize?: (context: ExcaliburGraphicsContext) => void;
 }
 export interface ExcaliburGraphicsContextState {
     opacity: number;
@@ -158,11 +196,33 @@ export interface DebugDraw {
      */
     drawCircle(pos: Vector, radius: number, color: Color, stroke?: Color, thickness?: number): void;
     /**
-     * Draw debug text
-     * @param text
-     * @param pos
+     * Debug text styling options
      */
-    drawText(text: string, pos: Vector): void;
+    drawText(text: string, pos: Vector, options?: DebugTextOptions): void;
+    /**
+     * Measure the pixel dimensions of debug text as it would be drawn by {@apilink DebugDraw.drawText},
+     * accounting for the optional scale factor. Useful for sizing UI around debug labels.
+     * @param text   Text to measure
+     * @param scale  Glyph scale factor, defaults to 1
+     */
+    measureText(text: string, scale?: number): {
+        width: number;
+        height: number;
+    };
+}
+export interface DebugTextOptions {
+    /**
+     * Optional foreground color override for the debug text
+     */
+    foreground?: Color;
+    /**
+     * Optional background color drawn behind the debug text
+     */
+    background?: Color;
+    /**
+     * Optional scale factor applied to the debug text glyphs, defaults to 1
+     */
+    scale?: number;
 }
 export interface ExcaliburGraphicsContext {
     width: number;
@@ -312,6 +372,50 @@ export interface ExcaliburGraphicsContext {
      * @internal
      */
     updatePostProcessors(elapsed: number): void;
+    /**
+     * Register a custom renderer plugin with the graphics context.
+     *
+     * The renderer is immediately initialized with the WebGL context.
+     * Use this for renderers that should always be available.
+     *
+     * In the Canvas 2D fallback context this is a no-op.
+     * @param renderer The renderer plugin to register
+     */
+    register<T extends RendererPlugin>(renderer: T): void;
+    /**
+     * Lazily register a custom renderer plugin with the graphics context.
+     *
+     * The renderer factory is stored and only instantiated the first time it is
+     * requested via {@apilink ExcaliburGraphicsContext.get}. Use this for renderers
+     * that may not be needed in every game to avoid unnecessary initialization cost.
+     *
+     * In the Canvas 2D fallback context this is a no-op.
+     * @param type     The unique renderer type name (matches {@apilink RendererPlugin.type})
+     * @param renderer A factory function that creates the renderer
+     */
+    lazyRegister<TRenderer extends RendererPlugin>(type: TRenderer['type'], renderer: () => TRenderer): void;
+    /**
+     * Look up a registered renderer plugin by its type name.
+     *
+     * If the renderer was lazily registered, it will be instantiated and initialized
+     * on first access.
+     *
+     * @param rendererName The unique renderer type name
+     * @returns The renderer plugin, or `null` if not found
+     */
+    get(rendererName: string): RendererPlugin | null;
+    /**
+     * Issue a draw command to a named renderer plugin.
+     *
+     * The renderer is looked up by name (auto-instantiating lazy renderers) and its
+     * `draw()` method is called with the provided arguments. Draw calls are sorted
+     * by z-index and renderer priority before flushing.
+     *
+     * In the Canvas 2D fallback context this is a no-op.
+     * @param rendererName The unique renderer type name to draw with
+     * @param args         Arguments forwarded to the renderer's `draw()` method
+     */
+    draw<TRenderer extends RendererPlugin>(rendererName: TRenderer['type'], ...args: Parameters<TRenderer['draw']>): void;
     /**
      * Gets or sets the material to be used in the current context's drawings
      *

package/build/esm/src/engine/graphics/context/framebuffer.d.ts

@@ -0,0 +1,154 @@
+import type { Color } from '../../color';
+import { ImageFiltering } from '../filtering';
+import type { ImageWrapConfiguration } from '../image-source';
+import { ImageWrapping } from '../wrapping';
+import type { ExcaliburGraphicsContextWebGL } from './excalibur-graphics-context-webgl';
+declare global {
+    interface WebGL2RenderingContext {
+        /**
+         * Experimental only in chrome
+         */
+        drawingBufferFormat?: number;
+    }
+}
+export interface FramebufferOptions {
+    graphicsContext: ExcaliburGraphicsContextWebGL;
+    width: number;
+    height: number;
+    /**
+     * How this framebuffer's texture is sampled when used as a source.
+     *
+     * Default {@apilink ImageFiltering.Pixel} (nearest), matching the engine's frame targets which are
+     * only ever sampled 1:1. Pass {@apilink ImageFiltering.Blended} (linear) for anything that samples
+     * at a different resolution, like downsample/upsample blur chains.
+     */
+    filtering?: ImageFiltering;
+    /**
+     * How this framebuffer's texture wraps when sampled outside 0-1 UVs, default {@apilink ImageWrapping.Clamp}
+     */
+    wrapping?: ImageWrapConfiguration | ImageWrapping;
+    /**
+     * Match the canvas transparency semantics, used to pick a compatible blit format. Default true.
+     */
+    transparency?: boolean;
+}
+/**
+ * A texture-backed WebGL framebuffer that is both a render **destination** and a texture **source**.
+ *
+ * Draw into it by passing it as the `destination` of a {@apilink ShaderPass.draw} (or any consumer of
+ * {@apilink Framebuffer.glFramebuffer}), sample from it by passing it as a `source` (or reading
+ * {@apilink Framebuffer.texture}). There is no implicit bind/unbind protocol to sequence.
+ *
+ * Contents are premultiplied alpha, matching the rest of the Excalibur WebGL pipeline.
+ */
+export declare class Framebuffer {
+    protected _gl: WebGL2RenderingContext;
+    protected _graphicsContext: ExcaliburGraphicsContextWebGL;
+    readonly transparency: boolean;
+    readonly filtering: ImageFiltering;
+    readonly wrapping: ImageWrapConfiguration;
+    /**
+     * Format compatible with the canvas drawing buffer, needed for {@apilink Framebuffer.blitToScreen}
+     */
+    readonly bufferFormat: number;
+    private _width;
+    private _height;
+    private _texelSize;
+    private _frameBuffer;
+    private _frameTexture;
+    private _disposed;
+    constructor(options: FramebufferOptions);
+    get width(): number;
+    get height(): number;
+    /**
+     * `[1 / width, 1 / height]`, useful for passing to shaders that sample neighboring texels (blurs etc.)
+     */
+    get texelSize(): [texelWidth: number, texelHeight: number];
+    /**
+     * The color texture backing this framebuffer, for sampling as a source.
+     *
+     * On a {@apilink MultisampleFramebuffer} reading this resolves the MSAA renderbuffer first.
+     */
+    get texture(): WebGLTexture;
+    /**
+     * The framebuffer to bind when drawing **into** this framebuffer.
+     *
+     * On a {@apilink MultisampleFramebuffer} this is the multisampled renderbuffer framebuffer.
+     */
+    get glFramebuffer(): WebGLFramebuffer;
+    /**
+     * The framebuffer with the resolved color texture attached
+     * @internal
+     */
+    protected get _textureFramebuffer(): WebGLFramebuffer;
+    private _toGlFiltering;
+    private _toGlWrapping;
+    private _setupFramebuffer;
+    /**
+     * Resize the framebuffer, contents are discarded
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Clears the framebuffer to the provided color (transparent black by default)
+     *
+     * Leaves this framebuffer bound
+     */
+    clear(color?: Color): void;
+    /**
+     * Copies the current (resolved) contents into the provided texture, which is
+     * reallocated at this framebuffer's dimensions
+     */
+    copyToTexture(texture: WebGLTexture): void;
+    /**
+     * Blits the (resolved) contents 1:1 to the canvas drawing buffer
+     */
+    blitToScreen(): void;
+    /**
+     * Performs any resolve necessary to make {@apilink Framebuffer._textureFramebuffer} current, returns it
+     * @internal
+     */
+    protected _resolve(): WebGLFramebuffer;
+    /**
+     * Binds this framebuffer for drawing and sets the viewport to its dimensions.
+     *
+     * Meant for internal use by the context's batched flush, pipeline code passes framebuffers
+     * explicitly as destinations instead.
+     * @internal
+     */
+    bind(): void;
+    /**
+     * Returns drawing to the canvas
+     * @internal
+     */
+    unbind(): void;
+    /**
+     * Deletes the GL resources owned by this framebuffer, it cannot be used afterwards
+     */
+    dispose(): void;
+}
+export interface MultisampleFramebufferOptions extends FramebufferOptions {
+    /**
+     * Optionally specify number of anti-aliasing samples to use, by default the max for the platform
+     */
+    samples?: number;
+}
+/**
+ * A {@apilink Framebuffer} backed by a multisampled renderbuffer.
+ *
+ * Drawing goes into the MSAA renderbuffer ({@apilink Framebuffer.glFramebuffer}); reading
+ * {@apilink Framebuffer.texture} (or blitting/copying) resolves the samples into the backing
+ * color texture first, so consumers never need to sequence the resolve themselves.
+ */
+export declare class MultisampleFramebuffer extends Framebuffer {
+    readonly samples: number;
+    private _renderBuffer;
+    private _renderFrameBuffer;
+    private _msaaDisposed;
+    constructor(options: MultisampleFramebufferOptions);
+    get glFramebuffer(): WebGLFramebuffer;
+    get texture(): WebGLTexture;
+    resize(width: number, height: number): void;
+    blitToScreen(): void;
+    protected _resolve(): WebGLFramebuffer;
+    dispose(): void;
+}

package/build/esm/src/engine/graphics/context/glsl.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Tagged template literal for authoring Excalibur {@apilink Material} fragment shaders.
+ *
+ * It handles the boilerplate and, most importantly, the alpha space bookkeeping.
+ *
+ * ## Automatic alpha premultiplication
+ *
+ * Excalibur's WebGL pipeline is premultiplied end to end. Textures are uploaded with
+ * `UNPACK_PREMULTIPLY_ALPHA_WEBGL`, so a raw `texture(u_graphic, uv)` hands back a premultiplied
+ * value, and the blend function is `(ONE, ONE_MINUS_SRC_ALPHA)`, so the fragment output must be
+ * premultiplied too. Doing your own alpha math in the middle of that is a reliable source of
+ * washed out blending and dark halos on antialiased edges.
+ *
+ * Shaders written with this tag instead get a **straight (un-premultiplied) alpha authoring
+ * space**. Sampling calls are un-premultiplied on the way in and your color output is
+ * premultiplied on the way out, so ordinary intuitive alpha math works in between:
+ *
+ * ```ts
+ * const material = game.graphicsContext.createMaterial({
+ *   name: 'fade',
+ *   fragmentSource: glsl`
+ *     in vec2 v_uv;
+ *     uniform sampler2D u_graphic;
+ *     out vec4 fragColor;
+ *     void main() {
+ *       vec4 color = texture(u_graphic, v_uv);
+ *       color.a *= 0.5; // just works, no manual premultiply needed
+ *       fragColor = color;
+ *     }`
+ * });
+ * ```
+ *
+ * Filtering still happens in premultiplied space where it belongs, only the filtered result is
+ * converted. See https://www.realtimerendering.com/blog/gpus-prefer-premultiplication/
+ *
+ * To sample a texture that is not color data (a lookup table, a noise or data texture) use
+ * `ex_texture_raw(tex, uv)`, which is passed through untouched. To turn the whole transform off
+ * for a shader, add `#pragma excalibur premultiply(off)` to its source.
+ *
+ * ## Other conveniences
+ *
+ * * Adds `#version 300 es` and a `precision` declaration if you did not write them
+ * * Injects the `pixel_texture(sampler2D, vec2)` pixel art filter if your source references it
+ * * Injects `uniform vec2 u_graphic_resolution;` alongside it if you have not declared it
+ * * Exposes `ex_premultiply(vec4)` / `ex_unpremultiply(vec4)` if you need to convert by hand
+ */
+export declare function glsl(strings: TemplateStringsArray, ...values: any[]): string;

package/build/{dist → esm/src/engine}/graphics/context/material-renderer/material-renderer.d.ts

@@ -10,6 +10,7 @@ export declare class MaterialRenderer implements RendererPlugin {
     private _quads;
     private _buffer;
     private _layout;
+    private _seedPass;
     initialize(gl: WebGL2RenderingContext, context: ExcaliburGraphicsContextWebGL): void;
     dispose(): void;
     draw(image: HTMLImageSource, sx: number, sy: number, swidth?: number, sheight?: number, dx?: number, dy?: number, dwidth?: number, dheight?: number): void;