DEV Community: saltmire

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

Godot 4 GPUParticles2D not showing? 5 reasons your particles aren't appearing

saltmire — Mon, 03 Aug 2026 01:52:13 +0000

You added a GPUParticles2D, pressed Play, and the node is there in the tree — but
zero particles appear. No error. Just silence. This is one of Godot 4's quietest
failure modes because the engine never warns you when a particle system can't show
anything. Work through these five causes in order; one of them is almost certainly it.

1. No process material assigned

Symptom. Node is in the tree, the inspector shows Process Material: [empty], no
particles appear even though emitting = true.

Cause. GPUParticles2D without a ParticleProcessMaterial emits nothing and
gives no error. It's easy to forget when you duplicate an existing node, detach the
resource, or instantiate the node in code.

Fix. Always assign a material, even a default one:

var particles := GPUParticles2D.new()
var mat := ParticleProcessMaterial.new()
mat.emission_shape = ParticleProcessMaterial.EMISSION_SHAPE_POINT
mat.initial_velocity_min = 50.0
mat.initial_velocity_max = 100.0
particles.process_material = mat
add_child(particles)

If you're doing it in the editor, select the node, click the Process Material
property in the Inspector, and pick New ParticleProcessMaterial.

2. `emitting` is false

Symptom. Particles existed in a previous scene, you reset or duplicated the node,
and now nothing comes out.

Cause. emitting defaults to true in a fresh node, but gets serialized on save.
Resetting the scene, calling queue_free() and re-instantiating, or setting it false
in an animation player and never restoring it will silence the emitter with no
feedback.

Fix. If you're spawning a burst in code, make sure you set emitting = true after
any other property setup:

func burst(pos: Vector2) -> void:
    var p: GPUParticles2D = BURST_SCENE.instantiate()
    p.position = pos
    p.emitting = true   # must be explicit — don't rely on the saved default
    add_child(p)

And after a one_shot burst completes, emitting is automatically set back to
false by the engine — this is correct behavior, not a bug. To replay the effect,
call restart():

particles.one_shot = true
particles.restart()   # resets the timer and starts emitting again

3. Visibility rect too small (particles culled)

Symptom. Particles appear in the editor's 2D viewport but disappear at runtime,
or only show near the center of the screen.

Cause. Godot 4 frustum-culls GPUParticles2D using the node's
visibility_rect. The default is a tiny Rect2(-100, -100, 200, 200). If particles
travel outside that rect — especially for large explosions, projectile trails, or
slow heavy particles — they vanish the moment the computed position leaves the box.

Fix. Fit the rect to your actual spread. You can ask Godot to estimate it for you:
in the editor, select the node while it's emitting and press the Visibility Rect
button in the toolbar to auto-calculate. In code, size it conservatively:

# a symmetric 512×512 box centred on the emitter — adjust to fit your spread:
particles.visibility_rect = Rect2(-256, -256, 512, 512)

For very dynamic effects that change size at runtime, set it once to the maximum
possible extent and leave it; the cost of a slightly oversized rect is negligible.

4. `lifetime` or `amount` are too small to see

Symptom. A particle or two flickers for a frame and disappears.

Cause. The engine allocates exactly amount particles and recycles them as they
die. If lifetime is 0.1 and amount is 4, you get four particles that live for
a tenth of a second and that's it. At 60 fps they're visible for ~6 frames — fast
enough to read as a flicker or not register at all.

Fix. For a hit burst you actually want to see: amount of at least 8–12, and
lifetime of 0.4–0.8 seconds. If it still looks sparse, also check amount_ratio —
it scales the actual emission count between 0 and 1 and defaults to 1.0, but can be
set to 0 by an animation.

particles.amount = 12
particles.lifetime = 0.5
particles.amount_ratio = 1.0  # full count; check this if amount looks right but few spawn

5. The `one_shot` trap — particles fire once at scene load and stop

Symptom. The burst works exactly once (at startup), then never again.

Cause. one_shot = true + emitting = true on scene load means the system fires
immediately and marks itself done. The next time your code calls emitting = true on
an already-exhausted one-shot system, nothing happens.

Fix. Start one_shot emitters with emitting = false and use restart() to fire
them on demand. This guarantees a clean run each time:

@onready var particles := $HitParticles  # one_shot = true in the inspector

func play_hit() -> void:
    particles.restart()   # safe to call even if already running — resets and re-emits

restart() is the canonical way to trigger a one_shot effect from code; it also
resets the randomization seed, so each burst looks fresh.

What all five have in common

Every one of these is a silent no-op: the node exists, no error is thrown, and you
get nothing. The engine provides no warning when a particle system can't render, which
is what makes these bugs hard to notice. If you want guaranteed visible bursts without
wiring GPUParticles2D from scratch — process material, lifetime, amount, visibility
rect and all — that's exactly what Saltmire Spark does with a single call.

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

Originally published at https://saltmire.github.io/godot-4-particles-not-showing.html

Object pooling vs instantiate in Godot 4 — when it actually matters

saltmire — Fri, 31 Jul 2026 03:35:02 +0000

"Just pool everything" is the most repeated performance advice in gamedev, and it is
wrong about half the time. Pooling buys you predictable frame time, and it costs you
code you have to keep correct forever. Here is the honest comparison — what each option
really does in Godot 4, and the number that tells you which one you need.

What `instantiate()` actually costs

Every PackedScene.instantiate() allocates the node tree, resolves the script, and
registers the node with the scene tree on add_child(). Then, when you queue_free(),
the node is destroyed at the end of the frame.

For a handful of nodes this is nothing. The problem is not the average — it is the
spike. Spawn forty enemies in one frame and that whole cost lands inside a single
_process, which is exactly the moment the player is already looking at a busy screen.

# Fine for a door, a pickup, a boss.
var bullet := BULLET.instantiate()
bullet.global_position = muzzle.global_position
add_child(bullet)

What pooling actually costs

A pool trades allocation for bookkeeping: you create N objects up front, hand them out,
and take them back. Frame time gets flat and boring — which is the whole point.

extends Node
## Minimal pool. Pre-warms N instances, hands them out, takes them back.
const SIZE := 128

var _scene : PackedScene = preload("res://scenes/Bullet.tscn")
var _free  : Array[Node] = []

func _ready() -> void:
    for i in SIZE:
        var n := _scene.instantiate()
        n.set_process(false)
        n.set_physics_process(false)
        n.hide()
        add_child(n)
        _free.append(n)

func take() -> Node:
    # Empty pool = fall back to a real instance. Never return null: a silent
    # missing bullet is far harder to debug than one extra allocation.
    var n : Node = _free.pop_back() if not _free.is_empty() else _scene.instantiate()
    if n.get_parent() == null:
        add_child(n)
    n.show()
    n.set_process(true)
    n.set_physics_process(true)
    return n

func give_back(n: Node) -> void:
    if n == null or not is_instance_valid(n):
        return
    n.hide()
    n.set_process(false)
    n.set_physics_process(false)
    _free.append(n)

The catch nobody mentions: a pooled object is never fresh. It keeps whatever state
the last user left on it — velocity, timers, tween references, connected signals. That
is where pooling bugs come from, and they are nasty because the object works the first
time and misbehaves the fiftieth.

Give every poolable object an explicit reset and call it in take():

func reset() -> void:
    velocity = Vector2.ZERO
    modulate = Color.WHITE
    _lifetime = 0.0
    set_deferred("monitoring", true)

The comparison

	`instantiate()`	Pool
Code to maintain	none	pool + a `reset()` per object
Frame time	spiky on bursts	flat
Memory	grows and shrinks	fixed, reserved up front
Bug class	none of its own	stale state carried between uses
Startup	instant	pre-warm cost at load
Good for	doors, pickups, bosses, UI	bullets, hordes, particles, damage numbers

The number that decides it

Do not guess. Open the profiler and look at frame time, not FPS — the average hides
exactly the spike you care about.

The rule of thumb that has held up for us: pool when you spawn and free more than
about 20 objects per second, continuously. Below that, instantiate() is not your
bottleneck and a pool is just extra surface for bugs.

A bullet-heaven is the clearest case on the "pool it" side. Hundreds of projectiles,
dozens of enemies and a damage number on every hit — all churning every single second
for a fifteen-minute run. There, allocation is not a detail; it is the frame budget.

A puzzle game spawning a tile every few seconds is the clearest case on the other side.
Pooling it would be pure cost.

Prewarm, or your first wave stutters

If you build the pool inside _ready() of a scene the player is already looking at, you
moved the spike instead of removing it. Build it during the loading screen, or spread it
across frames with await get_tree().process_frame every N instances.

What we do in practice

Pool the things that repeat by the hundreds: projectiles, enemies, damage numbers, hit
particles. Instantiate everything else. Two rules keep it from rotting — every poolable
object owns a reset(), and the pool never returns null.

If you are building a wave-based or bullet-heaven game, this pattern is not optional —
it is the difference between a run that holds 60 FPS at minute twelve and one that does
not.

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-object-pooling-vs-instantiate.html

How to make floating damage numbers in Godot 4 (pooled, no lag)

saltmire — Thu, 23 Jul 2026 13:42:31 +0000

Floating damage numbers are one of the cheapest ways to make combat feel like it
lands. But the naive version — instantiate() a Label every hit — quietly thrashes
the garbage collector and stutters once a horde starts taking damage. Here's the
version that scales: a small reusable scene plus a pool that never allocates mid-fight.

Step 1: the number scene

Make a scene with a single Label root, call it DamageNumber. Give it a script:

class_name DamageNumber extends Label

func show_value(value: int, crit := false) -> void:
    text = str(value)
    modulate = Color(1, 0.9, 0.3) if crit else Color.WHITE
    scale = Vector2.ONE * (1.4 if crit else 1.0)
    modulate.a = 1.0

Set the label's horizontal_alignment to Center in the inspector so it grows from
its middle. That's the whole visual — everything else is motion.

Step 2: animate one number

A damage number does two things: drift up and fade out. Tween both in parallel, then
report back when it's done so the pool can reclaim it:

signal finished(node)

func play(at: Vector2) -> void:
    global_position = at
    var rise := at + Vector2(randf_range(-12, 12), -34)
    var t := create_tween().set_parallel()
    t.tween_property(self, "global_position", rise, 0.55) \
        .set_trans(Tween.TRANS_QUAD).set_ease(Tween.EASE_OUT)
    t.tween_property(self, "scale", Vector2.ONE, 0.18)   # settle the crit pop
    t.tween_property(self, "modulate:a", 0.0, 0.55).set_delay(0.15)
    t.chain().tween_callback(func(): finished.emit(self))

The small random x-jitter matters more than it looks: without it, ten hits on the same
enemy stack into one unreadable blur.

Step 3: the pool (the part that actually matters)

Instead of creating and freeing labels, preallocate a handful and hand them out. When
one finishes, it goes back in the box:

extends Node2D

@export var scene: PackedScene           # DamageNumber.tscn
@export var pool_size := 24
var _free: Array[DamageNumber] = []

func _ready() -> void:
    for i in pool_size:
        var n: DamageNumber = scene.instantiate()
        n.hide()
        n.finished.connect(_reclaim)
        add_child(n)
        _free.append(n)

func spawn(value: int, at: Vector2, crit := false) -> void:
    var n: DamageNumber = _free.pop_back() if _free else _steal_oldest()
    n.show()
    n.show_value(value, crit)
    n.play(at)

func _reclaim(n: DamageNumber) -> void:
    n.hide()
    _free.append(n)

pool_size is the only tuning knob: it should be a little above the most numbers you
expect on screen at once. If the pool empties during a big burst, _steal_oldest()
recycles the number that's been alive longest — visually you never notice.

func _steal_oldest() -> DamageNumber:
    var n: DamageNumber = get_child(0)   # oldest live child
    move_child(n, get_child_count() - 1) # rotate it to the back
    return n

Step 4: fire it from a hit

Wherever damage is applied — your hurtbox's hurt signal is the natural place — call
the spawner. Push crits and the hit direction through so the number can react:

func _on_hurt(damage: float, source: Node, knockback: Vector2) -> void:
    hp -= damage
    var crit := damage >= crit_threshold
    $DamageNumbers.spawn(int(damage), global_position + Vector2(0, -20), crit)

Offsetting slightly opposite the knockback (- knockback.normalized() * 10) makes the
number feel like it's popping off the hit rather than sitting on the sprite.

That's the whole system

Preallocated pool, parallel rise-and-fade tween, crit color/scale, readable jitter —
that's floating damage numbers that hold up when the screen fills with enemies. If
you'd rather not wire the pool, the signal plumbing and the hit source by hand,
pooled damage numbers are one of the pieces already built into Saltmire Hitbox,
alongside the Hitbox2D/Hurtbox2D that emit the hit in the first place.

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-floating-damage-numbers.html

Godot 4 Area2D not detecting hits? 6 reasons area_entered isn't firing

saltmire — Tue, 21 Jul 2026 03:45:10 +0000

You connected area_entered, you can see the two areas overlapping in the editor, and
nothing happens. This is the single most common Godot 4 combat bug, and it's almost
always one of these six things. Work down the list — they're ordered by how often
they're the culprit.

1. `monitoring` is off (or the wrong area is monitoring)

An Area2D only detects others when monitoring = true. And detection has a
direction: the scanner needs monitoring; the thing being found needs
monitorable. If both areas monitor each other you get double hits; if neither does,
you get silence.

# the attacker scans, doesn't need to be found:
hitbox.monitoring = true
hitbox.monitorable = false
# the target is found, doesn't scan:
hurtbox.monitoring = false
hurtbox.monitorable = true

2. Layers and masks don't line up (the classic)

collision_layer is what you are; collision_mask is what you look for. For A to
detect B, A's mask must include B's layer. Same number in both layer fields with
empty masks = they never see each other.

# hurtbox exists on layer 3:
hurtbox.collision_layer = 0
hurtbox.set_collision_layer_value(3, true)
hurtbox.collision_mask = 0
# hitbox looks for layer 3:
hitbox.collision_layer = 0
hitbox.set_collision_mask_value(3, true)

Check this in code, not just the inspector — a parent scene or tween can overwrite
layer bits at runtime and the panel won't show it.

3. There's no enabled `CollisionShape2D`

An Area2D with no shape (or a shape whose disabled is true, or whose shape
resource is null) has nothing to collide with. It fails silently — no error, no
warning.

var cs := hitbox.get_node("CollisionShape2D")
assert(cs.shape != null and not cs.disabled, "hitbox shape missing/disabled")

A frequent trap: calling cs.disabled = true to "turn off" an attack and forgetting
to flip it back before the next swing.

4. The signal is connected to the wrong node

area_entered fires on the area that's doing the monitoring. If you connected the
signal on the hurtbox but the hurtbox has monitoring = false (correct, per #1), the
callback never runs. Connect area_entered on the monitoring area, or use
body_entered if the other side is a CharacterBody2D/StaticBody2D rather than an
Area2D.

hitbox.area_entered.connect(_on_hit)   # hitbox monitors, so it emits

Mixing up area_entered (Area↔Area) and body_entered (Area↔Body) is its own silent
no-op — pick the one that matches what the other node actually is.

5. The hit started already overlapping (the melee trap)

area_entered only fires the frame two areas begin overlapping. If your hitbox
turns on while it's already sitting on top of the target — extremely common for a
melee swing that activates mid-contact — the signal never fires and the hit is lost.
Scan what's already inside when you activate:

func activate() -> void:
    monitoring = true
    for area in get_overlapping_areas():
        _on_hit(area)

Note get_overlapping_areas() is only accurate after at least one physics frame of
monitoring — if you enable and scan in the same frame, call
await get_tree().physics_frame first.

6. Physics is paused or the node is disabled

If the area's process_mode is PROCESS_MODE_DISABLED, or the tree is paused and the
node doesn't have PROCESS_MODE_ALWAYS, monitoring quietly stops. This bites during
hit-stop / slow-motion, when you drop Engine.time_scale or pause the tree for feel.

# keep the hitbox live through a pause used for hit-stop:
hitbox.process_mode = Node.PROCESS_MODE_ALWAYS

The fast way to never hit this again

Every bug above comes from the same place: Area2D gives you the raw primitive and
makes you wire the rules — direction, layers, shapes, overlap-on-activate, pause
behavior — by hand, with no errors when you get it wrong. If you'd rather drop in two
nodes that already handle all six, that's exactly what Saltmire Hitbox is:
Hitbox2D / Hurtbox2D with zero layer setup, correct monitoring out of the box, and
the melee overlap case handled for you.

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-not-detecting.html

6 Godot 4 game feel tricks (each just a few lines of GDScript)

saltmire — Sat, 18 Jul 2026 15:55:07 +0000

"Game feel" is the difference between a hit that just subtracts HP and a hit that
lands. In Godot 4 almost none of it needs plugins — it's small, cheap touches
stacked on top of each other. Here are six you can paste in today, each only a few
lines.

1. Squash and stretch on impact

Nothing sells a hit like a quick scale pop. Punch the scale up, then let it spring
back with an elastic transition:

func pop(node: Node2D, amount := 0.25, duration := 0.25) -> void:
    var base := node.scale
    var t := create_tween()
    node.scale = base * (1.0 + amount)
    t.tween_property(node, "scale", base, duration) \
        .set_trans(Tween.TRANS_ELASTIC).set_ease(Tween.EASE_OUT)

Call pop($Sprite2D) on landing, on pickup, on button press — anywhere you want a
tiny "yes".

2. Sprite flash on hit

A single white frame reads instantly as "that connected". Drive a flash_amount
uniform on a tiny shader and tween it back to zero:

// flash.gdshader
shader_type canvas_item;
uniform float flash_amount : hint_range(0.0, 1.0) = 0.0;
void fragment() {
    vec4 c = texture(TEXTURE, UV);
    COLOR = vec4(mix(c.rgb, vec3(1.0), flash_amount), c.a);
}

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

3. Pooled damage numbers

Floating numbers give weight to every hit — but instancing a Label per hit thrashes
the GC. Spawn from a small pool instead and tween position + fade:

func damage_number(pos: Vector2, value: int) -> void:
    var label := _pool_get()          # reuse a Label from a preallocated array
    label.text = str(value)
    label.global_position = pos
    label.modulate.a = 1.0
    var t := create_tween().set_parallel()
    t.tween_property(label, "global_position", pos + Vector2(0, -32), 0.5)
    t.tween_property(label, "modulate:a", 0.0, 0.5)
    t.chain().tween_callback(func(): _pool_return(label))

The pool is just an array you fill on _ready() and hand out round-robin — no
instantiate() on the hot path.

4. Knockback that eases out

Instant teleport-back feels cheap; a short eased slide feels physical:

func knockback(body: Node2D, dir: Vector2, strength := 180.0, duration := 0.15) -> void:
    var target := body.global_position + dir.normalized() * strength
    create_tween().tween_property(body, "global_position", target, duration) \
        .set_trans(Tween.TRANS_QUART).set_ease(Tween.EASE_OUT)

For a CharacterBody2D you'd feed this into velocity instead, but the easing idea
is the same: fast start, soft stop.

5. Slow-motion on the big hit

Reserve time dilation for moments that earn it — a finisher, a boss stagger. Drop
Engine.time_scale, wait in real time (unscaled), then ramp back:

func slowmo(scale := 0.05, real_seconds := 0.15) -> void:
    Engine.time_scale = scale
    var timer := get_tree().create_timer(real_seconds, true, false, true) # ignore_time_scale
    await timer.timeout
    create_tween().tween_method(
        func(v): Engine.time_scale = v, scale, 1.0, 0.2)

The true at the end of create_timer is what makes it ignore time_scale — miss
that and your slow-mo waits in slow-mo and never ends.

6. Camera punch

A quick directional shove on the camera, snapping back, adds impact without a full
shake routine:

func punch(cam: Camera2D, dir: Vector2, amount := 8.0, duration := 0.12) -> void:
    var base := cam.offset
    cam.offset = base + dir.normalized() * amount
    create_tween().tween_property(cam, "offset", base, duration) \
        .set_trans(Tween.TRANS_BACK).set_ease(Tween.EASE_OUT)

Point dir opposite the hit — punch the camera away from the impact and the brain
fills in the force.

Stacking them

The magic is in combining: on a real hit you might flash() the target, pop() it,
spawn a damage_number(), knockback() it, and punch() the camera — all in the
same frame. Individually each is a nudge; together they're the difference between
flat and juicy. The only hard part is wiring them into one clean call and keeping the
tweens from stepping on each other, which is exactly the boilerplate Saltmire Impact
folds into a single line.

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-game-feel-tricks.html

Godot 4 hitbox and hurtbox the easy way (damage, teams, i-frames, knockback)

saltmire — Fri, 17 Jul 2026 13:31:30 +0000

Almost every action game needs the same thing: something that deals damage, and
something that takes it. In Godot 4 the raw tools are Area2D + CollisionShape2D,
but wiring them into a real hit is where people get stuck — collision layers vs
masks, stopping the player from hurting itself, not draining a target every physics
frame, and adding knockback and invincibility. Here's the whole thing, cleanly.

The idea: two areas, opposite jobs

A Hitbox is an Area2D on your attack (a sword swing, a bullet, a stomp). It only scans — it never needs to be detected.
A Hurtbox is an Area2D on anything that can be damaged. It only needs to be detected — it never scans.

That split is the trick most tutorials skip, and it's why layers get confusing.

Layers vs masks, in one sentence

collision_layer is what you are; collision_mask is what you look for. So:

# hurtbox: I exist on layer 20, and I look for nothing.
collision_layer = 0
set_collision_layer_value(20, true)
collision_mask = 0
monitorable = true
monitoring = false

# hitbox: I exist on nothing, and I look for layer 20.
collision_layer = 0
collision_mask = 0
set_collision_mask_value(20, true)
monitoring = true

Now a hitbox sees hurtboxes and only hurtboxes — no stray collisions with
walls or bodies. Pick any free bit; 20 is just an example.

Teams (so the player doesn't hit itself)

Give each box a team integer and refuse same-team hits:

func _on_area_entered(area):
    if area is Hurtbox and area.team != team:
        area.receive(damage, self)

The bug nobody warns you about: overlapping-on-activate

area_entered only fires when two areas start overlapping. If your hitbox turns
on while it's already sitting on top of the target — very common for a melee swing —
the signal never fires and the hit is silently lost. Fix it by also scanning what's
already inside when the swing starts:

func activate():
    active = true
    for area in get_overlapping_areas():
        _try_hit(area)

Invincibility frames and knockback

After a hit, ignore further hits for a moment, and push the target away:

func receive(damage, source):
    if _invincible: return
    var dir = (global_position - source.global_position).normalized()
    hurt.emit(damage, dir * knockback_strength)
    if invincible_time > 0.0:
        _invincible = true
        get_tree().create_timer(invincible_time).timeout.connect(
            func(): _invincible = false)

That's a complete, correct hitbox/hurtbox: layers handled, friendly fire blocked,
no lost melee hits, i-frames and knockback in place.

Skip the boilerplate

If you'd rather drop in two nodes and move on, Saltmire Hitbox packages exactly
this — Hitbox2D / Hurtbox2D with zero layer setup, plus damage types, crits,
per-type resistances, animation-frame timing and a runtime debug overlay. There's a
free MIT Lite core too if you just want the basics.

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-hitbox-hurtbox.html

"Tween vs AnimationPlayer in Godot 4 — which to use and when"

saltmire — Tue, 14 Jul 2026 14:03:48 +0000

Both Tween and AnimationPlayer animate values in Godot 4. Both can move, fade,
scale, and colour things. If you've ever stared at a new node and wondered which one
to reach for, here's the honest breakdown.

Quick comparison

	Tween	AnimationPlayer
Lives in	code (`create_tween()`)	a node in the scene tree
Keyframes	no — set target value + duration	yes, visual timeline editor
Multi-property tracks	no (chains, not tracks)	yes
Blend / cross-fade	no	yes, via `AnimationTree`
Reacts to runtime values	yes — target set in code	harder, needs manual sync
Easing / curves	built-in enums	curve editor
Restartable mid-flight	yes — `kill()` + new tween	yes — `stop()` + `play()`
Scene export	not really	yes, included in `.tscn`
Best for	juice, reactive effects, one-shot polish	locomotion, cutscenes, multi-track sync

When Tween wins: reactive, code-driven effects

Tween is not a node. You call create_tween() and it runs and frees itself — no
leftover scene nodes, no cleanup. That makes it the right tool for short, reactive
effects where the target value is only known at runtime.

Pop-scale on hit:

func pop(target: Node2D) -> void:
    var tw := create_tween()
    tw.tween_property(target, "scale", Vector2(1.35, 1.35), 0.08) \
        .set_ease(Tween.EASE_OUT)
    tw.tween_property(target, "scale", Vector2.ONE, 0.14) \
        .set_trans(Tween.TRANS_ELASTIC).set_ease(Tween.EASE_OUT)

Slide a UI panel in from a dynamic off-screen position:

func slide_in(panel: Control, start_x: float) -> void:
    panel.position.x = start_x
    var tw := create_tween()
    tw.tween_property(panel, "position:x", 0.0, 0.3) \
        .set_trans(Tween.TRANS_BACK).set_ease(Tween.EASE_OUT)

Fade and free a damage number:

func float_number(label: Label, value: int) -> void:
    label.text = str(value)
    var tw := create_tween().set_parallel(true)
    tw.tween_property(label, "position:y", label.position.y - 40, 0.6)
    tw.tween_property(label, "modulate:a", 0.0, 0.5).set_delay(0.1)
    tw.chain().tween_callback(label.queue_free)

Tweens are also chainable (.chain()) and parallelizable (.set_parallel(true)),
so you can sequence multi-step effects entirely in code without an editor.

When AnimationPlayer wins: authored sequences and character animation

AnimationPlayer is a node you add to the scene. Open the Animation panel, and every
property on any child node can be a keyframe. That makes it the right tool for
anything you want to edit visually — especially when more than two properties move
in sync, or when animations need to blend.

A melee attack that moves the body, flashes the sprite, and emits a particle:

func attack() -> void:
    $AnimationPlayer.play("attack")
    await $AnimationPlayer.animation_finished
    _return_to_idle()

All the timing lives in the authored clip. Tweak it in the editor without touching
code.

Blended locomotion (walk → run → idle):

Add an AnimationTree on top of AnimationPlayer and build a state machine or
blend space — then drive it from code with a single float:

$AnimationTree.set("parameters/blend_position", velocity.length() / max_speed)

That cross-fade would take hundreds of lines to replicate with tweens.

The rule of thumb

Reach for Tween when the target value is decided at runtime, the effect is
under ~0.5 s, and it's self-contained (scale pop, slide in, fade out, number float).

Reach for AnimationPlayer when you want to edit the sequence visually, more
than two properties move together, or animations need to blend.

Most games use both: AnimationPlayer for character locomotion and cutscenes, Tweens
for every piece of reactive UI juice.

Godot 4 vs Godot 3: the one breaking change

In Godot 3, Tween was a node you added to the scene tree. In Godot 4 it's
instantiated with create_tween() directly on a Node (or get_tree().create_tween()
if you're outside a node). There are no more stale tween nodes dangling in your tree.
If you're porting from Godot 3, that's the only real rewire needed.

If you want the juice without the wiring

Screen shake, hit-stop, floating damage numbers, and sprite flash are the most
common tween-based juice effects every action game needs. If you'd rather not
re-derive each one per project, Saltmire Juice is a free, MIT-licensed add-on
that ships all of them as one-call autoloads — Juice.shake(), Juice.hit_stop(),
Juice.damage_number() — drop it in and move on.

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

Originally published at https://saltmire.github.io/godot-4-tween-vs-animationplayer.html

"Fixing Godot 4 save-file load errors: JSON parse error, null instance, and missing files"

saltmire — Fri, 10 Jul 2026 13:56:12 +0000

You shipped a save system, it worked on your machine, and now the console is red on
load. Save/load bugs are nasty because they only show up after a write already
happened — the bad data is already on disk. Here are the three errors that break
Godot 4 saves most often, why each one happens, and the exact fix.

1. `JSON Parse Error: ... at line N`

Symptom. On load you get something like:

JSON Parse Error: Unexpected end of stream at line 1

or a parse error pointing at a spot in the middle of your file.

Cause. The file was written partially. This almost always means the game
crashed (or was force-quit) during the write, or two systems wrote to the same
file at once. FileAccess flushes on close(); if you never reach close(), you
get a truncated, unparseable file.

Fix. Never write in place. Write to a temp file, then rename it over the real
one — rename is atomic on every desktop OS, so the save is either the old file or
the complete new one, never a half of each:

func save_state(data: Dictionary, path := "user://save.json") -> void:
    var tmp := path + ".tmp"
    var f := FileAccess.open(tmp, FileAccess.WRITE)
    if f == null:
        push_error("Save failed to open %s: %d" % [tmp, FileAccess.get_open_error()])
        return
    f.store_string(JSON.stringify(data))
    f.close()  # flush BEFORE the rename
    DirAccess.rename_absolute(ProjectSettings.globalize_path(tmp),
                              ProjectSettings.globalize_path(path))

And always guard the read instead of trusting JSON.parse_string:

func load_state(path := "user://save.json") -> Dictionary:
    if not FileAccess.file_exists(path):
        return {}
    var text := FileAccess.get_file_as_string(path)
    var parsed = JSON.parse_string(text)
    if parsed == null or typeof(parsed) != TYPE_DICTIONARY:
        push_warning("Save at %s is corrupt — falling back to empty." % path)
        return {}
    return parsed

2. `Invalid call ... Attempt to call ... on a null instance`

Symptom.

Invalid call. Nonexistent function 'get' in base 'Nil'.

right after you read the save back.

Cause. JSON.parse_string returns null on failure, and you used the result
without checking. It also cannot return your original types — a Vector2 you
stored becomes a plain array or null, a custom object becomes a Dictionary. So
saved.player_pos.x blows up because player_pos is not a Vector2 anymore.

Fix. Serialize non-JSON types explicitly on the way out, and rebuild them on the
way in. Don't assume the shape survived:

# on save
data["player_pos"] = {"x": player.position.x, "y": player.position.y}

# on load
var d: Dictionary = load_state()
if d.has("player_pos"):
    var p = d["player_pos"]
    player.position = Vector2(p.get("x", 0.0), p.get("y", 0.0))

Every read from the loaded dictionary should use .get(key, default) so a missing
key gives a sane value instead of a Nil.

3. `Error opening file` / values silently wrong after an update

Symptom. Either the file just isn't there on a fresh install, or a returning
player loads an old save and half their state is missing after you added fields.

Cause. Two separate issues wearing the same coat: (a) you read before any save
exists, and (b) the save's schema changed between versions and old files don't
have the new keys.

Fix. Version your saves and migrate forward. Stamp a version number on write,
and run migrations on read so an old file becomes a valid current one:

const SAVE_VERSION := 3

func migrate(d: Dictionary) -> Dictionary:
    var v := int(d.get("version", 1))
    if v < 2:
        d["settings"] = d.get("settings", {"volume": 1.0})  # added in v2
    if v < 3:
        d["playtime"] = d.get("playtime", 0.0)              # added in v3
    d["version"] = SAVE_VERSION
    return d

Now old saves keep loading instead of erroring, and new fields get safe defaults.

The pattern behind all three

Every one of these bugs is the same root cause: treating the disk as trustworthy.
It isn't. A robust save layer writes atomically, validates on read, defaults every
missing key, and migrates old schemas — none of which is hard, but all of which is
easy to forget until a player loses a save. If you'd rather not re-derive the atomic
write, corruption guard, backup fallback, and schema migration in every project,
that's exactly the boring, tested wiring Saltmire Save is.

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-file-load-errors.html

DEV Community: saltmire

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

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

What I'd do differently starting over

Godot 4 GPUParticles2D not showing? 5 reasons your particles aren't appearing

1. No process material assigned

2. emitting is false

3. Visibility rect too small (particles culled)

4. lifetime or amount are too small to see

5. The one_shot trap — particles fire once at scene load and stop

What all five have in common

Object pooling vs instantiate in Godot 4 — when it actually matters

What instantiate() actually costs

What pooling actually costs

The comparison

The number that decides it

Prewarm, or your first wave stutters

What we do in practice

How to make floating damage numbers in Godot 4 (pooled, no lag)

Step 1: the number scene

Step 2: animate one number

Step 3: the pool (the part that actually matters)

Step 4: fire it from a hit

That's the whole system

Godot 4 Area2D not detecting hits? 6 reasons area_entered isn't firing

1. monitoring is off (or the wrong area is monitoring)

2. Layers and masks don't line up (the classic)

3. There's no enabled CollisionShape2D

4. The signal is connected to the wrong node

5. The hit started already overlapping (the melee trap)

6. Physics is paused or the node is disabled

The fast way to never hit this again

6 Godot 4 game feel tricks (each just a few lines of GDScript)

1. Squash and stretch on impact

2. Sprite flash on hit

3. Pooled damage numbers

4. Knockback that eases out

5. Slow-motion on the big hit

6. Camera punch

Stacking them

Godot 4 hitbox and hurtbox the easy way (damage, teams, i-frames, knockback)

The idea: two areas, opposite jobs

Layers vs masks, in one sentence

Teams (so the player doesn't hit itself)

The bug nobody warns you about: overlapping-on-activate

Invincibility frames and knockback

Skip the boilerplate

"Tween vs AnimationPlayer in Godot 4 — which to use and when"

Quick comparison

When Tween wins: reactive, code-driven effects

When AnimationPlayer wins: authored sequences and character animation

The rule of thumb

Godot 4 vs Godot 3: the one breaking change

If you want the juice without the wiring

"Fixing Godot 4 save-file load errors: JSON parse error, null instance, and missing files"

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

2. `emitting` is false

4. `lifetime` or `amount` are too small to see

5. The `one_shot` trap — particles fire once at scene load and stop

What `instantiate()` actually costs

1. `monitoring` is off (or the wrong area is monitoring)

3. There's no enabled `CollisionShape2D`

1. `JSON Parse Error: ... at line N`

2. `Invalid call ... Attempt to call ... on a null instance`

3. `Error opening file` / values silently wrong after an update