godot-autopilot-resources
Skill1 starsChanged 17 days agoMITView on GitHub
Godot resource and file operations guide: load, save, create and duplicate resources; transactional rename and move with reference rewriting; UID and dependency management; the import pipeline and path rules. Use when working with .tres/.tscn/.import files or the project layout.
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- cpp-registrationSkill
- domain-tool-authoringSkill
- gda-demo-e2eSkill
- gda-e2e-analysisSkill
- skill-proposerSkill
- thread-security-gateSkill
- wiki-maintainerSkill
- godot-autopilot-contentSkill
- godot-autopilot-csharpSkill
- godot-autopilot-runtimeSkill
- godot-autopilot-scene-systemSkill
- godot-autopilot-scriptingSkill
- godot-autopilot-serversSkill
- godot-autopilotSkill
- godot-autopilot-toolsSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 118
Wait for retry_after_ms, then retry the same call.
- Distinctive: line 124
All paths are normalized and boundary-checked before use: path traversal, absolute-path escapes, unknown schemes and writes outside the …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Resource and File Operations
Invocation: use the native MCP tools first; when that channel is down, follow the calling ladder in the godot-autopilot-tools skill (the gda CLI, via bunx, a global install, or the standalone gda binary); with no CLI available, work through its references/manual-fallback.md.
Working with .tres/.tscn files, .import sidecars, UIDs and the res:// layout through the resource domain tools plus three text-file tools (write_file, read_file, find_in_files). Every tool is invoked through call_tool; see the godot-autopilot-tools skill for the discovery protocol.
Load, create, duplicate and save
load_resourceloads a file from disk into memory, with optionaltype_hint, and returns a locator (class,path,object_id,object_id_str) that the property tools accept.create_resourceinstantiates a Resource subclass by class name (type): both ClassDB engine classes and global script classes (GDScript class_name / C# [GlobalClass]) are accepted - C# global classes require the editor to have loaded the assembly - while abstract or invalid scripts are rejected. Passnameto register the instance so later calls can reference it asmemory://name.duplicate_resourceduplicates a file-backed resource in memory:deep(default false) controls sub-resource copying, and the duplicate is returned as a locator, not written to disk. Passnameto also register the duplicate so later calls can reference it asmemory://name; the registration is what keeps the duplicate alive across calls. Save it withsave_resourceto materialize a new file. In-memory instances must be saved and reloaded before they can be duplicated.save_resourcerequirespath: it is the load path used to locate an existing file and the default destination, overridable withdest_path. Locators:object_id/object_id_str(fromcreate_resource), in-memoryname, orpath; if none resolves,class_typeplusnamecreates and registers a new instance. Locating bypathloads the file from disk, so unsaved in-memory modifications are not included (the response warns about this; passnameorobject_idto save the live instance). Whendest_pathdiffers frompathand the resource was located throughpath, the save is copy-on-write: the resource is deep-duplicated first so the cached source instance is left unmodified, and the response adds copy_on_write: true plus source_path. In-place saves keep their behavior. Missing directories are created recursively, the editor file system is refreshed, and the saved file is loaded back for verification.reload_resourceforce-reloads the file atpathfrom disk with a CACHE_MODE_REPLACE load, replacing the editor's cached instance; the response is{result: "reloaded", path, replaced}. Use it after a file changed on disk outside the editor so later reads (and apath-located save) observe the on-disk contents instead of a stale cached copy.copy_resource_filecopies a file byte-for-byte todest_path(both required): parent directories are created recursively, an existing target is overwritten, and an editor scan is triggered afterwards. It does not rewrite references and does not copy .import/.uid sidecars (imported assets need a reimport, and a uid duplicated from the source text resource may be re-minted by the scan). Prefer it over aload_resourceplussave_resourceround-trip for a plain file copy; use the load/save pair when you need the loaded instance re-serialized at a new path.
create_resource type=Resource name=player_stats
save_resource name=player_stats path=res://data/player_stats.tresThe save response reports directories_created and a verified flag; verified=true means the file was read back and loads.
memory:// caveat: a memory:// resource must never be assigned to a node property (that corrupts the scene file). Save it to disk with save_resource first, then assign by file path. The same rule applies to TileSet and SpriteFrames resources built by the tilemap and animation tools.
create_directory creates a res:// directory including missing parents, is idempotent (reports already_existed when present), and triggers a file system scan so subsequent calls see it immediately.
Threaded loading
For large resources use the three-step chain so the editor stays responsive:
1. load_resource_threaded starts the background load (use_sub_threads enables parallel loading)
2. get_resource_load_threaded_status poll until the status is loaded (values: invalid_resource, in_progress, failed, loaded)
3. get_resource_load_threaded fetches the resource; blocks until completeIntrospection and search
Type, existence and directory listings:
get_resource_typereports the engine class a file actually holds;get_resource_typeslists every instantiable Resource subclass (validtypevalues forcreate_resource);get_resource_extensionslists recognized extensions per type.has_resourceasks the engine loader whether a path is loadable - it is not a plain file-existence check.get_resource_dir_fileslists a directory's entries; subdirectories appear as plain names, so combine withhas_resourceto tell resources from folders.
UIDs and the dependency graph:
get_resource_uidreads the numeric UID behind a uid:// reference (-1 when the file has none);set_resource_uidassigns one (auto-generated whenuidis omitted) and triggers a reimport so the assignment persists.get_resource_dependencieslists the external files a resource references;has_resource_dependencychecks one specific edge.get_resource_referencesis the reverse lookup - who references this resource. Pass exactly one ofpath,uidorclass_name; each hit reports the matched kinds (path, uid, script_class).
Plain-text search:
read_filereturns a file's full text (res://, user:// or absolute path).find_in_filesrecursively searches text files:queryis required;dirdefaults to res://;extensionsdefaults to gd/tscn/tres/cs/md/json/h/cpp;max_resultsdefaults to 500 and hitting the limit reports truncated: true. This is the standard way to prove that a rename or move rewrote every reference.
Transactional rename and move
rename_resource_file (path plus new_path; from and to are accepted as aliases) is single-file only: a directory path fails fast with a structured error that directs you to move_resource_file. move_resource_file (path plus new_directory) accepts a file or a directory. Both are engine-aware transactions, not raw file moves. For each affected file they:
- Save open scenes that equal or reference the file, rewrite the file on disk, then reload those scenes (their undo history resets).
- Rewrite path= and uid= tokens in every dependent .tscn/.tres under res://.
- Move the .uid sidecar with the file (the .import sidecar of imported assets migrates too), keeping the UID stable.
- Remap project.godot entries pointing at the old path - application/run/main_scene and autoload/* values, preserving the leading * singleton marker - and save the file.
- Notify the editor file system.
Reload behavior in the engine: the dependency rewrite rewrites each affected file as a whole, and every open scene that references it is placed on a reload queue with the currently edited scene moved to the front. Each queued scene is then reloaded immediately, and a reload clears that scene's undo history. Two consequences: you cannot step back through the pre-transaction edit state with undo after the reload, and any change that was not captured by the save in step 1 is lost - the transaction saves first precisely to narrow that window, but treat unsaved edits in unrelated open scenes as at risk.
move_resource_file keeps the file name and takes new_directory inside res:// (absolute like res://assets/sfx or relative like assets/sfx; trailing slashes are trimmed; user:// is rejected). When path is a directory, every file moves recursively preserving the sub-folder layout, empty source folders are left behind, and a file system scan runs afterwards. The directory walk skips .import and .uid sidecars and moves each main file through its own reference-rewriting transaction, which migrates the file's sidecars (they follow their owners) and rewrites the references pointing at it - a directory move is a sequence of per-file transactions whose reports are aggregated. After a file moves or is force-deleted, any open scene tab still pointing at its old path is closed automatically and listed in closed_tabs; a tab that is the currently edited scene is left open and reported in closed_tabs_warning instead.
Read the structured report instead of assuming success. rename_resource_file returns updated_files (per-file change counts), stale_references ({file, token} leftovers that could not be rewritten), uid_preserved, remapped_settings, saved_scenes, reloaded_scenes, unsupported_binary_references (binary resources such as .scn/.res/.csv/.translation cannot be rewritten in place), closed_tabs when a stale scene tab was closed, and import_sidecar_warning when a .import move failed. move_resource_file returns moved ({from, to, updated_files, uid_preserved}), failed, plus the aggregated stale_references, unsupported_binary_references, saved_scenes, reloaded_scenes, closed_tabs, closed_tabs_warning and import_sidecar_warnings.
A script_class token in stale_references means a global class_name changed: run scan_editor_file_system afterwards so the class re-registers.
Verified transaction behavior (asserted by the L2 integration suite): after a rename, find_in_files finds the new path and no longer finds the old path anywhere under the directory, get_resource_references flips from old to new, and uid_preserved is true. After a move, moved is non-empty while failed and stale_references are empty, reloaded_scenes lists the referencing scenes that were saved and reloaded, and has_resource_dependency immediately reports the new location.
rename_resource_file:
path: res://assets/enemy.tres
new_path: res://assets/actors/enemy.tres
move_resource_file:
path: res://assets/sfx/boom.wav
new_directory: res://assets/audioDeleting files safely
remove_resource_file is a two-stage flow:
- Dry-run (default, no
force): a reverse-reference scan over every .tscn/.tres under res:// (path and uid tokens) returns would_delete plus dependents ({file, matched} objects) and a hint. Nothing is deleted - even with zero dependents an explicit force=true is required. - force=true: the file is preferentially moved to the OS trash (trashed=true; permanent=true only when the trash is unavailable or fails), its cached reference path is cleared, the .uid sidecar travels with it, and the editor file system is updated.
To discard a whole directory, move_os_file_to_trash (OS domain) trashes a res:// or user:// folder in one call.
Imports and editor readiness
reimport_resource_files(editor only) queues one or more files (filesarray or a singlepath) for reimport. It is asynchronous: the response confirms the queued count, not completion. Reimport only has an effect on files that carry a .import sidecar: for a .tres/.gd and similar non-imported files the engine logs a BUG error and the tool still reports "reimport queued" - refresh those withreload_resourceinstead. Pollget_editor_file_system_status(editor domain) until scanning is false.set_resource_import_options(editor only) is the supported way to change import parameters: it writes whitelisted.import[params]keys (audio loop/compression and texture filter/mipmap families; any other key is rejected) and queues a reimport in one call. Hand-writing.importfiles is deprecated for parameter changes. The response reports the applied keys with reimport queued - pollget_editor_file_system_statusuntil scanning is false, then verify withget_resource_typeorread_fileon the.import.set_resource_uidtriggers a filesystem reimport so the assignment persists.scan_editor_file_systemrescans the project - run it after a class_name rename that left script_class tokens, or after out-of-band file changes; directory moves trigger one automatically.
Scan gating in brief: the editor file system is a state machine (idle, scanning, processing changes, importing). A scan request issued while a scan or change pass is already running is silently ignored - not queued, not errored. The first scan of an editor session runs on the main thread; later scans run on a low-priority background thread, and their filesystem_changed notification is deferred onto the main loop. get_editor_file_system_status is the readiness gate: its response carries only scanning (bool) and progress (float) - there is no is_importing or doing_first_scan field, and progress is not a gate; poll until scanning is false. The full state machine, import ordering and sidecar rules are in references/import-and-sidecars.md.
Editor readiness soft errors
While the editor is importing or scanning, resource write operations fail soft with a readiness error instead of corrupting state:
{"error": "editor is currently importing/scanning resources; retry shortly",
"retryable": true, "retry_after_ms": 500}Wait for retry_after_ms, then retry the same call.
Path rules
- Resource operations - load, save, create, duplicate, rename, move, delete, reimport and the dependency/reference queries - accept res:// paths only.
write_fileandread_filealso accept user:// (andread_fileaccepts absolute paths). Never splice a path from one namespace into the other.- All paths are normalized and boundary-checked before use: path traversal, absolute-path escapes, unknown schemes and writes outside the project are rejected with a structured error.
write_fileinside res:// is engine-managed: imported asset types are queued for reimport, plain text files get update_file, and script-like files (.gd/.gdshader/.gdshaderinc/.cs) additionally return a diagnostics object reporting whether the script still loads. Writes to user:// or absolute targets are plain I/O and report engine_managed: false.
Gotchas
- Open scenes during rename/move: for every open scene touched by the transaction, the engine reloads it immediately after rewriting dependencies (the currently edited scene is reloaded first), and the reload wipes that scene's undo history. Save-before-rewrite covers the transaction's own edits; anything else unsaved in those scenes is gone, and undo cannot restore it.
- Copying a resource file mints a fresh UID: when a resource file is duplicated through the engine's file-copy pipeline (editor copy/paste, not the in-memory
duplicate_resource), the copy always gets a newly minted UID, and the engine first force-saves any edited cached resources back to the source file so the copy cannot drift from what is on disk. Consequence: a file copied next to its original is a different resource as far as uid:// references are concerned - repoint references at the copy explicitly. - Duplicate UIDs are silently re-minted: if the scan finds a file whose UID already maps to a different existing file, nothing fails - the engine quietly mints a new UID for the newcomer, rewrites it into the file's data, and emits only a WARN. References holding the old UID keep resolving to the old file. If a duplicated scene "does not react to edits", compare
get_resource_uidof both files. - Scans are not queueable: a
scan_editor_file_systemcall that lands while the editor is mid-scan or mid-import does nothing. Rely on the retryable soft error and theget_editor_file_system_statuspoll loop instead of fire-and-forget scans.
See also
- godot-autopilot - task-to-tool routing
- godot-autopilot-tools - the discovery protocol and the tool gotcha catalog
- godot-autopilot-scene-system - scene lifecycle (open scenes are saved and reloaded by rename/move) and assigning resources to node properties (memory:// is rejected)
- godot-autopilot-content - the memory:// TileSet and SpriteFrames that must be saved before they can be assigned
- references/import-and-sidecars.md - the import pipeline, hand-writing .import files, sidecar rules, duplicate UIDs and the scan state machine
- references/tool-reference.md - the full resource and text-file tool tables
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

