Phaser HTML5 Game Framework

The Mesh Game Object allows for complex geometry rendering. It is supported by the Geom.Mesh namespace for generating vertex and face data.

Core Mesh Concepts:

• Vertices & Faces: A Mesh is composed of Geom.Mesh.Vertex instances (position, uv, normals, color, alpha) and Geom.Mesh.Face instances (references to three vertices).
• Data Storage: Unlike older versions, Mesh.vertices is an array of Vertex objects, and Mesh.faces is an array of Face objects. UV, color, and alpha data are now stored directly within the Vertex instances.
• Transformations: Use modelPosition, modelRotation, and modelScale (all Vector3) to transform the entire mesh geometry.
• Projections: Use setPerspective or setOrtho to define the projection matrix.
• Animation: Meshes include an Animation State Component, allowing for texture animations.

The ScaleManager (accessible via game.scale or this.scale in a Scene) manages how the game canvas is sized and displayed. It uses three internal size components to drive calculations:

• gameSize: The unmodified dimensions from your config. Used for world bounds and cameras. Access via game.scale.width / game.scale.height.
• baseSize: The auto-rounded gameSize. This sets the actual canvas.width and canvas.height attributes.
• displaySize: The CSS-scaled canvas size after applying scale mode, parent bounds, and zoom. This sets canvas.style.width and canvas.style.height.

Scaling is achieved by keeping the baseSize fixed and stretching the element via CSS (displaySize), which is more performant than constant canvas resizing.

If you want to create a custom WebGL pipeline but do not want to rewrite your shaders to support multiple textures, you should extend SinglePipeline instead of the older TextureTintPipeline. SinglePipeline is designed to emulate the old behavior using just a single texture, making it easier to integrate existing shader code. While you can extend it, it is recommended to update your shaders for better performance if possible.

// Example concept: extending SinglePipeline for custom shader logic
class MyCustomPipeline extends SinglePipeline {
    // implementation
}

Layers allow you to apply a Post FX Pipeline to a whole range of children simultaneously. This is often more efficient than applying effects to each child individually.

Important Constraints for Layers:

• Layers have no position, size, rotation, scale, or scroll factor within a Scene.
• You cannot enable physics or input on a Layer.
• Layers have no texture, tint, origin, crop, or bounds.

Comparison with Containers:

• If you need position, size, rotation, scale, or input, use a Container instead.
• You can add Containers to Layers, but you cannot add Layers to Containers.

What you CAN set on a Layer:

• Alpha
• Blend Mode
• Depth
• Mask
• Visible state (affects all children)

Use SpriteGPULayer to render millions of objects (like parallax backgrounds or particle effects) with minimal CPU overhead. It works by uploading a large buffer of data to the GPU once and then reusing it, skipping the expensive per-frame upload required by regular Sprites.

Key Characteristics:

• Performance: Runtime cost is ~1% of the vertex cost of regular sprites.
• Memory: High memory usage (approx. 168 bytes per layer member on both CPU and GPU) in exchange for speed.
• Features: Supports animations and scroll factor per-member.

Best Practice for Initialization: To avoid long initialization times (which can take seconds if creating new config objects for every member), create a single config object and edit it for each new member during the setup loop.

Phaser 4 replaces the v3 Pipeline system with a RenderNode graph. Instead of one pipeline handling multiple responsibilities, each RenderNode handles exactly one specific rendering task via its run() method.

Game objects use role-based maps to reference nodes. Common roles include:

• Submitter: Runs other node roles for each element.
• Transformer: Provides vertex coordinates.
• Texturer: Handles textures.

You can override these roles or pass custom data to them using setRenderNodeRole.

// Override a specific render role:
gameObject.setRenderNodeRole('Submitter', 'MyCustomSubmitter');

// Pass data to a render node:
gameObject.setRenderNodeRole('Transformer', 'MyTransformer', {
    customProperty: 42
});

// Remove a custom node (falls back to default):
gameObject.setRenderNodeRole('Submitter', null);

A Phaser.Renderer.WebGL.DrawingContext is an internal object representing a localized WebGL state (camera, blend modes, framebuffer, etc.). It acts as a specific "drawing setup."

Usage Rules

• Nesting: DrawingContexts are nestable. You can create a copy using drawingContext.getClone(), modify it, and return to the previous state.
• Lifecycle: When using a context, you must call drawingContext.use() at the start and drawingContext.release() at the end. This handles clearing the context and managing batch renders.
• Framebuffers: If a DrawingContext holds a framebuffer, drawingContext.texture refers to that texture. Everything drawn within that context is directed to that texture.