
Godot 4の.tresが「Cannot get class」で全滅する原因と一括修正法【実録#36・.tresの罠】
ある朝、Godot 4.6で開発中のスマホゲームを起動したら、コンソールがこの赤字で埋まりました。
ERROR: Cannot get class 'CardEffect'.
at: _instantiate_internal (core/object/class_db.cpp:565)
ERROR: res://data/cards/card_block_basic.tres:3 - Parse Error:
Can't create sub resource of type 'CardEffect'.
同じエラーが29ファイル全件、カスタム型18種すべてで発生。マスタデータが空のまま、ゲームだけは平然と動いている状態でした。
この記事は、Godot 4でGDScriptのclass_nameをカスタムリソースにして、手書きの.tresが読めずに詰まっている人向けです。preloadを足してもダメ、キャッシュを確認してもダメ、という段階まで来ている人には、そのまま答えになると思います。
結論を先に言います。原因は「.tresパーサーはClassDBを引くが、GDScriptのclass_nameはScriptServerにしか登録されない」というGodot内部の構造です。そして解決は、29ファイルを手で直すのではなく、Pythonスクリプト1本での一括変換でした。
読み終わると、次の状態になります。
「Cannot get class」エラーの根本原因を、内部構造から説明できる
エディタ保存の.tresと手書きの.tresが内部的に別物である理由が分かる
手元の.tresを、動く形式へ一括変換できる
きっかけ:マスタデータを.tresで手書き管理していた

まず前提から書きます。
私はこのゲームのマスタデータ(カード、ボス、アイテムなど)を、GDScriptのカスタムリソースで管理しています。class_name CardDataのようにクラスを定義して、データ本体は.tresファイルに書く方式です。カスタム型は全部で18種ありました。
なぜこの方式かというと、データとロジックを分離して、AIにデータ追加を任せやすくするためです。.tresはただのテキストなので、Claude Codeに「カードを10枚追加して」と頼めば、コードを触らずにデータが増えます。楽をするための設計でした。
エディタでポチポチ作るのではなく、.tresをテキストとして手書き(正確にはAIに書かせて)量産していたわけです。あなたも、データ量が多いプロジェクトで同じことを考えたことはありませんか。
症状:29ファイル全滅、なのにゲームは動く

ところがゲームを起動すると、冒頭のエラーです。
Cannot get class 'CardEffect'.——CardEffectはちゃんと定義してあります。class_name CardEffectと書いたスクリプトはプロジェクト内に存在するし、エディタ上でも補完が効く。なのにロード時だけ「そんなクラスは知らない」と言われる。
しかもタチが悪いことに、ゲーム自体はエラーを吐きながら普通に起動します。マスタデータのロードに失敗しても、リストが空になるだけ。カードが1枚も出ないまま、画面は動く。クラッシュしてくれた方がまだ親切でした。
被害は.tresファイル29件すべて。手で直すにも、そもそも「何をどう直せば読めるのか」がこの時点では分かりませんでした。
試してダメだったこと3連発

原因にたどり着くまでに、定番の対処を一通り空振りしました。同じ道を辿る人が多いはずなので、先に潰しておきます。
ダメその1:preload()の追加
「クラスが見つからないなら、先に読み込ませればいい」と考えて、起動スクリプトにpreload("res://scripts/data/card_effect.gd")を追加しました。結果は変化なし。同じエラーです。
スクリプトをメモリに載せることと、「クラス名で引けるようになること」は別問題でした。これは後で分かります。
ダメその2:global_script_class_cache.cfgの確認
Godotはclass_nameの一覧を.godot/global_script_class_cache.cfgにキャッシュしています。「キャッシュが壊れているのでは」と疑って中身を確認しましたが、18種すべて正しく登録されていました。キャッシュ再生成も効果なし。
キャッシュは正常。なのに読めない。ここで「登録場所そのものが違うのでは」という疑いが芽生えました。
ダメその3:起動方法の変更
--headless起動と通常起動で挙動が変わるか試しました。どちらも同じエラー。実行環境の問題ではなく、もっと根っこの問題だと確定しました。
ここまでで分かったのは、「クラス定義は存在し、キャッシュにも載っているのに、.tresのロード時だけ見つからない」という奇妙な状況です。あなたなら次に何を疑いますか。
原因:ClassDBとScriptServerは別の台帳だった

答えはGodotのC++側、エラーメッセージに出ていたclass_db.cppにありました。ここは無料で全部説明します。
Godotには、クラスを管理する台帳が2つあります。
ClassDB:C++で実装された組み込みクラス(Node、Resource、Sprite2Dなど)の台帳
ScriptServer:GDScriptのclass_nameで宣言されたクラスの台帳
そして.tresパーサーは、type="CardData"のような型指定を見つけると、ClassDB::instantiate()でオブジェクトを生成しようとします。つまりClassDBしか引かない。
一方、GDScriptのclass_nameはScriptServerにしか登録されません。エディタの補完が効くのはScriptServerのおかげ。でも.tresパーサーはそっちを見ない。台帳が違うので、永遠に見つからないわけです。
preloadが効かなかった理由もこれで説明がつきます。スクリプトを読み込んでもScriptServerが充実するだけで、ClassDBには1ミリも影響しないからです。
では、なぜエディタで保存した.tresは動くのか
ここが一番の罠です。エディタからカスタムリソースを保存すると、問題なく読める.tresができます。だから「手書きの何かが間違っている」と思い込んで、延々と書き方を疑うことになる。
実は、エディタが保存する.tresは内部的にext_resource形式になっています。type="CardData"とクラス名で指定するのではなく、type="Resource"(組み込み型)で生成して、スクリプトファイルへのパスをscript =プロパティで直接参照する形式です。
手書き(公式チュートリアル風):type="CardData" → ClassDBを引いて死ぬ
エディタ保存:type="Resource" + script = ExtResource(...) → クラス名解決が不要なので動く
公式チュートリアルには[gd_resource type="MyClass"]と書ける例が出てきます。でも実際には、この書き方はロード経路によっては動きません。エディタ上でリソースとして開けば動くのに、load()で読むと死ぬ。この非対称が、ハマりを深くします。
解決:全.tresをext_resource形式に変換する

原因が分かれば、方針は1つです。手書きの29ファイルを、エディタ保存と同じext_resource形式に変換する。
Before/Afterはこうなります。
# Before(動かない)
[gd_resource type="CardData" load_steps=2 format=3]
[sub_resource type="CardEffect" id="CardEffect_1"]
# After(動く)
[gd_resource type="Resource" load_steps=4 format=3]
[ext_resource type="Script" path="res://scripts/data/card_data.gd" id="S1"]
[ext_resource type="Script" path="res://scripts/data/card_effect.gd" id="S2"]
[sub_resource type="Resource" id="CardEffect_1"]
script = ExtResource("S2")
...
[resource]
script = ExtResource("S1")
ポイントは3つです。
型指定は全部Resource(組み込み型)にする
クラスごとにext_resource type="Script"でスクリプトを参照する
本体・sub_resourceの両方にscript = ExtResource(...)を差す
構造は単純ですが、29ファイル × 型18種を手作業で直すのは現実的ではありません。sub_resourceの数だけload_stepsも再計算が必要で、1つズレるとまた別のエラーが出ます。
そこで、Pythonの変換スクリプトを書いて一括変換しました。実行は1回、29ファイルが数秒で全部直り、ゲームのマスタデータが完全に復活しました。✅
Godot移植まわりでは、実録#33(Web製ゲームのGodot移植)や実録#30(AI生成モーションの罠)でも書きましたが、Godotは「エディタ経由なら動くのに、外から触ると死ぬ」パターンが多いです。今回はその最たるものでした。
有料部分の目次(隠さず全部見せます)

ここまでで「なぜ動かないか」「どう直すべきか」は全部説明しました。ここから先は、実際に変換を回すときの具体的な手順・罠・コードです。
1. 設計判断の理由:エディタで再保存する案・C#に逃げる案を捨てた理由
2. ハマりどころの全リスト:load_stepsの計算式/sub_resourceだけ変換漏れするケース/[resource]セクションへのscript差し込み位置/カスタム型を含まないファイルのスキップ判定
3. そのまま動く変換スクリプト全文(約110行・Python):型→スクリプトパスのマップを自分のプロジェクトに書き換えるだけで動く
4. カスタマイズの勘所3点:自分のプロジェクトに合わせる際の注意
私はこの原因にたどり着くまでに、preload追加・キャッシュ確認・起動方法変更を全部空振りしました。原因が分かった後も、load_stepsの再計算やsub_resourceの差し替えを29ファイル分、手でやれば確実にどこかでミスります。有料部分には、その試行錯誤と手作業を丸ごと省略する変換スクリプト一式と、自分で書き直す場合に踏む罠の全リストを置いておきます。
◀ 前回: 絵が描けない個人開発者がキャラとアプリアイコンを外注ゼロで確定させる方法【実録#35・AIとコードでゲームアイコン】
📚 シリーズ全話はまとめマガジンへ
https://note.com/lazy_engineer/m/m03a726b1673c
💡 ここから先は有料です(¥500)
「Cannot get class」で.tresが全滅した状態から、Pythonスクリプト1発で29ファイルを復活させた実物のコードと、変換で踏む罠の回避手順を答え合わせできる形で全部渡します。