ziva-sh/godot-skills

godot-scene-organization

Structures Godot 4 projects so scenes stay reusable and references do not break - when to make a scene, a script or a Resource, instancing with @export PackedScene, preload and load, @onready and %UniqueName node access, ready order, groups, autoloads, clas…

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/ziva-sh/godot-skills --skill godot-scene-organization

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

Scene organization in Godot 4

Scene, script or Resource

  • Scene (`.tscn`): a reusable tree of nodes with its own resources: a player, an enemy, a pickup, a UI panel, a level. Anything you place more than once or want to run alone (F6) is a scene.
  • Script (`.gd`): behaviour attached to one node. Attach it to the root of the scene it controls, not to a parent that reaches into it.
  • Resource script (`extends Resource` with `class_name`): data without a node, such as item stats, wave definitions or save data, edited in the Inspector and saved as .tres.

A scene should work when run on its own. If it needs something from outside (a target, a spawn parent), expose it with @export or a signal instead of get_parent() chains.

Instancing scenes

gdscript
extends Node2D

@export var enemy_scene: PackedScene
@export var spawn_parent: Node2D


func spawn_enemy(at: Vector2) -> void:
	var enemy := enemy_scene.instantiate() as Node2D
	enemy.position = at
	spawn_parent.add_child(enemy)


func load_level(path: String) -> void:
	var packed := load(path) as PackedScene
	if packed == null:
		push_error("Level not found: " + path)
		return
	get_tree().change_scene_to_packed(packed)
  • @export var x: PackedScene is set in the Inspector and survives file moves, because the scene stores the reference.
  • const BULLET := preload("res://bullet.tscn") resolves at parse time: a missing file is a parse error (Preload file "res://bullet.tscn" does not exist.). Good for fixed assets.
  • load() resolves at runtime and returns null with an error if the path is wrong. Use it for paths built at runtime.
  • instantiate() (not Godot 3's instance()) returns a Node; cast it to the type you need. Free instances with queue_free().

Finding nodes

gdscript
extends Control

@onready var title: Label = %Title
@onready var start_button: Button = %StartButton
@onready var music: AudioStreamPlayer = $Music
@onready var optional_hint: Label = get_node_or_null("Hint")


func _ready() -> void:
	title.text = "Main menu"
	start_button.grab_focus()
	if optional_hint:
		optional_hint.visible = false
	music.play()
  • $Path is get_node("Path"), relative to this node. It errors if the node is missing; use get_node_or_null() for optional nodes.
  • %Name reaches a node marked "Access as Unique Name" (right-click in the Scene dock) anywhere in the same scene, so it survives reparenting inside the scene. It does not reach into instanced child scenes: use $Child/%Name, or %Child/%Name when the instance is itself unique.
  • @onready variables are assigned just before _ready(). They are null in _init() and _enter_tree().
  • _ready() runs on children before their parent, so a parent's _ready() can use its children, but a child's _ready() must not rely on the parent being ready.
  • Type @onready variables (: Label) so the parser checks member names; $Label.txt on an untyped path is only caught at runtime.

Groups

Groups tag nodes across scenes. Add them in the Node dock (Groups tab) or in code, then query the tree:

gdscript
extends Node


func _ready() -> void:
	add_to_group("enemies")


func alert_all_enemies() -> void:
	get_tree().call_group("enemies", "set_alerted", true)
	for enemy in get_tree().get_nodes_in_group("enemies"):
		print(enemy.name)
	var player := get_tree().get_first_node_in_group("player") as Node2D
	if player:
		print("Player at ", player.global_position)

call_group() calls immediately in Godot 4. Use get_tree().call_group_flags(SceneTree.GROUP_CALL_DEFERRED, ...) to defer.

Autoloads

An autoload is a node created before the main scene and kept across scene changes. Use it for state that outlives one scene (settings, save data, a scene switcher) and for a signal-only event bus. Register it in Project Settings > Globals > Autoload; project.godot then contains:

ini
[autoload]

Events="*res://autoload/events.gd"

The * means "Enable" is checked, so scripts can use the name directly (Events.player_died.emit()). Do not free() or queue_free() an autoload. Keep autoloads few: anything that belongs to one level should live in that level's scene.

Note for tools: godot --check-only --script does not load autoloads, so a script that uses an autoload name reports Identifier not found: Events there even though it runs fine. Verify such scripts by running the scene (see the godot-verify skill).

class_name

class_name Player registers a global type, so other scripts can write var player: Player and get member checking. The editor keeps a global class cache in .godot/; after adding a class_name outside the editor, open the editor or run godot --headless --path . --import before checking scripts that use it.

UIDs, .uid files and moving files

Godot 4 references resources by UID as well as path. Scenes and resources store their own UID in the file header, imported assets in their .import file, and since Godot 4.4 scripts and shaders get a companion file (player.gd.uid, water.gdshader.uid). An editor-saved reference looks like:

text
[ext_resource type="Script" uid="uid://dxxoiuob4eoum" path="res://game_manager.gd" id="1_feb5d"]

Rules:

  • Commit *.uid files to version control. Do not add them to .gitignore.
  • Move and rename files in the Godot FileSystem dock when you can; it updates references.
  • When moving a script or shader outside Godot (shell, IDE, agent), move its .uid file with it, then open the editor or run godot --headless --path . --import so the UID cache learns the new path. Until that scan, the old path is still used and loading fails.
  • If the .uid file is left behind, Godot generates a new UID for the moved script and scenes that referenced the old one fall back to their stale path: WARNING: ... invalid UID: uid://... - using text path instead: res://old/path.gd, then ERROR: ... referenced non-existent resource.
  • When writing a .tscn by hand, do not invent uid= values. Omit the attribute and use a correct path; the editor adds UIDs when it next saves the scene.
  • A hand-written Godot 4 scene starts with [gd_scene format=3] and references resources by string id: [ext_resource type="Script" path="res://main.gd" id="1_main"], then script = ExtResource("1_main") on the node. Child nodes need parent="." or a path from the root. Godot 4.7 also writes unique_id= on nodes; omit it by hand.
  • load("uid://...") and preload("uid://...") accept UID strings. Copy a UID from the FileSystem dock context menu; ResourceUID.id_to_text(ResourceLoader.get_resource_uid(path)) returns it from code.

Common mistakes

  • Reaching up with get_parent().get_parent() or absolute paths like /root/Main/Player. Export a reference, use a group, or emit a signal.
  • Using a node in _init() or before it entered the tree.
  • Hard-coding res:// paths to scenes in many scripts instead of exporting a PackedScene.
  • Moving .gd files without their .uid files, or ignoring *.uid in git.
  • Making everything an autoload because it is convenient.
来自同一仓库

更多 Skills

全部 Skills
ziva-sh
社区

godot-4-api-pitfalls

Fixes Godot 3 APIs and GDScript syntax that AI assistants write into Godot 4 projects, such as KinematicBody2D, moveandslide(velocity), export, onready, setget, yield, string connect(), instance(), randrange, the Tween node, File, changescene, Spatial, rect properties, PoolArray, OS time functions and the old TileMap API. Use when writing, reviewing or porting GDScript for Godot 4.x, when a script fails with "not declared", "not found in base", "was removed in Godot 4" or "is not present on the

1小时安装量
1
GitHub Stars
0
最近更新
11月11日
ziva-sh
社区

godot-control-layout

Builds Godot 4 Control UIs that resize instead of clipping or overlapping - containers versus anchors, anchor presets from code, size flags, customminimumsize, MarginContainer margins, Label wrapping, mousefilter, CanvasLayer HUDs, Godot 4 theme override names (addthemecoloroverride and friends) and the display/window/stretch settings for multiple resolutions. Use when creating or fixing menus, HUDs, dialogs and inventory screens, when UI elements are cut off, zero-sized, overlapping, ignoring p

1小时安装量
1
GitHub Stars
0
最近更新
11月11日
ziva-sh
社区

godot-signals

Godot 4 signal patterns and their failure modes - declaring typed signals, emit(), connect() and disconnect() with Callables, bind() and unbind(), lambdas, CONNECTONESHOT and CONNECTDEFERRED, await on signals and timers, editor-made connections stored in .tscn files, and the call down, signal up rule. Use when wiring UI buttons, timers, Area2D or body events and custom game events, when replacing Godot 3 connect("signal", self, "method") or yield code, or when debugging "already connected", "Met

1小时安装量
1
GitHub Stars
0
最近更新
11月11日
ziva-sh
社区

godot-tilemaplayer

Correct Godot 4.3+ TileMapLayer code - setcell(coords, sourceid, atlascoords), reading cells and custom data, erasing, coordinate conversion, terrains, tile collision through TileSet physics layers, finding the tile a body hit, and migrating from the deprecated TileMap node and its layer-index API. Use when placing, reading or erasing tiles from GDScript, building a TileSet in code, generating levels procedurally, handling tile collisions, or porting TileMap code from Godot 3 or Godot 4.0 to 4.2

1小时安装量
1
GitHub Stars
0
最近更新
11月11日