class

UniversalMaterial

Inherits Reference < Object

Ergonomic wrapper and fluent builder around a ShaderMaterial backed by res://addons/pattern_material/shaders/pattern_replace.gdshader.

Combines Faces, Glyphs, SpritesheetAtlas, Patterns, PatternGenerator, and Palette with typed helper methods for configuring projection modes, transforms, wave motions, outlines, bevels, 3D cel shading, drop shadows, retro dithering, dissolve wipes, backdrop refraction, and vertex effects.

Constants

LEGACY_SHADER_PATH = "res://shaders/pattern_replace.gdshader"

SHADER_PATH = "res://addons/pattern_material/shaders/pattern_replace.gdshader"

Constructors

comic_halftone

Preset factory: 90s comic book halftone print with dithered lighting and hatched drop shadow.

cutout_character

Preset factory: 2.5D animated cutout character style.

enamel_pin_badge

Preset factory: glossy enamel pin badge with metallic bevel and inner/outer rim.

glass_lens

Preset factory: refractive duotone frosted glass lens style.

new(material : ShaderMaterial = ShaderMaterial.new)

retro_hologram

Preset factory: CRT scanline & VHS glitch hologram style.

sticker_glyph

Preset factory: embossed enamel pin / sticker glyph badge style.

vhs_glitch_portal

Preset factory: kaleidoscopic VHS glitch portal with chromatic RGB split and spherical/radial symmetry.

water_caustics

Preset factory: 3D animated water caustics with surface waves and refraction.

Instance methods

apply_to(target_mat : ShaderMaterial) : self

Copies all configured shader parameters onto another ShaderMaterial.

apply_to(target_node : Node) : self

Assigns the underlying ShaderMaterial onto a GeometryInstance3D (material_override), CSGShape3D / CanvasItem (material), or MeshInstance3D mesh surface.

ensure_shader!

Ensures pattern_replace.gdshader is assigned to the underlying ShaderMaterial when running in Godot.

generator

get_param?(name : String) : ParamValue | Nil

material

parameters

save_tres(path : String) : String

Writes to_tres to path on disk and returns the resolved filesystem path.

set_3d_surface(projection : ProjectionMode = ProjectionMode::WorldTriplanar, use_base_texture : Bool = false, tile_base_texture : Bool = true) : self

Configures 3D surface mode (enables tile_base_texture or disables use_base_texture for pure pattern brushes).

set_atlas(atlas : SpritesheetAtlas, key : String | Char | Symbol) : self

Configures the material to display an icon cell from any SpritesheetAtlas.

set_backdrop_fx(blend_mode : BackdropBlendMode = BackdropBlendMode::StandardAlpha, refraction : Float64 = 0.0, pixel_size : Float64 = 1.0, blur_lod : Float64 = 0.0, chromatic_aberration : Float64 = 0.0) : self

Configures screen-space backdrop effects (refraction, pixelation, frosted blur, chromatic split, and backdrop blend modes).

set_bevel(enabled : Bool = true, strength : Float64 = 0.5, angle : Float64 = 2.356) : self

Configures Win98 / sticker inner bevel & emboss lighting.

set_cel_shading(enabled : Bool = true, strength : Float64 = 0.35, bands : Int = 2, dither_light : Bool = false, light_dir : Vector3 = Vector3.new(0.4_f32, 0.8_f32, 0.5_f32)) : self

Configures 3D directional Cel / Bayer-dithered toon lighting.

set_colors(fg : Palette::ColorId | Int | String | Symbol | Color, bg : Palette::ColorId | Int | String | Symbol | Color, outline : Palette::ColorId | Int | String | Symbol | Color | Nil = nil, unreplaced : Palette::ColorId | Int | String | Symbol | Color | Nil = nil) : self

Configures fg_color, bg_color, and optional outline_color / unreplaced_color using Palette indices, names, or Colors.

set_dissolve(amount : Float64, edge_width : Float64 = 0.05, edge_color : Palette::ColorId | Int | String | Symbol | Color = "white") : self

Configures pattern-driven dissolve wipe.

set_dither(enabled : Bool = true, strength : Float64 = 0.5, pixel_size : Float64 = 2.0) : self

Configures 4x4 Bayer matrix dithering.

set_drop_shadow(enabled : Bool = true, offset : Vector2 = Vector2.new(4.0_f32, -4.0_f32), color : Palette::ColorId | Int | String | Symbol | Color = "deep_indigo", dither : Bool = false, use_pattern : Bool = false) : self

Configures the 2.5D offset paper-cutout drop shadow (with optional Bayer dither or pattern hatch).

set_face(key : String | Char | Symbol) : self

Configures the material to display a face icon from Faces (res://textures/fontawesome/faces.svg).

set_fresnel(enabled : Bool = true, power : Float64 = 2.5, invert_pattern : Bool = false, color : Palette::ColorId | Int | String | Symbol | Color | Nil = nil) : self

Configures 3D Fresnel rim highlighting / pattern inversion.

set_generator(gen : PatternGenerator) : self

Assigns a procedural PatternGenerator to custom_pattern on the material.

set_glyph(key : String | Char | Symbol) : self

Configures the material to display a badge glyph from Glyphs (res://textures/fontawesome/letter_glyphs.svg).

set_outline(enabled : Bool = true, width : Float64 = 3.0, mode : OutlineMode = OutlineMode::Center, color_mode : OutlineColorMode = OutlineColorMode::SolidColor, boil_amp : Float64 = 0.0, boil_freq : Float64 = 8.0) : self

Configures outline stroke parameters including optional boiling lines and outline color mode.

set_param(name : String, value : ParamValue) : self

Sets a shader parameter on both the underlying Godot ShaderMaterial (when active) and the local parameter mirror for inspection/testing.

set_pattern(key : String | Symbol) : self

Assigns custom_pattern from Patterns (res://addons/pattern_material/textures/patterns/*.svg).

set_pattern(gen : PatternGenerator) : self

Assigns a procedural PatternGenerator to custom_pattern.

set_pattern_blend(mode : BlendMode = BlendMode::Replace, opacity : Float64 = 1.0, invert : Bool = false) : self

Configures pattern compositing blend mode, opacity, and black/white inversion.

set_position_motion(linear_speed : Vector2 = Vector2.new(0.0_f32, 0.0_f32), wave_mode : PositionWaveMode = PositionWaveMode::None, wave_amp : Vector2 = Vector2.new(0.25_f32, 0.25_f32), wave_freq : Vector2 = Vector2.new(1.0_f32, 1.0_f32), wave_phase : Vector2 = Vector2.new(0.0_f32, 0.0_f32)) : self

Configures linear UV drift speed and periodic wave oscillation for pattern position.

set_replace_mask(mode : ReplaceMode = ReplaceMode::G, color : Palette::ColorId | Int | String | Symbol | Color = "white", threshold : Float64 = 0.5, hard_edges : Bool = true, hard_edge_threshold : Float64 = 0.5) : self

Configures which channel or target color is replaced by the pattern, plus hard-edge contour snapping.

set_retro_crt(glitch_intensity : Float64 = 0.25, scanline_strength : Float64 = 0.3, scanline_density : Float64 = 120.0, emission_strength : Float64 = 1.0) : self

Configures VHS glitch and CRT scanlines.

set_ripple(enabled : Bool = true, mode : RippleMode = RippleMode::CrossWave, amp : Vector2 = Vector2.new(0.05_f32, 0.05_f32), freq : Vector2 = Vector2.new(6.0_f32, 6.0_f32), speed : Vector2 = Vector2.new(2.0_f32, 2.0_f32)) : self

Configures spatial UV wave/ripple distortion across the pattern.

set_rotation_motion(linear_speed : Float64 = 0.0, wave_mode : RotationWaveMode = RotationWaveMode::None, wave_amp : Float64 = 0.5, wave_freq : Float64 = 1.0) : self

Configures continuous angular spin and periodic pendulum wave swing for pattern rotation.

set_scale_pulse(wave_mode : ScaleWaveMode = ScaleWaveMode::None, wave_amp : Vector2 = Vector2.new(0.25_f32, 0.25_f32), wave_freq : Vector2 = Vector2.new(1.0_f32, 1.0_f32)) : self

Configures periodic breathing/pulsing oscillation for pattern scale.

set_surface_fx(pixel_size : Float64 = 1.0, chromatic_split : Float64 = 0.0) : self

Configures surface pixelation and prismatic RGB channel split on the pattern itself.

set_theme(theme : Palette::Theme | String | Symbol, use_tritone : Bool = false) : self

Applies a curated Palette::Theme (setting fg_color, bg_color, outline_color, unreplaced_color, and optional mid_color).

set_time_quantization(enabled : Bool = true, fps : Float64 = 12.0) : self

Configures choppy 90s / stop-motion FPS time quantization.

set_transform(scale : Float64 = 1.0, non_uniform_scale : Vector2 = Vector2.new(1.0_f32, 1.0_f32), offset : Vector2 = Vector2.new(0.0_f32, 0.0_f32), rotation : Float64 = 0.0, flip_x : Bool = false, flip_y : Bool = false, mirror_tiles : Bool = false, scaling : Bool = true, kaleidoscope_segments : Int = 0) : self

Configures static UV transform, tiling scale, rotation, mirroring, and N-fold kaleidoscope symmetry.

set_transparency(master_opacity : Float64 = 1.0, pattern_alpha_affects_surface : Bool = true, outline_ignores_master_opacity : Bool = false, opacity_dither_enabled : Bool = false, alpha_scissor_threshold : Float64 = 0.001) : self

Configures surface transparency, per-region cutout/translucency, and 90s screen-door dithered opacity.

set_tritone(mid : Palette::ColorId | Int | String | Symbol | Color, mid_point : Float64 = 0.5, enabled : Bool = true) : self

Configures the 3-color tritone palette ramp (bg_color -> mid_color -> fg_color).

set_vertex_fx(billboard : BillboardMode = BillboardMode::Disabled, motion : VertexMotionMode = VertexMotionMode::Disabled, wave_amp : Vector2 = Vector2.new(0.08_f32, 0.08_f32), wave_freq : Vector2 = Vector2.new(2.0_f32, 2.0_f32), wave_speed : Float64 = 2.0, vertex_snap : Bool = false, snap_resolution : Float64 = 160.0) : self

Configures vertex billboarding, 3D surface waves, or paper cutout sway.

to_tres

Serializes this UniversalMaterial configuration to a Godot 4 .tres ShaderMaterial string.

Nested types