gdscript-advanced
Use when writing production-grade GDScript — performance idioms, metaprogramming, @tool lifecycle, async pitfalls, signal/Callable trade-offs, profiler-driven idioms, and common pitfalls
jame581 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add jame581/GodotPrompter --skill gdscript-advanced技能说明
name: gdscript-advanced description: Use when writing production-grade GDScript — performance idioms, metaprogramming, @tool lifecycle, async pitfalls, signal/Callable trade-offs, profiler-driven idioms, and common pitfalls
GDScript Advanced
Production-grade GDScript depth — for shipping games, not for learning the language. Pair with gdscript-patterns for fundamentals.
Related skills: gdscript-patterns for language fundamentals, godot-optimization for engine-side perf work, godot-debugging for runtime diagnosis, csharp-godot for the C# alternative.
Intent: This skill is GDScript-only by design (allowlisted). C# users should read
csharp-godot. Adding C# parity here would undermine the audience split.
1. When to reach for advanced GDScript
You're past gdscript-patterns when:
- You're hitting a profiler bottleneck and need to know which idioms are fast
- You're writing editor tools and need
@toollifecycle correctness - You're seeing coroutines that never resume or
Callablelifetime bugs - You need metaprogramming (calling functions by name, dynamic dispatch) without footguns
- You're shipping a real game and want to avoid the patterns that look fine but break under load
This skill assumes you already know typed parameters, @onready, await, match, and lambdas (covered in gdscript-patterns).
2. Performance idioms
Static vars and methods (Godot 4.4+) avoid per-instance overhead:
class_name Tally extends Node
static var _global_score: int = 0
static func add_score(amount: int) -> void:
_global_score += amount
static func get_score() -> int:
return _global_score
Avoid singletons-as-autoloads when a static method on a class would do.
Vector2i vs Vector2 / Vector3i vs Vector3 — integer vectors are 30-40% faster on hot paths (tile coords, grid math). Convert to float only at the rendering boundary:
var grid_pos: Vector2i = Vector2i(8, 12) # cheap
var world_pos: Vector2 = Vector2(grid_pos) * TILE_SIZE # convert at boundary
PackedArray* over generic Array — PackedInt32Array, PackedFloat32Array, PackedVector2Array, etc. allocate contiguous memory and skip Variant boxing. Use them for buffers, vertex arrays, hot-loop accumulators.
var positions: PackedVector3Array = PackedVector3Array()
positions.resize(1000) # one allocation
for i in 1000:
positions[i] = Vector3(i, 0, 0)
Typed Dictionary access — typed dicts (Godot 4.4+) skip the Variant unbox per read:
var stats: Dictionary[String, int] = {}
stats["hp"] = 100 # no boxing
is_instance_valid vs null check — is_instance_valid() does an engine-side lookup; != null is a pointer compare. Prefer != null after @onready assignment; reserve is_instance_valid() for nodes that may be queue_free'd while a reference is held.
Common pitfall:
_processdoingif is_instance_valid(target)once per frame burns ~1µs per call — tiny per-call but multiplies fast.
3. Metaprogramming
Callable.bind, Callable.call, Callable.call_deferred give you dynamic dispatch without Object.call(name) security risks.
Binding arguments:
var greeter: Callable = print_named.bind("Player")
greeter.call() # prints "Hello, Player"
func print_named(name: String) -> void:
print("Hello, %s" % name)
Deferred calls — run on the next frame's idle phase, useful for cross-thread or signal-storm safety:
heavy_recompute.call_deferred()
Object.set / Object.get / Object.has_method — for truly dynamic code (script reloading, modding):
if obj.has_method("on_damaged"):
obj.call("on_damaged", 25)
Security gotcha: Never pass
obj.call(user_string, ...)whereuser_stringcomes from save files, network, or mod content without an allowlist.call("queue_free")is a free crash. Match against a known set:
const ALLOWED_RPCS: PackedStringArray = ["take_damage", "apply_buff", "set_position"]
if user_method in ALLOWED_RPCS and obj.has_method(user_method):
obj.call(user_method, args)
See references/metaprogramming-recipes.md for full Callable patterns and the modding security model.
4. @tool lifecycle
@tool scripts run in the editor as well as in-game. Two failure modes dominate:
- Editor-only logic accidentally runs at play time
- In-game logic accidentally runs in the editor and crashes the editor
The guard:
@tool
extends Node
func _ready() -> void:
if Engine.is_editor_hint():
_setup_editor_preview()
else:
_setup_game_runtime()
Editor notifications — use _notification for editor lifecycle events (NOTIFICATION_EDITOR_PRE_SAVE, NOTIFICATION_EDITOR_POST_SAVE, NOTIFICATION_PARENTED):
func _notification(what: int) -> void:
if what == NOTIFICATION_EDITOR_PRE_SAVE:
_bake_preview()
Common pitfall: a
@toolscript that callsget_tree().create_timer()at editor time. Editor has no main loop in some contexts — guard withis_editor_hint().
See references/tool-script-recipes.md for full
@toolpatterns including editor preview, baking, and procedural mesh generation.
5. Async pitfalls
await suspends the function and hands control back to its caller until the signal fires. It has three trap shapes:
Trap 1 — await in _ready returns early, so the node reports ready before it is initialized:
# BAD: the first await returns control, so `ready` is emitted and the parent's
# _ready() runs while `inventory` is still empty
func _ready() -> void:
await get_tree().create_timer(1.0).timeout
inventory = load_inventory()
Fix: finish everything other nodes read at ready time before the first await. If part of setup genuinely has to wait, set an `is