magic-glow

magic-glow — Pulsing Light + Drifting Motes

Three layered cues that together read as "magical": a pulsing OmniLight3D (sin-wave energy), drifting additive billboard motes orbiting the source, and optional emission on the source mesh itself. Used for: enchanted items, soul gems, runes, summoning circles, wisps, fairies, magical waypoints. The recipe writes a single controller that builds and animates all three layers from one node.

When to use

• "This sword is enchanted — add a glow."
• "Make the soul gem pulse with light."
• "Magic rune on the floor glowing."
• "Wisp / fairy / firefly companion."
• "The summoning circle is active."
• "Quest item glows so the player notices it."
• Pre-charge phase before casting lightning or muzzle-flash (charge-up beam).

When NOT to use

• The user wants a static, non-animated glow — just enable emission on the mesh's material; this recipe is overkill.
• The user wants flames, not a glow — use fire (or magic-fire variant of fire).
• The user wants a beam shooting out, not an aura — use lightning with the plasma-laser variant.
• The user wants a screen-space bloom on the whole scene — that's WorldEnvironment.glow_*, not a per-object recipe.
• The user wants a 2D glow on a UI sprite — use canvas_item shader with a radial gradient, not this 3D recipe.

Recipe

1. Files to create

addons/vfx/magic-glow/magic_glow.gd
addons/vfx/magic-glow/magic_glow.tscn

No custom shader — uses canonical additive billboard motes (see _building-blocks/additive-billboard-particles.md) plus an OmniLight3D. Optional: pair with the source mesh's existing material's emission.

2. GDScript controller

addons/vfx/magic-glow/magic_glow.gd:

@tool
class_name MagicGlow
extends Node3D

## Builds: OmniLight3D (pulsing) + GPUParticles3D motes (drifting orbit) + optional mesh emission tween.
## Add as a child of any glowing object.

@export_group("Color")
@export var glow_color: Color = Color(0.55, 0.85, 1.0)
@export_range(0.0, 12.0) var light_energy_base: float = 1.4
@export_range(0.0, 12.0) var light_energy_amplitude: float = 0.8

@export_group("Pulse")
@export_range(0.05, 4.0) var pulse_hz: float = 0.7
@export var pulse_easing: Curve  ## leave null for sine; assign for custom

@export_group("Light")
@export_range(0.5, 30.0) var light_range: float = 4.0
@export var light_shadow_enabled: bool = false

@export_group("Motes")
@export_range(0, 256) var mote_count: int = 24
@export_range(0.05, 4.0) var mote_radius: float = 0.6
@export_range(0.5, 8.0)  var mote_lifetime: float = 2.0
@export_range(0.01, 0.30) var mote_size: float = 0.06
@export_range(0.0, 8.0)  var mote_emission_boost: float = 4.0
@export var mote_drift_up: float = 0.3       ## meters/sec mean upward drift

@export_group("Source mesh emission (optional)")
@export var pulse_source_mesh: NodePath      ## point at a MeshInstance3D to tween its emission_energy_multiplier
@export_range(0.0, 12.0) var source_emission_base: float = 1.0
@export_range(0.0, 12.0) var source_emission_amplitude: float = 1.5

var _light: OmniLight3D
var _motes: GPUParticles3D
var _source_mesh: MeshInstance3D
var _source_mat: BaseMaterial3D
var _t: float = 0.0
var _intensity: float = 1.0

func _ready() -> void:
    _build_light()
    _build_motes()
    _resolve_source_mesh()
    set_process(true)

func _build_light() -> void:
    _light = OmniLight3D.new()
    _light.light_color = glow_color
    _light.light_energy = light_energy_base
    _light.omni_range = light_range
    _light.shadow_enabled = light_shadow_enabled
    add_child(_light)

func _build_motes() -> void:
    if mote_count <= 0:
        return
    _motes = GPUParticles3D.new()
    _motes.amount = mote_count
    _motes.lifetime = mote_lifetime
    _motes.one_shot = false
    _motes.explosiveness = 0.0
    _motes.local_coords = true

    var pm := ParticleProcessMaterial.new()
    pm.emission_shape = ParticleProcessMaterial.EMISSION_SHAPE_SPHERE
    pm.emission_sphere_radius = mote_radius
    pm.direction = Vector3.UP
    pm.spread = 180.0
    pm.initial_velocity_min = 0.05
    pm.initial_velocity_max = 0.20
    pm.gravity = Vector3(0, mote_drift_up * 0.5, 0)
    pm.scale_min = mote_size * 0.7
    pm.scale_max = mote_size * 1.3
    pm.color = glow_color
    pm.damping_min = 0.5
    pm.damping_max = 1.2
    _motes.process_material = pm

    var mesh := QuadMesh.new()
    mesh.size = Vector2.ONE
    # 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 = glow_color
    bm.emission_enabled = true
    bm.emission = glow_color
    bm.emission_energy_multiplier = mote_emission_boost
    mesh.material = bm
    _motes.draw_pass_1 = mesh

    add_child(_motes)

func _resolve_source_mesh() -> void:
    if pulse_source_mesh.is_empty(): return
    var n := get_node_or_null(pulse_source_mesh)
    if n is MeshInstance3D:
        _source_mesh = n
        var m := _source_mesh.get_active_material(0)
        if m is BaseMaterial3D:
            _source_mat = m
            _source_mat.emission_enabled = true
            if _source_mat.emission == Color.BLACK:
                _source_mat.emission = glow_color

func _process(delta: float) -> void:
    _t += delta
    var phase: float = (sin(_t * TAU * pulse_hz) + 1.0) * 0.5   # 0..1
    if pulse_easing:
        phase = pulse_easing.sample(phase)

    if _light:
        _light.light_energy = (light_energy_base + light_energy_amplitude * phase) * _intensity
    if _source_mat:
        _source_mat.emission_energy_multiplier = (source_emission_base + source_emission_amplitude * phase) * _intensity

func set_intensity(scale: float) -> void:
    ## Scale all visible cues 0..1+ (e.g., charge-up: tween from 0 to 1 over a second).
    ## Held as a separate factor rather than multiplied into light_energy_base /
    ## light_energy_amplitude: a multiplying version (`light_energy_base *= scale`)
    ## pins both fields to 0.0 forever after set_intensity(0.0), so the charge-up
    ## tween from 0 to 1 never brings the glow back.
    _intensity = scale
    if _motes:
        _motes.amount_ratio = scale

func extinguish(fade_seconds: float = 0.6) -> void:
    var t := create_tween().set_parallel(true)
    t.tween_property(_light, "light_energy", 0.0, fade_seconds)
    if _motes:
        t.tween_property(_motes, "amount_ratio", 0.0, fade_seconds)
    t.chain().tween_callback(queue_free)