DEV Community: saltmire

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

5 Godot 4 scene transition effects (and how to build each one)

saltmire — Thu, 09 Jul 2026 12:46:03 +0000

Swapping scenes in Godot 4 is one line: get_tree().change_scene_to_file(). Making
that swap feel intentional is the part that takes effort. Here are five transition
effects — from dead simple to shader-powered — with paste-able GDScript for each.

1. Fade to black

The classic. A ColorRect at CanvasLayer 100 sits invisible on top of everything.
Tween its alpha to 1, change the scene, tween back to 0:

# SceneTransition.gd — autoload
@onready var overlay: ColorRect = $CanvasLayer/Overlay  # full-viewport, black, alpha 0

func fade_to(path: String, duration := 0.3) -> void:
    var t := create_tween()
    t.tween_property(overlay, "modulate:a", 1.0, duration)
    await t.finished
    get_tree().change_scene_to_file(path)
    t = create_tween()
    t.tween_property(overlay, "modulate:a", 0.0, duration)

Call it: SceneTransition.fade_to("res://scenes/Level2.tscn"). Squaring the tween
curve (Tween.TRANS_SINE) makes the fade-out feel less abrupt.

2. Iris wipe (circle close)

An iris wipe closes a circle over the screen, swaps the scene, then opens again.
You need one shader on the ColorRect:

// iris.gdshader
shader_type canvas_item;
uniform float radius : hint_range(0.0, 1.5) = 1.5;
uniform vec2  center = vec2(0.5, 0.5);

void fragment() {
    float dist = length(UV - center);
    COLOR = vec4(0.0, 0.0, 0.0, step(radius, dist));
}

Then in GDScript:

func iris_to(path: String, duration := 0.4) -> void:
    var mat: ShaderMaterial = overlay.material
    var t := create_tween()
    t.tween_method(func(v): mat.set_shader_parameter("radius", v), 1.5, 0.0, duration)
    await t.finished
    get_tree().change_scene_to_file(path)
    t = create_tween()
    t.tween_method(func(v): mat.set_shader_parameter("radius", v), 0.0, 1.5, duration)

Point center at a character or door for a dramatic theatrical close.

3. Pixelate

The screen dissolves into chunky blocks before the cut. Capture the screen with
hint_screen_texture and floor each UV to the nearest block:

// pixelate.gdshader
shader_type canvas_item;
uniform float block_size : hint_range(1.0, 128.0) = 1.0;
uniform sampler2D screen_texture : hint_screen_texture, filter_nearest;

void fragment() {
    vec2 vp = 1.0 / SCREEN_PIXEL_SIZE;
    vec2 snapped = floor(SCREEN_UV * vp / block_size) * block_size / vp;
    COLOR = texture(screen_texture, snapped);
}

Tween block_size from 1.0 up to 64.0 (fully pixelated), change scene, tween
back down. Looks great for retro or lo-fi aesthetics.

4. Slide / pan

No shader needed — just move nodes. Instantiate the next scene offscreen, then tween
both the current scene out and the new one in simultaneously:

func slide_to(path: String, dir := Vector2.LEFT, duration := 0.4) -> void:
    var vp := get_viewport().get_visible_rect().size
    var next := load(path).instantiate()
    next.position = -dir * vp
    get_tree().root.add_child(next)

    var t := create_tween().set_parallel()
    t.tween_property(get_tree().current_scene, "position", dir * vp, duration)
    t.tween_property(next, "position", Vector2.ZERO, duration)
    await t.finished

    get_tree().current_scene.queue_free()
    get_tree().current_scene = next

Pass Vector2.RIGHT / Vector2.UP / Vector2.DOWN to control slide direction.
Add .set_ease(Tween.EASE_IN_OUT).set_trans(Tween.TRANS_CUBIC) for a polished
mobile-menu feel.

5. Dissolve (noise dither)

A dissolve removes pixels in a pseudo-random order using a grayscale noise texture
as a threshold map — much more interesting than a uniform fade:

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

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

Assign any seamless noise texture to noise, then tween threshold from 0.0 to
1.0 to dissolve out. Use a SubViewport to capture the outgoing scene so the
dissolve continues to run after the scene has already changed.

Which one to use

Effect	Complexity	Best for
Fade	Trivial	Any genre — never wrong
Iris	One shader	Dramatic story beats, cutscenes
Pixelate	One shader	Retro, lo-fi, pixel-art games
Slide	Pure GDScript	Menu flows, mobile feel
Dissolve	Shader + noise texture	Cinematic, horror, RPG

Skip the wiring

Each effect above is ~15 lines of code. The time cost is the autoload setup,
managing which CanvasLayer owns what, and making the await-able API safe against
overlapping calls. If you want all five (plus wipes and a smooth fade-in-on-load
default) as a single drop-in for Godot 4, that is what Saltmire Transitions is.

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-scene-transitions.html

Godot 4 screen shake and hit-stop in one script

saltmire — Wed, 08 Jul 2026 22:28:12 +0000

"Game feel" is mostly a handful of cheap effects stacked on top of otherwise
normal gameplay. Two of the highest-impact ones are screen shake and
hit-stop. Here is how to do both in Godot 4 with code you can reuse.

Screen shake on a Camera2D

The trick is to offset the camera by a random amount each frame and decay that
amount over time. Attach this to your Camera2D:

extends Camera2D

var _trauma := 0.0        # 0..1, how much shake is queued
var _decay := 4.0         # how fast it fades per second
var _max_offset := 12.0   # pixels at full trauma

func shake(amount: float) -> void:
    _trauma = min(_trauma + amount, 1.0)

func _process(delta: float) -> void:
    if _trauma <= 0.0:
        offset = Vector2.ZERO
        return
    _trauma = max(_trauma - _decay * delta, 0.0)
    var t := _trauma * _trauma           # square it: small hits stay subtle
    offset = Vector2(
        randf_range(-1, 1) * _max_offset * t,
        randf_range(-1, 1) * _max_offset * t
    )

Call camera.shake(0.4) on a hit. Squaring the trauma (t = _trauma * _trauma)
is what makes it feel good — light hits barely nudge, big hits kick hard.

Hit-stop (freeze frames)

Hit-stop briefly freezes the game on impact so a hit reads as heavy. In Godot 4
you scale Engine.time_scale down, wait, then restore it. Use an unscaled timer
so the freeze itself is not slowed:

func hit_stop(duration := 0.08, scale := 0.05) -> void:
    Engine.time_scale = scale
    # ignore_time_scale so the wait runs in real time
    await get_tree().create_timer(duration, true, false, true).timeout
    Engine.time_scale = 1.0

await hit_stop() on a big hit. Keep it short — 60–120 ms is plenty. Longer than
that and the game feels laggy instead of punchy.

Stacking them

A satisfying hit usually fires several of these at once: shake + hit-stop + a
white flash on the sprite + damage numbers + a little particle burst. Each is a
few lines, but wiring all of them, tuned, for every hit type — light hit, heavy
hit, crit, death — is where the boilerplate piles up.

func on_enemy_hit(enemy, damage):
    camera.shake(0.3)
    await hit_stop()
    flash(enemy.sprite)
    spawn_damage_number(enemy.global_position, damage)
    # ...and a particle burst, and sound, per hit type

Skip the wiring

The individual effects are free to build. If you would rather call one function —
Impact.hit(enemy, "heavy") — and get shake, curved hit-stop, flash, damage
numbers and shader FX in tuned combos, that is what Saltmire Impact is. The
building-block pieces (Juice, FX, Trail, Spark) are free and open source; Impact
is the orchestrator that ties them together.

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-screen-shake-hit-stop.html

How to save and load your game in Godot 4 (the honest way)

saltmire — Wed, 08 Jul 2026 22:28:11 +0000

Every game needs to save state, and Godot 4 gives you everything you need in the
standard library. Here is a real, working system you can paste into a project
today — followed by the parts that quietly break in production.

The minimal version

Godot's FileAccess writes bytes; JSON turns a Dictionary into a string and
back. Put the two together and you have save/load:

const SAVE_PATH := "user://savegame.json"

func save_game(data: Dictionary) -> void:
    var f := FileAccess.open(SAVE_PATH, FileAccess.WRITE)
    f.store_string(JSON.stringify(data))
    f.close()

func load_game() -> Dictionary:
    if not FileAccess.file_exists(SAVE_PATH):
        return {}
    var f := FileAccess.open(SAVE_PATH, FileAccess.READ)
    var text := f.get_as_text()
    f.close()
    var parsed = JSON.parse_string(text)
    return parsed if typeof(parsed) == TYPE_DICTIONARY else {}

Call save_game({"hp": 80, "level": 3}) and later var d = load_game(). That is
genuinely all you need for a jam game.

Why `user://` and not `res://`

res:// is your project — it is read-only in an exported game. Always save to
user://, which maps to a real per-user folder on desktop and to IndexedDB on the
web export. Same API either way, so your code does not change per platform.

Multiple save slots

Do not hardcode one path. Key the filename by a slot name so you can build a
load-game menu:

func slot_path(slot: String) -> String:
    return "user://saves/%s.json" % slot

func save_to(slot: String, data: Dictionary) -> void:
    DirAccess.make_dir_recursive_absolute("user://saves")
    var f := FileAccess.open(slot_path(slot), FileAccess.WRITE)
    f.store_string(JSON.stringify(data))
    f.close()

To list existing slots for a menu, walk the directory with DirAccess.

The four things that bite later

The snippet above works — until real players use it. These are the problems that
turn a two-line save system into a two-week refactor:

Corruption. A crash or power-off mid-write leaves a half-written file. JSON.parse_string returns null and the player loses everything. The fix is to write to a temp file, then rename over the real one, and keep a rotating backup to restore from.
Save editing. A plain JSON file in user:// is trivial to open and edit — players will change their gold to 9999. If that matters, you need to encrypt the file (FileAccess.open_encrypted_with_pass).
Schema changes. You ship an update that renames coins to gold. Every existing save still has coins. Without a migration step, old saves crash or silently lose data.
Save size. A big world save is megabytes of JSON. gzip typically cuts that by ~90%, but only helps if you wire compression in from the start.

None of these are hard individually. The problem is that they all show up after
launch, one at a time, in bug reports.

If you just want it handled

You can build all four yourself — or drop in a tool that already has them, with a
headless self-test that proves each one with a real number. That is exactly what
Saltmire Save Lite (free) and Saltmire Save (the full version) are for: the same
one-line Save.write / Save.read API, with encryption, backups, migration and
compression when you need them.

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

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

DEV Community: saltmire

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. 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

The pattern behind all three

5 Godot 4 scene transition effects (and how to build each one)

1. Fade to black

2. Iris wipe (circle close)

3. Pixelate

4. Slide / pan

5. Dissolve (noise dither)

Which one to use

Skip the wiring

Godot 4 screen shake and hit-stop in one script

Screen shake on a Camera2D

Hit-stop (freeze frames)

Stacking them

Skip the wiring

How to save and load your game in Godot 4 (the honest way)

The minimal version

Why user:// and not res://

Multiple save slots

The four things that bite later

If you just want it handled

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

Why `user://` and not `res://`