godot-shaders-vfx
Use when writing or reviewing a Godot shader, particle effect, full-screen grade or post-processing setup, when an effect costs too many frames, or when a game needs graphics quality settings.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-13
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- godot-shaders-vfx
- description
- Use when writing or reviewing a Godot shader, particle effect, full-screen grade or post-processing setup, when an effect costs too many frames, or when a game needs graphics quality settings.
03 SKILL.md 正文
Shaders, particles and post-processing in Godot 4
Sources, tests and renderer details: ${CLAUDE_PLUGIN_ROOT}/docs/art.md. Every shader below compiles and renders in Godot
4.7.2 (the kit compiles them in CI). Feel and timing of effects live in game-juice; this skill is how to build them.
1. Shader basics
- A
.gdshaderfile starts withshader_type:canvas_item(2D and UI),spatial(3D),particles,skyorfog. Put it in aShaderMaterial; expose knobs asuniforms with hints (hint_range,source_color). vertex()runs per vertex (move, wobble, wind);fragment()runs per covered pixel and is where the cost is;light()runs per pixel per light.- One
ShaderMaterialshared by many nodes shares its uniforms: a hit flash set on one enemy flashes them all. Useinstance uniformandSetInstanceShaderParameter("amount", 1f)per node, or a duplicated material. - The C# names of particle classes differ from the editor's:
GpuParticles2D,GpuParticles3D,CpuParticles2D,GpuParticlesCollisionBox3D.GPUParticles2Ddoes not compile.
2. Four shaders worth having
Dissolve (drive threshold from 0 to 1 with a Tween; noise_tex a NoiseTexture2D):
shader_type canvas_item;
uniform sampler2D noise_tex : hint_default_white, filter_linear, repeat_enable;
uniform float threshold : hint_range(0.0, 1.0) = 0.0;
uniform vec4 edge_color : source_color = vec4(1.0, 0.5, 0.1, 1.0);
uniform float edge_width : hint_range(0.0, 0.2) = 0.05;
void fragment() {
vec4 base = texture(TEXTURE, UV) * COLOR;
float n = texture(noise_tex, UV).r;
float t = threshold * (1.0 + edge_width); // so 1.0 removes everything, edge included
float keep = step(t, n);
float edge = keep * (1.0 - step(t + edge_width, n));
COLOR = vec4(mix(base.rgb, edge_color.rgb, edge), base.a * keep);
}
Damage flash (set amount to 1 on a hit, tween to 0 over 0.1 s):
shader_type canvas_item;
instance uniform float amount : hint_range(0.0, 1.0) = 0.0;
uniform vec4 flash_color : source_color = vec4(1.0);
void fragment() {
vec4 base = texture(TEXTURE, UV) * COLOR;
COLOR = vec4(mix(base.rgb, flash_color.rgb, amount), base.a);
}
Rim light (fresnel), on top of normal lighting:
shader_type spatial;
uniform vec4 albedo : source_color = vec4(0.6, 0.6, 0.6, 1.0);
uniform vec4 rim_color : source_color = vec4(0.3, 0.7, 1.0, 1.0);
uniform float rim_power : hint_range(0.5, 8.0) = 3.0;
uniform float rim_strength : hint_range(0.0, 4.0) = 1.5;
void fragment() {
ALBEDO = albedo.rgb;
float fresnel = pow(1.0 - clamp(dot(NORMAL, VIEW), 0.0, 1.0), rim_power);
EMISSION = rim_color.rgb * fresnel * rim_strength;
}
Full-screen grade, on a ColorRect (full rect, MouseFilter Ignore) in a CanvasLayer above the game:
shader_type canvas_item;
uniform sampler2D screen_tex : hint_screen_texture, filter_linear_mipmap;
uniform float contrast : hint_range(0.0, 2.0) = 1.0;
uniform float saturation : hint_range(0.0, 2.0) = 1.0;
uniform vec4 tint : source_color = vec4(1.0);
void fragment() {
vec3 c = textureLod(screen_tex, SCREEN_UV, 0.0).rgb;
c = (c - 0.5) * contrast + 0.5;
c = mix(vec3(dot(c, vec3(0.2126, 0.7152, 0.0722))), c, saturation);
COLOR = vec4(c * tint.rgb, 1.0);
}
In a 3D game, put that CanvasLayer at layer -1: it grades the 3D world but not the UI on layers 0 and up. Posterize,
crosshatch, paper tint, grain and vignette all work there, and cheerful assets under a stark grade give a distinctive look
cheaply (posterize under soft fog bands: godot-pitfalls).
In the Compatibility renderer colours above 1.0 are clamped, so an edge or rim cannot glow through bloom there.
3. What a shader costs
- The fragment shader runs once per covered pixel per layer: cost grows with screen coverage and overdraw, not with the number of objects. Large transparent quads (smoke, full-screen effects) are the usual culprits.
- Each texture read costs; filtering costs more. A branch on per-pixel data is expensive; on a uniform it is fine. Quality
variants are
#defines or separate shaders, not runtimeifs. - Measure, do not guess:
benchreportsgpuMs(GPU time per frame),drawCalls,primitivesand memory. Run it with and without the effect, at the target resolution (-Resolution 1920x1080), and compare. Fill-rate bound when a small window is much faster than a large one. Viewport.DebugDraw = Viewport.DebugDrawEnum.Overdrawshows where layers pile up.- Precision qualifiers (
lowp,mediump, usually 16 bits,highp, the default 32) can speed up fragment maths on phones; desktop GPUs mostly ignore them. Colour maths survives 16 bits; positions, UVs on large textures andTIME(it runs to an hour before it wraps) do not. Some mobile drivers misbehave with them, so add them only wherebenchon the device shows a gain:
shader_type canvas_item;
uniform lowp vec4 tint : source_color = vec4(1.0);
void fragment() {
mediump vec4 base = texture(TEXTURE, UV) * COLOR; // colour: fine in 16 bits
highp float wave = sin(TIME * 2.0 + UV.x * 6.283); // TIME grows: keep it at full precision
COLOR = vec4(base.rgb * tint.rgb * (0.9 + 0.1 * wave), base.a);
}
4. Particles
GpuParticles2D/3D |
CpuParticles2D/3D |
|
|---|---|---|
| Many particles | yes | slower past a few thousand |
Trails, sub-emitters, EmitParticle |
Forward+ and Mobile only | no trails |
| Web, old mobile, Compatibility | limited (above); Adreno 3xx unsupported | safe choice |
- Bursts (impact sparks, explosions):
OneShot = true,Explosiveness = 1,Emitting = true; free it onFinished(p.Finished += p.QueueFree;). Loops (fire, smoke):OneShot = false, someRandomness. - Footstep dust: a small one-shot burst spawned at the foot on the footstep event,
LocalCoords = falseso it stays behind. Engine flames:LocalCoords = trueso they follow the ship. - Sub-emitters:
SubEmitterpoints at the child system;ParticleProcessMaterial.SubEmitterMode = AtEnd(sparks that burst into smoke). 3D trails needTrailEnabled, aRibbonTrailMeshorTubeTrailMeshinDrawPass1, and Use Particle Trails on its material. - Culling:
VisibilityRect(2D) orVisibilityAabb(3D) must contain the effect (Particles > Generate Visibility Rect), or it pops out at the screen edge; too big, and it is never culled. - Change
AmountRatio, notAmount, at run time (Amountrestarts the system).Preprocesswarms a loop up but runs the simulation many times at start; keep it short. - Cost: sweep 100, 1000 and 10000 particles with
bench -Sweep particles=100,1000,10000(a test scene reads--particles=<n>;sweep.rows[]gives p99 per value), and sweep particle size, since overdraw usually dominates.
5. Post-processing and quality tiers
What each renderer has (4.7):
| Effect | Compatibility | Mobile | Forward+ |
|---|---|---|---|
| Glow (bloom), tonemap, adjustments, LUT, fog, MSAA | yes (simpler glow) | yes | yes |
| SSAO | yes (radius, intensity) | no | yes |
| SSR, SSIL, SDFGI, volumetric fog, TAA, FSR | no | no | yes |
| Depth of field, FXAA | no | yes | yes |
Switching on an unsupported effect only prints a warning; check RenderingServer.GetCurrentRenderingMethod()
(forward_plus, mobile, gl_compatibility) first. A starting point for the settings menu:
| Setting | Low | Medium | High | Ultra |
|---|---|---|---|---|
Viewport.Scaling3DScale (FSR on Forward+) |
0.67 | 0.77 | 0.87 | 1.0 |
Viewport.Msaa3D |
off | 2x | 4x | 4x |
| Shadow atlas, soft filter | 1024, hard | 2048, low | 4096, medium | 8192, high |
Sun DirectionalShadowMaxDistance |
40 | 80 | 120 | 200 |
| SSAO | off | low, half size | medium | high |
| SSR, volumetric fog | off | off | on | on |
| SSIL | off | off | off | on |
| Depth of field | off | far | far and near | far and near, high |
Viewport.MeshLodThreshold |
4 | 2 | 1 | 0.5 |
Keep tonemapping and glow the same in every tier: they are the look, not a cost. Apply a tier in one function that sets the
Viewport, the Environment and the sun (RenderingServer.DirectionalShadowAtlasSetSize,
DirectionalSoftShadowFilterSetQuality, EnvironmentSetSsaoQuality), and let --quality=low select it so bench can
compare tiers in one run: bench -Sweep quality=low,medium,high.
6. Shaders from GodotShaders.com and elsewhere
Each post there is CC0, MIT or GPL v3, chosen by its author and shown at the bottom of the post; its images and videos are not
covered. Record each one in assets.json (source URL, author, licence: CC0-1.0, MIT, GPL-3.0-only); doctor warns
about GPL, which would bind the whole game. MIT asks for nothing on screen; the shipped build needs its copyright line
and licence text, which credits writes (asset-pipeline).
7. Prove it
- [ ] the
validaterunner compiles every.gdshaderin the project, used or not (a broken one fails the run) - [ ]
benchwith and without each costly effect, and once per quality tier, at the target resolution;gpuMsrecorded - [ ] screenshots of each effect at its peak (
shot), judged withlook - [ ] every imported shader has its entry in
assets.json
04 同仓库更多 Skills
over-budget
Use when a fixture exceeds the size budget.
bad-yaml
暂无简介
bad-workflow-description
Use when testing; runs the kit and then reads the JSON.
bad-version
Use when a fixture quotes a stale package version.
bad-value
Use when a fixture passes a value outside a parameter's set.
bad-trigger
Helps with Godot tests.