hit-spark

hit-spark — One-Shot Impact Sparks

Tiny stretched additive billboards spraying outward from an impact point, oriented to the surface normal so the burst points the right way. Used for: bullets hitting metal, sword clashes, footsteps on stone, ricochets, lightning endpoints, hammer strikes. The recipe is a GPUParticles3D configured for one-shot bursts plus a spawn_hit_spark(position, normal) static helper that orients the emitter, restarts it, and frees after lifetime.

When to use

• "Sparks when the bullet hits the wall."
• "Sword clash sparks."
• "Sparks under the hammer when the blacksmith works."
• "Footstep sparks on stone for the heavy armor."
• "Ricochet sparks when the projectile glances off."
• "Mining: sparks fly when pickaxe hits rock."
• Endpoint sparks on lightning and muzzle-flash recipes (they reference this).

When NOT to use

• The user wants a flash at the impact, not a spray of particles — use muzzle-flash (recolor it).
• The user wants debris chunks (rock pieces, splinters) — those are physics objects, not particles. Spawn RigidBody3D shards, then sparks on top.
• The user wants water droplets at a water impact — recolor this recipe blue/white (it works) or pair with water-ripple for the ring on the surface.
• The user wants persistent burning sparks that linger and cool down — that's a hybrid; use this for the burst, then tiny fire particles for residual embers.

Recipe

1. Files to create

addons/vfx/hit-spark/hit_spark.gd
addons/vfx/hit-spark/hit_spark.tscn

No custom shader — uses the canonical additive billboard material (see _building-blocks/additive-billboard-particles.md). A StandardMaterial3D with the right flags is enough. (BaseMaterial3D is abstract: BaseMaterial3D.new() is a parse error. Its enum constants are still the right names to use.)

2. GDScript controller

addons/vfx/hit-spark/hit_spark.gd:

@tool
class_name HitSpark
extends GPUParticles3D

@export_group("Spark size")
@export_range(8, 256)   var spark_count: int = 24 :
    set(v): spark_count = v; _apply()
@export_range(0.05, 1.5) var burst_speed: float = 0.6 :
    set(v): burst_speed = v; _apply()
@export_range(0.05, 1.5) var spark_lifetime: float = 0.35 :
    set(v): spark_lifetime = v; _apply()
@export_range(5.0, 90.0) var spread_degrees: float = 35.0 :
    set(v): spread_degrees = v; _apply()
@export_range(0.0, 9.8)  var gravity_strength: float = 4.0 :
    set(v): gravity_strength = v; _apply()

@export_group("Look")
@export var spark_color: Color = Color(1.0, 0.85, 0.45)
@export_range(0.0, 12.0) var emission_boost: float = 5.0
@export var stretch_to_velocity: bool = true

func _ready() -> void:
    one_shot = true
    emitting = false
    explosiveness = 1.0   # all particles spawn in frame 1
    _apply()
    _ensure_material()

func _apply() -> void:
    amount = spark_count
    lifetime = spark_lifetime

    var pm := process_material as ParticleProcessMaterial
    if pm == null:
        pm = ParticleProcessMaterial.new()
        process_material = pm
    pm.emission_shape = ParticleProcessMaterial.EMISSION_SHAPE_POINT
    pm.direction = Vector3.UP                  # local +Y; the controller orients the node to the surface normal
    pm.spread = spread_degrees
    pm.initial_velocity_min = burst_speed * 6.0
    pm.initial_velocity_max = burst_speed * 12.0
    pm.gravity = Vector3(0, -gravity_strength, 0)
    pm.scale_min = 0.04
    pm.scale_max = 0.10
    pm.color = spark_color
    pm.damping_min = 1.5
    pm.damping_max = 3.0
    if stretch_to_velocity:
        pm.particle_flag_align_y = true
        pm.scale_curve = _make_streak_curve()

func _ensure_material() -> void:
    if draw_pass_1 == null:
        var mesh := QuadMesh.new()
        mesh.size = Vector2(0.08, 0.30) if stretch_to_velocity else Vector2(0.10, 0.10)
        # BaseMaterial3D is abstract ("Native class "BaseMaterial3D" cannot be
        # constructed as it is abstract"); StandardMaterial3D is the concrete subclass.
        var bm := StandardMaterial3D.new()
        bm.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA
        bm.blend_mode = BaseMaterial3D.BLEND_MODE_ADD
        bm.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
        bm.billboard_mode = BaseMaterial3D.BILLBOARD_PARTICLES
        bm.albedo_color = spark_color
        bm.emission_enabled = true
        bm.emission = spark_color
        bm.emission_energy_multiplier = emission_boost
        mesh.material = bm
        draw_pass_1 = mesh

func _make_streak_curve() -> CurveTexture:
    var c := Curve.new()
    c.add_point(Vector2(0.0, 1.0))
    c.add_point(Vector2(0.8, 1.0))
    c.add_point(Vector2(1.0, 0.0))   # shrink at end of life
    var ct := CurveTexture.new()
    ct.curve = c
    return ct

## Static helper. Spawns a transient one-shot burst at world `position`, oriented to `normal`.
##   parent: where to attach the spark instance (defaults to the scene tree root)
##   position: world-space impact point
##   normal: world-space surface normal at the impact
##   intensity: 0.0–1.0+ scales the burst (light tap = 0.4, heavy hit = 1.0, explosion = 1.6)
static func spawn_hit_spark(
        parent: Node,
        position: Vector3,
        normal: Vector3 = Vector3.UP,
        intensity: float = 1.0,
        scene_path: String = "res://addons/vfx/hit-spark/hit_spark.tscn"
    ) -> HitSpark:
    if not ResourceLoader.exists(scene_path):
        push_error("HitSpark: scene missing at %s" % scene_path)
        return null
    # `var inst := load(...).instantiate()` cannot infer a type; the `as HitSpark`
    # cast is what gives this one a static type.
    var inst := load(scene_path).instantiate() as HitSpark
    if inst == null:
        push_error("HitSpark: %s is not a HitSpark scene" % scene_path)
        return null
    parent.add_child(inst)
    inst.global_position = position
    # Orient local +Y (cone direction) to the surface normal.
    if normal.length_squared() > 0.0001:
        inst.look_at(position + normal, _safe_up(normal))
        inst.rotate_object_local(Vector3.RIGHT, deg_to_rad(-90.0))   # because look_at uses -Z forward
    inst.amount = max(4, int(inst.spark_count * intensity))
    inst.restart()
    inst.emitting = true
    var t := inst.get_tree().create_timer(inst.spark_lifetime + 0.1)
    t.timeout.connect(inst.queue_free)
    return inst

static func _safe_up(n: Vector3) -> Vector3:
    return Vector3.RIGHT if absf(n.dot(Vector3.UP)) > 0.99 else Vector3.UP