RefScope for Godot

Find references before you move, rename or delete a file.

RefScope is a small Godot 4 editor add-on (published as Reference Finder up to 0.1.5). Select a file and the dock answers two questions: which project files mention it, and which files it loads. Double-click a result to open it.

Godot's FileSystem dock does not answer the reverse question, and ResourceLoader.get_dependencies() only walks forward. This add-on builds a small text index of the project and answers both directions for the file you are looking at.

What you can do

• Pick the target from the file list, with Use selected from the FileSystem dock, or by typing a res:// path.
• Referenced by lists the files whose text mentions the target, labelled path or uid.
• References lists what the target loads: engine dependencies for scenes and resources, quoted paths and UIDs for scripts.
• Find text searches every scanned file for a key or value and shows file:line with the matching line.
• The file list and the results share the dock; drag the split bar to give either side more room.
• Open a result in the editor, reveal it in the FileSystem dock, or copy its path.
• Rescan rebuilds the index after files are added, renamed or edited outside the editor.

Why the uid matching matters

When you move a file, the editor rewrites references as uid://... strings that no longer contain the old path. A plain text search for the old path then finds nothing. RefScope also matches the exact uid:// string, so a reference that survived a move is still listed, marked uid.

Speed

The index is built in small batches on the editor's main loop, 40 files per frame, with a progress line. A measured 1,408-file / 1.6 MB project took 168 ms in total with a worst frame of 5 ms.

From a script, CI or a coding agent

The same two answers are available without opening the editor, which is what a CI check or an automated edit needs:

godot --headless --path . --script res://addons/refscope/inspect.gd -- --target=res://scenes/hero.tscn --json

It prints one JSON line: the target, its uid://, how many files were scanned, every referring file with path or uid, and what the target loads. --text=<word> adds the text search, and --fail-if-referenced exits non-zero while a referrer still exists — usable as a gate before removing a file. Exit codes are 0 completed, 1 usage, 2 target missing, 3 referrers found.

It runs in a project that was never opened in the editor: when the engine's UID cache is empty, the target's UID is read from its .uid file or from the scene's header, so a moved uid:// reference is still found. Nothing is written to the project.

Install

Unzip the download, copy addons/refscope into your project, then enable RefScope in Project > Project Settings > Plugins. The dock appears in the right panel. To remove it, disable the plugin and delete the folder; the add-on does not modify project files.

Verified environment and limits

• Godot 4.4 or later; the shipped archive was installed and exercised on 4.4.1, 4.5.2, 4.6.3 and 4.7.2 standard, Windows 11. Godot 4.3 and earlier, macOS, Linux and the .NET builds are untested. 0.1.7 runs on 4.4 because it no longer calls a ResourceUID function that 4.4 does not have, and because a uid://-only load now resolves in a checkout that was never opened (a fresh clone, or CI before the first editor run).
• Text matching only. A path that a script assembles at runtime is not found. A hit is a text hit, not proof that the code path still runs, and an empty Referenced by list is not proof that a file is unused.
• Scanned: tscn, tres, gd, cs, gdshader, gdshaderinc, cfg, json, import, godot, escn. Binary .res/.scn files can be the target but are not text-searched. Files over 8 MiB are skipped and counted. .godot and hidden directories are skipped. Only res:// is indexed.
• No rename, move, delete or rewrite is performed. No automatic re-index; press Rescan.

What this is not

Not a dependency graph, not an orphan analysis, not a safe-delete tool. It answers "what mentions this file" as text and shows what the engine reports as dependencies.

Includes the add-on source, a commercial license, the installation guide and the recorded measurements. Source repository is private.

---

ファイルを指しているものを、動かす前に確認する

RefScope は Godot 4 エディター用の小さなアドオンです（0.1.5 までは Reference Finder という名前で販売していました）。右ドックでファイルを1つ選ぶと、「どのファイルがそのファイルに触れているか」と「そのファイルが何を読み込むか」を並べて表示します。結果をダブルクリックするとエディターで開きます。

Godot の FileSystem ドックは逆方向を答えず、ResourceLoader.get_dependencies() は順方向だけを返します。このアドオンはプロジェクトの小さなテキスト索引を作り、いま見ているファイルについて両方向を答えます。

できること

• ファイル一覧のクリック、FileSystem ドックからの Use selected、res:// パスの直接入力で対象を選ぶ。
• Referenced by：対象を本文中で言及しているファイルを、path か uid の一致種別付きで一覧する。
• References：対象が読み込むものを一覧する。シーンとリソースはエンジンの依存、スクリプトは引用符付きパスと UID から解決する。
• Find text：走査対象の全ファイルからキーや値を検索し、file:line と該当行を表示する。
• ファイル一覧と結果はドックを分け合って表示され、境界バーをドラッグして広さを変えられます。
• 結果をエディターで開く、FileSystem ドックで示す、パスをコピーする。
• Rescan：エディター外でファイルを追加・改名・編集した後に索引を作り直す。

uid 一致が要る理由

ファイルを移動すると、エディターは参照を uid://... 文字列へ書き換えます。この文字列には元のパスが残らないため、旧パスを本文検索しても何も見つかりません。RefScope は uid:// の完全一致も照合するので、移動を生き延びた参照も uid として一覧に残ります。

速度

索引はエディターのメインループ上で1フレーム40ファイルずつ、進捗表示付きで作ります。実測では1,408ファイル／1.6MBのプロジェクトで合計168ms、最悪フレーム5msでした。

スクリプト・CI・コーディングエージェントから

エディターを開かずに同じ2つの答えを得られます。CIの検査や自動編集ではこちらが要ります。

godot --headless --path . --script res://addons/refscope/inspect.gd -- --target=res://scenes/hero.tscn --json

1行のJSONで、対象、その uid://、走査したファイル数、参照元（path か uid の別付き）、対象が読み込むものを出します。--text=<語> で本文検索も加わり、--fail-if-referenced は参照元が残っている間は非ゼロで終了するので、削除前の関門に使えます。終了コードは 0 完了、1 使い方の誤り、2 対象なし、3 参照元あり。

エディターで一度も開いていないプロジェクトでも動きます。エンジンのUIDキャッシュが空のときは、対象の .uid ファイルかシーンのヘッダーからUIDを読むため、移動後の uid:// 参照も見つかります。プロジェクトへは何も書き込みません。

導入と削除

ZIPを展開し、addons/refscope をプロジェクトへコピーして、プロジェクト → プロジェクト設定 → プラグイン で RefScope を有効にします。右パネルにドックが出ます。削除するときはプラグインを無効にしてフォルダーを消してください。プロジェクトのファイルは変更しません。

確認済み環境と制限

Godot 4.4以降が対象です。配布ZIPを4.4.1・4.5.2・4.6.3・4.7.2 standard / Windows 11へ導入して確認しています。4.3以前・macOS・Linux・.NET版は未確認です。0.1.7 は 4.4 に無い ResourceUID の関数を呼ばないようにし、一度も開いていないチェックアウト（fresh clone や CI の初回）でも uid:// だけの読み込みを解決するようにしました。

テキスト一致のみ。 スクリプトが実行時に組み立てるパスは見つかりません。ヒットは「その文字列がある」という意味で、コードが今も通る証明ではありません。Referenced by が空でも、未使用である証明にはなりません。

走査対象は tscn・tres・gd・cs・gdshader・gdshaderinc・cfg・json・import・godot・escn です。バイナリの .res／.scn は対象にはなりますが本文検索はしません。8MiB を超えるファイルは飛ばして件数に表示します。.godot と隠しディレクトリは除外し、res:// のみを索引します。

改名・移動・削除・書き換えは行いません。自動再走査もしないので、必要なら Rescan を押してください。

これは何ではないか

依存グラフでも、未使用アセットの解析でも、安全に削除するための道具でもありません。「このファイルに触れているのは誰か」をテキストとして答え、エンジンが返す依存を表示します。

アドオンのソース、商用ライセンス、導入説明、実測記録を同梱します。ソースリポジトリは非公開です。

Questions and bug reports

Contact onpont@gmail.com. Include your Godot version, your OS, the add-on version you installed, and the exact message or the steps that reproduce it. Replies come from the seller; there is no paid support tier and asking does not require an account. The public comment section below also works, but it is visible to everyone.

質問・不具合の連絡先

onpont@gmail.com までご連絡ください。Godotの版、OS、導入したアドオンの版、表示されたメッセージか再現手順を添えていただけると助かります。返信は販売者が行います（有料の導入支援はありません）。下のコメント欄も使えますが、内容は公開されます。