メインコンテンツへスキップ
見出し画像

仕様書14本からGodotゲーム82ファイルをClaude Codeで実装する方法【実録#40・仕様書から丸ごと実装】

    Godotのエディタで起動ボタンを押すと、タイトル画面が立ち上がります。

    そこから戦闘に入ると、カードを引き、手札を切り、敵と殴り合い、勝てば装備を持ち帰り、負ければ全部失う。

    このデッキビルド型ローグライトの一式を、私はほとんど手打ちしていません。

    仕様書14本を書いて、Claude Codeに読ませただけです。

    出来上がったのは、GDScriptが47本、シーンが7枚、マスタデータが28件、合わせて82ファイル。

    キャラの立ち絵やカードアート、ボスや背景の画像13件も、Pythonスクリプト1本で自動生成しました。

    この記事は、こんな人に向けて書いています。

    • 仕様書をAIエージェントに渡して、動くゲームまで一気に作らせたい人

    • 「設計書がそのままコードになる」フローを、自分のプロジェクトでも試したい人

    • GodotのGDScriptで作りたいけど、AI任せにしたときの地雷が怖い人

    読み終わると、仕様書を分割してAIに丸投げする実装フローの全体像が手に入ります。

    そして、私が82ファイルを吐かせる過程で踏んだ5つの地雷と、その避け方が分かります。

    手作業でゲームを1本作るのが、もう無理だった

    章扉カード01

    まず、なぜこんな作り方をしたのかを話させてください。

    私は絵が描けません。ゲームエンジンも本業ではありません。

    それでも「持ち帰り/死亡ロスト型のデッキビルドローグライト」を作りたかった。

    普通に作ろうとすると、戦闘ロジック、カード効果、セーブ、UI、マスタデータ管理と、やることが山積みです。

    個人開発でここを全部手打ちすると、たいてい最初の戦闘画面が動く前に力尽きます。

    あなたも、作りたいゲームの構想はあるのに、実装量を想像した瞬間にやる気が消えた経験はありませんか。

    私はあります。だから発想を逆にしました。

    自分で書くのをやめて、「AIが読める仕様書」を書くことに全力を注ぐ方向に切り替えたのです。

    仕様書を14本に割ったのが分岐点だった

    章扉カード02

    やったことはシンプルです。

    仕様を1枚の巨大なドキュメントにせず、役割ごとに14本のspecファイルに分割しました。

    戦闘の状態管理、カードのデータ構造、セーブ、UI、マスタデータの形式。

    こういう単位で1本ずつ、Claude Codeが迷わない粒度に切り分けたわけです。

    巨大な1枚仕様は、AIにとって「どこから作ればいいか分からない指示書」になります。

    逆に14本に割ると、Claude Codeは依存関係の浅いものから順に、着実にファイルを生やしていきました。

    AIに自走で作業させる考え方そのものは、以前ループ設計の記事(実録#27)で書いたものと地続きです。

    「1枚の設計をAIに渡して自律的に作業させる」という発想を、今回はゲーム丸ごとに適用した形になります。

    82ファイルの内訳と、生えてきた順番

    章扉カード03

    最終的に出来上がった82ファイルの内訳はこうです。

    • GDScript: 47本(戦闘・カード・セーブ・UI・マネージャ類)

    • シーン(.tscn): 7枚(タイトル・戦闘・リザルトなど)

    • マスタデータ(.tres/.json): 28件(カード・敵・装備の定義)

    ロジックのGDScriptより、データ定義のマスタが多いのがデッキビルドの特徴です。

    カード1枚ずつ、敵1体ずつが独立したデータなので、ここが自然と膨らみます。

    そしてこの「データが多い」構造が、後で地雷を踏む伏線にもなりました。

    Godotの.tresは、書き方を1つ間違えると読み込み時に全滅します。

    このあたりは以前、.tresが「Cannot get class」で落ちる話(実録#36)に詳しく書きました。

    今回もまさにその罠を踏んだのですが、原因と一括修正法はその記事に譲ります。

    アート13件も、Pythonスクリプト1本で流した

    章扉カード04

    コードだけでなく、アセットも人力でやると詰みます。

    キャラの立ち絵、カードアート、ボス、背景。

    これをOpenAIのgpt-image-1で生成し、rembgで背景を透過に抜き、Godotの.tresを自動で書き換える。

    ここまでをPythonスクリプト1本にまとめて、13件を一気に流しました。

    生成AI画像の背景除去そのものは、以前アイコンの白い四隅を消す話(実録#23)でも扱ったテーマです。

    ただ今回は「生成→除去→.tres反映」までを無人で通すのが目的でした。

    あなたなら、この工程のどこを人に残しますか。私は「絵の採否だけ人、あとは全部スクリプト」に落ち着きました。

    つまり、詰まりました(正直に5つ)

    章扉カード05

    ここまで読むと全自動でスラスラ動いたように見えますが、実際は違います。

    82ファイルを吐かせる途中で、最低でも5つの地雷を踏みました。

    1. .tresにインナークラスを書くと全滅する問題
    2. gpt-image-1のimg-to-imgが透過出力に非対応だった問題
    3. PowerShell経由でPythonのf-stringを渡すとSyntaxErrorになる問題
    4. 初回起動でセーブが無くてクラッシュする問題
    5. デッキシャッフルが毎回変わって再現できない問題

    どれも「AIが悪い」わけではなく、GDScriptと外部APIの仕様を私が知らなかっただけです。

    そして地雷の性質上、1つずつ検索して原因を特定して直すことになります。

    ここから先では、この5つの原因と対処を、実際に直したコードの形で全部出します。

    この記事で手に入るもの(目次)

    章扉カード06

    有料部分の見出しは、隠さず全部見せます。

    • 設計判断:なぜ仕様書を14本に割り、なぜgpt-image-1を選んだか

    • 地雷①:.tresにインナークラスが使えない理由と、トップレベルclass_nameへの逃がし方

    • 地雷②:img-to-imgが透過非対応、rembgフォールバックの組み方

    • 地雷③:PowerShell×Pythonのf-string問題、ファイル経由で回避する型

    • 地雷④:初回起動クラッシュを止めるload_or_new()の実装

    • 地雷⑤:非決定論シャッフルを、rng注入で再現可能にする

    • 運用して分かった実数値(82ファイルの生え方・アセット13件の内訳)

    • アセット生成スクリプトの骨格(そのまま流用できる形)

    • 自分のゲームに合わせる3つのカスタマイズ勘所

    無料部分で「なぜ動くか」は全部話しました。ここから先は「どう直すか」の具体です。

    この5つの地雷は、知らずに踏むと1件ずつ検索して原因を切り分けることになります。

    有料部分には、私が実際に直したコードと、AIに丸投げする仕様書の割り方を、答え合わせできる形で全部置いておきます(アセット生成スクリプトの骨格つき)。

    ◀ 前回: 敵より怖い「味方AI」をGodotで作る:FSM+2メーターで"読めるやらかし"を設計する【実録#39・ポンコツ味方AI】

    📚 シリーズ全話はまとめマガジンへ

    https://note.com/lazy_engineer/m/m03a726b1673c

    💡 ここから先は有料です(¥500)
    仕様書14本の割り方と、82ファイルを生やす途中で踏んだ5つの地雷の直し方を、コードごと持ち帰れます。

     
     
    ITエンジニア9年目 / AI自動化 / note副業実録 AIを使えば、もっと楽できると気づいた。 noteで月10万円を目指す過程を、売上スクショ付きで全部公開します。 うまくいかない月も、ちゃんと出します。 「重い副業はしたくない」エンジニア・IT系の人に届けたい。

    あなたへのおすすめ