muzzle-flash

muzzle-flash — One-Shot Star-Burst Flare

A muzzle flash is on screen for 60–100 ms. Long enough to read, too short to animate. The recipe: a single billboarded quad with a star-burst gradient shader, fired by restart() on a weapon's fired signal, plus an OmniLight3D snapping on for 60 ms to light the room. Optional: a tiny GPUParticles3D one-shot for sparks. Doom Eternal does this. Half-Life 2 did this. Every shooter does this.

When to use

• "Add a muzzle flash to the rifle / pistol / shotgun."
• "When I fire, the gun should flash."
• "Spell-cast burst at the wizard's palm." (one-shot at hand position)
• "Cannon fires, big flash at the barrel."
• The user just hooked up a weapon and the firing reads as silent / weightless.

When NOT to use

• The user wants a continuous flame (flamethrower) — use fire, not muzzle-flash.
• The user wants the impact spark on the wall the bullet hit — that's hit-spark.
• The user wants a tracer line from barrel to target — use an ImmediateMesh recipe, not this. The current Summer build has no Line3D (ClassDB.class_exists("Line3D") is false).
• The user wants a slow-glowing spell charge-up — use magic-glow for the buildup, then this for the release frame.

Recipe

1. Files to create

addons/vfx/muzzle-flash/muzzle_flash.gdshader
addons/vfx/muzzle-flash/muzzle_flash.gd
addons/vfx/muzzle-flash/muzzle_flash.tscn  (reusable scene)

2. Shader code

addons/vfx/muzzle-flash/muzzle_flash.gdshader:

shader_type spatial;
render_mode unshaded, blend_add, depth_draw_never, cull_disabled, shadows_disabled;

uniform vec4  flash_color    : source_color = vec4(1.0, 0.85, 0.45, 1.0);
uniform vec4  core_color     : source_color = vec4(1.0, 1.0, 0.95, 1.0);
uniform float intensity      : hint_range(0.0, 1.0) = 1.0;       // driven by the controller (1 → 0)
uniform float emission_boost : hint_range(0.0, 12.0) = 6.0;
uniform int   ray_count      : hint_range(2, 8) = 4;
uniform float ray_sharpness  : hint_range(0.5, 32.0) = 8.0;
uniform float random_seed    : hint_range(0.0, 6.2831) = 0.0;    // rotates the star per shot

void vertex() {
    // Billboard toward the camera. The bare mat4(INV_VIEW_MATRIX[0..2], MODEL_MATRIX[3])
    // form discards the node's scale, so the per-shot `flash_size` randomisation in
    // fire() would never reach the screen — normalize the basis and re-apply scale.
    MODELVIEW_MATRIX = VIEW_MATRIX * mat4(
        normalize(INV_VIEW_MATRIX[0]),
        normalize(INV_VIEW_MATRIX[1]),
        normalize(INV_VIEW_MATRIX[2]),
        MODEL_MATRIX[3]) * mat4(
        vec4(length(MODEL_MATRIX[0].xyz), 0.0, 0.0, 0.0),
        vec4(0.0, length(MODEL_MATRIX[1].xyz), 0.0, 0.0),
        vec4(0.0, 0.0, length(MODEL_MATRIX[2].xyz), 0.0),
        vec4(0.0, 0.0, 0.0, 1.0));
    MODELVIEW_NORMAL_MATRIX = mat3(MODELVIEW_MATRIX);
}

void fragment() {
    vec2 c = UV - vec2(0.5);
    float r = length(c) * 2.0;
    float ang = atan(c.y, c.x) + random_seed;

    // Soft radial core: hottest at center, falls off to zero at the edge.
    float core = smoothstep(1.0, 0.0, r);
    core = pow(core, 2.0);

    // Star-burst rays: cosine of angle * ray_count gives N spokes.
    float rays = pow(max(cos(ang * float(ray_count)), 0.0), ray_sharpness);
    rays *= smoothstep(1.05, 0.05, r);  // rays fade to edge

    float mask = clamp(core + rays * 0.85, 0.0, 1.0);

    // Mix core color (white-hot) into flash color at the very center.
    vec3 col = mix(flash_color.rgb, core_color.rgb, pow(core, 4.0));

    // `render_mode unshaded` outputs ALBEDO and discards EMISSION entirely
    // (scene_forward_clustered.glsl:2962 — `frag_color = vec4(albedo, alpha)`
    // under MODE_UNSHADED), so the bloom boost has to live in ALBEDO.
    ALBEDO = col * emission_boost * intensity;
    ALPHA  = mask * intensity;
}