Universal Modder のインストールと使い方

必要なもの

必要なツールをまとめて入れる

winget install Git.Git Python.Python.3.12 astral-sh.uv Gyan.FFmpeg
winget install BlenderFoundation.Blender   # 任意：3D → スプライト用

brew install git python ffmpeg uv
brew install --cask blender                 # 任意

sudo apt install git python3 python3-venv ffmpeg
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows・macOS・Linux で使える機能

ツールキットの大半はクロスプラットフォームです。動いているゲームを操作する部分（起動、スクリーンショット、入力、ゲーム音だけのウィンドウ録画）は Windows が中心です。ゲームの多くが Windows 用だからです。エージェントは Windows のゲームをネイティブでも WSL2 からでも操作できます。

macOS や Linux でも、OS 標準のキャプチャツール（screencapture、ffmpeg、xdotool）でゲーム内テストはできますが、事前設定はありません。Linux で xEdit を動かしたノートや、macOS の Wine で HL2 を動かしたノートが、それが可能なことを示しています。

エージェント別インストール（比較表）

どの方法でも、同じスキル（Agent Skills 形式）、fal MCP サーバー、um CLI が入ります。

Claude Code

シェルではなく、Claude Code のセッション内で実行します：

/plugin marketplace add rehan-remade/universal-modder
/plugin install universal-modder@universal-modder

どのフォルダでも使えるよう user スコープを選び、求められたら /reload-plugins を実行します。Claude Desktop での使い方や各スキルの呼び出し方を含む詳しい手順は Universal Modder + Claude Code のページにあります。

OpenAI Codex

codex plugin marketplace add rehan-remade/universal-modder
codex plugin add universal-modder@universal-modder

Codex はスキルを .agents/skills から、MCP 設定を .codex/config.toml から読み込みます。

Gemini CLI

gemini extensions install https://github.com/rehan-remade/universal-modder

拡張機能のマニフェストは gemini-extension.json、指示は GEMINI.md（AGENTS.md を参照）から読み込まれます。

VS Code + GitHub Copilot

1. 設定を開き、chat.plugins.enabled を有効にします。
2. コマンドパレットで Chat: Install Plugin From Source を実行します。
3. https://github.com/rehan-remade/universal-modder を貼り付けます。

MCP 設定は .vscode/mcp.json にあります。

Cursor

Cursor Marketplace からインストールするか、リポジトリを clone して開きます。Cursor は AGENTS.md と .cursor/mcp.json を自動で読み込みます。

OpenCode

git clone https://github.com/rehan-remade/universal-modder
cd universal-modder
opencode

opencode.json がスキルと fal MCP サーバーを追加します。

その他のエージェント

# スキルだけをエージェントのスキルフォルダへ
npx skills add https://github.com/rehan-remade/universal-modder

# まるごと使う場合：clone したフォルダでエージェントを起動
git clone https://github.com/rehan-remade/universal-modder

um CLI を単体でインストール

プラグインのインストールや clone で、um は自動的に PATH に入ります。別の場所でスキルを使う場合や、普通のターミナルで um を使いたい場合はツールとして入れます。GitHub からのインストールで、PyPI にはないため pip install universal-modder では入りません。

uv tool install git+https://github.com/rehan-remade/universal-modder
# または
pipx install git+https://github.com/rehan-remade/universal-modder

各コマンドグループには例つきの --help があります。um CLI リファレンスも参照してください。

fal API キーを設定する

fal.ai/dashboard/keys でキーを取得します（クレジットのチャージが必要。キーは一度しか表示されないので保存を）。fal MCP サーバーと um fal の両方がこのキーで動きます。

export FAL_KEY="your-key"
# 永続化する
echo 'export FAL_KEY="your-key"' >> ~/.zshrc   # または ~/.bashrc

setx FAL_KEY "your-key"
# 新しいターミナルを開き、エージェントを再起動

キーがない場合は、um comfy でローカルの ComfyUI を使って画像を作れます。音声・3D・動画には fal が必要です。料金は費用のページへ。

インストールを確認する

um --help
um kb search "terraria"       # 既存のフィールドノート（リポジトリ外でも動作）
um scan --list                # このマシンで見つかったゲーム
um fal price fal-ai/trellis-2 # FAL_KEY が使えるか確認

最初のセッション：元に戻せる小さな変更を 1 つ

1. 扱いやすいゲームを選ぶ定番のローダーがあるゲームが一番やさしい入り口です：Terraria（tModLoader）、Stardew Valley（SMAPI）、Minecraft（Fabric/Forge）、BepInEx 対応の Unity ゲーム、UE4SS 対応の Unreal ゲーム。ゲームライブラリを見る。
2. まず調査を頼む
   プロンプトコピー

   私の Terraria はどのエンジン？ 誰かが MOD したことはある？（ナレッジベースを検索して）どのルートで進める？ まだ何も変更しないで。

3. バックアップと実験環境を任せるエージェントは um backup create でセーブのスナップショットを取り、別のプロファイルやワールドを使い、ローダーを入れる前に確認してきます。
4. まず 1 つ動かす
   プロンプトコピー

   敵の間を 4 回跳ね返ってから戻ってくるブーメランを 1 つ追加して。最初は仮のスプライトで、ゲーム内で動いたら fal でスプライトを作って。

5. 確認してから広げるゲームを起動して自分の目で見てから、次を頼みましょう。長いプロジェクトは MODLOG.md に記録されます。新しいセッションでは「MODLOG.md を読んで続きをやって」と伝えます。

トラブルシューティング

マーケットプレイスの追加で Git / SSH エラーが出る

プラグインのマーケットプレイスは Git で clone されます。GitHub の SSH キーがないマシンでは、GitHub に HTTPS を使うよう Git を設定します：

git config --global url."https://github.com/".insteadOf git@github.com:

インストール後にスキルが表示されない

/reload-plugins（Claude Code）を実行するか、エージェントを再起動します。/plugin でプラグインが有効か確認してください。

um: command not found

プラグインのインストール後に新しいターミナルを開くか、上記の uv tool install で CLI を入れ、~/.local/bin が PATH にあるか確認します（uv tool update-shell）。

um fal でキーがないと言われる

FAL_KEY は、エージェントを起動した環境に設定されている必要があります。setx やシェル設定の変更後はエージェントを再起動してください。

um win が動かない

Windows または WSL2 から Windows のゲームを操作する専用です。macOS / Linux ではゲーム内テストを手動で行ってください。