DEV Community: saltmire

Godot 4 change_scene_to_file not working? 4 causes and fixes

saltmire — Sun, 27 Sep 2026 13:15:06 +0000

Changing scenes in Godot 4 looks like a one-liner: get_tree().change_scene_to_file("res://level_2.tscn").
Then the door trigger throws an error, the game crashes one line later, or the build
you exported loads a black screen. The call itself is almost never the bug — what
happens around it is. Here are the four causes, ordered by how often they show up.

1. Code after the call runs on a scene that's already gone

Symptom. The scene changes, but you get
Cannot call method 'get_first_node_in_group' on a null value (or any
get_tree()-based call failing) on the line right after change_scene_to_file().

Cause. Since Godot 4.2, the outgoing scene is removed from the tree
immediately when you call change_scene_to_file(). From that point until the end
of the frame, get_tree() on that scene returns null and
get_tree().current_scene is null too — the new scene isn't added until the end
of the frame. So anything you do after the call is running on a node that's no
longer in the tree.

# broken — get_tree() is null on the second line
func _on_exit_reached() -> void:
    get_tree().change_scene_to_file("res://levels/level_2.tscn")
    get_tree().current_scene.spawn_player()  # null

Fix. Make the scene change the last thing the old scene does. Anything the new
scene needs goes into an autoload beforehand, and the new scene reads it in its own
_ready():

# old scene
func _on_exit_reached() -> void:
    GameState.spawn_point = "north_door"   # autoload survives the change
    get_tree().change_scene_to_file("res://levels/level_2.tscn")

# new scene (level_2.gd)
func _ready() -> void:
    var marker := get_node("Spawns/" + GameState.spawn_point) as Marker2D
    $Player.global_position = marker.global_position

2. "Can't change this state while flushing queries"

Symptom. You change scene from a body_entered / area_entered signal (a door,
a level exit, a death pit) and the output fills with
Can't change this state while flushing queries. Use call_deferred() or set_deferred() to change monitoring state instead.

Cause. Those signals fire during the physics step, while the physics server is
still processing collisions. Changing the scene removes every Area2D and
CollisionShape2D in it right then — in the middle of the step that's iterating
over them.

Fix. Defer the call so it runs after the physics step finishes:

func _on_body_entered(body: Node2D) -> void:
    if body.is_in_group("player"):
        get_tree().change_scene_to_file.call_deferred("res://levels/level_2.tscn")

The same rule applies to anything else that adds or frees collision nodes from inside
a physics callback — defer it.

3. The path breaks after a rename — or only in the exported build

Symptom. It worked yesterday, now nothing happens. Or it works perfectly in the
editor but the exported game shows a black screen or stays on the same scene.

Cause. change_scene_to_file() doesn't throw — it returns an Error, and most
code ignores it. Two common reasons it fails:

You moved or renamed the .tscn in the FileSystem dock. The editor updates references inside scenes, but not string literals in your scripts.
Case mismatch: res://Levels/Level_2.tscn vs res://levels/level_2.tscn. Windows and macOS don't care in the editor; the exported .pck does.

Fix. First, stop ignoring the return value:

var err := get_tree().change_scene_to_file(path)
if err != OK:
    push_error("Scene change to %s failed: %s" % [path, error_string(err)])

Then remove the fragile string entirely. Export a PackedScene and drag the file into
the Inspector — Godot tracks it by UID, so renames and moves keep working:

@export var next_scene: PackedScene

func go_next() -> void:
    get_tree().change_scene_to_packed.call_deferred(next_scene)

4. The change fires twice

Symptom. Your fade plays twice, a level gets skipped, or you get a second error
right after the first scene change.

Cause. The player's body often overlaps a trigger with more than one shape, or
re-enters it on the same frame, so body_entered fires more than once. Each call
queues another scene change — and if you have a fade tween in front of it, you now
have two tweens racing each other.

Fix. Guard it with a flag and switch the trigger off on the first hit:

var _leaving := false

func _on_body_entered(body: Node2D) -> void:
    if _leaving or not body.is_in_group("player"):
        return
    _leaving = true
    set_deferred("monitoring", false)
    get_tree().change_scene_to_packed.call_deferred(next_scene)

What all four have in common

A scene change is a destructive operation on the whole tree: it frees every node,
including the one that asked for it. Treat it like queue_free() on yourself —
do it last, do it deferred when physics is involved, point it at a tracked
resource instead of a string, and make sure it only happens once.

Once that's solid, the next thing most games want is a transition that hides the
cut — and wiring a fade, a loading step and the deferred change together is exactly
where these four bugs love to come back. Saltmire Transitions packages that part
into a single call, with the fades, wipes and the safe scene swap already handled,
and it's free.

If you'd rather drop this in than build it, Saltmire Transitions does it as a ready-made tool: https://saltmire.itch.io/saltmire-transitions-scene-transition-kit-for-godot-4

Originally published at https://saltmire.github.io/godot-4-change-scene-not-working.html

What I learned building a health component with i-frames in Godot 4

saltmire — Fri, 25 Sep 2026 12:26:33 +0000

Every Godot 4 project I start ends up with var health := 100 pasted into the player, then
the enemy, then the breakable crate. Then the three copies drift apart. Here is what I
learned pulling health out into one reusable component, roughly in the order each bug
showed up.

Lesson 1: health is not the player's job

The first version always lives inside the player script:

var health := 100

func take_damage(amount: int) -> void:
    health -= amount
    if health <= 0:
        die()

That's fine until an enemy needs the same logic, then a destructible barrel, then a boss
with a health bar. Once there are three copies, one gets clamping, one gets a signal for
the UI, and one gets neither. The fix is a small node you can drop into any scene:

class_name HealthComponent
extends Node

signal health_changed(current: int, max_health: int)
signal died

@export var max_health := 100
var current := max_health

func _ready() -> void:
    current = max_health

func damage(amount: int) -> void:
    current = clampi(current - amount, 0, max_health)
    health_changed.emit(current, max_health)
    if current == 0:
        died.emit()

func heal(amount: int) -> void:
    current = clampi(current + amount, 0, max_health)
    health_changed.emit(current, max_health)

The owner (player, enemy, crate) connects to died and decides what death means. The
component only counts. That split turned out to matter more than any of the code.

Lesson 2: the health bar should never ask for health

My early UI code read player.health every frame in _process. That works, but it ties
the health bar to one specific node and breaks the moment the player is freed and
respawned. With the signal, the bar just listens:

func bind(health: HealthComponent) -> void:
    health.health_changed.connect(_on_health_changed)
    _on_health_changed(health.current, health.max_health)

func _on_health_changed(current: int, max_health: int) -> void:
    value = float(current) / max_health * 100.0

Calling the handler once inside bind() is the part I kept forgetting. Without it the bar
shows 100% until the first hit, even if the scene loaded with the player at half health.

Lesson 3: the double-hit bug is what i-frames actually fix

I thought invincibility frames were a design choice, something that makes the game feel
fairer. In practice they fixed a real bug first. A spike hitbox overlapping the player
for 12 physics frames dealt damage 12 times, and a single sword swing could hit twice
when the enemy's hurtbox entered, left, and re-entered the area during the animation.

A timer inside the component fixes both at the source:

@export var iframe_duration := 0.5
var _invulnerable := false

func damage(amount: int) -> void:
    if _invulnerable or current == 0:
        return
    current = clampi(current - amount, 0, max_health)
    health_changed.emit(current, max_health)
    if current == 0:
        died.emit()
        return
    if iframe_duration > 0.0:
        _invulnerable = true
        get_tree().create_timer(iframe_duration).timeout.connect(
            func(): _invulnerable = false)

Enemies in a horde game usually want iframe_duration = 0.0 (or something very short)
so fast weapons still feel fast. The player usually wants 0.5–1.0 seconds. Making it an
export instead of hard-coding it was what let one component work for both.

Lesson 4: "died" must fire exactly once

This bug wasted an evening. Two projectiles hit an enemy on the same physics frame. Both
called damage(), both saw current == 0 afterwards, and died fired twice. The enemy
dropped two coins, the kill counter went up by two, and the second queue_free() threw
an error on an instance that was already queued.

That's why the check at the top of damage() has or current == 0. Once health reaches
zero, the component ignores everything after it. It's one condition, and it's also the
only place that condition needs to exist. Anything listening to died can assume it runs
once per life.

If you add a respawn, give it an explicit reset instead of healing from zero:

func reset() -> void:
    current = max_health
    _invulnerable = false
    health_changed.emit(current, max_health)

heal() on a dead entity was the other source of zombies. I made healing from 0 do
nothing, and revival only happens on purpose.

Lesson 5: flash the sprite from the owner, not the component

The component should not know there's a sprite. When I put modulate changes inside it,
it broke immediately on the crate, which used a different node structure. Now the owner
reacts to the signal it already has:

func _ready() -> void:
    $HealthComponent.health_changed.connect(func(_c, _m): _flash())

func _flash() -> void:
    var t := create_tween()
    $Sprite2D.modulate = Color(1, 0.4, 0.4)
    t.tween_property($Sprite2D, "modulate", Color.WHITE, 0.15)

What I'd do differently starting over

Build the component first, before the second thing that can take damage exists. Put
i-frames and the "dead means dead" guard in from day one, because both bugs show up the
first time two hits land close together. And keep the component dumb: it counts, emits,
and refuses. Everything visual belongs to whoever owns it.

The part this post skips is the other half: who is allowed to hit whom. That's
collision layers, teams, making sure the player's own sword doesn't hurt the player, and
knockback direction. That's the wiring I got tired of redoing in every project.

If you'd rather drop this in than build it, Saltmire Hitbox does it as a ready-made tool: https://saltmire.itch.io/saltmire-hitbox

Originally published at https://saltmire.github.io/godot-4-health-component-iframes.html

Area2D vs RayCast2D vs ShapeCast2D for melee attacks in Godot 4 — which and when

saltmire — Wed, 23 Sep 2026 12:27:08 +0000

You press attack, the sword animation plays, and now the game has to answer one
question: what did that swing touch? Godot 4 gives you three nodes that can answer it —
Area2D, RayCast2D and ShapeCast2D — and every tutorial seems to pick a different
one. They are not interchangeable. Each one answers the question at a different time
and with a different shape, and that is the whole decision.

Area2D: an overlap you listen to

An Area2D with a CollisionShape2D child sits in the world and emits signals when
other areas or bodies enter it. For melee, you enable it during the active frames of the
attack and listen for area_entered.

extends Area2D # the sword's hitbox

@export var damage := 10

func _ready() -> void:
    monitoring = false
    area_entered.connect(_on_area_entered)

func start_swing() -> void:
    set_deferred("monitoring", true)

func end_swing() -> void:
    set_deferred("monitoring", false)

func _on_area_entered(area: Area2D) -> void:
    if area.has_method("take_hit"):
        area.take_hit(damage)

Strengths: it's visual (you size the shape in the editor), it tracks lingering hitboxes
for free (a fire patch, a spinning blade), and it plays nicely with collision layers.

The catch everyone hits eventually: Area2D results lag by one physics frame. Overlaps
are computed during the physics step, so if you turn monitoring on and immediately call
get_overlapping_areas() in the same frame, you get an empty array. For a 3-frame jab at
60 FPS, losing one frame is a third of your active window. That's the source of the
classic "my attack only hits sometimes" bug.

RayCast2D: a line, checked right now

A RayCast2D tests a single line from its origin to target_position. Its killer
feature for combat is force_raycast_update() — it queries the physics space
immediately, in the same frame.

@onready var ray: RayCast2D = $RayCast2D

func fire_hitscan(direction: Vector2, reach: float) -> void:
    ray.target_position = direction.normalized() * reach
    ray.collide_with_areas = true
    ray.force_raycast_update()
    if ray.is_colliding():
        var target := ray.get_collider()
        var point := ray.get_collision_point() # great for spawning a spark
        if target.has_method("take_hit"):
            target.take_hit(10)

Perfect for hitscan guns, lasers, line-of-sight checks and spear thrusts. Bad for a wide
sword arc: a line has no thickness, so a swing that visually clips an enemy's shoulder
will miss if the ray passes a pixel beside it. It also only returns the first
thing it hits — no piercing without extra work.

ShapeCast2D: a shape, swept and checked right now

ShapeCast2D (new in Godot 4) is the middle ground: it sweeps a real shape along
target_position and, like the ray, can be forced to update on the spot. Set
target_position to Vector2.ZERO and it becomes an instant "what overlaps this shape
right now" query.

@onready var cast: ShapeCast2D = $ShapeCast2D

func swing() -> void:
    cast.target_position = Vector2.ZERO # instant overlap, no sweep
    cast.collide_with_areas = true
    cast.force_shapecast_update()
    for i in cast.get_collision_count():
        var target := cast.get_collider(i)
        if target and target.has_method("take_hit"):
            target.take_hit(10)

It has thickness like an Area2D, answers in the same frame like a RayCast2D, and returns
multiple hits (capped by max_results). The trade-off: it's a one-shot query, not a
listener — nothing tells you when something walks into a lingering hitbox later.

The comparison

	Area2D	RayCast2D	ShapeCast2D
Shape	any, has area	a line	any, has area
When results are ready	next physics frame	same frame (forced)	same frame (forced)
Multiple targets	yes	first hit only	yes (`max_results`)
Lingering hitboxes	built in (signals)	no	no — you re-query
Collision point	no	yes	yes, per hit
Fast projectiles (tunneling)	can tunnel	sweeps, won't tunnel	sweeps, won't tunnel
Best for	hurtboxes, AoE zones, slow attacks	hitscan, lasers, LOS	instant melee, dashes, fast bullets

The rule that decides it

Ask two questions:

Does the hit need to land on the exact frame the button was pressed? Short jabs, parries and hitscan do. Use a forced RayCast2D (thin) or ShapeCast2D (wide).
Does the hitbox stay alive and keep hurting things that walk into it? Fire, spikes, a spinning blade, and — importantly — every character's hurtbox. That's Area2D.

Most shipped action games end up with both: Area2D hurtboxes on every character, and
the attack side checked with whatever fits the move. What they all need on top, no
matter which node detects the overlap, is the same boring layer: teams so enemies don't
hit each other, a per-swing "already hit" list so one slash doesn't deal damage five
frames in a row, i-frames, and knockback direction.

That layer is what Saltmire Hitbox is — a drop-in Hitbox2D / Hurtbox2D pair with teams,
per-swing hit tracking, i-frames and knockback already wired, so you pick the detection
style above and skip writing the bookkeeping for the third time.

If you'd rather drop this in than build it, Saltmire Hitbox does it as a ready-made tool: https://saltmire.itch.io/saltmire-hitbox

Originally published at https://saltmire.github.io/godot-4-area2d-vs-raycast-vs-shapecast.html

How to add a loading screen with a progress bar in Godot 4

saltmire — Sun, 20 Sep 2026 12:52:17 +0000

The default get_tree().change_scene_to_file() works fine for small scenes — but once
your scenes grow (packed tilemaps, many enemies, heavy resources), the player will see a
frozen frame before anything appears. The fix is threaded loading with a real progress bar.

How Godot 4 threaded loading works

Godot 4's ResourceLoader can load a scene in a background thread while your loading
screen stays interactive. There are three calls you need:

load_threaded_request(path) — queue the load; call once.
load_threaded_get_status(path, progress_array) — poll every frame; fills progress_array[0] with a 0.0–1.0 float.
load_threaded_get(path) — grab the finished PackedScene when status is THREAD_LOAD_LOADED.

Step 1: build the loading screen scene

Create a new scene with a CanvasLayer root (name it LoadingScreen) and add two
children: a ColorRect that fills the screen and a ProgressBar.

Set the ProgressBar:

Min Value: 0, Max Value: 100
Anchor it full-width near the bottom, or centered — your call.
Show Percentage: on or off, both are fine.

Attach this script to LoadingScreen:

extends CanvasLayer

@export var next_scene_path: String = ""

var _progress := []

func _ready() -> void:
    if next_scene_path.is_empty():
        push_error("LoadingScreen: next_scene_path is not set.")
        return
    ResourceLoader.load_threaded_request(next_scene_path)

func _process(_delta: float) -> void:
    if next_scene_path.is_empty():
        return
    var status := ResourceLoader.load_threaded_get_status(next_scene_path, _progress)
    if not _progress.is_empty():
        $ProgressBar.value = _progress[0] * 100.0
    match status:
        ResourceLoader.THREAD_LOAD_LOADED:
            var scene: PackedScene = ResourceLoader.load_threaded_get(next_scene_path)
            get_tree().change_scene_to_packed(scene)
        ResourceLoader.THREAD_LOAD_FAILED:
            push_error("LoadingScreen: failed to load " + next_scene_path)

Step 2: trigger it from any scene

Anywhere you would have called change_scene_to_file("res://levels/level_2.tscn"), do
this instead:

func _go_to_next_level() -> void:
    var loader: PackedScene = preload("res://ui/LoadingScreen.tscn")
    var screen := loader.instantiate()
    screen.next_scene_path = "res://levels/level_2.tscn"
    get_tree().root.add_child(screen)

The loading screen overlays the current scene, starts loading level_2.tscn in the
background, and swaps out once the load is done. The current scene never freezes.

Step 3: enforce a minimum display time

For small scenes, loading finishes in milliseconds and the progress bar flashes past.
A minimum display time of 0.5–1 second feels less jarring:

const MIN_SHOW_TIME := 0.6

var _elapsed := 0.0
var _loaded_scene: PackedScene = null

func _process(delta: float) -> void:
    _elapsed += delta
    if next_scene_path.is_empty():
        return
    var status := ResourceLoader.load_threaded_get_status(next_scene_path, _progress)
    if not _progress.is_empty():
        $ProgressBar.value = _progress[0] * 100.0
    if status == ResourceLoader.THREAD_LOAD_LOADED and _loaded_scene == null:
        _loaded_scene = ResourceLoader.load_threaded_get(next_scene_path)
    if _loaded_scene != null and _elapsed >= MIN_SHOW_TIME:
        get_tree().change_scene_to_packed(_loaded_scene)

The scene is grabbed as soon as it is ready, but the transition waits until the minimum
time has passed. The progress bar still fills to 100% immediately — only the switch is
delayed.

Step 4: add a fade-out before switching

change_scene_to_packed cuts instantly. To soften it, tween the CanvasLayer modulate
alpha to 0 before switching:

if _loaded_scene != null and _elapsed >= MIN_SHOW_TIME:
    var t := create_tween()
    t.tween_property(self, "modulate:a", 0.0, 0.3)
    await t.finished
    get_tree().change_scene_to_packed(_loaded_scene)

Keep the tween short (0.2–0.4 s). Anything longer kills pacing.

Common gotcha: duplicate load requests

If you call load_threaded_request on a path that is already being loaded (for example,
a player hits a trigger twice), Godot returns ERR_ALREADY_IN_USE. Add a guard so it
does not spam errors:

func _ready() -> void:
    var err := ResourceLoader.load_threaded_request(next_scene_path)
    if err != OK and err != ERR_ALREADY_IN_USE:
        push_error("load_threaded_request failed: " + str(err))

ERR_ALREADY_IN_USE means the load is already queued — load_threaded_get will still
return the resource when it finishes, so no action needed.

The finished loading screen

That is the whole setup: a CanvasLayer overlay, three ResourceLoader calls, an
optional minimum display time, and an optional fade-out. It works for any scene size.
If you want richer transitions on the way in or out — iris wipes, pixelate, dissolve,
or slides — Saltmire Transitions wraps those into a one-line call and handles the
scene-switch timing internally.

If you'd rather drop this in than build it, Saltmire Transitions does it as a ready-made tool: https://saltmire.itch.io/saltmire-transitions-scene-transition-kit-for-godot-4

Originally published at https://saltmire.github.io/godot-4-loading-screen-progress-bar.html

Godot 4 camera shake not working right? 4 causes and fixes

saltmire — Tue, 15 Sep 2026 14:57:36 +0000

You wire up a quick camera shake for hits, and something's off. Either it barely
registers, it snaps back the instant it starts, or — worst case — the camera stays
crooked long after the shake should have stopped. None of these are random. Here are
the four causes, ordered by how often they show up.

1. The shake writes to `position` instead of `offset`

Symptom. The shake fires — you can see the value change in the debugger — but
on screen the camera doesn't move, or barely twitches.

Cause. Most camera-follow code sets Camera2D.position (or
global_position) every frame to track the player: position = target.global_position.
If your shake also writes to position, whichever one runs last that frame wins.
Since follow logic usually runs every _process() tick right alongside your shake,
the follow call quietly overwrites the shake before the frame ever renders.

Fix. Never shake position — shake offset. It's a separate property Camera2D
gives you specifically so shake and follow don't collide:

# follow logic — untouched, keeps writing to position every frame
func _process(_delta: float) -> void:
    global_position = target.global_position

# shake — writes to offset instead, so it never fights the line above
func shake(amount: float, duration: float) -> void:
    var t := create_tween()
    var elapsed := 0.0
    while elapsed < duration:
        offset = Vector2(randf_range(-amount, amount), randf_range(-amount, amount))
        await get_tree().create_timer(0.02).timeout
        elapsed += 0.02
    offset = Vector2.ZERO

2. Overlapping shakes fight each other

Symptom. Rapid hits (a combo, a burst of bullets) make the camera snap and
stutter instead of shaking smoothly — it looks broken exactly when it should look
most intense.

Cause. Each shake() call above starts its own loop or tween writing to the
same offset. Trigger a second shake before the first finishes and now two timers
are both setting offset every frame — whichever one updates last on a given frame
wins, so the camera jumps between two unrelated random values instead of blending.

Fix. Track the strongest active shake instead of letting every call run its own
independent loop, and only ever start one shake process:

var _shake_strength := 0.0
var _shake_decay := 4.0  # per second

func add_shake(amount: float) -> void:
    _shake_strength = max(_shake_strength, amount)  # take the strongest hit, don't stack

func _process(delta: float) -> void:
    if _shake_strength > 0.01:
        offset = Vector2(randf_range(-1, 1), randf_range(-1, 1)) * _shake_strength
        _shake_strength = lerp(_shake_strength, 0.0, _shake_decay * delta)
    else:
        offset = Vector2.ZERO

Now three hits in a row just raise _shake_strength back up — one continuous decay
curve, no fighting timers.

3. `offset` never gets reset when the shake ends

Symptom. After the last hit of a fight, the camera stays permanently nudged
off-center — sometimes only noticeable because the player feels slightly
off-screen.

Cause. A Tween that shakes offset and gets interrupted (the node dies, the
scene changes, a queue_free() fires mid-tween) never reaches its own cleanup step,
so whatever random value it last wrote stays there forever.

Fix. Don't rely on the tween finishing naturally — reset explicitly in
_exit_tree(), and prefer the decay-based approach in cause #2, which always
converges back to Vector2.ZERO on its own instead of depending on a tween
completing:

func _exit_tree() -> void:
    offset = Vector2.ZERO

4. Shake decays at a fixed frame count, not a fixed time

Symptom. Shake feels right on your dev machine but too fast, too slow, or too
short on a player's monitor with a different refresh rate.

Cause. Loops like for i in range(10): offset = random(); await get_tree().process_frame
tie the shake's duration to frame count, not real time. At 60 FPS that's ~166ms; at
144 FPS it's ~69ms — the same code produces a visibly different shake depending on
the display.

Fix. Drive the decay off delta, as in cause #2's lerp(_shake_strength, 0.0, _shake_decay * delta) — the shake takes the same wall-clock time regardless of
frame rate, because delta shrinks to compensate on faster monitors.

What all four have in common

Every case comes down to the same thing: offset is a single shared value, and
shake logic that doesn't own it exclusively — through direct writes, competing
tweens, or frame-count timing — ends up fighting something else that also touches
the camera. Route shake through one decaying value, keep it separate from whatever
sets position, and reset it on exit.

If you'd rather skip writing (and re-debugging) this yourself, that's exactly what
Saltmire Impact wraps into a single call — shake, hit-stop, flash and damage
numbers combined into tunable combos that don't step on your own camera-follow code.

If you'd rather drop this in than build it, Saltmire Impact does it as a ready-made tool: https://saltmire.itch.io/saltmire-impact

Originally published at https://saltmire.github.io/godot-4-camera-shake-not-working.html

What I learned building an enemy state machine in Godot 4

saltmire — Fri, 04 Sep 2026 03:29:44 +0000

I wrote "just use a match statement, it's fine" three times before I stopped saying it. It
is fine, right up until an enemy needs a fourth state and two of the transitions start
depending on each other. Here is what actually cost time building enemy AI for a
wave-based game, in the order it bit me.

Lesson 1: the match statement is fine until state 4

A two-state enemy — chase, attack — is genuinely not worth a framework:

func _physics_process(delta: float) -> void:
    match state:
        State.CHASE:
            velocity = (player.global_position - global_position).normalized() * speed
            if global_position.distance_to(player.global_position) < attack_range:
                state = State.ATTACK
        State.ATTACK:
            attack_timer -= delta
            if attack_timer <= 0.0:
                do_attack()
                state = State.CHASE

The moment a third and fourth state show up — hurt, dead, stagger, windup — the match
block stops being one enemy's logic and becomes a grid of every state times every other
state it might transition to. That grid is where the bugs live, not in any single state.

Lesson 2: the bug is never inside a state, it's in the transition

Every state-machine bug I actually spent time on was the same shape: state A left some
flag or timer set that state C didn't know to check. An enemy stuck mid-attack-animation
forever, still receiving hits, was not a bug in the attack state — it was the hurt state
interrupting attack without cleaning up attack_timer or resetting the animation.

The fix that made these bugs findable is giving every state an explicit enter and
exit, and never mutating another state's data directly:

func change_state(new_state: State) -> void:
    if new_state == state:
        return
    _exit_state(state)
    state = new_state
    _enter_state(new_state)

func _exit_state(s: State) -> void:
    match s:
        State.ATTACK:
            attack_timer = 0.0
            sprite.stop()

func _enter_state(s: State) -> void:
    match s:
        State.HURT:
            velocity = Vector2.ZERO
            hurt_timer = HURT_DURATION
            sprite.play("hurt")

One entry point for every transition means you can put a single print in
change_state and see the entire life of an enemy in the log, instead of guessing which
of six scattered state = X lines fired.

Lesson 3: a Node-per-state is not overkill once you have more than one enemy type

I resisted the State-as-a-Node pattern for a long time — it felt like ceremony for
something a match statement already did. It earns its cost the moment you have more than
one enemy type sharing behavior: a ranged enemy and a melee enemy both need chase and
hurt, but attack is completely different.

class_name EnemyState
extends Node

func enter(_enemy: Node) -> void: pass
func exit(_enemy: Node) -> void: pass
func physics_update(_enemy: Node, _delta: float) -> void: pass

class_name ChaseState
extends EnemyState

func physics_update(enemy: Node, delta: float) -> void:
    enemy.velocity = enemy.direction_to_player() * enemy.speed
    if enemy.in_attack_range():
        enemy.state_machine.change_to("attack")

Now attack is swappable per enemy scene without touching chase or hurt at all. For
a single enemy type, this is genuinely more code than a match statement for no benefit —
the crossover point is real, not just taste.

Lesson 4: "dead" is a state too, and it needs to block every other transition

The bug that took longest to track down: an enemy could take lethal damage, enter
hurt, and the hurt-state's timer would flip it back to chase — bringing a corpse back
to life for one frame before queue_free() caught up. dead was handled as an
if health <= 0: queue_free() check scattered in three places instead of being a real
state in the machine.

func take_damage(amount: int) -> void:
    health -= amount
    if health <= 0:
        change_state(State.DEAD)   # one path in, nothing else can override it
        return
    change_state(State.HURT)

Once dead was a state like any other — with its own enter() that disables the
hitbox, stops physics, and plays the death animation before freeing — the flicker-back-
to-life bug had nowhere left to come from.

What I'd do differently starting over

Start with the match statement — it is not a mistake, it is correctly the cheapest thing
that works for two or three states. Move to per-state nodes only when a second enemy
type needs to reuse half the states, not before. And treat dead as a first-class
state from the start; bolting it on as a health check scattered across the codebase is
where the worst bugs hide.

None of this is really about state machines. It's about giving every transition exactly
one door in and one door out, so that when an enemy does something wrong, there is
exactly one function to put a breakpoint in.

If you'd rather drop this in than build it, Survivors Template does it as a ready-made tool: https://saltmire.itch.io/survivors-template-godot

Originally published at https://saltmire.github.io/godot-4-enemy-state-machine.html

What a survivors-like actually needs in Godot 4 — and what you can skip

saltmire — Fri, 04 Sep 2026 03:28:40 +0000

A survivors-like looks like the easiest genre to build. The player moves, the weapons
fire themselves, the enemies walk straight at you. You can have that on screen in a
weekend, and most people do.

Then it stalls. Not because the loop is hard, but because the five systems around
the loop are where the whole genre actually lives. Here is what each one has to do,
what it costs you, and the two things everybody builds that they did not need.

1. Waves have to be data, not code

The first version is always a Timer and a spawn_enemy() that gets an if added to
it every session. By hour ten it is a wall of conditionals nobody can tune.

The fix is not clever, it is just early: waves are a resource you edit, not a function
you extend.

class_name Wave
extends Resource

@export var enemy: PackedScene
@export var starts_at: float = 0.0     ## seconds into the run
@export var ends_at: float = 60.0
@export var per_second: float = 2.0
@export var hp_mult: float = 1.0

func _process(delta: float) -> void:
    _t += delta
    for wave in waves:
        if _t < wave.starts_at or _t > wave.ends_at:
            continue
        _budget[wave] = _budget.get(wave, 0.0) + wave.per_second * delta
        while _budget[wave] >= 1.0:
            _budget[wave] -= 1.0
            _spawn(wave)

The accumulator matters more than it looks. Spawning on a Timer ties your difficulty
curve to frame rate and to timer granularity; accumulating a float budget lets you say
"2.4 enemies per second" and actually get it.

Once waves are resources, balancing stops being programming. That is the whole point —
you will re-tune this a hundred times before release.

2. Enemy count is the thing that breaks first

The genre's entire fantasy is too many of them. That means the first wall you hit is
not AI, it is allocation: three hundred enemies spawning and dying every few seconds.

Two decisions carry almost all of it:

Pool the enemies and the bullets. Not because allocation is slow on average, but because the spike lands in one frame, exactly when the screen is busiest. I wrote the honest version of this trade-off in object pooling vs instantiate — including when pooling is a waste of your time.
Do not give each enemy a _process. Three hundred script callbacks per frame is real cost for behaviour that is "walk toward the player". Move them from one manager loop over a packed array of positions, and let the node be a dumb sprite.

3. The upgrade draft is the actual game

Movement is the verb, but the reason people replay is the level-up screen. Three cards,
one choice, a build that compounds. That system needs to be data from the first day,
because you are going to write eighty of these.

class_name Upgrade
extends Resource

@export var id: StringName
@export var title: String
@export var max_stacks: int = 5
@export var weight: float = 1.0
@export var requires: Array[StringName] = []   ## unlocks that must exist first

func draft(count: int = 3) -> Array[Upgrade]:
    var pool := all.filter(func(u): return _eligible(u))
    var picks: Array[Upgrade] = []
    var total := 0.0
    for u in pool:
        total += u.weight
    while picks.size() < count and not pool.is_empty():
        var roll := randf() * total
        for u in pool:
            roll -= u.weight
            if roll <= 0.0:
                picks.append(u)
                total -= u.weight
                pool.erase(u)
                break
    return picks

Weighted, filtered by what the player already owns, drawn without replacement. That is
the whole engine. Everything else is content you can write on a bad day.

4. Damage has to be honest

With hundreds of overlapping bodies, the bugs stop being visual and start being unfair:
a hit that lands twice in one swing, a hit that fires a damage number for a target that
was invincible, knockback that reads as a teleport.

The three rules that fix nearly all of it:

One hit per swing. A lingering hitbox must not drain a target every frame.
Invincibility frames on the receiver, not the attacker.
The hit event fires only when damage was actually taken. If the target was in i-frames, no number, no spark, no sound. Nothing is more confusing than feedback for a hit that did not happen.

If you are wiring this from scratch, the layer/mask half of it is covered in
hitbox and hurtbox the easy way.

5. Meta progression decides whether run two happens

This is the one everybody bolts on last. It is also the one that turns a demo into a
game, because it is the reason to press "again" after dying at minute nine.

It does not need to be big. Currency earned per run, a handful of permanent unlocks,
and a save file that survives a crash mid-run. What it does need is to exist before
you tune difficulty, because permanent upgrades change every balance number you already
set.

What you can skip

Pathfinding. Enemies walk at the player. A steering vector and a cheap separation push between neighbours looks better than A* here, and costs a fraction.
Per-enemy AI scripts. One state and a speed value covers ninety percent of the roster. Save the scripting for the three enemies that actually do something.

Build it or start from one

If you want to learn the genre, build it. All five systems above are honest work and
none of them is beyond a solo dev — that is why the write-up exists.

If you want to ship, the argument for starting from a template is that the five systems
above are the ones you would spend a month getting wrong first. The
Survivors Template is the
data-driven version of exactly this — waves, draft, pooling and meta progression already
wired, with the full source and a playable web demo so you can judge the feel before
paying anything.

The rest of the tools I use for the combat and feel layer are on the
tools page, most of them free and MIT.

If you'd rather drop this in than build it, Survivors Template does it as a ready-made tool: https://saltmire.itch.io/survivors-template-godot

Originally published at https://saltmire.github.io/godot-4-survivors-like-systems.html

RigidBody2D vs CharacterBody2D for knockback in Godot 4 — which and when

saltmire — Fri, 04 Sep 2026 03:28:35 +0000

Every combat game needs knockback, and every combat game asks the same question at
some point: should the thing that just got hit be a RigidBody2D, or should you fake
the shove on the CharacterBody2D you already have? Both work. They fail in different
ways, and picking the wrong one costs you a rewrite mid-project.

The CharacterBody2D approach: a velocity you decay

Most character controllers in Godot 4 are already CharacterBody2D, driven by
move_and_slide(). Knockback here means adding a temporary velocity on top of the
normal movement input and letting it bleed off over a few frames.

extends CharacterBody2D

var knockback := Vector2.ZERO
const KNOCKBACK_FRICTION := 900.0

func apply_knockback(direction: Vector2, force: float) -> void:
    knockback = direction.normalized() * force

func _physics_process(delta: float) -> void:
    var input_velocity := get_input_velocity() # your normal movement code

    knockback = knockback.move_toward(Vector2.ZERO, KNOCKBACK_FRICTION * delta)

    velocity = input_velocity + knockback
    move_and_slide()

This is cheap, deterministic, and stays inside move_and_slide()'s collision rules —
the body still slides along walls correctly while it's being pushed. The catch: it is
entirely your own simulation. There is no real physics response, so two bodies pushed
into each other don't interact, and the "weight" of a hit is whatever curve you hand-tune
into KNOCKBACK_FRICTION.

The RigidBody2D approach: apply_impulse and let physics do it

A RigidBody2D gives you a real physics body — mass, impulses, collision response
between bodies for free.

extends RigidBody2D

func apply_knockback(direction: Vector2, force: float) -> void:
    apply_impulse(direction.normalized() * force)

That's the whole function. The physics engine handles the deceleration (via
linear_damp), the collisions with other rigid bodies, and bodies piling into each
other look and feel physical because they are physical. The catch: RigidBody2D
doesn't give you move_and_slide()-style character control. If your enemy or player
also needs precise, responsive movement input, you're now fighting the physics engine
for control of the same body, and that fight usually shows up as jitter against walls
or a character that "floats" a frame after landing.

The comparison

	CharacterBody2D (faked)	RigidBody2D (real)
Setup cost	one velocity field + `move_toward`	`apply_impulse` and done
Feel	fully tunable, but hand-rolled	physically consistent, less tunable
Body-to-body interaction	none — you'd have to script it	free, physics engine handles it
Movement input while knocked back	trivial to blend	fights the physics solver
Determinism	yes	mostly, minor solver variance
Good for	player character, most enemies	ragdolls, debris, crowds, destructibles

The hybrid most shipped games actually use

The honest answer is that neither option alone covers a whole game. The pattern that
holds up: keep your player and most enemies on CharacterBody2D with faked knockback,
because you need tight control over their movement every single frame. Switch to
RigidBody2D only for things that are allowed to lose control entirely — a dead
enemy's ragdoll, a barrel that goes flying, loose debris in a destructible wall.

A trick that gets you most of the RigidBody feel without giving up control: keep the
CharacterBody2D, but scale the knockback force by the target's own "weight" stat and
add a short window where player input is ignored so the hit actually reads:

var knockback_lock_timer := 0.0

func apply_knockback(direction: Vector2, force: float, weight: float = 1.0) -> void:
    knockback = direction.normalized() * (force / max(weight, 0.1))
    knockback_lock_timer = 0.12  # player input ignored for ~2 hit-stop frames

func _physics_process(delta: float) -> void:
    knockback_lock_timer = max(knockback_lock_timer - delta, 0.0)
    var input_velocity := Vector2.ZERO if knockback_lock_timer > 0.0 else get_input_velocity()

    knockback = knockback.move_toward(Vector2.ZERO, KNOCKBACK_FRICTION * delta)
    velocity = input_velocity + knockback
    move_and_slide()

That weight parameter is the part people skip and then wonder why every enemy flies
the same distance regardless of size.

The number that actually decides it

If the object needs to respond to player input on the same frame it's simulating physics,
it's a CharacterBody2D with faked knockback — no exceptions, because fighting the
physics solver for input responsiveness is a losing, ongoing cost. If the object never
takes player input again after the hit (a corpse, debris, a thrown prop), it's a
RigidBody2D and you get the physics for free.

Wiring this up by hand means a direction, a force, a weight, teams so you don't
knock back your own allies, and i-frames so one hit doesn't chain into five — all before
you've written a single line of actual combat design. Saltmire Hitbox ships that whole
layer as a drop-in Hitbox2D / Hurtbox2D pair, knockback included, so the comparison
above is a five-minute decision instead of a rewrite.

If you'd rather drop this in than build it, Saltmire Hitbox does it as a ready-made tool: https://saltmire.itch.io/saltmire-hitbox

Originally published at https://saltmire.github.io/godot-4-knockback-rigidbody-vs-characterbody.html

Godot 4 'signal already connected' — why it happens and how to fix it

saltmire — Tue, 18 Aug 2026 13:25:56 +0000

Your game is running, something triggers, and Godot prints a wall of red to the Output
panel:

E 0:00:01.887  _ready(): Signal 'area_entered' is already connected to a callable 'Enemy._on_hit'.

The signal usually still fires — but now every connected callback runs twice, so you get
double damage, duplicate score increments, and bugs that only appear after a few game
cycles. Here are the four causes, ordered by how often they bite.

1. `connect()` is called in `_ready()` and the node is freed and reinstantiated

Symptom. The first run works fine. After the player dies and the scene reloads, the
error appears on the second play-through.

Cause. When a node is freed and a new instance enters the tree, _ready() runs again.
If you connected a signal to a long-lived object — an autoload, the HUD, a game manager
— that object still holds the connection from the previous instance. A second connect()
stacks a second listener on top.

Fix. Guard with is_connected() or disconnect explicitly in _exit_tree():

func _ready() -> void:
    if not hitbox.area_entered.is_connected(_on_hit):
        hitbox.area_entered.connect(_on_hit)

func _exit_tree() -> void:
    if hitbox.area_entered.is_connected(_on_hit):
        hitbox.area_entered.disconnect(_on_hit)

If the connection should only fire once (a pickup, a trigger zone), use the
CONNECT_ONE_SHOT flag instead — Godot disconnects it automatically after one fire:

zone.body_entered.connect(_on_player_enter, CONNECT_ONE_SHOT)

2. `connect()` is called inside a loop or a function that runs every frame

Symptom. The error prints once per frame (or once per loop iteration), and the
callback runs n times more than expected.

Cause. Putting connect() inside _process(), _physics_process(), or a for loop
that iterates over live nodes calls it on every tick or every element. Godot allows
duplicate connections by default; each call stacks another listener.

Fix. Move connect() to _ready() or _enter_tree() — run it once, not repeatedly:

# WRONG — connects every physics frame:
func _physics_process(_delta: float) -> void:
    for area in get_overlapping_areas():
        area.damaged.connect(_take_damage)

# RIGHT — connects once when the node is ready:
func _ready() -> void:
    for child in get_children():
        if child.has_signal("damaged"):
            child.damaged.connect(_take_damage)

3. Multiple instances all connect to the same shared target

Symptom. One enemy works correctly. Spawn three enemies and every hit triggers the
callback three times — or three times on each of the three enemies.

Cause. Each instance calls connect() on the same shared node (an autoload or a
global HUD). Three instances × one connect() each = three listeners. When the signal
fires, all three run.

Fix. Connect signals to self (the instance that owns them), not to a shared target:

# each Enemy connects its own hitbox to its own method — no collision:
func _ready() -> void:
    hitbox.area_entered.connect(_on_hit)

func _on_hit(area: Area2D) -> void:
    take_damage(area.damage)

If you need a central listener, let the manager register instances and call their methods
directly instead of stacking signal connections:

# GameManager.gd
var enemies: Array[Enemy] = []

func register(e: Enemy) -> void:
    enemies.append(e)
    # no connect() here — call e.take_damage() directly when needed

4. Using `disconnect()` with the wrong callable reference

Symptom. You call disconnect() before connect() to get a clean slate, but the
error still appears. Or disconnect() prints "Signal not connected" even though you just
connected it.

Cause. In Godot 4, a Callable is matched by both the bound object and the method
name. A new lambda is a different Callable object even if the body is identical —
disconnect() can't find it and does nothing, leaving the old listener in place.

# WRONG — two different Callable objects; disconnect() fails silently:
signal.connect(func(): _handle_hit())
signal.disconnect(func(): _handle_hit())  # not found — old listener stays

Fix. Store the callable in a variable and reuse the same reference for both calls:

var _hit_callable: Callable

func _ready() -> void:
    _hit_callable = _on_hit          # store the bound method
    hitbox.area_entered.connect(_hit_callable)

func _exit_tree() -> void:
    if hitbox.area_entered.is_connected(_hit_callable):
        hitbox.area_entered.disconnect(_hit_callable)

Named methods (_on_hit, not lambdas) are the safest choice for connections you need
to remove later.

What all four have in common

Every case is the same root problem: connect() was called more than once for the same
(signal, callable) pair. Godot 4 doesn't deduplicate connections by default — each extra
call adds another listener, and every listener fires when the signal emits.

The safe pattern is always: connect once in _ready() or _enter_tree(), disconnect
explicitly in _exit_tree(), and guard with is_connected() when the timing is
uncertain. If you'd rather skip wiring Area2D signals for combat altogether — and
avoid this entire class of bug — that's what Saltmire Hitbox handles internally:
Hitbox2D manages its own connections and tears them down automatically when the node
leaves the tree.

If you'd rather drop this in than build it, Saltmire Hitbox does it as a ready-made tool: https://saltmire.itch.io/saltmire-hitbox

Originally published at https://saltmire.github.io/godot-4-signal-already-connected.html

5 Godot 4 sprite shader effects you can build in one script

saltmire — Sun, 16 Aug 2026 14:38:25 +0000

A Sprite2D with a flat texture reads as static. A Sprite2D that can dissolve,
outline, flash, freeze, or glow reads as alive. All five of those are small
canvas_item shaders — no particles, no extra nodes, just a ShaderMaterial and a
uniform you drive from a Tween. Here are five you can paste in today.

1. Dissolve

A noise texture decides, pixel by pixel, which parts of the sprite disappear first.
Tween threshold from 0 to 1 and the sprite erodes away instead of just fading:

// dissolve.gdshader
shader_type canvas_item;
uniform float threshold : hint_range(0.0, 1.0) = 0.0;
uniform sampler2D noise : hint_default_white;

void fragment() {
    vec4 c = texture(TEXTURE, UV);
    float n = texture(noise, UV).r;
    if (n < threshold) { discard; }
    COLOR = c;
}

func dissolve(sprite: CanvasItem, duration := 0.6) -> void:
    var mat: ShaderMaterial = sprite.material
    create_tween().tween_method(
        func(v): mat.set_shader_parameter("threshold", v), 0.0, 1.0, duration)

Any seamless grayscale noise texture works for noise — a cheap Perlin or Worley
texture gives you a very different silhouette than plain static.

2. Outline

Sample the alpha channel a few pixels in each direction; if the center pixel is
transparent but a neighbor isn't, that pixel is edge:

// outline.gdshader
shader_type canvas_item;
uniform vec4 outline_color : source_color = vec4(1.0, 1.0, 1.0, 1.0);
uniform float width : hint_range(0.0, 4.0) = 1.0;

void fragment() {
    vec4 c = texture(TEXTURE, UV);
    vec2 px = width / vec2(textureSize(TEXTURE, 0));
    float a = texture(TEXTURE, UV + vec2(px.x, 0)).a
            + texture(TEXTURE, UV - vec2(px.x, 0)).a
            + texture(TEXTURE, UV + vec2(0, px.y)).a
            + texture(TEXTURE, UV - vec2(0, px.y)).a;
    if (c.a < 0.1 && a > 0.0) {
        COLOR = outline_color;
    } else {
        COLOR = c;
    }
}

Toggle it from GDScript for a "targetable" or "selected" state:

func set_outlined(sprite: CanvasItem, on: bool) -> void:
    (sprite.material as ShaderMaterial).set_shader_parameter("width", 1.0 if on else 0.0)

Works on any sprite with transparent padding — no separate outline sprite to keep in
sync.

3. Hit-flash

The fastest way to sell a hit: slam the sprite to solid white for a frame, then let
it fade back. One uniform, one mix:

// flash.gdshader
shader_type canvas_item;
uniform float amount : hint_range(0.0, 1.0) = 0.0;

void fragment() {
    vec4 c = texture(TEXTURE, UV);
    COLOR = vec4(mix(c.rgb, vec3(1.0), amount), c.a);
}

func flash(sprite: CanvasItem, duration := 0.12) -> void:
    var mat: ShaderMaterial = sprite.material
    mat.set_shader_parameter("amount", 1.0)
    create_tween().tween_method(
        func(v): mat.set_shader_parameter("amount", v), 1.0, 0.0, duration)

Fire this on every take_damage() call and hits instantly feel like they landed,
even before a damage number or knockback shows up.

4. Freeze (grayscale + tint)

Desaturate the sprite and push it toward a cold blue — reads as "frozen" or
"stunned" without swapping a single texture:

// freeze.gdshader
shader_type canvas_item;
uniform float amount : hint_range(0.0, 1.0) = 0.0;
uniform vec4 tint : source_color = vec4(0.6, 0.8, 1.0, 1.0);

void fragment() {
    vec4 c = texture(TEXTURE, UV);
    float gray = dot(c.rgb, vec3(0.299, 0.587, 0.114));
    vec3 frozen = mix(vec3(gray), tint.rgb, 0.5);
    COLOR = vec4(mix(c.rgb, frozen, amount), c.a);
}

func set_frozen(sprite: CanvasItem, frozen: bool, duration := 0.2) -> void:
    var mat: ShaderMaterial = sprite.material
    create_tween().tween_method(
        func(v): mat.set_shader_parameter("amount", v),
        mat.get_shader_parameter("amount"), 1.0 if frozen else 0.0, duration)

Pair it with Engine.time_scale on that one enemy (via a per-node "local slow"
trick, since time_scale is global) and the freeze reads as more than cosmetic.

5. Hologram

Horizontal scanlines plus a fresnel-style rim glow, both driven by TIME, turns a
flat sprite into a sci-fi projection:

// hologram.gdshader
shader_type canvas_item;
uniform vec4 glow_color : source_color = vec4(0.3, 0.9, 1.0, 1.0);
uniform float scan_speed : hint_range(0.0, 10.0) = 3.0;

void fragment() {
    vec4 c = texture(TEXTURE, UV);
    float scan = sin((UV.y * 40.0) - TIME * scan_speed) * 0.5 + 0.5;
    float rim = pow(1.0 - abs(UV.x - 0.5) * 2.0, 3.0);
    vec3 col = mix(c.rgb, glow_color.rgb, 0.4 + rim * 0.3);
    COLOR = vec4(col, c.a * (0.7 + scan * 0.3));
}

No GDScript needed to drive this one — TIME animates it for free once the
material is assigned. Just set glow_color per-sprite if you want factions or
rarities to glow differently.

Wiring five shaders without five headaches

Individually each of these is one small .gdshader file and a couple of uniforms.
The part that actually eats time is the plumbing: giving every sprite its own
ShaderMaterial instance (share one and every dissolve syncs together, which is
almost never what you want), keeping amount/threshold tweens from fighting
each other when two effects fire on the same frame, and remembering which uniform
name goes with which shader across a whole project. That bookkeeping is exactly
what Saltmire FX collapses into a one-line call per effect.

If you'd rather drop this in than build it, Saltmire FX does it as a ready-made tool: https://saltmire.itch.io/saltmire-fx

Originally published at https://saltmire.github.io/godot-4-sprite-shader-effects.html

How to add motion trails and afterimages in Godot 4

saltmire — Thu, 13 Aug 2026 14:05:06 +0000

Motion trails — those fading ghost copies left behind a dashing character — are one
of the quickest wins for game feel. They make speed readable without any physics
changes. Here's how to build one from scratch in Godot 4, then tips for turning it
into a reusable component.

How it works

The idea is simple: every N milliseconds, take a snapshot of the character's current
sprite frame and position, then fade that snapshot out. Stack several snapshots and
you get a trail. No physics, no shaders required to start.

Step 1: the ghost scene

Create a new scene with a Sprite2D root. Name it TrailGhost. Give it this script:

class_name TrailGhost extends Sprite2D

func play(tex: Texture2D, region: Rect2, use_region: bool,
          at: Vector2, flipped_h: bool, alpha_start := 0.7,
          duration := 0.25) -> void:
    texture = tex
    region_rect = region
    region_enabled = use_region
    global_position = at
    flip_h = flipped_h
    modulate.a = alpha_start
    var t := create_tween()
    t.tween_property(self, "modulate:a", 0.0, duration) \
        .set_trans(Tween.TRANS_QUAD).set_ease(Tween.EASE_IN)
    t.tween_callback(queue_free)

This ghost reads the source sprite's current frame data, drops itself at the right
world position, and auto-destroys after fading. The region_rect copy is what makes
the snapshot land on the correct animation frame rather than the whole spritesheet.

Step 2: the trail emitter

In your character scene, add a child Node2D called Trail. Give it this script,
and export a reference to the character's AnimatedSprite2D (or Sprite2D):

extends Node2D

@export var ghost_scene: PackedScene
@export var source: AnimatedSprite2D
@export var interval := 0.04          # seconds between ghosts
@export var ghost_duration := 0.25
@export var alpha_start := 0.65

var _timer := 0.0
var _active := false

func activate() -> void:  _active = true
func deactivate() -> void: _active = false

func _process(delta: float) -> void:
    if not _active:
        return
    _timer += delta
    if _timer < interval:
        return
    _timer = 0.0
    _spawn_ghost()

func _spawn_ghost() -> void:
    if not source or not ghost_scene:
        return
    var g: TrailGhost = ghost_scene.instantiate()
    get_tree().current_scene.add_child(g)   # world-space, not parented to character
    var frames := source.sprite_frames
    var anim := source.animation
    var frame_idx := source.frame
    var tex := frames.get_frame_texture(anim, frame_idx)
    g.play(tex, Rect2(), false,
           source.global_position, source.flip_h,
           alpha_start, ghost_duration)

Adding the ghost to the scene root instead of the character means it stays at the
right world position even when the character moves. If you parent it to the character,
it follows along and the trail collapses.

Step 3: wire it to a dash

Call activate() and deactivate() around any movement where you want a trail.
A typical dash looks like this in the character script:

func _dash() -> void:
    $Trail.activate()
    var t := create_tween()
    t.tween_property(self, "velocity", dash_dir * dash_speed, 0.0)
    await get_tree().create_timer(dash_duration).timeout
    $Trail.deactivate()

For continuous speed-based trails (racing games, bullet hell), you can skip the
manual toggle and drive it from speed instead:

func _process(delta: float) -> void:
    var spd := velocity.length()
    if spd > trail_threshold:
        $Trail.activate()
    else:
        $Trail.deactivate()

Step 4: make it look good

A few small tweaks make a big difference:

Interval vs duration ratio — if interval is close to ghost_duration, ghosts
are sparse and the trail feels dotted. For a solid streak, keep interval at roughly
one-sixth of ghost_duration (e.g. 0.04s / 0.25s).

Tint the ghosts — multiply modulate by a color before calling play(). Cyan
works well for ice dashes; orange for fire. Set it on the Trail node as an export:

@export var tint := Color.WHITE

# inside _spawn_ghost(), after g.play():
g.modulate *= tint

Z-index — give TrailGhost a lower z_index than the character (e.g. -1) so
the trail sits behind the sprite, not on top of it.

Layer trails on AnimatedSprite2D frames — if your character uses a packed
spritesheet with region_enabled = true, read texture_region_rect instead of
region_rect and set region_enabled = true on the ghost. The script above leaves
a Rect2() placeholder — swap it for source.get_rect() if your frames are
packed that way.

When to pool

queue_free is fine for short dashes where you spawn 5–10 ghosts per dash. Once
you're emitting dozens per second — flying enemies, bullet patterns — the alloc
pressure adds up. A small pool (pre-spawn 20 ghosts, hide/show rather than
instantiate/free) keeps the frame time flat. The same pooling pattern from the
damage-numbers post applies directly here.

The finished trail

That's the core: a self-destructing ghost scene, a timer-driven emitter, and an
on/off signal tied to your movement logic. Tweak interval, duration, and tint per
ability and you get a different personality for every dash in the game. If you'd
rather drop in a single addon with pooling, color modes, and a one-call API already
wired up, that's exactly what Saltmire Trail handles.

If you'd rather drop this in than build it, Saltmire Trail does it as a ready-made tool: https://saltmire.itch.io/saltmire-trail

Originally published at https://saltmire.github.io/godot-4-motion-trail-afterimage.html

What I learned building a save-slot menu in Godot 4

saltmire — Mon, 10 Aug 2026 14:20:17 +0000

I built save/load for a project three separate times before I admitted the real work was
never the file I/O. It was the menu. Here is what actually cost time, in the order it bit me.

Lesson 1: "one save file" always becomes "N save slots"

Every prototype starts with user://save.dat and a single Continue button. Then a
playtester asks "can I have two characters going at once?" and the whole save layer has
to grow a slot number it was never designed to carry.

Design the path with a slot from day one, even if you ship with one slot:

func slot_path(slot: int) -> String:
    return "user://save_slot_%d.json" % slot

Retrofitting this later means migrating existing players' saves, which is lesson 4.

Lesson 2: the menu needs data the save file doesn't have yet

A save-slot screen wants to show a thumbnail, a play-time, a location name, and a
timestamp — none of which live naturally inside your gameplay save data. I kept trying to
derive them from the save file at load time, which meant loading every slot just to draw
the menu. Slow, and it loads slots the player never picks.

The fix is a tiny separate metadata blob written alongside the save, cheap to read for
every slot up front:

func write_meta(slot: int, area_name: String, play_seconds: float) -> void:
    var meta := {
        "area": area_name,
        "play_seconds": play_seconds,
        "saved_at": Time.get_datetime_string_from_system(),
        "thumb": "user://save_slot_%d.png" % slot,
    }
    var f := FileAccess.open("user://save_slot_%d.meta.json" % slot, FileAccess.WRITE)
    f.store_string(JSON.stringify(meta))

The menu reads N small .meta.json files, not N full save files. Loading the actual slot
only happens once the player commits to it.

Lesson 3: the thumbnail is a viewport capture, and timing matters

Grabbing a screenshot for the slot thumbnail is one call, but calling it at the wrong
moment gives you a black square or a half-drawn frame:

func save_thumbnail(slot: int) -> void:
    await RenderingServer.frame_post_draw
    var img := get_viewport().get_texture().get_image()
    img.resize(320, 180)
    img.save_png("user://save_slot_%d.png" % slot)

Awaiting frame_post_draw instead of just calling it inline was the difference between a
usable thumbnail and a black one — the viewport texture isn't guaranteed populated on the
same frame you request the save.

Lesson 4: "new game" and "continue" are the same button, and that's the bug

I originally wired an empty slot to "New Game" and a filled slot to "Continue" as two
different UI states. That is correct until a slot's save file gets corrupted — then the
slot has data but nothing loads, and the player is stuck on a menu that offers no way
forward. Every slot needs a fallback path from "load failed" back to "start over in this
slot," not just a happy path:

func open_slot(slot: int) -> void:
    var result := SaveGame.load_slot(slot)
    if result.ok:
        start_game(result.data)
    elif FileAccess.file_exists(slot_path(slot)):
        show_corrupt_slot_dialog(slot)   # offer: retry, restore backup, or overwrite
    else:
        start_new_game(slot)

This is the one lesson I'd tell past-me to learn first — a corrupt slot isn't an edge
case, it's a guarantee over a long enough playtest, and the menu is the only place a
player can recover from it.

Lesson 5: deleting a slot needs a confirm, and needs to actually delete the metadata too

Obvious in hindsight, but I shipped a build where "delete slot" removed the save file and
left the .meta.json and .png behind — so the empty slot still rendered a thumbnail and
a play-time from the deleted run. Delete is three files, not one, or the slot lies to the
player.

What I'd do differently starting over

Build the slot number and the metadata sidecar file on day one, even for a single-slot
game — it costs nothing early and it is the exact thing that's expensive to retrofit.
Treat "load failed" as a menu state you design for, not an exception you catch. And test
delete by actually looking at the file list after, not just the menu.

The mechanics of reading and writing JSON to user:// are the easy 20% of "add saving" to
a game. The slot menu, the corrupt-file recovery, and the thumbnail timing are the other
80%, and none of it is specific to any one game — which is exactly the kind of thing worth
not re-solving from scratch every project.

If you'd rather drop this in than build it, Saltmire Save does it as a ready-made tool: https://saltmire.itch.io/saltmire-save

Originally published at https://saltmire.github.io/godot-4-save-slot-menu.html

DEV Community: saltmire

Godot 4 change_scene_to_file not working? 4 causes and fixes

1. Code after the call runs on a scene that's already gone

2. "Can't change this state while flushing queries"

3. The path breaks after a rename — or only in the exported build

4. The change fires twice

What all four have in common

What I learned building a health component with i-frames in Godot 4

Lesson 1: health is not the player's job

Lesson 2: the health bar should never ask for health

Lesson 3: the double-hit bug is what i-frames actually fix

Lesson 4: "died" must fire exactly once

Lesson 5: flash the sprite from the owner, not the component

What I'd do differently starting over

Area2D vs RayCast2D vs ShapeCast2D for melee attacks in Godot 4 — which and when

Area2D: an overlap you listen to

RayCast2D: a line, checked right now

ShapeCast2D: a shape, swept and checked right now

The comparison

The rule that decides it

How to add a loading screen with a progress bar in Godot 4

How Godot 4 threaded loading works

Step 1: build the loading screen scene

Step 2: trigger it from any scene

Step 3: enforce a minimum display time

Step 4: add a fade-out before switching

Common gotcha: duplicate load requests

The finished loading screen

Godot 4 camera shake not working right? 4 causes and fixes

1. The shake writes to position instead of offset

2. Overlapping shakes fight each other

3. offset never gets reset when the shake ends

4. Shake decays at a fixed frame count, not a fixed time

What all four have in common

What I learned building an enemy state machine in Godot 4

Lesson 1: the match statement is fine until state 4

Lesson 2: the bug is never inside a state, it's in the transition

Lesson 3: a Node-per-state is not overkill once you have more than one enemy type

Lesson 4: "dead" is a state too, and it needs to block every other transition

What I'd do differently starting over

What a survivors-like actually needs in Godot 4 — and what you can skip

1. Waves have to be data, not code

2. Enemy count is the thing that breaks first

3. The upgrade draft is the actual game

4. Damage has to be honest

5. Meta progression decides whether run two happens

What you can skip

Build it or start from one

RigidBody2D vs CharacterBody2D for knockback in Godot 4 — which and when

The CharacterBody2D approach: a velocity you decay

The RigidBody2D approach: apply_impulse and let physics do it

The comparison

The hybrid most shipped games actually use

The number that actually decides it

Godot 4 'signal already connected' — why it happens and how to fix it

1. connect() is called in _ready() and the node is freed and reinstantiated

2. connect() is called inside a loop or a function that runs every frame

3. Multiple instances all connect to the same shared target

4. Using disconnect() with the wrong callable reference

What all four have in common

5 Godot 4 sprite shader effects you can build in one script

1. Dissolve

2. Outline

3. Hit-flash

4. Freeze (grayscale + tint)

5. Hologram

Wiring five shaders without five headaches

How to add motion trails and afterimages in Godot 4

How it works

Step 1: the ghost scene

Step 2: the trail emitter

Step 3: wire it to a dash

Step 4: make it look good

When to pool

The finished trail

What I learned building a save-slot menu in Godot 4

Lesson 1: "one save file" always becomes "N save slots"

Lesson 2: the menu needs data the save file doesn't have yet

Lesson 3: the thumbnail is a viewport capture, and timing matters

Lesson 4: "new game" and "continue" are the same button, and that's the bug

1. The shake writes to `position` instead of `offset`

3. `offset` never gets reset when the shake ends

1. `connect()` is called in `_ready()` and the node is freed and reinstantiated

2. `connect()` is called inside a loop or a function that runs every frame

4. Using `disconnect()` with the wrong callable reference