Mode7Sprite2D

float mode7_bottom_horizon_mask_amount = 0.0

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

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

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)

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)

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

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.

int 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

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

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

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

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

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("")

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).

Material mode7_saved_material

(Non-editor) Property to save the material the user had before enabling Mode 7.

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

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

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

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.

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.

INTERPOLATION_NONE = 0

Enum: Mode7InterpolationMode

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.

INTERPOLATION_LERP = 1

Enum: Mode7InterpolationMode

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.

INTERPOLATION_PROJECTION = 2

Enum: Mode7InterpolationMode

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.