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/textures/typedefs/StampConfig.js
,
src/textures/typedefs/CaptureConfig.js
../sprites-and-images/SKILL.md, ../loading-assets/SKILL.md, ../cameras/SKILL.md
Quick Start
js
// 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:
| RenderTexture | DynamicTexture |
|---|
| What it is | Image game object + auto-created DynamicTexture | Texture in the Texture Manager |
| Created via | this.add.renderTexture(x, y, w, h)
| this.textures.addDynamicTexture(key, w, h)
|
| Visible on its own | Yes (it extends Image) | No (must be assigned to a game object) |
| Shared across objects | Possible via | Yes, by key |
| Cross-scene use | No (belongs to one Scene) | Yes (textures are global) |
| Has position/scale/alpha | Yes (all Image components) | No (it is a Texture, not a GameObject) |
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
,
,
,
,
,
all delegate to its underlying
(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
.
The Command Buffer (v4 Architecture)
In Phaser 4, drawing calls (
,
,
,
,
,
,
) do
not execute immediately. They push commands into a
array. You must call
to flush and execute the buffer.
js
rt.clear();
rt.fill(0x000000);
rt.draw(sprite, 128, 128);
rt.render(); // REQUIRED -- nothing appears without this
For RenderTexture game objects, the
property controls automatic rendering:
| Mode | Behavior |
|---|
| (default) | Draws the texture contents to the frame each tick. You call manually when content changes. |
| Calls automatically every frame but does NOT display itself. Useful for textures reused by other objects. |
| Calls every frame AND draws itself to the frame. |
js
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
. Call
to keep commands between renders, so the same drawing replays each frame:
js
rt.preserve(true);
rt.clear();
rt.draw(sprite);
// On every subsequent render(), clear + draw will repeat
Stamp Game Object
(
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 (
).
The Method vs the Stamp Game Object
These are different things:
rt.stamp(key, frame, x, y, config)
this.add.stamp(x, y, texture, frame)
Common Patterns
Drawing Sprites and Game Objects
js
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
method accepts: renderable game objects, Groups, Containers, Display Lists, other RenderTextures/DynamicTextures, Texture Frames, texture key strings, or arrays of any of these.
Note:
and
parameters on
only apply to Texture Frames/strings. Game objects use their own alpha and tint when drawn.
Stamping Textures with Config
The
method draws a texture frame with full transform control. The frame is centered on the x/y position by default (origin 0.5).
js
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
method draws a game object with temporary property overrides, restoring originals afterward:
js
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
js
// 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:
js
rt.fill(0xffffff); // white background
rt.erase(circleSprite, 100, 100); // punch a hole shaped like the sprite
rt.render();
Repeating / Tiling a Texture
js
// 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.
js
// Full texture snapshot -- callback receives an HTMLImageElement
rt.snapshot(function (image) {
document.body.appendChild(image); // or use as texture source
});
// Area snapshot
rt.snapshotArea(0, 0, 128, 128, function (image) {
// image is 128x128 region from top-left
}, 'image/jpeg', 0.8);
// Single pixel -- callback receives a Phaser.Display.Color
rt.snapshotPixel(64, 64, function (color) {
console.log(color.r, color.g, color.b, color.a);
});
Using as a Texture Source for Other Objects
js
const rt = this.add.renderTexture(0, 0, 256, 256);
rt.draw(complexScene);
rt.render();
// Register in the Texture Manager under a key
rt.saveTexture('composited');
// Now any game object can use it
this.add.image(400, 300, 'composited');
this.add.sprite(100, 100, 'composited');
// Updates to the RenderTexture automatically reflect on all users
For DynamicTexture, the key is set at creation time:
js
const dt = this.textures.addDynamicTexture('terrain', 1024, 1024);
dt.repeat('grass', null);
dt.render();
this.add.image(512, 512, 'terrain'); // already keyed
Procedural Generation
js
const dt = this.textures.addDynamicTexture('starfield', 800, 600);
dt.fill(0x000011);
for (let i = 0; i < 200; i++) {
const x = Phaser.Math.Between(0, 800);
const y = Phaser.Math.Between(0, 600);
const brightness = Phaser.Math.FloatBetween(0.3, 1);
dt.stamp('star', null, x, y, { alpha: brightness, scale: Phaser.Math.FloatBetween(0.5, 1.5) });
}
dt.render();
this.add.image(400, 300, 'starfield');
Minimap Pattern
js
create() {
// Small RenderTexture as minimap
this.minimap = this.add.renderTexture(700, 50, 150, 100);
this.minimap.setScrollFactor(0); // fixed to camera
this.minimap.setRenderMode('all'); // auto-render every frame
this.minimap.preserve(true);
}
// In update or a callback:
this.minimap.clear();
this.minimap.fill(0x111111);
// Draw scaled-down versions of world objects
this.minimap.capture(player, { x: px * 0.1, y: py * 0.1, scale: 0.1 });
// render() is automatic in 'all' mode
Callbacks in the Command Buffer
Insert logic between draw commands that executes during
:
js
rt.clear();
rt.draw(background);
rt.callback(() => {
// Runs during render, after background is drawn
sprite.setTint(0xff0000);
});
rt.draw(sprite);
rt.callback(() => {
sprite.setTint(0xffffff); // restore after drawing
});
rt.render();
Resizing
js
// Resize erases all content and recreates the framebuffer
rt.resize(512, 512);
// Optional: disable force-even rounding
rt.resize(513, 513, false);
Internal Camera
Both RenderTexture and DynamicTexture have a
property that controls how game objects are positioned when drawn. Scroll, zoom, and rotate this camera to transform drawn content. Note:
ignores the camera; only
and game object rendering respect it.
js
rt.camera.setScroll(100, 50);
rt.camera.setZoom(2);
rt.draw(sprite); // sprite drawn with camera transform applied
rt.render();
API Quick Reference
RenderTexture (extends Image)
| Method | Signature | Description |
|---|
| (entries, x?, y?, alpha?, tint?)
| Draw game objects, textures, groups, etc. |
| | Draw with temporary property overrides |
| (key, frame?, x?, y?, config?)
| Stamp a texture frame with transform |
| | Draw using ERASE blend mode |
| (rgb, alpha?, x?, y?, w?, h?)
| Fill with color |
| | Clear to transparent |
| (key, frame?, x?, y?, w?, h?, config?)
| Tile a texture as fill pattern |
| | Flush the command buffer |
| | Keep command buffer between renders |
| | Insert callback into command buffer |
| | Resize (erases content) |
| | Register in Texture Manager |
| | Set 'render', 'redraw', or 'all' |
| (callback, type?, quality?)
| Full snapshot to Image |
| (x, y, w, h, callback, type?, quality?)
| Area snapshot |
| | Single pixel to Color |
DynamicTexture (extends Texture)
Same drawing methods as RenderTexture (
,
,
,
,
,
,
,
,
,
,
,
,
), plus:
| Method/Property | Description |
|---|
setSize(w, h?, forceEven?)
| Resize the texture |
| Internal Camera for draw positioning |
| Array of pending draw commands |
| WebGL DrawingContext with framebuffer |
| Returns the underlying WebGLTextureWrapper |
StampConfig (for config parameter)
| Property | Default | Description |
|---|
| 1 | Alpha value |
| 0xffffff | Tint color (WebGL only) |
| 0 | Degrees (overrides rotation if non-zero) |
| 0 | Radians |
| 1 | Uniform scale |
| / | 1 | Per-axis scale (overrides ) |
| / | 0.5 | Origin point |
| 0 | Blend mode |
CaptureConfig (for config parameter)
| Property | Description |
|---|
| , , or a |
| Camera override for rendering |
| , , , , , | Override game object properties temporarily |
| , , | Scale overrides |
| , , | Additional overrides |
Factory Methods
js
this.add.renderTexture(x, y, width?, height?) // default 32x32
this.add.stamp(x, y, texture, frame?)
this.textures.addDynamicTexture(key, width?, height?, forceEven?) // default 256x256
Gotchas
-
Must call . In Phaser 4, drawing methods buffer commands. Nothing appears until
is called (unless using
or
).
-
Cannot draw to itself. A DynamicTexture/RenderTexture silently skips entries that reference itself.
-
Command buffer clears after render. Call
before drawing if you need the same commands to replay each frame.
-
ignores the internal camera. Only game objects drawn via
or
respect the
property. Texture stamps are positioned absolutely.
-
Default sizes differ. RenderTexture defaults to 32x32. DynamicTexture defaults to 256x256.
-
rounds dimensions up. By default, width/height are rounded to even numbers for rendering quality. Pass
as the last argument if you need exact odd dimensions.
-
Snapshots are expensive. They use
(WebGL) which blocks the GPU pipeline. Avoid per-frame snapshots.
is cheaper than full
.
-
WebGL1 has no anti-aliasing on framebuffers. Shapes and Graphics drawn to a RenderTexture may have jagged edges. Use pre-rendered sprite textures instead.
-
erases content. Resizing destroys and recreates the framebuffer.
-
renames, does not copy. Calling
assigns the DynamicTexture to the Texture Manager under that key. Calling it again with a different key renames it. Destroying the RenderTexture without saving first destroys the texture.
-
alpha/tint params only affect Texture Frames. When drawing game objects, they use their own alpha and tint values. The
and
parameters on
only apply when drawing texture strings or Frame instances.
-
WebGL context loss. DynamicTexture contents are lost on context loss. Listen for the
event to redraw.
-
Groups/Containers: x, y offset is additive. When drawing a Group or Container with
, the x/y offset is added to each child's position. Children at (100, 50) drawn with offset (10, 10) appear at (110, 60) in the texture.
Source File Map
| File | Description |
|---|
src/gameobjects/rendertexture/RenderTexture.js
| RenderTexture game object (extends Image, proxies to DynamicTexture) |
src/gameobjects/rendertexture/RenderTextureFactory.js
| factory registration |
src/gameobjects/rendertexture/RenderTextureRender.js
| WebGL/Canvas render functions for RenderTexture |
src/gameobjects/rendertexture/RenderTextureRenderModes.js
| Enum: , , |
src/textures/DynamicTexture.js
| Core DynamicTexture class (command buffer, drawing, snapshots) |
src/textures/DynamicTextureCommands.js
| Command constants (CLEAR, FILL, STAMP, DRAW, ERASE, etc.) |
src/textures/typedefs/StampConfig.js
| StampConfig typedef for |
src/textures/typedefs/CaptureConfig.js
| CaptureConfig typedef for |
src/gameobjects/stamp/Stamp.js
| Stamp game object (light Image, ignores camera scroll) |
src/gameobjects/stamp/StampFactory.js
| factory registration |