Render Textures

Render Textures and Dynamic Textures

Drawing game objects to off-screen textures in Phaser 4 -- RenderTexture game object, DynamicTexture for shared textures, the Stamp helper, command-buffer rendering, snapshots, procedural generation, and minimap patterns.

Key source paths: src/gameobjects/rendertexture/, src/textures/DynamicTexture.js, src/gameobjects/stamp/, src/textures/typedefs/StampConfig.js, src/textures/typedefs/CaptureConfig.js Related skills: ../sprites-and-images/SKILL.md, ../loading-assets/SKILL.md, ../cameras/SKILL.md

Quick Start

// In a Scene's create() method:

// 1. RenderTexture -- a visible game object with its own DynamicTexture
const rt = this.add.renderTexture(400, 300, 256, 256);
rt.draw('player', 128, 128);          // draw a texture by key at center
rt.fill(0x222244, 0.5);               // semi-transparent fill
rt.render();                           // flush the command buffer

// 2. DynamicTexture -- a shared texture in the Texture Manager
const dt = this.textures.addDynamicTexture('composite', 512, 512);
dt.stamp('coin', null, 64, 64, { scale: 2, angle: 45 });
dt.render();
this.add.image(400, 300, 'composite'); // any game object can use it

// 3. Stamp game object -- lightweight Image that ignores camera scroll
const hud = this.add.stamp(10, 10, 'heart');

Core Concepts

RenderTexture vs DynamicTexture

Phaser 4 splits texture-drawing into two layers:

When to use which:

• Use RenderTexture when you need a single visible surface you draw onto (paint canvas, trail effect, composite sprite).
• Use DynamicTexture when many game objects share the same generated texture, or you need a texture for masks/shaders, or you need cross-scene access.

RenderTexture is a thin proxy. Methods like draw(), stamp(), fill(), clear(), erase(), snapshot() all delegate to its underlying this.texture (a DynamicTexture).

Origin note: RenderTexture extends Image, so its origin defaults to (0.5, 0.5). If you want top-left positioning (common for full-screen or minimap RTs), call rt.setOrigin(0, 0).

The Command Buffer (v4 Architecture)

In Phaser 4, drawing calls (draw, stamp, fill, clear, erase, repeat, capture) do not execute immediately. They push commands into a commandBuffer array. You must call .render() to flush and execute the buffer.

rt.clear();
rt.fill(0x000000);
rt.draw(sprite, 128, 128);
rt.render();  // REQUIRED -- nothing appears without this

For RenderTexture game objects, the renderMode property controls automatic rendering:

rt.setRenderMode('all');       // auto-render + display every frame
rt.setRenderMode('all', true); // same, plus preserve the command buffer

Preserve Mode

By default the command buffer clears after render(). Call preserve(true) to keep commands between renders, so the same drawing replays each frame:

rt.preserve(true);
rt.clear();
rt.draw(sprite);
// On every subsequent render(), clear + draw will repeat

Stamp Game Object

Stamp (this.add.stamp(x, y, texture, frame)) is a lightweight Image subclass that ignores camera scroll and transform during rendering. It is used internally by DynamicTexture for drawing operations and is also useful for HUD elements. It extends Image with custom render nodes (DefaultStampNodes).

The stamp() Method vs the Stamp Game Object

These are different things:

• `rt.stamp(key, frame, x, y, config)` -- a method on RenderTexture/DynamicTexture that draws a texture frame to the surface with transform options (alpha, tint, angle, scale, origin, blendMode).
• `this.add.stamp(x, y, texture, frame)` -- a factory that creates a Stamp game object added to the Scene display list.

Common Patterns

Drawing Sprites and Game Objects

const rt = this.add.renderTexture(0, 0, 800, 600);

// Single game object at an offset
rt.draw(sprite, 100, 100);

// Array of objects
rt.draw([sprite1, sprite2, sprite3]);

// Group or Container (only visible children are drawn)
rt.draw(enemyGroup);
rt.draw(myContainer, 50, 50);  // offset added to children positions

// Entire Scene display list
rt.draw(this.children);

// Texture by string key
rt.draw('explosion', 200, 200);

// Don't forget to flush
rt.render();

The draw() method accepts: renderable game objects, Groups, Containers, Display Lists, other RenderTextures/DynamicTextures, Texture Frames, texture key strings, or arrays of any of these.

Note: alpha and tint parameters on draw() only apply to Texture Frames/strings. Game objects use their own alpha and tint when drawn.

Stamping Textures with Config

The stamp() method draws a texture frame with full transform control. The frame is centered on the x/y position by default (origin 0.5).

rt.stamp('bullet', null, 100, 100, {
    alpha: 0.8,
    tint: 0xff0000,
    angle: 45,          // degrees (takes precedence over rotation)
    scale: 2,           // uniform scale
    scaleX: 1.5,        // overrides scale for X
    scaleY: 0.5,        // overrides scale for Y
    originX: 0,         // top-left origin
    originY: 0,
    blendMode: 0
});
rt.render();

Capture -- Drawing with Overrides (v4)

The capture() method draws a game object with temporary property overrides, restoring originals afterward:

rt.capture(player, {
    x: 64,
    y: 64,
    scale: 0.5,
    alpha: 0.8,
    rotation: Math.PI / 4,
    transform: 'world',    // 'local', 'world', or a TransformMatrix
    camera: someCamera      // optional camera override
});
rt.render();

This is useful for drawing an object at a different position/scale without modifying the object itself.

Filling and Clearing

// Fill entire texture with color
rt.fill(0xff0000);          // solid red
rt.fill(0x000000, 0.5);     // semi-transparent black

// Fill a region
rt.fill(0x00ff00, 1, 10, 10, 100, 50);  // green rect at (10,10) size 100x50

// Clear everything (transparent)
rt.clear();

// Clear a region
rt.clear(10, 10, 100, 50);

rt.render();

Erasing

Erase uses ERASE blend mode to cut holes in the texture:

rt.fill(0xffffff);           // white background
rt.erase(circleSprite, 100, 100);  // punch a hole shaped like the sprite
rt.render();

Repeating / Tiling a Texture

// Fill the entire RenderTexture with a tiled pattern
rt.repeat('grass', null);                        // tile the whole surface
rt.repeat('brick', null, 0, 0, 256, 128);       // tile a specific region
rt.repeat('tile', 'frame2', 0, 0, 512, 512, {
    tileScaleX: 2,
    tileScaleY: 2,
    tilePositionX: 16,
    alpha: 0.8
});
rt.render();

Snapshots (Pixel Capture)

Snapshots read pixel data from the framebuffer. They are expensive and blocking -- use sparingly.

// Full texture snapshot -- callback receives an HTMLImageElement
rt.snapshot(function (image) {
    document.body.appendChild(image);  // or use as texture source
});

// Area snapshot