Sprite stacking for 2.5D graphics in Godot 4.

Latest release · Godot Asset Library · Documentation · MPL-2.0 licence

Shader Stacker turns a single-column sprite sheet into a rotatable 2.5D object. It draws each slice through Godot's 2D rendering API, offsets the layers to create height and keeps stacks in the correct screen-space order as the camera moves.

Features

• SpriteStack renders and rotates layered sprite sheets.
• StackCamera sorts stacks by screen position and height within its viewport.
• Reset2D keeps ordinary 2D nodes upright when the camera rotates or uses unequal zoom for an isometric look.
• The preview tool reloads a sprite sheet from disk as it changes.
• The add-on works in the editor and at runtime.

Install

Shader Stacker targets Godot 4.

1. Download the latest release, install it from the Godot Asset Library, or clone this repository.
2. Copy addons/ShaderStacker into the addons directory of the Godot project.
3. In Godot, open Project → Project Settings → Plugins and enable Shader Stacker.
4. Reopen any scenes that were already open so the custom nodes appear in the Create New Node dialog.

For crisp pixel art, set Project Settings → Rendering → Textures → Canvas Textures → Default Texture Filter to Nearest.

Quick start

1. Add a SpriteStack node to a scene.
2. Assign a single-column sprite sheet to sprite_sheet. Each row must have the same height; place the bottom slice in the bottom row and the top slice in the top row.
3. Set layers to the number of rows in the sheet.
4. Adjust pitch to change the distance between slices and yaw to rotate the stack.
5. Add a StackCamera to the same viewport for camera-aware rotation and depth sorting.

Open project.godot and run the project to see the included teapot demo. Run PreviewTool/PreviewTool.tscn to inspect a sprite sheet while editing it; the tool checks the source file for changes once a second.

Nodes

SpriteStack

Property	Type	Purpose
sprite_sheet	Texture2D	Single-column sheet containing the stack's slices.
layers	int	Number of equal-height rows in the sheet.
z	int	Height of the stack relative to the floor.
yaw	float	Rotation of the stack's upward direction.
pitch	float	Distance in pixels between slices.
static_yaw	bool	Stops the stack from following camera rotation.
static_z	bool	Excludes the stack from StackCamera depth sorting.

StackCamera

StackCamera extends Camera2D. Each frame, it finds participating nodes in its viewport and assigns their z_index from their height and screen-space position. Setting zoom.y below zoom.x compresses the scene vertically for an isometric look.

Reset2D

Place ordinary 2D content under a Reset2D node when it should ignore the camera's rotation, vertical compression or height offset. The reset_position, reset_rotation and reset_scale properties control these corrections separately.

How it works

The Godot 4 version uses CanvasItem drawing rather than a custom shader. SpriteStack reads the sprite sheet from bottom to top, draws one texture region for each layer and offsets each region along a camera-aware vector. StackCamera then sorts every participating stack in screen space. Sorting groups are scoped to a viewport, so independent viewports do not affect one another.

Rendering work grows with the number of layers, and sorting work grows with the number of participating nodes. Keep layer counts and stack counts within the performance budget of the target hardware.

For a 3D shader-based approach, see Pixel Perfect Sprite Stacking — Edges in 3D.

Project status

The latest tagged release is v4.0.5. Development is low-volume, and maintenance is provided on a best-effort basis. Focused bug reports and pull requests are welcome.

Licence

Shader Stacker is available under the Mozilla Public License 2.0.