DEV Community: saltmire

JSON vs ConfigFile vs Resource in Godot 4 — which save format and when

saltmire — Sat, 17 Oct 2026 12:28:30 +0000

Godot 4 gives you three sanctioned ways to write a save file, and the docs describe each
one without ever telling you which to pick. So you pick the first one you read about,
ship it, and discover the trade-off six months later when a player's Vector2 comes back
as a Dictionary or an old save crashes the new build. Here's what each format actually
costs.

JSON: portable, readable, type-lossy

FileAccess plus JSON is the path most tutorials take, because it's the one that
looks like saving in every other language.

func save_game(data: Dictionary) -> void:
    var f := FileAccess.open("user://save.json", FileAccess.WRITE)
    f.store_string(JSON.stringify(data, "\t"))

func load_game() -> Dictionary:
    if not FileAccess.file_exists("user://save.json"):
        return {}
    var f := FileAccess.open("user://save.json", FileAccess.READ)
    var parsed = JSON.parse_string(f.get_as_text())
    return parsed if parsed is Dictionary else {}

The catch is that JSON has no idea what a Godot type is. It knows objects, arrays,
strings, numbers, booleans and null — that's the whole list. Three consequences bite in
practice:

Numbers come back as floats. Save level = 3, load 3.0. Anything you feed to an array index or a match on an int needs an explicit int() on the way out.
Dictionary keys become strings. {1: "sword"} saves and loads as {"1": "sword"}. Inventory slots keyed by int are the usual victim.
Vector2, Color and friends don't survive. You convert them by hand going in and coming out, every field, forever.

What you get in exchange is real: the file is plain text any tool can read, nothing in it
can execute, and you can parse it outside Godot — a web leaderboard, a Python script, a
save editor you write in an afternoon.

ConfigFile: Variants that round-trip, in an INI file

ConfigFile stores sections and keys, and it keeps Godot's own types.

func save_game() -> void:
    var cfg := ConfigFile.new()
    cfg.set_value("player", "position", Vector2(120, 48))
    cfg.set_value("player", "hp", 3)
    cfg.set_value("world", "unlocked", ["cave", "ridge"])
    cfg.save("user://save.cfg")

func load_game() -> void:
    var cfg := ConfigFile.new()
    if cfg.load("user://save.cfg") != OK:
        return
    var pos: Vector2 = cfg.get_value("player", "position", Vector2.ZERO)
    var hp: int = cfg.get_value("player", "hp", 3)

Vector2 goes in and Vector2 comes out. 3 stays an int. Arrays and Dictionaries of
Variants work too, and get_value() takes a default as its third argument — which quietly
solves the "player has an old save without this key" problem that forces try/except
gymnastics in JSON.

The limits: it stores Variants, not objects, so a custom class instance isn't going in.
It's flat by nature — two levels, section and key — so deeply nested state gets encoded as
one big Dictionary value and you've lost the readability you came for. And the format is
Godot's own, so nothing outside the engine parses it for free.

Resource: typed, autocompleted, and the one with a security warning

A custom Resource turns your save into a class with real fields.

class_name SaveData extends Resource

@export var hp: int = 3
@export var position: Vector2 = Vector2.ZERO
@export var unlocked: Array[String] = []

func save_game(data: SaveData) -> void:
    ResourceSaver.save(data, "user://save.tres")

func load_game() -> SaveData:
    if not ResourceLoader.exists("user://save.tres"):
        return SaveData.new()
    return load("user://save.tres") as SaveData

Typos become editor errors instead of runtime nils, and you get autocomplete on your own
save. It is by far the nicest to write.

Two things to know before you ship it. First, resource files can reference scripts, and
loading one runs them — the Godot docs say outright not to load resources from untrusted
sources. A save file in user:// is a file the player (or anything else on their machine)
can swap. If your game ever accepts a save from elsewhere — cloud sync, a Discord
"try my seed", a modding scene — that's a code-execution path, not just a cheating one.
Second, the file is tied to your script: rename the class, move the file, or drop an
@export and old saves stop loading cleanly.

The comparison

	JSON	ConfigFile	Resource (.tres)
Keeps `int` vs `float`	no	yes	yes
`Vector2` / `Color` round-trip	manual	yes	yes
Dictionary int keys	become strings	yes	yes
Typed fields + autocomplete	no	no	yes
Readable / editable by players	yes	yes	yes (and riskier)
Parseable outside Godot	yes	no	no
Missing key has a default	hand-rolled	built in	class default
Safe to load untrusted files	yes	yes	no
Survives renaming your classes	yes	yes	no
Built-in password encryption	via `FileAccess`	`save_encrypted_pass`	no

One honest note on that last row: the key ships inside your game binary, so encryption
here stops casual editing, not a determined player.

The rule

Shipping a single-player game and you want the least future pain? ConfigFile. It
round-trips Godot's types, defaults are built in, and nothing in it can run.

Anything outside Godot ever reads the save — a server, a stats page, a tool? JSON, and
pay the type-casting tax deliberately.

Prototype or jam, all internal, speed is everything? Resource. Just know you'll want
to move off it before you accept a save file you didn't write.

Whichever you pick, the format is the easy half. The half that shows up later is
versioning old saves into a new schema, not corrupting the file when the game is killed
mid-write, and keeping a backup to fall back on. Saltmire Save is the paid tool I built
after writing that layer one time too many: one-line save and load, plus schema migration,
backup recovery, gzip compression and encryption — MIT licensed, so you can read exactly
how it handles each of these.

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-json-vs-configfile-vs-resource-save.html

Fixing set_shader_parameter not working in Godot 4

saltmire — Thu, 15 Oct 2026 12:30:01 +0000

Sprite shaders are the one place in Godot 4 where wrong code doesn't crash — it just
quietly does nothing. You call a setter, the sprite doesn't change, and there is no error
to search for. Or worse: it works, and lights up all twelve enemies on screen.

The symptoms that bring people here:

Invalid call. Nonexistent function 'set_shader_param' in base 'ShaderMaterial'.
The uniform changes fine in the inspector, but nothing happens from code.
One enemy gets hit and every enemy flashes white.
Invalid property path 'shader_param/progress' from a tween.

Five causes, ordered by how often they show up.

1. You're calling the Godot 3 name

Symptom. Nonexistent function 'set_shader_param', or an old tutorial's
material.set("shader_param/flash", 1.0) that fails silently.

Cause. Godot 4 renamed it. shader_param is gone; it's shader_parameter everywhere —
the method, the property path, the get_ version.

Fix.

# Godot 3 — dead
material.set_shader_param("flash_amount", 1.0)
material.set("shader_param/flash_amount", 1.0)

# Godot 4
material.set_shader_parameter("flash_amount", 1.0)

Note which half fails. The method call raises an error you can see. The
material.set("shader_param/...") form is a generic property write — it returns nothing
and warns nothing, which is why it survives in copy-pasted code for months.

2. The material is shared between every instance

Symptom. The shader works, but hitting one enemy flashes the whole screen's worth
of them.

Cause. A ShaderMaterial saved as a .tres file, or assigned once in a scene, is
one resource. Every instance of that scene points at the same object. Setting a
parameter sets it for all of them. This is also why it looks right in a single-enemy
test scene and breaks the moment you spawn a crowd.

Fix. Give each instance its own copy on spawn:

func _ready() -> void:
    # shallow duplicate: own parameter values, same compiled Shader
    var mat := sprite.material as ShaderMaterial
    if mat:
        sprite.material = mat.duplicate()

Or do it without code: select the material in the inspector and tick Resource >
Local to Scene. Each instantiated scene then gets its own copy automatically.

Worth knowing: the per-instance uniform shortcut
(set_instance_shader_parameter) lives on GeometryInstance3D, not on CanvasItem. In
2D, duplicate() or Local to Scene is the answer.

3. The uniform name doesn't match — and Godot won't tell you

Symptom. No error at all. The call runs, nothing changes.

Cause. set_shader_parameter() accepts any name. If no uniform matches — a typo, a
renamed uniform, the wrong shader on the node — the value is stored and never read.
There is no warning.

Fix. Check against the shader's actual uniform list instead of guessing:

func _ready() -> void:
    var mat := sprite.material as ShaderMaterial
    for u in mat.shader.get_shader_uniform_list():
        print(u["name"], " : ", u["type"])

Two related traps:

A uniform you never declared in the shader won't appear in the inspector either — that's your fastest check. Visible in the inspector, ignored from code means a typo in the string, not a shader problem.
get_shader_parameter() returns null when nothing has been set on that material. It does not fall back to the default written in the shader, so don't use it to read a starting value.

4. A tween is animating the wrong property path

Symptom. Invalid property path, or a tween that completes instantly with no visible
change.

Cause. Tweening a uniform means tweening a property on the material, with the
Godot 4 path, not the node and not the Godot 3 prefix.

Fix.

func flash() -> void:
    var mat := sprite.material as ShaderMaterial
    mat.set_shader_parameter("flash_amount", 1.0)
    var tw := create_tween()
    tw.tween_property(mat, "shader_parameter/flash_amount", 0.0, 0.15)

create_tween() on the node binds the tween's life to that node, so a dying enemy can't
leave a tween poking at a freed material.

5. `use_parent_material` is on

Symptom. Setting the parameter on the node's own material does nothing, and the
inspector seems to ignore the material too.

Cause. CanvasItem.use_parent_material is checked (sometimes inherited from a scene
you copied). The node renders with the parent's material; its own is unused.

Fix. Uncheck it, or set the parameter on whichever material actually renders:

var mat := sprite.material as ShaderMaterial
if sprite.use_parent_material:
    mat = sprite.get_parent().material as ShaderMaterial

The quick triage order

When a uniform won't move, go in this order: is the name in
get_shader_uniform_list()? Is use_parent_material off? Is the material a
duplicate() or Local to Scene? Is the tween path
shader_parameter/<name>? Four checks and the silent cases stop being mysterious.

Most of this is plumbing, not effects work — which is the thinking behind Saltmire FX.
Each call (FX.hit_flash($Sprite2D), FX.dissolve($Sprite2D), outline, freeze,
hologram) builds a fresh ShaderMaterial on the node you passed in, so causes 1, 2 and 3
can't reach your code: nothing is shared between instances and no uniform name is spelled
on your side. The tweens come from target.create_tween(), for the lifetime reason in
cause 4. It's MIT and the shaders are plain .gdshader files, so you can read exactly
what it does, or lift the pattern and keep writing it yourself — the five checks above are
the whole of it either way.

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-set-shader-parameter-not-working.html

7 Godot 4 melee attack mistakes (and the fix for each)

saltmire — Tue, 13 Oct 2026 12:21:35 +0000

A melee attack in Godot 4 looks like a ten-minute job: put an Area2D on the sword,
listen for area_entered, subtract health. Then you playtest. The enemy dies from
standing next to you, one swing deals triple damage, the player hits themselves, and the
sword hitbox points right while the character faces left.

These are the seven mistakes behind almost every "my melee attack is broken" thread,
with the fix for each.

1. The hitbox is on all the time

If the sword's Area2D monitors every frame, anything that touches the sword takes
damage — including an enemy that just walked into you while you were idle. A hitbox
should only exist during the active frames of the attack.

# player.gd
@onready var sword_hitbox: Area2D = $Pivot/SwordHitbox

func _ready() -> void:
    sword_hitbox.monitoring = false

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

Then, in the attack animation, add a Property track on
Pivot/SwordHitbox:monitoring: key true on the frame the blade swings out, false
when it's done. The animation now owns the timing, which is where a designer will look
for it.

2. One swing hits the same enemy three times

area_entered fires every time an overlap starts. If the enemy's hurtbox has two
shapes, or the enemy gets knocked back and slides into the blade again, one swing lands
several hits. Keep a list of what this swing already hit and clear it when a new swing
starts:

# sword_hitbox.gd
extends Area2D

@export var damage := 10.0
var _hit_this_swing: Array[Area2D] = []

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

func start_swing() -> void:
    _hit_this_swing.clear()

func _on_area_entered(area: Area2D) -> void:
    if area in _hit_this_swing:
        return
    _hit_this_swing.append(area)
    if area.has_method("take_hit"):
        area.take_hit(damage, global_position)

Call start_swing() from a Call Method track on the first frame of the attack
animation, right before monitoring turns on.

3. The player hits themselves

The sword's Area2D overlaps the player's own hurtbox on the first frame of every
swing. Don't fix this with if area.owner == self checks scattered everywhere — fix it
in the collision bits. Put hurtboxes on team layers (player_hurtbox,
enemy_hurtbox) and give the player's sword a mask that only contains
enemy_hurtbox. The overlap never happens, so there's nothing to filter.

4. "Function blocked during in/out signal"

You try to turn the hitbox off the moment it hits something:

func _on_area_entered(area: Area2D) -> void:
    monitoring = false  # error!

Godot refuses, because you're changing physics state while the physics server is in the
middle of reporting overlaps. The error message tells you the fix:

func _on_area_entered(area: Area2D) -> void:
    set_deferred("monitoring", false)

The same applies to toggling CollisionShape2D.disabled from inside a body or area
signal — use set_deferred("disabled", true).

5. The hitbox doesn't flip with the character

Sprite2D.flip_h = true mirrors the picture, not the child nodes. Your sword hitbox
stays on the right. Put everything that should mirror under a Node2D pivot and flip
that instead:

@onready var pivot: Node2D = $Pivot  # holds Sprite2D + SwordHitbox

func _physics_process(_delta: float) -> void:
    var dir := Input.get_axis("move_left", "move_right")
    if dir != 0.0:
        pivot.scale.x = sign(dir)

Flip the pivot, not the CharacterBody2D itself — a negative scale on a physics body
gets reset by the physics server and causes strange behaviour.

6. The damage logic lives in the sword

When the hitbox does area.get_parent().health -= damage, every attack in the game
needs to know how every target stores health, handles invincibility frames and reacts.
Flip the dependency: the hurtbox receives the hit and forwards it, and the receiver
decides what happens.

# hurtbox.gd
extends Area2D
signal hurt(amount: float, from_position: Vector2)

func take_hit(amount: float, from_position: Vector2) -> void:
    hurt.emit(amount, from_position)

The enemy connects hurt to its own health component, which can ignore the hit during
i-frames, apply resistances or trigger knockback. The sword stays dumb, and any new
attack — arrows, explosions, spikes — reuses the same hurtbox.

7. The active window is one frame long

A fast jab that enables monitoring for a single frame often misses. The new overlap is
picked up on the next physics step, and if your animation turns the hitbox off before
that step runs, the signal never fires. At 60 physics ticks per second, keep active
windows at 3+ physics frames (about 0.05 s). If a design really needs a single-frame
hit, skip the signal and query directly:

func instant_hit() -> void:
    await get_tree().physics_frame
    for area in sword_hitbox.get_overlapping_areas():
        _on_area_entered(area)

The pattern behind all seven

Every mistake above is the same thing in a different costume: a melee attack is not
"an Area2D on a sword", it's a small contract — when the box is live, who it can
see, how many times it may hit, and who decides what a hit means. Write that
contract once and every attack in your game gets it for free.

Saltmire Hitbox is that contract packaged as a Hitbox2D / Hurtbox2D pair for
Godot 4: activate() / deactivate() for active windows, a one-hit-per-swing option
with reset(), teams instead of hand-set collision bits, a helper that binds the
hitbox to specific AnimatedSprite2D frames, plus knockback and i-frames on the
receiving side. If you'd rather build it yourself, the seven fixes above are the core
of what it does.

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-melee-attack-mistakes.html

How to make XP gems with a pickup magnet and level-up bar in Godot 4

saltmire — Sun, 11 Oct 2026 12:26:14 +0000

Every survivors-like has the same small loop: an enemy dies, a gem drops, you walk near it,
it flies into you, the XP bar ticks up. It looks like nothing, but a big part of the
satisfaction comes from that loop. Get it wrong and pickups feel sticky or laggy, or they
tank the frame rate once 300 gems are lying on the floor.

This tutorial builds it in Godot 4: an XP gem scene, a magnet area on the player, a smooth
pull that speeds up, and an XP component with a level curve that a UI bar can listen to.

Step 1: the gem scene

Create xp_gem.tscn with this tree:

XPGem (Area2D)
- Sprite2D
- CollisionShape2D (small circle, radius ~6)

Put the gem on its own physics layer, for example layer 5 "pickups", with no mask.
The gem doesn't need to detect anything. The player's areas will detect it.

# xp_gem.gd
extends Area2D

@export var value := 1

var target: Node2D = null
var speed := 0.0

const ACCEL := 900.0      # px/s² — how fast the pull ramps up
const MAX_SPEED := 700.0

func attract(to: Node2D) -> void:
    if target == null:
        target = to

func _physics_process(delta: float) -> void:
    if target == null:
        return
    if not is_instance_valid(target):
        target = null
        return
    speed = min(speed + ACCEL * delta, MAX_SPEED)
    global_position = global_position.move_toward(target.global_position, speed * delta)

The acceleration is the important part. A constant speed looks robotic. Starting at zero
and ramping up gives the little "pop then whoosh" players expect.

Step 2: two areas on the player

The player needs two Area2D children, both with mask = layer 5:

MagnetArea: big circle (radius ~80). It decides when a gem starts flying.
CollectArea: small circle (radius ~12). It decides when a gem is absorbed.

Keeping them separate lets you upgrade the magnet radius without changing how close a gem
has to get before it counts.

# player.gd (relevant part)
extends CharacterBody2D

@onready var magnet_shape: CollisionShape2D = $MagnetArea/CollisionShape2D
@onready var xp: XPComponent = $XPComponent

func _ready() -> void:
    $MagnetArea.area_entered.connect(_on_magnet_area_entered)
    $CollectArea.area_entered.connect(_on_collect_area_entered)

func _on_magnet_area_entered(area: Area2D) -> void:
    if area.has_method("attract"):
        area.attract(self)

func _on_collect_area_entered(area: Area2D) -> void:
    if area.has_method("attract"):
        xp.add(area.value)
        area.queue_free()

func set_magnet_radius(r: float) -> void:
    (magnet_shape.shape as CircleShape2D).radius = r

One gotcha: shapes are shared resources. If several scenes use the same CircleShape2D,
growing it on one player grows it on all of them. Tick Local to Scene on the shape (or
duplicate() it in _ready) before changing the radius at runtime.

Step 3: drop gems when enemies die

In your enemy's death code, spawn the gem with call_deferred. Death usually happens
inside a physics callback, and adding an Area2D during one triggers the
"Can't change this state while flushing queries" error.

# enemy.gd
const GEM := preload("res://xp_gem.tscn")

@export var xp_value := 1

func die() -> void:
    var gem := GEM.instantiate()
    gem.value = xp_value
    gem.global_position = global_position
    get_tree().current_scene.add_child.call_deferred(gem)
    queue_free()

Step 4: the XP component and level curve

Keep the numbers out of the player script. A small component does the math and only
emits signals, so the UI, the upgrade screen and the audio can each react on their own.

# xp_component.gd
class_name XPComponent
extends Node

signal xp_changed(current: int, needed: int)
signal leveled_up(new_level: int)

@export var base_needed := 5
@export var growth := 1.25   # each level needs 25% more

var level := 1
var current := 0

func needed_for(lvl: int) -> int:
    return int(round(base_needed * pow(growth, lvl - 1)))

func add(amount: int) -> void:
    current += amount
    # while, not if: one big gem can be worth several levels
    while current >= needed_for(level):
        current -= needed_for(level)
        level += 1
        leveled_up.emit(level)
    xp_changed.emit(current, needed_for(level))

That while is the most common bug in hand-rolled XP code. With if, a gem worth 40 XP at
level 1 gives one level and leaves the bar over 100%.

Step 5: the XP bar

A ProgressBar (or TextureProgressBar) at the top of the screen, driven only by the
signal:

# xp_bar.gd
extends ProgressBar

@export var xp_path: NodePath

func _ready() -> void:
    var xp: XPComponent = get_node(xp_path)
    xp.xp_changed.connect(_on_xp_changed)
    _on_xp_changed(xp.current, xp.needed_for(xp.level))

func _on_xp_changed(current: int, needed: int) -> void:
    max_value = needed
    create_tween().tween_property(self, "value", current, 0.15)

The short tween makes the bar slide instead of snap. On level-up it drops back toward zero
and refills, so the player can actually see it happen.

Step 6: survive 300 gems on screen

Late in a run, gems pile up faster than the player collects them. Three cheap fixes:

Merge on the floor. If more than ~150 gems exist, spawn the new one's value into the nearest existing gem instead of creating another node.
Don't run idle gems. Call set_physics_process(false) in the gem's _ready() and turn it back on in attract(). Then only gems that are flying cost anything per frame.
Vacuum pickup. A rare drop that calls attract(player) on every node in a "gems" group clears the floor and feels great.

Wrapping up

That's the whole loop: gem drops, magnet pull with acceleration, collect, XP curve with a
while, bar that tweens. What usually comes next is the level-up draft (pick 1 of 3
upgrades), weapons that scale with it, and waves that ramp up. That's where a small
prototype turns into a lot of systems to keep in sync. If you'd rather start from a
version where all of that is already wired together and data-driven, the Saltmire Survivors
Template ships it as a playable Godot 4 project.

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-xp-gem-magnet-pickup.html

What I learned making a smooth 2D camera follow in Godot 4

saltmire — Fri, 09 Oct 2026 12:27:27 +0000

A 2D camera looks like a five-minute job. Drop a Camera2D under the player, tick a box,
done. Then the sprite starts to shimmer, the camera shows the grey void past the edge of
the level, and every respawn swooshes across the whole map. Here is what I learned making
the camera feel right, in the order the problems showed up.

Lesson 1: a child camera is fine — until it isn't

The fastest setup is a Camera2D as a child of the player. It follows perfectly because
it is the player's transform. That's also the problem: when the player is freed on
death, the camera goes with it and the view snaps to the origin for a frame.

What I use now is a camera that lives in the level and chases a target:

extends Camera2D

@export var target: Node2D

func _physics_process(_delta: float) -> void:
    if is_instance_valid(target):
        global_position = target.global_position

The camera survives the player, can be pointed at a boss or a cutscene marker, and the
is_instance_valid check means a freed target just leaves the camera where it was.

Lesson 2: smoothing jitter is a timing problem, not a speed problem

I turned on position_smoothing_enabled, and the player sprite started to vibrate while
running. I spent too long tweaking position_smoothing_speed. No value fixed it.

The cause: the player moves in _physics_process (60 Hz by default) and the camera was
updating at the render rate. On a 144 Hz monitor they disagree on most frames, and
smoothing makes the mismatch visible. Make both run on the same clock:

func _ready() -> void:
    process_callback = Camera2D.CAMERA2D_PROCESS_PHYSICS
    position_smoothing_enabled = true
    position_smoothing_speed = 6.0

That fixed 90% of it. On Godot 4.3+, turning on Project Settings → Physics → Common →
Physics Interpolation fixed the rest, because it renders the in-between positions
for both the player and the camera. If you use pixel art, also check
rendering/2d/snap/snap_2d_transforms_to_pixel — sub-pixel camera positions make
pixel sprites shimmer even when the timing is right.

Lesson 3: read the limits from the level instead of typing them in

I hand-typed limit_right = 3200 for the first level. The second level was a different
size, and I forgot. The tilemap already knows how big the level is:

func fit_to_tilemap(layer: TileMapLayer) -> void:
    var used := layer.get_used_rect()
    var cell := layer.tile_set.tile_size
    var top_left := layer.to_global(Vector2(used.position * cell))
    var bottom_right := layer.to_global(Vector2(used.end * cell))
    limit_left = int(top_left.x)
    limit_top = int(top_left.y)
    limit_right = int(bottom_right.x)
    limit_bottom = int(bottom_right.y)

Two details I got wrong first. Limits are in global coordinates, so a tilemap that
isn't at the origin needs the to_global call. And if the level is smaller than the
screen, Godot can't satisfy both limits at once, so one side wins and the level sits
off-centre. For small rooms, I skip the limits and centre the camera on the room.

Turn on limit_smoothed = true too. Without it, the camera slides smoothly everywhere
except at the edge, where it suddenly stops dead.

Lesson 4: teleports need `reset_smoothing()`

With smoothing on, every respawn, door and checkpoint made the camera glide across the
whole level to catch up. It looks like a bug because it is one. After moving the target
instantly, tell the camera to jump too:

func snap_to_target() -> void:
    global_position = target.global_position
    reset_smoothing()

I call this from the respawn and from scene load. Calling it from _ready() alone
wasn't enough, because the target sometimes got its spawn position a frame later, so
I added a call_deferred("snap_to_target") there.

Lesson 5: look-ahead and screen shake both want `offset`

Platformers and top-down shooters feel better when the camera leans in the direction
you're moving, so you can see what's coming. The clean way is offset, because it
doesn't fight the smoothing on position:

@export var look_ahead := 48.0
@export var look_speed := 4.0

func _physics_process(delta: float) -> void:
    if not is_instance_valid(target):
        return
    global_position = target.global_position
    var dir := Vector2.ZERO
    var vel = target.get("velocity")  # null if the target has no velocity
    if vel is Vector2:
        dir = vel.normalized()
    offset = offset.lerp(dir * look_ahead, look_speed * delta)

Then I added screen shake, which also writes to offset. The two overwrote each
other every frame. Shake vanished while running, and stopping mid-shake left the camera
crooked. The fix is to keep each effect in its own variable and add them together in one
place:

var _look := Vector2.ZERO
var _shake := Vector2.ZERO

func _physics_process(delta: float) -> void:
    # ...update _look as above, update _shake from your shake code...
    offset = _look + _shake

That one line keeps both effects working.

What I'd do differently starting over

Start with a free-standing camera that follows a target, set to the physics clock. Read
limits from the level, and write snap_to_target() before the first respawn exists.
Treat offset as shared: anything that moves the view adds its own term instead of
writing directly.

That last point is where most of my camera bugs came from. Shake, hit-stop and
look-ahead all touch the same few properties at the same moment, and mixing them by
hand gets fiddly fast. That combination is what I eventually packaged up, so I stopped
rewriting it every project.

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-camera2d-follow-smoothing-limits.html

GPUParticles2D vs CPUParticles2D in Godot 4 — which and when

saltmire — Wed, 07 Oct 2026 12:31:13 +0000

You open the Add Node dialog, type "particles", and Godot 4 offers you two nodes that
look identical in the viewport: GPUParticles2D and CPUParticles2D. Both emit
sprites, both have amount, lifetime, one_shot and explosiveness. The names tell
you where the simulation runs, but not what that means for your game. Here's the
practical difference, and the rule I use to pick.

GPUParticles2D: the simulation lives in a shader

GPUParticles2D moves every particle on the graphics card. Its behaviour comes from a
ParticleProcessMaterial — velocity, gravity, scale curves, color ramps — which Godot
compiles into a shader.

var p := GPUParticles2D.new()
var mat := ParticleProcessMaterial.new()
mat.direction = Vector3(0, -1, 0)
mat.spread = 45.0
mat.initial_velocity_min = 120.0
mat.initial_velocity_max = 220.0
mat.gravity = Vector3(0, 400, 0)
p.process_material = mat
p.amount = 16
p.lifetime = 0.5
p.one_shot = true
p.explosiveness = 1.0
add_child(p)
p.restart()

What it gives you that the CPU node doesn't: turbulence, collision against
LightOccluder2D shapes, sub-emitters (a spark that spawns smoke when it dies),
trails, and custom particle shaders. It also scales: thousands of particles cost
the CPU almost nothing, because the CPU never touches them.

What it costs you:

A visibility_rect you must maintain. The node is culled by that rectangle, and the default is small. Particles that fly outside it simply vanish.
A first-use hitch. The process material is a shader, and shaders compile the first time they're used. On many machines the very first explosion stutters for a frame. You can hide it by firing each effect once off-screen during your loading screen.
Renderer quirks. GPU particles only work on the Compatibility renderer (the one web exports and many low-end Android devices use) since Godot 4.2, and that path is less battle-tested than Forward+. If you target the web, test there early.

CPUParticles2D: the simulation lives in a script loop

CPUParticles2D does the same job in engine code on the CPU. There is no process
material — every setting is a property directly on the node:

var p := CPUParticles2D.new()
p.direction = Vector2(0, -1)
p.spread = 45.0
p.initial_velocity_min = 120.0
p.initial_velocity_max = 220.0
p.gravity = Vector2(0, 400)
p.amount = 16
p.lifetime = 0.5
p.one_shot = true
p.explosiveness = 1.0
add_child(p)
p.restart()

That's the whole point of it: it behaves the same everywhere. Forward+, Mobile,
Compatibility, web, old integrated GPUs — the simulation is identical because it never
depended on the graphics card. There's no shader to compile, so no first-burst hitch,
and no visibility_rect to babysit — the bounds are computed for you.

The trade-off is a smaller feature set (no turbulence, collision, sub-emitters or trails)
and a cost that grows with particle count. Every particle is updated on the main CPU
every frame. Sixteen sparks per hit is nothing. Ten thousand snowflakes is not.

The comparison

	GPUParticles2D	CPUParticles2D
Where it simulates	GPU (shader)	CPU (engine loop)
Configuration	`ParticleProcessMaterial` resource	properties on the node
Cost of 10,000 particles	low on CPU	high on CPU
Cost of 15 small bursts	a draw + a shader each	tiny
Turbulence, collision, sub-emitters, trails	yes	no
First-use shader hitch	yes (pre-warm it)	no
`visibility_rect` culling	manual, easy to get wrong	automatic
Compatibility renderer / web	supported since 4.2, test it	works everywhere
`restart()`, `one_shot`, `finished` signal	yes	yes

Switching costs one click

You don't have to commit forever. Select a GPUParticles2D in the editor and the
toolbar's GPUParticles2D menu has Convert to CPUParticles2D. The CPU node has the
reverse option in its own toolbar menu. Features the CPU node lacks are dropped in the
conversion, so commit the scene first and compare.

If you build effects in code and ship to several platforms, you can also pick at runtime:

func make_burst_node() -> Node2D:
    var method: String = ProjectSettings.get_setting("rendering/renderer/rendering_method")
    if method == "gl_compatibility" or OS.has_feature("web"):
        return CPUParticles2D.new()
    return GPUParticles2D.new()

If you go this route, keep your tuning values in one place (a dictionary or a custom
resource) so both branches read the same numbers.

The rule that decides it

Ask two questions:

Is it a big, long-lived or fancy effect? Rain, snow, a fog bank, a magic vortex with turbulence, sparks that bounce off walls. That's GPUParticles2D.
Is it a small, short burst that fires a lot? Hit sparks, pickup glitter, dust from a footstep, a coin pop. That's CPUParticles2D. Especially if you export to the web.

Most 2D action games end up with both: a few big GPU systems for ambience, and many tiny
CPU bursts for feedback. The bursts are where the work really piles up, though — every
new enemy hit, pickup and death wants its own tuned node, its own one_shot setup, and
its own cleanup when it's done.

That's the part Saltmire Spark takes off your plate. It's a free, MIT-licensed autoload
that fires a tuned 2D burst in one line (Spark.burst(pos, "hit")) and frees itself
afterwards. It doesn't use either particle node — the particles are drawn procedurally —
so there's no process material, no visibility_rect and no renderer difference to think
about.

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-gpuparticles2d-vs-cpuparticles2d.html

Fixing 'previously freed instance' errors in Godot 4 combat code

saltmire — Mon, 05 Oct 2026 12:27:59 +0000

Combat is where Godot 4 projects start crashing for the first time. Everything works
until two things die in the same frame, or a homing bullet outlives its target, and the
debugger stops on one of these:

Trying to call a function on a previously freed instance.
Invalid access to property or key 'global_position' on a base object of type 'previously freed'.
Cannot call method 'take_damage' on a null value.
Resumed function 'flash()' after await, but class instance is gone.

(Exact wording shifts a little between 4.x versions — older builds say
Invalid get index ... (on base: 'previously freed') — but the causes are the same.)

"Previously freed" means your variable still points at a node that queue_free() already
deleted. The reference isn't null — it's a dangling pointer, so if target: and
if target != null: can both let it through. Here are the four ways combat code ends up
holding one, ordered by how often they show up.

1. A stored reference outlives the enemy

Symptom. A homing projectile, a turret or an enemy AI crashes a few frames after
its target dies.

Cause. You saved the target in a variable (var target: Node2D) and kept using it.
Something else killed the target and called queue_free(). Your variable never heard
about it.

Fix. Check is_instance_valid() before every use — it's the only check that catches
a freed node:

var target: Node2D

func _physics_process(delta: float) -> void:
    if not is_instance_valid(target):
        target = null
        _pick_new_target()
        return
    var dir := global_position.direction_to(target.global_position)
    velocity = dir * speed
    move_and_slide()

If many systems track the same enemy, clear the reference at the source instead of
checking everywhere. tree_exiting fires right before the node leaves the tree:

func set_target(t: Node2D) -> void:
    target = t
    t.tree_exiting.connect(func(): target = null, CONNECT_ONE_SHOT)

2. The reference is used again after an `await`

Symptom. Hit-flash or knockback code crashes only sometimes, usually on the killing
blow.

Cause. await pauses your function. Anything can happen while it's paused —
including the enemy dying. When the function resumes, every node reference captured
before the await is suspect.

# crashes when the hit also kills the enemy
func hit_flash(enemy: Node2D) -> void:
    enemy.modulate = Color.RED
    await get_tree().create_timer(0.1).timeout
    enemy.modulate = Color.WHITE   # enemy may be gone by now

Fix. Treat every await as a checkpoint and re-validate after it:

func hit_flash(enemy: Node2D) -> void:
    enemy.modulate = Color.RED
    await get_tree().create_timer(0.1).timeout
    if not is_instance_valid(enemy):
        return
    enemy.modulate = Color.WHITE

Even better: put the flash on the enemy itself, as a tween on its own sprite. A tween
created with the node's create_tween() is bound to that node and dies with it, so there
is nothing left to resume.

3. Two hits land in the same physics frame — the enemy dies twice

Symptom. No crash, but a shotgun blast drops double XP, plays the death sound twice,
or increments the kill counter by two.

Cause. queue_free() doesn't delete immediately — it deletes at the end of the frame.
If two bullets overlap the enemy in the same frame, both callbacks run while the node is
still perfectly valid, and both see hp <= 0.

Fix. Guard the death path with a flag (or is_queued_for_deletion()):

var dead := false

func take_damage(amount: float) -> void:
    if dead:
        return
    hp -= amount
    if hp <= 0.0:
        dead = true
        died.emit()
        drop_xp()
        queue_free()

Bullets that hit should also stop themselves right away — set_deferred("monitoring", false)
then queue_free() — so a single bullet can't register on two enemies in its last frame.

4. `get_parent()` chains return something you didn't expect

Symptom. Cannot call method 'take_damage' on a null value, or
Nonexistent function 'take_damage' in base 'Area2D'.

Cause. The attacker reaches into the victim:
area.get_parent().take_damage(10). That works until one enemy has its hurtbox nested
one level deeper, or the parent is a pooled node that's already been detached.

Fix. Don't make the attacker know the victim's tree. Check the contract instead of
the shape:

func _on_area_entered(area: Area2D) -> void:
    var victim := area.owner
    if is_instance_valid(victim) and victim.has_method("take_damage"):
        victim.take_damage(damage)

The pattern that removes most of these

Notice what causes 1, 2 and 4 have in common: the attacker holds a reference to the
victim and calls into it. Flip that around and most of the bugs disappear. The
attacker only overlaps an area; the victim's own hurtbox emits a signal; the victim
handles its own damage, death and flash. When the victim is freed, its signal
connections go with it — nobody is left holding a stale pointer.

# on the enemy — it owns its own death
func _ready() -> void:
    $Hurtbox.hurt.connect(_on_hurt)

func _on_hurt(amount: float, _source: Node, knockback: Vector2) -> void:
    take_damage(amount)
    velocity += knockback

That's exactly the shape Saltmire Hitbox is built around: drop a Hitbox2D on the attack
and a Hurtbox2D on anything that can be hurt, and damage arrives as a hurt signal on
the victim's side. The hitbox never calls into your enemy's script, one_shot stops a
lingering swing from hitting the same target every frame, and i-frames are one inspector
field. You still want the dead flag from cause 3 in your own death code — but the
dangling-reference class of crashes mostly stops existing.

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-previously-freed-instance-error.html

7 Godot 4 collision layer and mask tips that save you an afternoon of debugging

saltmire — Sat, 03 Oct 2026 12:29:00 +0000

Collision layers and masks are the Godot 4 feature everybody "gets" in five minutes and
then fights for the rest of the project. The player walks through a wall, the enemy's
sword hits other enemies, a raycast sees nothing. Nine times out of ten the physics is
fine — the bits are wrong.

Here are seven tips that make the bits boring.

1. Layer is what you are, mask is what you look for

That is the whole rule. collision_layer says which groups this object belongs to.
collision_mask says which groups this object scans for. Write it down for your game
before you click a single checkbox:

Node	Layer (what it is)	Mask (what it looks for)
Player body	player	world, enemy
Enemy body	enemy	world, player
Player sword (Area2D)	—	enemy_hurtbox
Enemy hurtbox (Area2D)	enemy_hurtbox	—
Walls / floor	world	—

Notice the empty cells. Static walls don't need to look for anything — things look for
them. A hurtbox just needs to exist on a layer. Most layer bugs come from filling in
every cell "just in case".

2. Name your layers before you use them

Open Project Settings → General → Layer Names → 2D Physics and give layers 1–5 real
names: world, player, enemy, player_hurtbox, enemy_hurtbox. The inspector's
layer grid then shows those names on hover, and "why is the sword on layer 4" becomes
a question you can answer by reading.

You can read the names back in code, which is handy for a debug overlay:

func layer_name(n: int) -> String:
    return ProjectSettings.get_setting("layer_names/2d_physics/layer_%d" % n, "")

3. The inspector counts from 1, the raw property is a bitmask

This is the trap that costs the afternoon. In the inspector, layer 3 is the third box.
In code, collision_layer is a 32-bit bitmask — so this:

collision_layer = 3 # looks like "layer 3"

actually means layers 1 and 2 (binary 011). Layer 3 alone is 4. Stop doing the
arithmetic in your head and use the 1-based helpers, which match the inspector:

collision_layer = 0
set_collision_layer_value(3, true)   # only layer 3
set_collision_mask_value(1, true)    # also scan layer 1
print(get_collision_mask_value(1))   # true

When something is off, print the mask in binary and read it right-to-left:

print(name, " layer=", String.num_int64(collision_layer, 2),
        " mask=", String.num_int64(collision_mask, 2))

4. Keep the numbers in one script

Once you set layers from code (spawned projectiles, a hitbox that changes team), magic
numbers spread fast. Put them in one place:

# res://physics_layers.gd
class_name PhysicsLayers

const WORLD := 1
const PLAYER := 2
const ENEMY := 3
const PLAYER_HURTBOX := 4
const ENEMY_HURTBOX := 5

# a bullet fired by the player
func _ready() -> void:
    collision_layer = 0
    collision_mask = 0
    set_collision_mask_value(PhysicsLayers.WORLD, true)
    set_collision_mask_value(PhysicsLayers.ENEMY_HURTBOX, true)

Keep these numbers in sync with the names from tip 2 and you never have to open the
project settings to remember what 5 meant.

5. Area2D detection is one-way — think from the detector's side

For an Area2D to report something in area_entered or body_entered, the Area2D's
mask must include the other object's layer. The other side's mask is irrelevant for
that signal. So for a sword hitting a hurtbox:

the sword (the one listening) masks enemy_hurtbox,
the hurtbox sits on layer enemy_hurtbox and keeps monitorable = true.

Listening from the hurtbox side instead works too — just mirror it. Pick one side.
Masking both ways and applying damage in both signal handlers is how one slash ends
up dealing damage twice.

Moving bodies follow the same idea: move_and_slide() only stops against objects whose
layer is in the moving body's mask. If the player walks through a wall, check the
player's mask for world, not the wall.

6. Raycasts and ShapeCasts have their own mask (and skip areas)

RayCast2D and ShapeCast2D don't care what layer their parent is on. They have their
own collision_mask, and by default collide_with_areas is false — so a ray aimed
at a hurtbox sees nothing. The same goes for direct space queries:

func line_of_sight(from: Vector2, to: Vector2) -> bool:
    var query := PhysicsRayQueryParameters2D.create(from, to)
    query.collision_mask = 1 << (PhysicsLayers.WORLD - 1) # bitmask, see tip 3
    query.exclude = [get_rid()]
    var hit := get_world_2d().direct_space_state.intersect_ray(query)
    return hit.is_empty()

Note the 1 << (n - 1): the query wants the raw bitmask, not the 1-based number.

7. TileMap walls get their layer from the TileSet

Setting the layer on a TileMapLayer node's inspector won't help if the walls still
pass through things. Tile collision lives in the TileSet resource: open it, look
under Physics Layers, and set collision_layer / collision_mask there. Each
physics layer of the TileSet has its own pair — a one-way platform layer and a solid
wall layer can sit on different bits.

Turn on Debug → Visible Collision Shapes while you check; if the tile shapes don't
draw, the tiles have no collision polygons painted yet and no layer setting will fix it.

The pattern behind all seven

Every tip above is bookkeeping: deciding, once, who is what and who looks for whom, and
then never letting a raw number decide it again. For combat specifically, that table
in tip 1 is the part people rebuild in every project — hitbox masks, hurtbox layers,
which team hits which.

Saltmire Hitbox Lite is a free, MIT Hitbox2D / Hurtbox2D pair that handles that
table for you: you set a team on each box and it wires the layers, so a player's sword
only finds enemy hurtboxes without you touching a single checkbox. If you'd rather keep
your own layer plan, the tips above are everything it does under the hood.

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

Originally published at https://saltmire.github.io/godot-4-collision-layers-masks-tips.html

How to save game settings (volume, fullscreen, keybinds) in Godot 4 with ConfigFile

saltmire — Thu, 01 Oct 2026 12:26:35 +0000

Every player opens the options menu, turns the music down, and expects it to stay down
next time. In Godot 4 the right tool for that is not your save system and not JSON — it's
ConfigFile, a tiny INI-style file that Godot reads and writes in one call.

This tutorial builds a Settings autoload that stores volume, fullscreen, vsync and
keyboard rebinds in user://settings.cfg and re-applies them every time the game starts.

Why ConfigFile for settings

It's human-readable ([audio] / master=0.8), so you can debug it by opening the file.
get_value(section, key, default) gives you a fallback for free — a missing key never crashes.
Settings are per machine, not per save slot. Keeping them out of your game save means deleting a slot never resets the player's volume.

Step 1: the Settings autoload

Create settings.gd and register it in Project → Project Settings → Globals → Autoload
with the name Settings.

extends Node

const PATH := "user://settings.cfg"

var config := ConfigFile.new()

func _ready() -> void:
    var err := config.load(PATH)
    if err != OK and err != ERR_FILE_NOT_FOUND:
        push_warning("Settings: could not read %s (error %d), using defaults" % [PATH, err])
    apply_all()

func get_setting(section: String, key: String, default_value: Variant) -> Variant:
    return config.get_value(section, key, default_value)

func set_setting(section: String, key: String, value: Variant) -> void:
    config.set_value(section, key, value)

func save() -> void:
    var err := config.save(PATH)
    if err != OK:
        push_error("Settings: save failed (error %d)" % err)

func apply_all() -> void:
    apply_volume("Master")
    apply_volume("Music")
    apply_volume("SFX")
    apply_display()
    apply_keybinds()

ERR_FILE_NOT_FOUND on the very first launch is normal — there's no file yet, so every
get_value falls back to its default.

Step 2: audio volume per bus

Store volume as a linear 0.0–1.0 value (what a slider gives you) and convert to
decibels only when applying. Make sure the buses Music and SFX exist in the Audio tab,
or skip them.

func apply_volume(bus_name: String) -> void:
    var idx := AudioServer.get_bus_index(bus_name)
    if idx == -1:
        return
    var linear: float = get_setting("audio", bus_name.to_lower(), 1.0)
    AudioServer.set_bus_volume_db(idx, linear_to_db(linear))
    AudioServer.set_bus_mute(idx, linear <= 0.001)

The mute line matters: linear_to_db(0.0) is -inf, and muting the bus at zero is cleaner
than relying on it.

Step 3: fullscreen and vsync

func apply_display() -> void:
    var fullscreen: bool = get_setting("display", "fullscreen", false)
    DisplayServer.window_set_mode(
        DisplayServer.WINDOW_MODE_FULLSCREEN if fullscreen
        else DisplayServer.WINDOW_MODE_WINDOWED)

    var vsync: bool = get_setting("display", "vsync", true)
    DisplayServer.window_set_vsync_mode(
        DisplayServer.VSYNC_ENABLED if vsync else DisplayServer.VSYNC_DISABLED)

On the web export, fullscreen requires a user gesture, so call this from a button press
rather than only at startup.

Step 4: keyboard rebinds that persist

Storing whole InputEvent objects works but makes the file noisy. For keyboard bindings,
the physical keycode (an int) is enough and survives keyboard layout changes.

const REBINDABLE := ["move_left", "move_right", "jump", "attack"]

func rebind(action: String, event: InputEventKey) -> void:
    # Replace only the keyboard event; keep gamepad bindings intact.
    for old in InputMap.action_get_events(action):
        if old is InputEventKey:
            InputMap.action_erase_event(action, old)
    InputMap.action_add_event(action, event)
    set_setting("keybinds", action, event.physical_keycode)

func apply_keybinds() -> void:
    for action in REBINDABLE:
        var code: int = get_setting("keybinds", action, 0)
        if code == 0:
            continue  # never rebound — keep the Input Map default
        var ev := InputEventKey.new()
        ev.physical_keycode = code
        for old in InputMap.action_get_events(action):
            if old is InputEventKey:
                InputMap.action_erase_event(action, old)
        InputMap.action_add_event(action, ev)

To capture the new key, put a "press any key" state in your rebind button and grab the
next InputEventKey in _unhandled_input, then call Settings.rebind(action, event).

Step 5: wire the options menu

extends Control

@onready var music_slider: HSlider = %MusicSlider
@onready var fullscreen_check: CheckButton = %FullscreenCheck

func _ready() -> void:
    music_slider.value = Settings.get_setting("audio", "music", 1.0)
    fullscreen_check.button_pressed = Settings.get_setting("display", "fullscreen", false)

    music_slider.value_changed.connect(func(v: float) -> void:
        Settings.set_setting("audio", "music", v)
        Settings.apply_volume("Music"))
    music_slider.drag_ended.connect(func(_changed: bool) -> void:
        Settings.save())

    fullscreen_check.toggled.connect(func(on: bool) -> void:
        Settings.set_setting("display", "fullscreen", on)
        Settings.apply_display()
        Settings.save())

Set the slider's range to 0–1 with a step of 0.05. Apply on every value_changed
so the player hears the change live, but only write to disk on drag_ended — no need to
hit the file system 60 times a second.

Common mistakes

Saving to res://. It's read-only in exported games. Always use user://.
Applying settings in the menu scene only. If the menu isn't loaded, nothing applies. That's why apply_all() runs in the autoload's _ready().
Storing decibels. Sliders feel wrong in dB; store linear, convert on apply.
Mixing settings into the save slot. One file per machine for settings, one per slot for progress.

Wrapping up

ConfigFile covers the options menu. Your actual game progress — player stats, inventory,
unlocked levels — is a different job, and that's the part where writing your own
serialization gets tedious. If you'd rather save and load that state in a single call,
Saltmire Save Lite is a free, MIT-licensed add-on that does exactly that.

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-settings-configfile.html

Godot 4 change_scene_to_file not working? 4 causes and fixes

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Fix. First, stop ignoring the return value:

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

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

@export var next_scene: PackedScene

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

4. The change fires twice

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

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

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

var _leaving := false

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

What all four have in common

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

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

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

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

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

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

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

Lesson 1: health is not the player's job

The first version always lives inside the player script:

var health := 100

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

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

class_name HealthComponent
extends Node

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

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

func _ready() -> void:
    current = max_health

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

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

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

Lesson 2: the health bar should never ask for health

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

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

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

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

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

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

A timer inside the component fixes both at the source:

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

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

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

Lesson 4: "died" must fire exactly once

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

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

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

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

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

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

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

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

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

What I'd do differently starting over

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

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

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

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

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

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

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

Area2D: an overlap you listen to

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

extends Area2D # the sword's hitbox

@export var damage := 10

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

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

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

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

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

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

RayCast2D: a line, checked right now

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

@onready var ray: RayCast2D = $RayCast2D

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

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

ShapeCast2D: a shape, swept and checked right now

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

@onready var cast: ShapeCast2D = $ShapeCast2D

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

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

The comparison

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

The rule that decides it

Ask two questions:

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

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

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

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

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

DEV Community: saltmire

JSON vs ConfigFile vs Resource in Godot 4 — which save format and when

JSON: portable, readable, type-lossy

ConfigFile: Variants that round-trip, in an INI file

Resource: typed, autocompleted, and the one with a security warning

The comparison

The rule

Fixing set_shader_parameter not working in Godot 4

1. You're calling the Godot 3 name

2. The material is shared between every instance

3. The uniform name doesn't match — and Godot won't tell you

4. A tween is animating the wrong property path

5. use_parent_material is on

The quick triage order

7 Godot 4 melee attack mistakes (and the fix for each)

1. The hitbox is on all the time

2. One swing hits the same enemy three times

3. The player hits themselves

4. "Function blocked during in/out signal"

5. The hitbox doesn't flip with the character

6. The damage logic lives in the sword

7. The active window is one frame long

The pattern behind all seven

How to make XP gems with a pickup magnet and level-up bar in Godot 4

Step 1: the gem scene

Step 2: two areas on the player

Step 3: drop gems when enemies die

Step 4: the XP component and level curve

Step 5: the XP bar

Step 6: survive 300 gems on screen

Wrapping up

What I learned making a smooth 2D camera follow in Godot 4

Lesson 1: a child camera is fine — until it isn't

Lesson 2: smoothing jitter is a timing problem, not a speed problem

Lesson 3: read the limits from the level instead of typing them in

Lesson 4: teleports need reset_smoothing()

Lesson 5: look-ahead and screen shake both want offset

What I'd do differently starting over

GPUParticles2D vs CPUParticles2D in Godot 4 — which and when

GPUParticles2D: the simulation lives in a shader

CPUParticles2D: the simulation lives in a script loop

The comparison

Switching costs one click

The rule that decides it

Fixing 'previously freed instance' errors in Godot 4 combat code

1. A stored reference outlives the enemy

2. The reference is used again after an await

3. Two hits land in the same physics frame — the enemy dies twice

4. get_parent() chains return something you didn't expect

The pattern that removes most of these

7 Godot 4 collision layer and mask tips that save you an afternoon of debugging

1. Layer is what you are, mask is what you look for

2. Name your layers before you use them

3. The inspector counts from 1, the raw property is a bitmask

4. Keep the numbers in one script

5. Area2D detection is one-way — think from the detector's side

6. Raycasts and ShapeCasts have their own mask (and skip areas)

7. TileMap walls get their layer from the TileSet

The pattern behind all seven

How to save game settings (volume, fullscreen, keybinds) in Godot 4 with ConfigFile

Why ConfigFile for settings

Step 1: the Settings autoload

Step 2: audio volume per bus

Step 3: fullscreen and vsync

Step 4: keyboard rebinds that persist

Step 5: wire the options menu

Common mistakes

Wrapping up

Godot 4 change_scene_to_file not working? 4 causes and fixes

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

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

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

4. The change fires twice

What all four have in common

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

Lesson 1: health is not the player's job

Lesson 2: the health bar should never ask for health

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

Lesson 4: "died" must fire exactly once

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

5. `use_parent_material` is on

Lesson 4: teleports need `reset_smoothing()`

Lesson 5: look-ahead and screen shake both want `offset`

2. The reference is used again after an `await`

4. `get_parent()` chains return something you didn't expect