Index of every page on this site: llms.txt
All skills
jame581 avatar

/godot-optimization

@426e8ab
by Jan Mesarčjame581/godotprompter979 stars
63
Run it yourself

Use when optimizing Godot games — profiler, draw calls, physics tuning, memory management, and common bottlenecks

Use this Skill: https://skilld.dev/gh/jame581/godotprompter/godot-optimization

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesmemory-management.md

≈2.7k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Memory Management & Object Pooling

Reference for skills/godot-optimization/SKILL.md — runtime memory monitoring, ResourceLoader caching, freeing semantics, and object pooling for high-churn entities.

← Back to SKILL.md


Memory Management

Monitoring Memory at Runtime

# Query engine memory monitors via Performance singleton
func _print_memory_stats() -> void:
    var static_mem  := Performance.get_monitor(Performance.MEMORY_STATIC)
    var peak_mem    := Performance.get_monitor(Performance.MEMORY_STATIC_MAX)
    var video_ram   := Performance.get_monitor(Performance.RENDER_VIDEO_MEM_USED)
    var obj_count   := Performance.get_monitor(Performance.OBJECT_COUNT)
    var node_count  := Performance.get_monitor(Performance.OBJECT_NODE_COUNT)

    print("Static RAM : %.2f MB" % (static_mem   / 1_048_576.0))
    print("Peak RAM   : %.2f MB" % (peak_mem     / 1_048_576.0))
    print("Video RAM  : %.2f MB" % (video_ram    / 1_048_576.0))
    print("Objects    : %d" % obj_count)
    print("Nodes      : %d" % node_count)

C#:

// Query engine memory monitors via Performance singleton
private void PrintMemoryStats()
{
    double staticMem = Performance.GetMonitor(Performance.Monitor.MemoryStatic);
    double peakMem = Performance.GetMonitor(Performance.Monitor.MemoryStaticMax);
    double videoRam = Performance.GetMonitor(Performance.Monitor.RenderVideoMemUsed);
    double objCount = Performance.GetMonitor(Performance.Monitor.ObjectCount);
    double nodeCount = Performance.GetMonitor(Performance.Monitor.ObjectNodeCount);

    GD.Print($"Static RAM : {staticMem / 1_048_576.0:F2} MB");
    GD.Print($"Peak RAM   : {peakMem / 1_048_576.0:F2} MB");
    GD.Print($"Video RAM  : {videoRam / 1_048_576.0:F2} MB");
    GD.Print($"Objects    : {objCount:F0}");
    GD.Print($"Nodes      : {nodeCount:F0}");
}

Watch for MEMORY_STATIC growing between identical scene loads — this usually means a resource is held by a long-lived reference.

ResourceLoader Caching Behaviour

Godot caches every resource loaded via load() or preload() by path. Subsequent loads of the same path return the same instance from cache. This means:

  • Resources are shared by default — modifying one instance modifies all users.
  • Use resource.duplicate() when you need a per-instance copy (e.g. per-enemy stats).
  • The cache does not keep a resource alive: it is freed as soon as its last reference is released, and its cache entry goes with it.
# Shared resource — all enemies use the same stats object (intended for read-only data)
const EnemyStats: Resource = preload("res://data/enemy_stats.tres")

# Per-instance copy — each enemy gets its own mutable copy
func _ready() -> void:
    _stats = EnemyStats.duplicate()
    _stats.health = _stats.max_health  # safe to modify

There is no eviction call and no garbage collector to wait for (in GDScript) — drop every reference and the resource is freed. To get a fresh copy that bypasses the cache:

# A new instance read from disk, not shared with other users of the path.
var fresh := ResourceLoader.load("res://data/enemy_stats.tres", "", ResourceLoader.CACHE_MODE_IGNORE)

For large resources that are only needed temporarily (e.g. a loading-screen video), keep them in a local variable and let it go out of scope — Godot's reference counting will free it.

Freeing Unused Resources

# Nodes: always use queue_free() unless you need synchronous teardown
func _on_enemy_died() -> void:
    queue_free()  # safe — deferred until end of current frame processing

# Nodes: free() is synchronous and immediate — only use when you are certain
# no other code will access the node in the same frame
func _force_remove_node(node: Node) -> void:
    node.free()  # while `node` is emitting: refused in debug builds, undefined behaviour in release

# Non-node RefCounted resources are freed automatically when the last
# reference is released — no manual call needed.
var texture: ImageTexture = ImageTexture.new()
# texture is freed when it goes out of scope or is set to null

# Non-node Object (not RefCounted) — must be freed manually
var raw_obj := Object.new()
raw_obj.free()

C#:

// Nodes: always use QueueFree() unless you need synchronous teardown
private void OnEnemyDied()
{
    QueueFree(); // safe — deferred until end of current frame
}

// Non-node RefCounted resources are freed automatically when the last
// reference is released. In C# the wrapper holds a reference until the GC finalizes it,
// so call Dispose() to release it immediately.
ImageTexture texture = new();
texture.Dispose(); // without this, freed only after the GC collects the wrapper

// Non-node GodotObject (not RefCounted) — must be freed manually
var rawObj = new GodotObject();
rawObj.Free();

queue_free vs free

Method Timing Safe inside callbacks Use when
queue_free() End of current frame Yes Normal node removal
free() Immediate Only if not inside own signal Synchronous teardown, editor tools

Always prefer queue_free() for nodes created during gameplay. free() inside a handler of a signal the same node is emitting is refused in the editor and debug exports ("Object is locked and can't be freed") and the script stops there; release exports skip that check and free the node mid-emission (undefined behaviour, can crash) — use queue_free().


Object Pooling

Calling instantiate() and queue_free() repeatedly for short-lived objects (bullets, hit effects, particles) is expensive because each cycle allocates and deallocates memory and re-runs _ready(). A pool pre-allocates a fixed set of instances and recycles them.

GDScript Pool

# object_pool.gd
class_name ObjectPool
extends Node

@export var scene: PackedScene
@export var initial_size: int = 20
@export var grow_size: int = 10

var _pool: Array[Node] = []

func _ready() -> void:
    _grow(initial_size)

## Return an available instance from the pool, growing the pool if needed.
func get_instance() -> Node:
    for instance in _pool:
        if not instance.is_inside_tree() or not instance.visible:
            _activate(instance)
            return instance
    # Pool exhausted — grow and return one new instance
    push_warning("ObjectPool: pool exhausted, growing by %d" % grow_size)
    _grow(grow_size)
    return get_instance()

## Return an instance to the pool by deactivating it.
func release(instance: Node) -> void:
    instance.visible = false
    instance.set_process(false)
    instance.set_physics_process(false)
    # Move off-screen so it does not interfere with queries
    if instance is Node2D:
        (instance as Node2D).global_position = Vector2(-10_000, -10_000)
    elif instance is Node3D:
        (instance as Node3D).global_position = Vector3(-10_000, -10_000, -10_000)

# --- private ---

func _grow(count: int) -> void:
    for i in count:
        var instance := scene.instantiate()
        add_child(instance)
        instance.visible = false
        instance.set_process(false)
        instance.set_physics_process(false)
        _pool.append(instance)

func _activate(instance: Node) -> void:
    instance.visible = true
    instance.set_process(true)
    instance.set_physics_process(true)

Usage:

# bullet_spawner.gd
@onready var _pool: ObjectPool = $BulletPool

func _fire(direction: Vector2) -> void:
    var bullet: Bullet = _pool.get_instance() as Bullet
    bullet.global_position = $Muzzle.global_position
    bullet.direction = direction
    bullet.speed = 600.0

# In bullet.gd — return self to pool when done
func _on_hit_something() -> void:
    # Do not queue_free — return to pool instead
    _pool.release(self)

C# Pool

// ObjectPool.cs
using Godot;
using System.Collections.Generic;

public partial class ObjectPool : Node
{
    [Export] public PackedScene Scene { get; set; }
    [Export] public int InitialSize { get; set; } = 20;
    [Export] public int GrowSize { get; set; } = 10;

    private readonly List<Node> _pool = new();

    public override void _Ready()
    {
        Grow(InitialSize);
    }

    /// <summary>Returns an available instance from the pool, growing if needed.</summary>
    public T GetInstance<T>() where T : Node
    {
        foreach (var node in _pool)
        {
            if (node is CanvasItem ci && !ci.Visible)
            {
                Activate(node);
                return (T)node;
            }
            if (node is Node3D n3d && !n3d.Visible)
            {
                Activate(node);
                return (T)node;
            }
        }
        GD.PushWarning($"ObjectPool: pool exhausted, growing by {GrowSize}");
        Grow(GrowSize);
        return GetInstance<T>();
    }

    /// <summary>Returns an instance to the pool.</summary>
    public void Release(Node instance)
    {
        if (instance is CanvasItem ci)
        {
            ci.Visible = false;
            if (instance is Node2D n2d)
                n2d.GlobalPosition = new Vector2(-10_000f, -10_000f);
        }
        else if (instance is Node3D n3d)
        {
            n3d.Visible = false;
            n3d.GlobalPosition = new Vector3(-10_000f, -10_000f, -10_000f);
        }
        instance.SetProcess(false);
        instance.SetPhysicsProcess(false);
    }

    private void Grow(int count)
    {
        for (int i = 0; i < count; i++)
        {
            var instance = Scene.Instantiate();
            AddChild(instance);
            if (instance is CanvasItem ci) ci.Visible = false;
            else if (instance is Node3D n3d) n3d.Visible = false;
            instance.SetProcess(false);
            instance.SetPhysicsProcess(false);
            _pool.Add(instance);
        }
    }

    private static void Activate(Node instance)
    {
        if (instance is CanvasItem ci) ci.Visible = true;
        else if (instance is Node3D n3d) n3d.Visible = true;
        instance.SetProcess(true);
        instance.SetPhysicsProcess(true);
    }
}

Usage in C#:

// BulletSpawner.cs
public partial class BulletSpawner : Node2D
{
    [Export] private ObjectPool _pool;

    private void Fire(Vector2 direction)
    {
        var bullet = _pool.GetInstance<Bullet>();
        bullet.GlobalPosition = GetNode<Marker2D>("Muzzle").GlobalPosition;
        bullet.Direction = direction;
    }
}

// Bullet.cs — return to pool instead of QueueFree
public partial class Bullet : CharacterBody2D
{
    [Export] private ObjectPool _pool;
    public Vector2 Direction { get; set; }

    private void OnHitSomething()
    {
        _pool.Release(this);
    }
}

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts7d3 checks · Risk SAFE
  • Gen Agent Trust Hub7d

    The skill provides comprehensive guidance for optimizing Godot engine projects, including performance profiling, draw call reduction, and memory management. No security issues or malicious patterns were detected.

  • Socket7d

    No alerts

  • Snyk7d

    Risk: LOW · No issues

Signed by skilld at 426e8ab. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 6 days ago.

Activeupdated last month

README badge

README badge for jame581/godotprompter/godot-optimization