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.

referencescpu-bottlenecks.md

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

CPU Bottlenecks (Script-Side Hot Paths)

Reference for skills/godot-optimization/SKILL.md — GDScript performance patterns: avoiding allocations, StringName, typed arrays, static typing, preload vs load.

← Back to SKILL.md


The patterns in this section are GDScript-specific, but the underlying principles (avoid per-frame allocations, use efficient comparisons, prefer typed collections) apply equally to C#. Each subsection includes a C# equivalent where the translation is non-trivial.

Avoid Allocations in _process

Allocating new heap objects (Arrays, Dictionaries, Strings) inside _process or _physics_process costs an allocation and a free every frame. GDScript has no garbage collector (it frees by reference counting); in C#, managed allocations also feed the GC. Vector2/Vector3 are stored inline and do not allocate.

# WRONG — allocates a new Array every frame
func _process(_delta: float) -> void:
    var nearby := get_tree().get_nodes_in_group("enemies")  # new Array each call
    for enemy in nearby:
        _check_aggro(enemy)

# RIGHT — cache the group query result, or use an Area2D overlap list
var _enemies: Array[Node] = []

func _ready() -> void:
    _enemies = get_tree().get_nodes_in_group("enemies")
    get_tree().node_added.connect(_on_node_added)
    get_tree().node_removed.connect(_on_node_removed)

func _on_node_added(node: Node) -> void:
    if node.is_in_group("enemies"):
        _enemies.append(node)

func _on_node_removed(node: Node) -> void:
    _enemies.erase(node)

func _process(_delta: float) -> void:
    for enemy in _enemies:  # no allocation
        _check_aggro(enemy)

C#:

// WRONG — querying the group every frame allocates a new Godot.Collections.Array
public override void _Process(double delta)
{
    var nearby = GetTree().GetNodesInGroup("enemies"); // new array each call
    foreach (var enemy in nearby)
        CheckAggro(enemy);
}

// RIGHT — cache the list and maintain it via signals
private readonly List<Node> _enemies = new();

public override void _Ready()
{
    foreach (var node in GetTree().GetNodesInGroup("enemies"))
        _enemies.Add(node);
    GetTree().NodeAdded += OnNodeAdded;
    GetTree().NodeRemoved += OnNodeRemoved;
}

private void OnNodeAdded(Node node)
{
    if (node.IsInGroup("enemies"))
        _enemies.Add(node);
}

private void OnNodeRemoved(Node node)
{
    _enemies.Remove(node);
}

public override void _Process(double delta)
{
    foreach (var enemy in _enemies) // no allocation
        CheckAggro(enemy);
}
# WRONG — constructing temporary vectors in a tight loop
func _process(_delta: float) -> void:
    for i in range(100):
        var offset := Vector2(i * 10.0, 0.0)  # 100 allocations per frame
        _draw_marker(position + offset)

# RIGHT — reuse a variable declared outside the loop
var _offset := Vector2.ZERO

func _process(_delta: float) -> void:
    for i in range(100):
        _offset.x = i * 10.0
        _offset.y = 0.0
        _draw_marker(position + _offset)

C#:

// In C#, Vector2 is a struct (value type) — no heap allocation in either case.
// However, avoiding repeated constructor calls is still marginally faster.
private Vector2 _offset;

public override void _Process(double delta)
{
    for (int i = 0; i < 100; i++)
    {
        _offset.X = i * 10.0f;
        _offset.Y = 0.0f;
        DrawMarker(Position + _offset);
    }
}

Use StringName for Comparisons

StringName uses interned hashing; comparing two StringName values is an O(1) integer comparison. Comparing String values is O(n) and allocates temporaries.

# WRONG — String comparison in a hot path
func _on_body_entered(body: Node) -> void:
    if body.name == "Player":  # String comparison
        _start_aggro()

# RIGHT — StringName literal (&"...") is interned at compile time
func _on_body_entered(body: Node) -> void:
    if body.name == &"Player":  # O(1) hash comparison
        _start_aggro()

C#:

// StringName in C# — cache as a static readonly field for O(1) comparison
private static readonly StringName PlayerName = new("Player");

private void OnBodyEntered(Node body)
{
    if (body.Name == PlayerName) // interned comparison
        StartAggro();
}
# Cache StringName constants at the class level for repeated use
const ACTION_JUMP := &"jump"
const ACTION_FIRE := &"fire"
const GROUP_ENEMIES := &"enemies"

func _process(_delta: float) -> void:
    if Input.is_action_pressed(ACTION_JUMP):
        _jump()
    if Input.is_action_just_pressed(ACTION_FIRE):
        _fire()

C#:

// Cache StringName constants as static readonly fields
private static readonly StringName ActionJump = new("jump");
private static readonly StringName ActionFire = new("fire");
private static readonly StringName GroupEnemies = new("enemies");

public override void _Process(double delta)
{
    if (Input.IsActionPressed(ActionJump))
        Jump();
    if (Input.IsActionJustPressed(ActionFire))
        Fire();
}

Typed Arrays

Typed arrays (Array[Node], Array[int]) skip per-element type checks and allow the VM to use more efficient access paths.

# Untyped — element type checked at every access
var bullets = []

# Typed — no per-element type check; also self-documents intent
var bullets: Array[Bullet] = []

# PackedArrays are the most efficient for value types — stored as contiguous memory
var positions: PackedVector2Array = PackedVector2Array()
var velocities: PackedFloat32Array = PackedFloat32Array()

C#:

// C# is statically typed — use concrete generic collections for best performance.
// Avoid Godot.Collections.Array (untyped) in hot paths; prefer List<T> or arrays.

// Untyped Godot collection — boxing and type checks on every access
Godot.Collections.Array bullets = new();

// Typed .NET collection — no boxing, cache-friendly
List<Bullet> bullets = new();

// For value types, use plain arrays for maximum throughput (contiguous memory)
Vector2[] positions = new Vector2[256];
float[] velocities = new float[256];

Static Typing Benefits

<!-- csharp-parity: n/a — C# is statically typed by definition; there is no untyped alternative to contrast against, so this optimisation does not exist there. -->

Static typing enables the GDScript VM to emit more efficient bytecode and catches errors at parse time rather than runtime. This one is GDScript-only — C# has no dynamic counterpart to trade away, so it starts where the "RIGHT" example below ends.

# Untyped — every operation goes through dynamic dispatch
func move(delta):
    velocity = direction * speed
    position += velocity * delta

# Typed — the compiler knows the exact types, generates faster bytecode
func move(delta: float) -> void:
    velocity = direction * speed
    position += velocity * delta

Type inference with := is equivalent to explicit types — use whichever is more readable.

preload vs load

preload resolves the resource path at parse time and embeds it into the script binary. load resolves at runtime and may trigger a disk read (or cache lookup).

# preload — resolved at compile time; safe to use at class scope
const BulletScene: PackedScene = preload("res://scenes/bullet.tscn")
const HitSound: AudioStream = preload("res://audio/hit.ogg")

# load — resolved at runtime; use for dynamic paths or optional resources
func _load_skin(skin_name: String) -> Texture2D:
    return load("res://skins/%s.png" % skin_name)

# WRONG — load() inside _process reads from disk (or cache) every frame
func _process(_delta: float) -> void:
    var tex = load("res://icon.svg")  # repeated runtime resolution
    $Sprite2D.texture = tex

# RIGHT — preload at class scope, assign once in _ready()
const IconTexture: Texture2D = preload("res://icon.svg")

func _ready() -> void:
    $Sprite2D.texture = IconTexture

C#:

// C# has NO preload — it is a GDScript parse-time construct with no C# equivalent.
// GD.Load<T>() is always a runtime lookup, so the cost has to be moved by hand.

// BEST — [Export] the resource and assign it in the editor. Loaded with the scene,
// zero runtime lookups, and a designer can swap it without touching code.
[Export] private PackedScene _bulletScene;
[Export] private AudioStream _hitSound;

// GOOD — static readonly, resolved once on first use of the type instead of per call.
private static readonly Texture2D IconTexture = GD.Load<Texture2D>("res://icon.svg");

public override void _Ready()
{
    GetNode<Sprite2D>("Sprite2D").Texture = IconTexture;
}

// For dynamic paths, GD.Load is the right tool — just never in a per-frame method.
private Texture2D LoadSkin(string skinName) => GD.Load<Texture2D>($"res://skins/{skinName}.png");

// WRONG — a runtime resolution every single frame.
public override void _Process(double delta)
{
    GetNode<Sprite2D>("Sprite2D").Texture = GD.Load<Texture2D>("res://icon.svg");
}

The engine caches loaded resources, so a repeated GD.Load is a cache lookup rather than a disk read — but it still costs a path resolution and a Variant round-trip every call. [Export] removes both.

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