Universal Modder の使い方：最初の Mod をゲーム内で動かすまで

Universal Modder は、Claude Code や Codex などのコーディングエージェントに「ゲームの Mod を作るための手順と道具」を追加するオープンソースのツールです。単体で起動するアプリではありません。まずエージェントにプラグインとして入れ、/universal-modder:mod-any-game に続けて作りたい Mod を一文で頼みます。あとはエージェントが使用エンジンの特定、セーブデータのバックアップ、コードの調査、fal での素材生成、実際のゲームでの動作確認までを順に進めます。

始める前に、次の4点だけは確認してください。

• 対象は自分が所有している PC ゲームです。シングルプレイ・オフラインか、自分で立てたサーバーに限られ、アンチチート付きのオンラインゲームは断られます。
• ゲームを自動で起動・操作して確かめる機能（um win）は、Windows と WSL でしか動きません。
• 費用はエージェント側の契約と、fal の素材生成の従量課金が別々にかかります。既定設定のスプライトは1枚 $0.211 です（2026年10月8日時点の fal の表示価格）。
• 最初の1本は、Terraria（tModLoader）や Stardew Valley（SMAPI）のように定番の前提MOD があるゲームで、小さな1機能から始めるのが近道です。

Universal Modder とは：改造するのはあなたのコーディングエージェント

GitHub の README によると、Universal Modder は次の4つをまとめた MIT ライセンスのプロジェクトです。

• スキル：エージェントが読む作業手順書です（Agent Skills 形式。プレイヤーの腕前の話ではありません）。中心になる mod-any-game には、全体の流れ、安全ルール、Unity・Unreal・.NET/XNA・Minecraft など12系統のエンジン別プレイブックが入っています。
• um コマンド：Python 製の CLI です。インストール済みゲームの検出（um scan）、セーブのバックアップ（um backup）、fal での素材生成（um fal）、スプライト加工（um sprite）、Windows ゲームの操作と録画（um win）、公開前チェック（um publish check）などを担当します。
• fal の MCP サーバー設定：エージェントが画像・3D・効果音の生成モデルを直接呼べるようにします。
• ナレッジベース：各エージェントが「どのバージョンで、どの方法で改造し、どこでつまずいたか」を書き残したフィールドノートです。2026年10月8日時点の一覧には、ゲーム別ノート78件と技術ノート50件があります。

対応エージェントは Claude Code、Codex、Gemini CLI、VS Code / GitHub Copilot、Cursor、OpenCode です。Agent Skills を読めるほかのエージェントにはスキルだけを入れることもできます。

リポジトリは2026年9月30日に公開され、10月8日時点でスター数は約5,400、バージョンは 0.2.0 で、GitHub の正式リリースはまだありません。Post-Cutoff の記事は、作者 Rehan Sheikh 氏が X のプロフィールで fal のエンジニアと名乗っていることを伝えています。素材生成が fal の有料 API を前提にしているのは、この背景と合わせて理解しておくとよいでしょう。

なお、universal-modder.org はこのプロジェクトをもとにしたコミュニティサイトで、サイト自身も「Community hub based on the open-source project」と表記しています。本家は GitHub のリポジトリです。

導入前の確認：エージェント、OS、ゲーム、費用

導入してから「自分の環境では動かなかった」とならないよう、次の条件で向き不向きを判断します。

OS の条件は、um win のコードが Windows か WSL 以外では実行を拒否する作りになっていることによります（win.py）。Linux では代わりに xdotool と ffmpeg を使うよう案内されます。macOS について公式の記述はありませんが、ナレッジベースには macOS の Wine 上で動かした例が1件あり、「まったく使えない」わけではありません。

コミュニティに定番の前提MOD（ローダー）があればそれを使う、というのがスキルの方針です。最初の1本も、そうしたゲームを選ぶと早く形になります。Terraria なら tModLoader、Stardew Valley なら SMAPI、Minecraft なら Fabric、Unity 製のゲームなら BepInEx です。ナレッジベースに同じゲームのノートがあれば、エージェントはそこに書かれたバージョンと方法から始められます。ただし、ノートがあるからといって自分のバージョンで同じように動くとは限りません。

必要なソフトと fal API キーの用意

README が挙げる必要なソフトは次のとおりです。

• Git
• Python 3.10 以上
• ffmpeg（録画と動画編集）
• uv（推奨。um が必要なライブラリを取得します）
• Blender（3D モデルをスプライトに変換するときだけ）

Windows なら、ターミナル（PowerShell）で winget を使ってまとめて入れられます。

winget install --id Git.Git -e
winget install Python.Python.3.12
winget install astral-sh.uv
winget install Gyan.FFmpeg

インストール後はターミナルを開き直し、git --version、python --version、uv --version、ffmpeg -version でバージョンが表示されるか確かめます。Claude Code をまだ入れていない場合は、PowerShell で irm https://claude.ai/install.ps1 | iex を実行し、claude --version で確認します。

素材を fal で作るなら、fal のダッシュボードで API キーを発行し、残高をチャージしておきます。キーは環境変数 FAL_KEY に入れます。

# Windows（設定後にターミナルを開き直す）
setx FAL_KEY "発行したキー"

# macOS / Linux（~/.zshrc や ~/.bashrc に追記）
export FAL_KEY=発行したキー

VGTimes のガイドによると、um はプロジェクトフォルダーの .env からもキーを読めますが、エージェントにつながる fal の MCP サーバーは環境変数しか読みません。迷ったら環境変数に設定しておけば両方で使えます。

エージェント別のインストールコマンド

コマンドは README のインストール表のとおりです。どのエージェントにも、同じスキル、fal の MCP サーバー、um コマンドが入ります。更新が速いプロジェクトなので、実行前に README の表も見ておいてください。

プラグインや clone で入れると um はエージェントから使える状態になります。それ以外の環境で um だけを入れるなら uv tool install git+https://github.com/rehan-remade/universal-modder （または pipx）を使います。

Claude Code で読み込まれたか確かめる

1. Mod 用のフォルダー（例：C:\mods）でターミナルを開き、claude を起動します。
2. 上の2つのコマンドを Claude Code の入力欄で順に実行します。スコープを聞かれたら、どのフォルダーでも使える User を選びます。
3. プラグインの再読み込みを求められたら /reload-plugins を実行します。
4. /plugin を開き、インストール済みの一覧に universal-modder があれば読み込みは完了です。
5. エージェントに um --help を実行させ、コマンド一覧が出れば um も使えます。

Claude Code のプラグイン解説には、使う前に知っておきたい点が3つあります。有効なプラグインのスキル名と説明は使っていないセッションでも毎回文脈に入るため、そのぶん利用枠を消費します。プラグインはあなたの権限でコードを実行します。また、ブラウザの claude.ai/code などクラウドのセッションは、ローカルに入れたプラグインを読み込みません。Mod を作らない期間は /plugin か claude plugin disable で無効にしておけます。

Codex と Gemini CLI での注意点

Codex では、上の2つのコマンドをターミナルで実行します。エージェントにファイル書き込みやコマンド実行をどこまで許すかは Codex の設定次第なので、Codex のサンドボックスと config.toml で承認・書き込み・ネットワークの設定を確認しておくと、作業中にどこで許可を求められるかを把握できます。

Gemini CLI を Windows の PowerShell で使う場合、スクリプト実行が無効な既定設定では gemini.ps1 がブロックされます。メンテナーの案内どおり gemini.cmd extensions install ... のように gemini.cmd で実行してください。

最初の Mod を作る手順：バックアップしてから小さな1機能

Universal Modder の進め方は、mod-any-game のスキルに書かれています。ここでは Terraria を例にしますが、ゲームが変わっても流れは同じです。

1. ゲームと作業フォルダーを準備する

Terraria を Steam で購入・インストールし、無料の tModLoader を Steam ライブラリに追加します。tModLoader はライブラリにないと起動せず、エージェントもこの所有確認を回避しません。一度手動で起動してフォルダーを作らせ、閉じておきます。次に C:\mods\terraria-first のような作業フォルダーを作り、そこでエージェントを起動します。

2. スキルを呼び、アイデアと完成条件を一文ずつ伝える

/universal-modder:mod-any-game Steam 版 Terraria に、敵から敵へ4回跳ね返ってから手元に戻るブーメランを1つ追加して。スプライトはゲームの絵柄に合わせて fal で作って。完成条件は、テスト用ワールドで敵に当てて動きを確かめられること。動画は不要です。

スキルは普通の依頼文からでも呼ばれることがありますが、手順どおりに進めたいなら名前を付けて呼ぶほうが確実です。完成条件を最初に決めておくのも、スキル側が求めていることです。スキルの既定では「ゲーム内で動く＋20〜45秒の紹介動画」が完成なので、動画がいらなければ最初に伝えます。作業フォルダーには作業日誌 MODLOG.md が作られ、パスや試したこと、失敗の理由、次の一手が記録されます。

3. 調査の結果と方針を確認する

エージェントはまず次のコマンドで下調べをします。

• um kb search "Terraria"：ナレッジベースに先行例があるか
• um scan --list：Steam・Epic・Xbox のインストール済みゲームの一覧
• um scan "Terraria"：エンジンとバージョン、アンチチートの有無、導入済みの前提MOD、セーブフォルダーの場所、改造ルートの候補

そのうえで、データ差し替え、前提MOD の API、コードへのパッチといった選択肢から、アイデアに届く最も手軽な方法を選び、理由を MODLOG.md に書きます。方針がおかしいと感じたら、この段階で止めて質問するのが一番安上がりです。

4. 本来のセーブデータをバックアップする

最初に Mod 入りで起動する前に、エージェントは um backup create "<セーブフォルダー>" --name terraria-saves でセーブを保存します。Terraria では tModLoader の -tmlsavedirectory で別のセーブフォルダーを使い、本来のキャラクターとワールドに触れずに試します。スクリーンショットとクリック位置がずれないよう、ゲームは決まったサイズのウィンドウモードに切り替えられます。前提MOD をゲームフォルダーに入れる、レジストリやグラフィック設定を変える、マウスとキーボードを操作するといった場面では、事前に許可を求められます。

5. まず小さく動く1機能を作り、ゲーム内で確かめる

いきなり全部を作らず、仮の絵で1つのアイテムを最後まで通します。定義して起動し、ログとスクリーンショットで「出現して、動く」ことを確かめてから、素材の生成や次の機能に広げます。判定に使うのは、エージェントのコードの読みではなく、実際に動いているゲームです。主なログの場所は次のとおりです。

エージェントがゲームを操作している間は、マウスやキーボードに触らないでください。クリック位置が狂います。同じ失敗が3回続くと、エージェントは作業を止め、分かったことを書き出してから方法を変えるか相談してきます。

6. 完成の判断と、翌日の再開

完成とみなすのは、最初に決めた条件をゲーム内で確認できたときです。エージェントの「できました」ではなく、テスト用ワールドで自分の目で動きを見て判断してください。作業が翌日にまたがるときは、同じフォルダーで新しいセッションを始め、「MODLOG.md を読んで続きから」と頼めば再開できます。

人に配る段階になったら、um publish check <Mod のフォルダー> --game "<インストール先>" でゲームファイルや逆コンパイルしたコード、API キーが混ざっていないかを確認します。作った Mod の導入手順は、エージェントが README にまとめます。学んだことはナレッジベース用のノートにでき、プルリクエストはあなたの了承があったときだけ出されます。

fal の素材費の目安：既定のスプライトは1枚 $0.211

um fal の各コマンドには、既定の生成モデルが決まっています（fal.py、--model で変更可）。2026年10月8日時点の fal の表示価格は次のとおりです。fal 自身が「価格は変更される場合がある」と書いているので、実行前に確認してください。

計算は「枚数（秒数）× fal の単価」です。

• 既定（high）のスプライト10枚：10 × $0.211 = 約 $2.11
• --quality medium で10枚：10 × $0.053 = 約 $0.53
• --quality low で10枚：10 × $0.006 = 約 $0.06
• Nano Banana 2（1K）で画像10枚：10 × $0.08 = $0.80
• 効果音を合計30秒：30 × $0.002 = 約 $0.06

これは素材だけの例です。作り直した分、3D や動画、エージェント側の利用料は含みません。絵柄を決めるまでの試作は um fal sprite "..." --quality medium で回し、採用するものだけ high にすると費用を抑えられます。生成のたびに fal_manifest.jsonl に記録が残るので、あとから何を何枚作ったかを数えられます。高い生成の前には、エージェントに um fal price で価格を確認させてください。透過 PNG がゲームで正しく抜けているかの確認方法は、GPT Image 2で透過PNG・WebPを作るが参考になります。

エージェント側の費用は fal とは別にかかります。1本の Mod でどれだけトークンを使うかの実測値は公開されていませんが、調査・逆コンパイル・テストの繰り返しは長いセッションになりがちです。プランごとの枠は Claude ProとMaxの利用制限を比較、作業中に上限へ達したときは Claude Codeのレート制限ガイドや Codexの429で再試行が終了したときを見てください。

サブスクを契約せず従量課金で試したい場合は、Codex を外部の API につなぐ方法もあります。たとえば laozhang.ai は Codex の config.toml にプロバイダーを追加して gpt-6-sol を使う手順を公開しており、料金はトークン単位です。設定の考え方は Codexを外部モデルAPIにつなぐを参照してください。ただし、Mod 作り1回あたりの費用や、逆コンパイルを含む作業でのモデルの出来は検証されていません。laozhang.ai では現在 Claude のモデルは提供されていないので、Claude Code で使う経路にはなりません。

断られる改造：アンチチート付きのオンラインと未所有のゲーム

Universal Modder のスキルには、頼まれても破らないルールが書かれています（safety.md）。導入前に知っておけば、「なぜ進まないのか」で迷いません。

• 自分が所有していないゲームは扱いません。ゲーム本体や ROM、ディスクイメージのダウンロードもしません。
• オンラインゲームのクライアントには、EasyAntiCheat、BattlEye、Vanguard、公式サーバーの VAC、Ricochet、ACE などで保護されている場合は手を出しません。代わりにオフラインモード、自分で立てたサーバー、Steam ワークショップやマップエディターなどの公式ツールを提案します。
• エイムボット、ESP（透視）、スピードハックのようなマルチプレイ向けのチートは作りません。
• アンチチート、DRM、所有確認は回避しません。
• ゲームファイル、抽出した素材、逆コンパイルしたコードは配布物に含めません。配るのは自分のコードと素材、パッチだけです。
• セーブ・プロファイル・ゲームフォルダーを変える前にバックアップします。

これはツール自身のルールで、法的な判断ではありません。safety.md は、素材を含まない作品でも削除要請は起きうる例として、Take-Two が2021年に GTA の解析コード（re3 / reVC）を GitHub から削除させて作者を訴えた件や、2024年に Activision が H2M Mod に停止通告を送った件を挙げています。商用利用や収益化はリスクを大きく上げるので、ゲームごとの EULA や Mod ポリシーを読んでください。AI で作ったことは正直に明記するよう勧められており、AI 製の作品を禁じているコミュニティもあります。

もうひとつ、話題の Mod の「ダウンロード」と称するものはマルウェアであることが多い、と safety.md は警告しています。前提MOD は公式のリポジトリやリリースからだけ入れてください。

エラー別の対処：UnicodeEncodeError から spawn git ENOENT まで

GitHub の Issue で報告された症状と、導入の前提が欠けているときに出る症状を、原因と対処の順に並べます。

同じ失敗が3回続いてエージェントが止まったときは、無理に続けさせず、MODLOG.md に残った原因の見立てを読んでから、ルートを変えるかゲームを変えるかを決めます。

プラグインなしでも Claude Code は改造できる？入れると変わること

できる、という報告があります。YouTube チャンネル「さつきのOSS研究室」は、動画タイトルで、Claude Code がプラグインなしでゲーム3本・8件の改造すべてに合格し、スキルは一度も呼ばれず Bash で直接改造したと伝えています。対象のゲームやバージョンはタイトルからは分からず、1人の検証者による小さな試行です。それでも「強いエージェントなら、プラグインがなくても改造の腕はある」ことを示す結果として読めます。

では何のために入れるのか。改造そのものよりも、その前後を毎回同じ手順で進めることに価値があります。

• 下調べ：um scan がエンジン、アンチチート、セーブの場所をまとめて調べ、ナレッジベースから先行例の正確なバージョンと落とし穴を引けます。
• 安全網：改造前のセーブのバックアップ、別のテスト用セーブ、マウス操作や前提MOD の導入前の確認が手順に組み込まれています。
• 断る範囲：オンライン＋アンチチートや所有確認の回避を断るルールが明文化されています。
• 素材と公開：fal の生成記録、スプライトの切り抜きと縮小、um publish check による配布物の検査が用意されています。

逆に、スキルが呼ばれなければこれらの手順は使われません。この報告のように、普通に頼むだけではスキルが読まれないことがあるので、手順に沿わせたいときは /universal-modder:mod-any-game と名前を付けて呼んでください。Mod を作らない期間はプラグインを無効にしておけば、毎ターンの文脈の消費も避けられます。

Universal Modder の料金・公式サイト・Mac 対応

Universal Modder は無料で使えますか？

ツール自体は MIT ライセンスで無料です。ただし、改造を進めるエージェント（Claude Code なら有料プランか API 課金）と、fal で素材を作る場合の従量課金は別にかかります。素材を作らない改造なら fal の費用はかかりません。

universal-modder.org は公式サイトですか？

本家は GitHub の rehan-remade/universal-modder です。universal-modder.org は「オープンソースのプロジェクトをもとにしたコミュニティハブ」と自ら説明しているサイトで、インストールボタンは公式のコマンドをコピーするだけです。README では、作った Mod を公開・リミックスできる公式の Mod ハブが「次に来る」と予告されています。

Mac でも Universal Modder を使えますか？

インストールと、調査・ナレッジ検索・素材生成のような Python のコマンドは macOS でも動く作りです。ゲームを自動で起動・操作・録画する um win は Windows か WSL でしか動かないので、ゲーム内の確認は自分で行うことになります。