godot-monte-carlo-balancer

Skill Chain

godot-resource-data-patterns → godot-economy-system →
  (godot-combat-system | godot-rpg-stats | godot-game-loop-waves) →
  godot-monte-carlo-balancer → godot-testing-patterns → godot-builder

鉄則：ソースから抽出し、設定不要にする

シミュレーション内で数値を手作業でコピーしないでください。起動時に Resources／ソースを解析し、次回の実行にデザイナーの変更を反映してください。

抽象モデル（Phase 0 で必須）

抽象化	意味	ない場合
セッション	制限のある試行	—
脅威	失敗へ向かう圧力	削除
防御／主体性	プレイヤーが操作できる要素	削除
故障	注意力への負荷	削除
リソース	消費されるフロー	削除
ラン中の経済	セッション内の支出	削除
メタ経済	ショップ／アンロック／プレステージ	削除
グレード	星／ランク／時間／スコア	削除

BALANCE_PLAN.md を作成してください。マッピングした行だけをシミュレーションしてください。

段階的な情報開示

必須：そのフェーズを実装する前に、リンク先のリファレンスを読んでください。

読み込まないでください：

• example-lane-defense.md — Phase 0 でレーンディフェンス／シフト TD にマッピングした場合を除く
• 06-genre-adaptation.md — ジャンルがデフォルトの PvE 勝率帯セッションと異なる場合を除く
• 07-godot-calibration.md — キャリブレーションを開始するとき、または Phase 0 で物理／AI の適用除外を認めなかった場合のみ（適用除外は、完全に数式ベースの数学のみのゲームであることを意味し、BALANCE_PLAN.md に記載します）

Phase 0 — 監査 → references/00-game-audit.md

ジャンル、勝敗、モード、カタログ、影響グラフ、経済、スタイル＋主要指標、抽出計画を確認します。デザイナーの承認を得てください。

Phase 1 — 抽出 → references/01-source-extraction.md

リソース優先の判断ツリー。シミュレーションの前に inspect を実行します。

Phase 2 — シミュレーション → references/02-simulation-engine.md

動作を表す PlayStyle × InputModel（マウス／タッチ／ゲームパッド）、モバイル向けの SessionModel、シード付き SmallRng、独立したジョブを rayon で並列実行します。

Phase 3 — 分析 → references/03-analysis-reporting.md

Wilson／ブートストラップの信頼区間に基づく判定、二次的な主体性のチェック、安定した JSON を扱います。

Phase 4 — 経済 → references/04-economy-retention.md

キャリア、ファーム、利息曲線、報酬頻度のチェックポイントを扱います。

Phase 5 — 調整 → references/05-tuning-generation.md

帯域スコアによる総当たり調整を行います。プロジェクトが Resource 優先の場合は .tres を出力します。

Phase 6 — ジャンル → references/06-genre-adaptation.md

指標の上書き＋ドメインスキルの連鎖を扱います。

Phase 7 — キャリブレーション → references/07-godot-calibration.md

全マトリックスの最終承認前に、Godot ヘッドレス実行と 3～5 個のゴールデンセルを照合します（適用除外の場合を除く）。

同梱リソース

コピー後の標準レイアウト：

tools/
  balance_lab.ps1          # from launcher.ps1
  balance_lab.sh           # from launcher.sh
  balance_lab/
    Cargo.toml
    src/main.rs            # clap stubs — expand per Phase 0

scripts/balance-lab-template/

Cargo.toml＋src/ を tools/balance_lab/ にコピーします。ランチャーはクレートディレクトリと同じ階層にある tools/balance_lab.ps1／tools/balance_lab.sh として配置します。

scripts/compare_balance_snapshots.py

CI 対応のスナップショット差分ツールです。

references/json-schema.md

安定した --json フィールドの契約です。

CLI 契約

balance-lab inspect
balance-lab simulate --level 3 --style average --runs 1000
balance-lab career --style casual --runs 200
balance-lab mode <key> --runs 500
balance-lab bruteforce --level 4 ...
balance-lab gen-level ...
balance-lab calibrate --cells golden.json
balance-lab --json <any command>
balance-lab --seed 42 <any command>

目標範囲（デフォルト。Phase 0 で上書き）

範囲は style × input_model のセルごとに定義されます。デフォルトの入力モデルは mouse です。

スタイル	入力	勝率の目標	下回る場合 →	上回る場合 →
afk	mouse	5% – 55%	難しすぎる	簡単すぎる
casual	mouse	55% – 90%	難しすぎる	簡単すぎる
average	mouse	70% – 95%	難しすぎる	簡単すぎる
pro	mouse	90% – 100%	難しすぎる	—
afk	touch	5% – 55%	難しすぎる	簡単すぎる
casual	touch	55% – 90%	難しすぎる	簡単すぎる
average	touch	65% – 92%	難しすぎる	簡単すぎる
pro	touch	85% – 100%	難しすぎる	—

シミュレーション対象の style × input_model セルがすべて範囲内に収まった場合に限り、レベルは OK です。難易度は入力速度だけにペナルティを課すのではなく、レベル曲線から生み出す必要があります。

プラットフォームルール：ゲームをモバイルでリリースする場合、マトリックスにはタッチ入力モデルを必ず含めてください。マウスでは OK でも、タッチでは難しすぎるレベルは、難しすぎます。

CI 判定ルール（唯一の基準）

モード	セルあたりの実行回数	OK のルール
探索／作業中	100～300	95% CI が範囲と重なること。そうでない場合は TOO_HARD／TOO_EASY／INCONCLUSIVE
承認／DoD／スナップショット	≥1000	すべてのスタイル × リリース対象の入力モデルについて、95% CI が範囲に完全に含まれること

格闘ゲーム／教育ゲーム／放置ゲームでは、勝率%を別の指標に置き換えることがよくあります。主要指標は Phase 0 で設定してください。

絶対にしてはいけないこと

データと抽出

• ゲームの数値をハードコードしたり、既存の Resources／.tres を無視したりしてはいけません — 手動コピーは劣化して誤った結論につながります。Resource プロジェクトで正規表現を使って大量に抽出すると、データレイヤーと競合します。Resource を優先し、正規表現はインラインの数式係数にのみ使ってください。最初の simulate の前に、inspect 内の (default!) をすべて明示してください。
• 埋め込み数式を無視してはいけません — 係数を抽出し、シミュレーション内で一度だけ再実装してください。数式の形状が変わった場合は、正規表現が明確にエラーを出すようにしてください。

シミュレーションの忠実性

• 最適なプレイだけをシミュレーションしてはいけません — プロ向けだけに合格する設定でリリースすると、プレイできない最低難易度が生まれます。AFK／カジュアルでの失敗こそ、プレイヤーが不具合として感じるものです。
• 人間を即時反応するものとしてモデル化してはいけません — 遅延ゼロのエージェントなら、実際のプレイヤーが見逃すジャムや故障の時間枠をクリアできます。その結果、難易度が反射神経だけを要求する仕組みに収束します。
• デスクトップの反応／タップのパラメーターをモバイルで使い回してはいけません — タッチでは、1 秒あたりのタップ数が少なく、見逃しやすく、遮蔽も発生します。マウスの数値を基準に調整すると、モバイルでプレイできないゲームをリリースすることになります。
• モバイルで中断のないセッションを前提にしてはいけません — 中断（通知、アプリ切り替え）とセッション時間の上限をモデル化してください。12 分間途切れることなく集中しなければならないレベルは、プラットフォームに適していません。
• 精度に依存する仕組みをタッチでテストせずに済ませてはいけません — 正確かつ素早いポインティングが必要な仕組みは、承認前にタッチの精度モデルを使ってシミュレーションしてください。
• メタゲームを省略してはいけません — ショップ／アップグレード／モード／リプレイを省略すると、「バランスの取れた」セッションが、キャリアの破綻したゲームを生みます。
• シード経路に非シード化の方法や HashMap のハッシュを使ってはいけません — デフォルトのハッシャーはプロセスごとにランダム化されるため、マシン間や Rayon のスケジュール間で CI の差分が誤って発生します。seed_for と安定したハッシュを使い、決定性をユニットテストしてください。
• rayon ジョブ間で RunState／RNG を共有してはいけません — 相互干渉がバランス調整のノイズに見え、再現性を損ないます。
• 未調整の物理／AI モデルから数学的なバランスを断言してはいけません — Phase 7 を実施するか、文書化された免除を用意してください。抽象化された DPS は Godot の衝突判定と同じではありません。

バランス調整の判断

• 単一の平均値だけで判断してはいけません — ヒストグラム、ダウンタイム、失敗の種類ごとの内訳、リソース比率では、五分五分の状況とスキルの壁が隠れてしまいます。
• 点推定だけで判定してはいけません — CI のルール（Search の重なり / SignOff ⊆）；Search は300以上、SignOff は1000以上です。
• リソースフローを確認せずに攻略可能と断定してはいけません — 消費に対する圧力と収入を確認してください（資源不足なのに「攻略可能」と判定してしまう、典型的な不具合です）。
• 難易度と経済を別々にバランス調整してはいけません — クリア時間が通貨／分に影響します。難易度を編集した後はキャリアを再実行してください。
• 農場を過度に弱体化した後、ショップへの到達可能性を再確認せずに済ませてはいけません — エクスプロイト対策のパッチで、進行ルートが行き止まりになることがよくあります。
• AFKからプロまでの PvE 帯域だけを使って PvP のバランス調整をしてはいけません — マッチアップ / MMR の指標も確認してください。

調整とメンテナンス

• 1つのセッションだけを切り離して調整してはいけません — 変更後は全マトリクスとキャリアを確認してください。
• シミュレーション検証なしで生成コンテンツを受け入れてはいけません。
• Resource 優先のプロジェクトに .gd ファクトリーを出力してはいけません — .tres / Resource の形式で出力してください。
• ゲームのソースを編集した後に GameData をキャッシュしたままにしてはいけません。
• デザイナーに手動コンパイルさせてはいけません — 自動で再ビルドするランチャーを使ってください。古いバイナリは古い結論につながります。
• エージェント向けに標準出力だけを使ってはいけません — --json と game_data_hash を使ってください。

基本手順（最初の取り組み）

1. Phase 0 → BALANCE_PLAN.md と、帯域 / 指標に関するデザイナーの合意。
2. Phase 1 の抽出 → inspect → 想定外の (default!) があれば、停止して抽出を修正してください（example-lane-defense.md の問題を参照）。
3. Phase 2–3：300回実行するセルを1つ（Search の重なり）→ 全マトリクス → 1000回実行時の SignOff ⊆。
4. Phase 4 のキャリア → 農場 / ショップのフラグ → Phase 7 のキャリブレーション（免除されていない場合）→ JSON スナップショット。

完了の定義

1. inspect で検証済み。想定外の (default!) がないこと。
2. シード決定性テストに合格していること。
3. Phase 7 に合格していること（または Phase 0 の免除が記録されていること）。
4. 全マトリクス（全レベル × 全スタイル × 出荷するすべての入力モデル、セルあたり1000回以上の実行）— すべてのセルで CI ⊆ 帯域（SignOff のルール）を満たすこと。
5. モードとキャリア：通貨／分が適正であること、支配的な農場がないこと、ショップに到達できること。
6. 関心曲線と報酬間隔のチェックポイントに合格していること。
7. CI 用の回帰 JSON スナップショットがコミットされていること。

リファレンス

段階的開示：特定の API を調査するときだけ公式ドキュメントへのリンクを開いてください。 作業を隣接ドメインに振り分けるときは関連スキルを読み込み、全体を一括で事前読み込みしないでください。

公式ドキュメント

• リソース — GameData の推奨抽出元です（正規表現による農場ではなく .tres を使用）。
• JSON — バランス調整用 JSON のスナップショット / CI への出力と解析。
• FileAccess — エクスポートされたバランスデータのダンプとゴールデンセルの読み込み。
• ResourceLoader — 抽出 / キャリブレーション用のデザイナー作成 Resource の読み込み。
• コマンドラインチュートリアル — Phase 7 のキャリブレーション実行に使うヘッドレス Godot。
• ユニットテスト — シードと抽出の決定性テスト。
• OS — ラボランチャー用のプロセス / 環境変数フック。
• ProjectSettings — CI のバランス調整ジョブ用のパスと機能タグ。
• RandomNumberGenerator — Rust ラボと同様のシード付き RNG パターン。
• SceneTree — ゴールデンセルのキャリブレーション用のヘッドレスシーン起動。
• Engine — ヘッドレスシミュレーション用の時間スケール / フレーム。
• ConfigFile — コード外でデザイナーが帯域を上書きするためのオプション。

関連スキル

前提条件

• godot-resource-data-patterns — 正規表現で抽出する前に、GameData を Resource 優先で扱います。
• godot-testing-patterns — Phase 7 向けのヘッドレスランナーとゴールデンセルです。
• godot-builder — キャリブレーション用の CLI／ヘッドレスプロジェクトのスキャフォールディングです。
• godot-project-foundations — 抽出パスを安定させるためのリポジトリ構成です。

補完スキル

• godot-economy-system — キャリア、シンク、ショップの到達可能性に関する入力です。
• godot-combat-system — マトリクスでシミュレーションするダメージ／ヘルスの Resource です。
• godot-rpg-stats — 抽出して調整するカーブと修正値です。
• godot-ability-system — スタイルマトリクス用のクールダウン／コストのロードアウトです。
• godot-game-loop-waves — シミュレーションセルとしてのウェーブ難易度帯です。
• godot-inventory-system — キャリアシミュレーション向けの戦利品／経済の連携です。

下流／利用側

• godot-genre-roguelike — メタプログレッションの勝率帯です。
• godot-genre-tower-defense — レーン防衛スタイルのマトリクスです（例の参照先を参照）。
• godot-genre-idle-clicker — キャリア／マイルストーン到達までの時間帯です。
• godot-genre-fighting — AFK→プロ PvE 以外の対戦マトリクスです。

マスター

• godot-master — バランスラボ用のライブラリルーターとミラー化されたモジュールエントリーです。