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.

referencesphysics-tuning.md

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

Physics Tuning

Reference for skills/godot-optimization/SKILL.md — collision layers, simplified shapes, tick rate, and Area-vs-raycast trade-offs.

← Back to SKILL.md


Collision Layers and Masks

Every physics body checks for collisions against bodies whose layer is included in its mask. Unnecessary mask bits cause wasted broadphase work.

# Project Settings > Layer Names > 3D Physics defines readable names.
# Assign layers so bodies only collide with what they need to.

# Example layer assignments (set in Inspector or via code):
# Layer 1 — Player
# Layer 2 — Enemies
# Layer 3 — Environment
# Layer 4 — Projectiles
# Layer 5 — Triggers / Sensors

# (layer numbers, not bit values — layer N is bit 1 << (N - 1))
# Player: layer 1, mask layers 2 + 3       (collides with enemies and environment)
# Enemy:  layer 2, mask layers 1 + 3       (collides with player and environment)
# Bullet: layer 4, mask layers 2 + 3       (hits enemies and environment only)
# Sensor: layer 5, mask layer 1            (detects player only)

func _ready() -> void:
    # Set via code (bit index is layer number minus 1)
    collision_layer = 1 << 3   # this body is on layer 4 (Projectiles)
    collision_mask  = (1 << 1) | (1 << 2)  # checks layers 2 and 3
// Same bit arithmetic; the properties are PascalCase and typed uint.
public override void _Ready()
{
    CollisionLayer = 1 << 3;              // this body is on layer 4 (Projectiles)
    CollisionMask  = (1 << 1) | (1 << 2); // checks layers 2 and 3
}

// Prefer named flags over bare shifts once you have more than a handful of layers.
[System.Flags]
private enum Layers : uint
{
    Player      = 1 << 0,
    Enemies     = 1 << 1,
    Environment = 1 << 2,
    Projectiles = 1 << 3,
    Sensors     = 1 << 4,
}

private void ConfigureBullet()
{
    CollisionLayer = (uint)Layers.Projectiles;
    CollisionMask  = (uint)(Layers.Enemies | Layers.Environment);
}

Simplified Collision Shapes

Mesh colliders (ConcavePolygonShape3D) are extremely expensive. Replace with primitives wherever possible.

Shape Cost Use for
SphereShape3D Cheapest Projectiles, pickups, rolling objects
CapsuleShape3D Cheap Characters, pillars
BoxShape3D Cheap Walls, crates, platforms
ConvexPolygonShape3D Moderate Irregular convex geometry
ConcavePolygonShape3D Expensive Static-only complex terrain (never on moving bodies)

Shape choice is an Inspector decision, not a code one — the guidance is identical in GDScript and C#:

  • Wrong: ConcavePolygonShape3D on a moving CharacterBody3D.
  • Right: CapsuleShape3D — approximates a character at minimal cost.
  • Acceptable: ConcavePolygonShape3D on a StaticBody3D only, and only if the mesh is not overly dense.

Physics Tick Rate Tuning

The default physics tick is 60 Hz (Engine.physics_ticks_per_second). Lowering it reduces CPU load at the cost of simulation fidelity.

# Lower the physics tick rate at runtime (e.g. for a top-down game that
# does not need 60 Hz physics accuracy)
func _ready() -> void:
    Engine.physics_ticks_per_second = 30

# Use max_physics_steps_per_frame to prevent the spiral-of-death
# (physics trying to catch up when the frame takes too long)
Engine.max_physics_steps_per_frame = 4

C#:

public override void _Ready()
{
    Engine.PhysicsTicksPerSecond = 30;
    Engine.MaxPhysicsStepsPerFrame = 4;
}

Change project-wide defaults in Project Settings > Physics > Common > Physics Ticks Per Second and Max Physics Steps Per Frame.

Area2D for Detection vs Raycasts

For detecting whether something enters a region, Area2D/Area3D is cheaper than running a raycast or shape query every frame because the engine maintains the overlap state incrementally.

# PREFER Area2D for "is the player in range?" checks
extends Area2D

func _ready() -> void:
    body_entered.connect(_on_body_entered)
    body_exited.connect(_on_body_exited)

func _on_body_entered(body: Node2D) -> void:
    if body.is_in_group("player"):
        _begin_aggro(body)

func _on_body_exited(body: Node2D) -> void:
    if body.is_in_group("player"):
        _end_aggro()

C#:

// PREFER Area2D for "is the player in range?" checks
public partial class AggroZone : Area2D
{
    public override void _Ready()
    {
        BodyEntered += OnBodyEntered;
        BodyExited += OnBodyExited;
    }

    private void OnBodyEntered(Node2D body)
    {
        if (body.IsInGroup("player"))
            BeginAggro(body);
    }

    private void OnBodyExited(Node2D body)
    {
        if (body.IsInGroup("player"))
            EndAggro();
    }
}
# Use raycasts only when you need directionality or line-of-sight checks,
# and cache the RayCast2D/3D node — do NOT create PhysicsRayQueryParameters
# every frame unless necessary.
@onready var _ray: RayCast3D = $RayCast3D

func _physics_process(_delta: float) -> void:
    if _ray.is_colliding():
        _handle_hit(_ray.get_collider())

C#:

// Cache the RayCast3D node — do NOT create PhysicsRayQueryParameters every frame
private RayCast3D _ray;

public override void _Ready()
{
    _ray = GetNode<RayCast3D>("RayCast3D");
}

public override void _PhysicsProcess(double delta)
{
    if (_ray.IsColliding())
        HandleHit(_ray.GetCollider());
}

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