balatro-mod-dev

Balatro Mod 開発

Steamodded、Lovely、SMODS を使用して Balatro の Mod を作成し、デバッグします。

エージェントをすばやく選択

調査やコード作成を行うときは、Task ツールを使って適切なサブエージェントを起動します。

調べたい内容	使用するエージェント	モデル	検索範囲
ゲーム関数の実装	game-source-researcher	sonnet	Balatro_src/ のみ
SMODS API の使用方法／フック	smods-api-researcher	sonnet	smods/ のみ
他の Mod での実装方法	mod-pattern-researcher	sonnet	Mods/ フォルダーのみ
Lovely のパッチ構文	lovely-patch-researcher	sonnet	lovely ファイルのみ
プロジェクトのアーキテクチャ／調査	project-explorer	sonnet	現在のプロジェクトのみ
計画に沿ったコード作成	code-writer	sonnet	現在のプロジェクトのみ
データ取得用の一時スクリプトの実行	script-runner	haiku	該当なし（実行）
コードの正確性レビュー	code-reviewer	opus	現在のプロジェクトのみ
複数の情報源から調査結果を統合	research-analyst	opus	現在のプロジェクトのみ
複雑な実装の計画	strategic-planner	opus	現在のプロジェクトのみ
ランタイムログ、ダンプ、互換性の調査	debug-inspector	sonnet	Lovely のログ／ダンプのみ

メインエージェントが直接担当： ユーザーとのやり取り、小規模な編集（20 行未満）、結果の提示。

並行処理： 異なる情報源を調査するときは、1 つのメッセージ内で複数の Task 呼び出しを行います。 逐次処理： 2 つ目の問い合わせが 1 つ目の結果に依存するときに使います。

5 段階のワークフロー、反復検索プロトコル、委任ルールについては、references/sub-agents.md を参照してください。

リポジトリの種類を把握する

自動判定： Mod のマニフェストの author と Git のリモートユーザー名を比較します。

# Get git remote username
git_user=$(git remote get-url origin 2>/dev/null | sed -E 's|.*[:/]([^/]+)/[^/]+\.git$|\1|' | tr '[:upper:]' '[:lower:]')

# Get mod author from manifest (first author, lowercase)
mod_author=$(jq -r '.author[0] // .author // ""' *.json 2>/dev/null | head -1 | tr '[:upper:]' '[:lower:]')

# Compare: match = own, no match = fork
[[ "$git_user" == "$mod_author" ]] && echo "own" || echo "fork"

種類	判定	意味
new	空のリポジトリ（ファイルなし）	ドキュメント一式、Logger.lua、ローカライズ
own	作者が Git ユーザーと一致	ドキュメント一式、構成の標準化
fork	作者が Git ユーザーと異なる	変更は最小限にし、一時ログのみ

ファイルの規則

ファイル	目的	Git
AGENTS.md	Mod の構成、関数、依存関係、制約、クイックリファレンス（AI エージェント向け）	無視
mod.config.json	同期／リリーススクリプト用のファイル一覧	無視
docs/knowledge-base.md	問題と学び	無視

AGENTS.md の目的： エージェント間のシームレスな引き継ぎを可能にします。別のエージェントが 1 つのファイルだけで Mod の構成、関数、依存関係、制約、リポジトリの種類をすばやく把握できるようにします。

ファイル配置ルール

ルートに置ける .md ファイルは次のもののみです。

• README.md、README_zh.md
• CHANGELOG.md、CHANGELOG_zh.md
• AGENTS.md
• LICENSE.md

その他すべての .md ファイルは docs/ に配置する必要があります。

外部参照（シンボリックリンク不要）

絶対パスを使って参照コードに直接アクセスできます。セットアップは不要です。

ソースの場所（macOS）

リソース	パス
ゲームソース（デスクトップ）	~/Development/GitWorkspace/Balatro_src/desktop/
ゲームソース（モバイル）	~/Development/GitWorkspace/Balatro_src/ios_plus/
Steamodded ソース	~/Development/GitWorkspace/smods/src/
Steamodded Lovely	~/Development/GitWorkspace/smods/lovely/
Lovely ドキュメント	~/Development/GitWorkspace/lovely-injector/
インストール済み Mod	~/Library/Application Support/Balatro/Mods/
Lovely ログ	~/Library/Application Support/Balatro/Mods/lovely/log/

ソースの場所（Windows）

リソース	パス
ゲームソース	環境によって異なります
インストール済み Mod	%APPDATA%/Balatro/Mods/
Lovely ログ	%APPDATA%/Balatro/Mods/lovely/log/

パターンのリファレンス

特定のトピックについては、以下のファイルを参照してください。

トピック	リファレンスファイル
Lovely.toml の構文	patterns/lovely-patches.md
SMODS のフック、設定、ローカライズ	patterns/smods-api.md
デスクトップとモバイルの違い	patterns/mobile-compat.md
UIBox、CardArea、描画順序	patterns/ui-system.md
ゲームのソースファイル一覧と検索のヒント	references/game-files.md
G.GAME、G.STATES、G.P_* グローバル	references/globals.md
Lua／LuaJIT の落とし穴、よくある MOD の不具合	references/lua-gotchas.md

新しい MOD のセットアップ（タイプ：new）

${CLAUDE_PLUGIN_ROOT}/templates/ フォルダー内のテンプレート：

ファイル	用途
agents-md-template.md	標準的な MOD 用の AGENTS.md テンプレート
agents-texture-pack-template.md	Malverk テクスチャパック用の AGENTS.md
mod-config-template.json	スクリプト設定
gitignore-template	標準の .gitignore
logger-template.lua	一元化されたロギングユーティリティ

メタファイル：

ファイル	用途
mod-json-template.json	SMODS MOD マニフェスト（{ModName}.json）
manifest-json-template.json	Thunderstore マニフェスト

templates/docs/ 内のユーザードキュメント：

ファイル	用途
description-template.md	docs/ 用の簡潔な README
NEXUSMODS_DESCRIPTION-template.txt	NexusMods 用 BBCode
knowledge-base-template.md	問題と学んだこと

基本的な MOD 構成（新しいリポジトリ）：

{ModName}/
├── main.lua                 # Entry point, mod registration
├── config.lua               # Config defaults (optional)
├── lovely.toml              # Lovely patches (if needed)
├── {ModName}.json           # SMODS mod manifest
├── manifest.json            # Thunderstore manifest
├── mod.config.json          # Script configuration
├── Utils/
│   └── Logger.lua           # Centralized logging
├── localization/
│   ├── en-us.lua            # English (required)
│   └── zh_CN.lua            # Chinese
├── assets/                  # Sprites, shaders
├── scripts/                 # Utility scripts
└── docs/                    # Documentation

利用可能なコマンド（合計 16 個 — プラグインに同梱、自動読み込み）

• /balatro-mod-dev:familiar - この MOD の概要を把握します（AGENTS.md を読み、アーキテクチャを整理します）
• /balatro-mod-dev:init - 新しい MOD を初期化します
• /balatro-mod-dev:sync-mod - ウォッチモードで同期を開始します（開始時に一度だけ実行）
• /balatro-mod-dev:bump-version [patch|minor|major] - バージョンを更新し、変更履歴を更新します
• /balatro-mod-dev:release - リリースパッケージを作成します（マニフェストからバージョンを自動検出）
• /balatro-mod-dev:fix-sprites <directory> [--preview] - スプライトの灰色の縁を修正します
• /balatro-mod-dev:refactor [focus-area] - 冗長なコード、古くなったフォールバック、モジュール化についてコードを確認します
• /balatro-mod-dev:debug - Lovely のログを確認して修正を検証します（リポジトリから MOD キーを自動検出）
• /balatro-mod-dev:test [scenario] - テストシナリオを実行し、Lovely のログで MOD の動作を検証します
• /balatro-mod-dev:draft-pr - PR メッセージの下書きを作成します（フォーク向け）
• /balatro-mod-dev:check - プロジェクトの健全性を監査し、不足しているルールを追加します
• /balatro-mod-dev:update-docs - すべてのドキュメントについて、正確さ、古さ、重複、冗長さを確認します
• /balatro-mod-dev:update-plugin - 新たな知見に基づいてプラグインを更新します
• /balatro-mod-dev:knowledge - セッションの作業を振り返り、発見したことを記録します
• /balatro-mod-dev:compact - 今すぐコンテキストを圧縮すべきかを判断します
• /balatro-mod-dev:help - 利用可能なコマンドとエージェントをすべて一覧表示します

サブエージェント（合計 11 個 — プラグインに同梱）

• game-source-researcher - ゲームの関数と挿入ポイントを探します（sonnet）
• smods-api-researcher - SMODS API のパターンと使用方法を探します（sonnet）
• mod-pattern-researcher - 他の MOD による機能の実装方法を探します（sonnet）
• lovely-patch-researcher - Lovely のパッチ構文と例を探します（sonnet）
• project-explorer - コードベースを幅広く調査します（sonnet）
• code-writer - 実装計画を実行し、コードを作成します（sonnet）
• script-runner - 一時スクリプトを実行し、結果を返します（haiku）
• code-reviewer - 正確性とエッジケースについてコードをレビューします（opus）
• research-analyst - 複数の調査結果をまとめます（opus）
• strategic-planner - 複雑な機能の実装戦略を立てます（opus）
• debug-inspector - 実行時ログ、ダンプ、MOD の互換性を調査します（sonnet）

ロギング

新規／自分のリポジトリの場合：

${CLAUDE_PLUGIN_ROOT}/templates/logger-template.lua の Utils/Logger.lua を使用します。

local Logger = require("Utils.Logger")
local log = Logger.create("ModuleName")
log("info", "Initialized")
log("error", "Failed: " .. err)

フォーク／他者のリポジトリの場合：

一時ログのみを使用してください（PR の前に削除します）。

pcall(print, "[Debug] checkpoint: " .. tostring(var))

ユーティリティスクリプト

スクリプト	目的
${CLAUDE_PLUGIN_ROOT}/scripts/sync_to_mods.template.sh	Mod ファイルをゲームの Mods フォルダーに同期します
${CLAUDE_PLUGIN_ROOT}/scripts/create_release.template.sh	リリースパッケージを作成します
${CLAUDE_PLUGIN_ROOT}/scripts/fix_transparent_pixels.py	スプライトの灰色の縁を修正します

ワークフロー：デバッグ

1. 既知の落とし穴（FFI cdata、nil のスコープ、ブール値の正規化）について、references/lua-gotchas.md を確認します
2. プラットフォーム（デスクトップかモバイルか）を確認します
3. ゲームのソースコードで関数を検索します
4. 他の Mod の実装を確認します
5. ログを追加します（自分の Mod には Logger.lua、フォークには一時的なログを使用します）
6. Lovely のログを確認します
7. 修正に3回以上失敗した場合： research-analyst（opus）を呼び出して、デバッグに関するすべての情報をまとめます

ワークフロー：ユーザードキュメントの更新

ユーザーが「すべてのユーザードキュメントを更新して」と言った場合：

1. すべてのファイルを確認します：README(_zh).md、CHANGELOG(_zh).md
2. docs/ を確認します：description.md、NEXUSMODS_DESCRIPTION.txt
3. {ModName}.json、manifest.json のバージョンを更新します
4. EN/ZH の一貫性を確認します