Attention: Here be dragons (unstable version)

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Redot.

Checking the stable version of the documentation...

Mode7Sprite2D

Inherits: Sprite2D < Node2D < CanvasItem < Node < Object

Extends Sprite2D to offer SNES Mode 7-style affine transformations per scanline.

Description

This class extends Sprite2D to replicate the Super Nintendo's Mode 7 graphics capabilities, which allowed affine transformations to be controlled per scanline.

This enabled the iconic perspective projection effect used in games like Super Mario World and F-Zero.

"Scanlines" were just how old televisions drew images - horizontal lines from the top down. The term is used in this class in deference to the Super Nintendo

behavior it's designed to reproduce, but in modern parlance a UV.y "band" is what this loosely equates to.

The "per-scanline" effect is driven by an array of Mode7ScanlineOverride resources (mode7_scanline_overrides), each encoding a 2x2 affine matrix (rotation, scale, skew), a translation offset,

and a pivot point for one horizontal band of the output. The shader interpolates between adjacent entries per-scanline using None, Lerp, or Projection modes.

Most of the time, you'll want Lerp or Projection. These interpolate between the values you set in each scanline override object in the array.

This is the mechanism by which it's not necessary to specify each individual scanline :).

Global rotation, pivot, and offset are applied after all per-scanline transforms.

Horizon masks cull transparent regions at the top or bottom of the sprite with optional tilt angles, matching an aircraft attitude indicator.

A region follow target lets the Mode 7 viewport track another Node2D each physics frame. This can be set in code, but moving an object and having the

viewing area "follow" that object, is a useful convenience.

How it works: One Mode7Sprite2D instance replaces the standard Sprite2D material with a custom canvas_item shader.

The shader reads per-scanline transforms from a 3-pixel-wide texture (transform matrix, offset/pivot, and modulate).

This approach allows intuitive property-based control while maintaining GPU-efficient per-fragment execution.

Properties

float

mode7_bottom_horizon_mask_amount

0.0

float

mode7_bottom_horizon_tilt

0.0

bool

mode7_enabled

false

Vector2

mode7_global_offset

Vector2(0, 0)

Vector2

mode7_global_pivot

Vector2(0.5, 0.5)

float

mode7_global_rotation

0.0

Mode7InterpolationMode

mode7_interpolation

0

bool

mode7_override_region_aspect

true

float

mode7_projection_aspect_ratio

1.0

float

mode7_projection_gamma

1.0

float

mode7_projection_pixel_aspect

1.0

float

mode7_projection_strength

1.0

NodePath

mode7_region_follow_target

NodePath("")

Array[Mode7ScanlineOverride]

mode7_scanline_overrides

[]

bool

mode7_tiling

false

float

mode7_top_horizon_mask_amount

0.0

float

mode7_top_horizon_tilt

0.0

Methods

void

force_update_follow_cache()

Enumerations

enum Mode7InterpolationMode: 🔗

Mode7InterpolationMode INTERPOLATION_NONE = 0

Nearest-neighbor: snap to this entry's transform for its UV band with no blending between rows. You typically only want this mode if you're scripting transformations for every scanline individually. For most cases, INTERPOLATION_LERP or INTERPOLATION_PROJECTION provides simpler and more intuitive control.

Mode7InterpolationMode INTERPOLATION_LERP = 1

Linear interpolation between adjacent entries in the override array. The shader uses standard lerping to blend transforms, pivots, and modulate colors across all intervening scanlines, creating smooth transitions regardless of how many overrides are in the array. Ideal for gradual effects like distance fog or terrain slope changes.

Mode7InterpolationMode INTERPOLATION_PROJECTION = 2

Perspective projection via per-scanline inverse-depth interpolation. Uses the first entry (index 0) as the top/horizon anchor and the last entry as the bottom/close anchor, mimicking how the SNES hardware projected a 3D plane onto the 2D screen. This mode requires exactly 2 scanline overrides in the array for correct behavior — additional entries are ignored.

Property Descriptions

float mode7_bottom_horizon_mask_amount = 0.0 🔗

  • void set_mode7_bottom_horizon_mask_amount(value: float)

  • float get_mode7_bottom_horizon_mask_amount()

Fraction (0..1) of the sprite to make transparent from the bottom up. 0 means no masking visible; 1 hides the entire sprite. Works independently of the top mask — both can be active simultaneously.

float mode7_bottom_horizon_tilt = 0.0 🔗

  • void set_mode7_bottom_horizon_tilt(value: float)

  • float get_mode7_bottom_horizon_tilt()

Tilt angle in degrees that rotates the bottom horizon line around the center like an aircraft attitude indicator. Positive values tilt clockwise (right side drops). Independent of mode7_bottom_horizon_mask_amount — always active and influences the horizon angle regardless of masking.

bool mode7_enabled = false 🔗

  • void set_mode7_enabled(value: bool)

  • bool is_mode7_enabled()

Enable or disable Mode 7 shader effects. When false, the sprite renders normally with no overhead from the custom material.

Acts as a master toggle — all other mode7_ properties only take effect when this is true.

Vector2 mode7_global_offset = Vector2(0, 0) 🔗

  • void set_mode7_global_offset(value: Vector2)

  • Vector2 get_mode7_global_offset()

Additive offset applied after all per-scanline transforms and global rotation. The offset is rotated by the same angle so it shifts in the global (screen) frame rather than the warped UV frame, giving a uniform screen-space translation regardless of per-scanline scaling.

Vector2 mode7_global_pivot = Vector2(0.5, 0.5) 🔗

  • void set_mode7_global_pivot(value: Vector2)

  • Vector2 get_mode7_global_pivot()

Pivot point in normalized [0..1] UV space around which mode7_global_rotation is applied. Defaults to center of the texture. Used for both global rotation and per-scanline transform anchoring.

float mode7_global_rotation = 0.0 🔗

  • void set_mode7_global_rotation(value: float)

  • float get_mode7_global_rotation()

Global rotation angle in degrees, applied after all per-scanline transforms. Rotates the entire warped image around mode7_global_pivot.

Valid range is -360 to 360 degrees.

Mode7InterpolationMode mode7_interpolation = 0 🔗

Determines how the shader blends the elements in the scanline override array across the sprite height. Choose based on your effect: INTERPOLATION_NONE for per-scanline precision, INTERPOLATION_LERP for smooth transitions between any number of overrides, or INTERPOLATION_PROJECTION for perspective with exactly 2 entries.

bool mode7_override_region_aspect = true 🔗

  • void set_mode7_override_region_aspect(value: bool)

  • bool is_mode7_override_region_aspect()

When true (default), non-square region rects have their rotations corrected to behave as if the region were square. This prevents rotations from skewing into shears when using a cropped region. Set to false if you want raw, uncorrected UV behavior for creative warping effects.

float mode7_projection_aspect_ratio = 1.0 🔗

  • void set_mode7_projection_aspect_ratio(value: float)

  • float get_mode7_projection_aspect_ratio()

Horizontal-to-vertical scale ratio for the perspective. 1.0 is uniform (classic Mode 7).

0.5 makes the horizontal scale half the vertical; values above 1.0 reverse the imbalance.

Useful for compensating non-square source art. Only applies in Projection interpolation mode. Recommended: 0.5–1.5, default 1.0.

float mode7_projection_gamma = 1.0 🔗

  • void set_mode7_projection_gamma(value: float)

  • float get_mode7_projection_gamma()

Gamma/power exponent for the inverse-depth curve. 1.0 is the classic linear 1/d progression.

Values below 1.0 soften the falloff so distant scanlines keep more perspective influence;

values above 1.0 sharpen it so the aggressive warp concentrates near the close anchor.

Only applies in Projection interpolation mode. Recommended: 0.5–2.0, default 1.0.

float mode7_projection_pixel_aspect = 1.0 🔗

  • void set_mode7_projection_pixel_aspect(value: float)

  • float get_mode7_projection_pixel_aspect()

Stretches/compresses the vertical coordinate before the inverse-depth calculation,

correcting for or exaggerating non-square display pixels (e.g. NTSC 8:7 ≈ 1.125).

Only applies in Projection interpolation mode. Recommended: 0.875–1.125, default 1.0 (square pixels).

float mode7_projection_strength = 1.0 🔗

  • void set_mode7_projection_strength(value: float)

  • float get_mode7_projection_strength()

Blends between a flat, unwarped image (0.0) and the full inverse-depth projection (1.0).

Lets you dial the perspective intensity down without reshaping the curve.

Only applies in Projection interpolation mode. Recommended: 0.0–1.0, default 1.0.

NodePath mode7_region_follow_target = NodePath("") 🔗

  • void set_mode7_region_follow_target(value: NodePath)

  • NodePath get_mode7_region_follow_target()

Path to a Node2D target. When set, the sprite's Sprite2D.region_rect shifts each physics frame so the Mode 7 viewport "follows" the target node while preserving its size and aspect ratio.

This creates the illusion of a moving camera or scrolling background. Only active when region mode is enabled on the sprite (Sprite2D.region_enabled must be true).

Array[Mode7ScanlineOverride] mode7_scanline_overrides = [] 🔗

Array of Mode7ScanlineOverride resources acting as anchors across the sprite height. Each entry defines a 2x2 affine matrix (rotation, scale, skew), a translation offset, and a pivot point, and the shader interpolates between adjacent entries for every output row (UV.y band).

When Mode 7 is enabled, a single default identity override is created automatically. Add more entries to interpolate between different transforms across the sprite height.

bool mode7_tiling = false 🔗

  • void set_mode7_tiling(value: bool)

  • bool is_mode7_tiling()

Whether out-of-bounds UV coordinates wrap (repeat) or become transparent. Enable this to make the texture tile seamlessly when the Mode 7 warp pushes UVs outside the [0..1] range.

float mode7_top_horizon_mask_amount = 0.0 🔗

  • void set_mode7_top_horizon_mask_amount(value: float)

  • float get_mode7_top_horizon_mask_amount()

Fraction (0..1) of the sprite to make transparent from the top down. 0 means no masking visible; 1 hides the entire sprite. Works independently of the bottom mask — both can be active simultaneously.

float mode7_top_horizon_tilt = 0.0 🔗

  • void set_mode7_top_horizon_tilt(value: float)

  • float get_mode7_top_horizon_tilt()

Tilt angle in degrees that rotates the top horizon line around the center like an aircraft attitude indicator. Positive values tilt clockwise (right side drops). Valid range is -360 to 360 degrees. Independent of mode7_top_horizon_mask_amount — always active and influences the horizon angle regardless of masking.

Method Descriptions

void force_update_follow_cache() 🔗

Re-resolve the follow target from mode7_region_follow_target and store it in the internal follow cache. Useful after a scene reload when you need to refresh the tracked target without waiting for Node.NOTIFICATION_ENTER_TREE.