godot-economy-system

決定木：通貨の表現方法

経済タイプ	保存形式	理由
UI で小数表示するソフトカレンシー（金、スクラップ）	int のセント／最小単位	正確な計算が可能です。表示時は value / 100.0 とします
プレミアム通貨／放置ゲームで扱う数量が 2^31 を大きく超える場合	BigInt／複数桁の int（または概算で問題ない場合に限り、慎重にスケーリングした float）	32 ビットの int の上限は約 21 億です
マルチプレイヤー／永続化するウォレット	サーバー上の権威ある int（または BigInt）	クライアントは支出を確定しません
表示上のみ小数を使う価格	引き続き最小単位の int	0.1 + 0.2 の浮動小数点誤差を防ぎます

この決定木を使わずに、「金額には float を使う」と「金額には float を絶対に使わない」を絶対に混在させないでください。どちらか一方を選び、徹底してください。

経済システムで絶対にしてはいけないこと

• 売買の価格差を絶対に省略しないでください — 買値と売値が同じだと、無限にお金を増やせます。
• 通貨のシンクを絶対に省略しないでください — 修理、税金、手数料、消耗品がインフレを防ぎます。
• 支出の検証をクライアントだけで絶対に行わないでください — マルチプレイヤーでは、サーバー／ホストが信頼できる唯一の情報源です。
• 戦利品の重みをスクリプトに絶対にハードコードしないでください — リソースを使用してください（loot_table_weighted.gd）。
• current >= amount の確認前に絶対に減算しないでください — アンダーフロー／負のウォレット残高によって、セーブデータが破損します。
• UI から残高を直接変更させないでください — UI はリクエストを送り、wallet_manager_singleton.gd／transaction_manager.gd が判断します。
• 本格的な RPG では、取引ログを絶対に無視しないでください — 通貨不足の監査証跡になります。
• 上限値を超える場合は、クランプせずに値を超過させないでください — ラップアラウンド／オーバーフローが起きる前に上限を適用してください。

---

推奨手順（必須）

1. currency_resource.gd — 額面のメタデータ
2. wallet_manager_singleton.gd — 残高とシグナル
3. transaction_manager.gd — 検証済みの支出／付与パイプライン
4. ウォレットと取引の仕組みを用意してから、ショップ／戦利品／UI に取りかかってください

場当たり的な EconomyManager のゴールドチュートリアルは削除してください。シーン内にウォレットのロジックを再度インラインで記述しないでください。

判断ポイント → スクリプト

タスク	読み込むもの	読み込まないもの
残高／Autoload ウォレット	wallet_manager_singleton.gd	Player にインラインでゴールドの int を記述すること
支出／付与の検証	transaction_manager.gd	UI から gold -= n を呼び出すこと
ショップでの売買＋在庫	shop_item_data.gd + shop_system_logic.gd	買値と売値を同じにすること
販売／評判による価格設定	dynamic_price_modifier.gd	—
重み付き戦利品	loot_table_weighted.gd	敵のスクリプトに % をハードコードすること
戦利品からウォレットへの連携	loot_drop_economy_bridge.gd	—
HUD の同期	currency_label_sync.gd	シグナルを使わずに _process でウォレットをポーリングすること
ウォレットの保存	economy_persistence_handler.gd	—
アイテム取得時の VFX	currency_pickup_effect.gd	—
複数アイテムの物々交換	trade_contract_resource.gd	—

利用可能なスクリプト（全カタログ）

• currency_resource.gd
• wallet_manager_singleton.gd — 必須
• transaction_manager.gd — 必須
• shop_item_data.gd
• shop_system_logic.gd
• dynamic_price_modifier.gd
• currency_label_sync.gd
• loot_table_weighted.gd — 重み／レア度
• loot_drop_economy_bridge.gd — 戦利品で通貨を付与しない場合は読み込まないでください
• economy_persistence_handler.gd
• currency_pickup_effect.gd
• trade_contract_resource.gd — 物々交換がある場合を除き、読み込まないでください
• economy_logger.gd — GPM／インフレのテレメトリーロガー
• item_value_estimator.gd — レア度に基づく商人の査定

エリート向けの追加機能

• 物々交換契約： trade_contract_resource.gd を介した、複数アイテムの交換取引です。
• GPM 分析： economy_logger.gd — [ECON] ログ行から、1 分あたりのゴールド獲得量を算出します。
• 価値推定器： item_value_estimator.gd — レア度に基づく売却価格曲線です。売却価格は常に購入価格を下回ります。

GPM のログ記録、動的な価格評価、移動したショップ／戦利品チュートリアルには、economy-elite-patterns.md の参照が必須です。ウォレットとトランザクションの基本手順のみの場合は、読み込まないでください。

リファレンス

段階的開示：特定の API を調べる場合にのみ公式ドキュメントのリンクを開き、関連スキルは関連分野へ移る際に読み込んでください。関連項目全体を事前に読み込まないでください。

公式ドキュメント

• リソース — 通貨、ショップアイテム、戦利品テーブル、取引契約は、共有可能な Resource アセットとして用意します。そうすることで、コードを変更せずにデザイナーが価格やドロップ率を調整できます。
• Resource — 実行時の価格補正や商人ごとの在庫を適用する場合は duplicate() を使用します。これにより、あるショップで共有 .tres テンプレートを変更しても、ほかのすべての商人に影響しません。
• GDScript のエクスポート — 購入／売却価格差、在庫上限、通貨 ID、戦利品の重みを @export で設定し、経済バランスをインスペクターから調整できるようにします。
• シングルトン（Autoload） — シーン遷移（ワールド ↔ ショップ ↔ メニュー）後も維持する必要がある残高には、WalletManager の Autoload を使用するのがエンジンの推奨パターンです。
• Autoload と通常のノードの比較 — グローバルなウォレット状態は Autoload に保持し、商人の UI や一時的なショップのロジックはシーンノードに保持します。これにより、テストやマルチプレイヤーの権限管理を柔軟に組み合わせられます。
• シグナルの使用 — balance_changed／transaction_failed を発行すれば、UI からウォレット残高を書き換えることなく、HUD のラベルやアイテム取得時の VFX が変更を受け取れます。
• ゲームの保存 — ウォレットの辞書（およびショップの在庫状態）を、ほかの進行状況データと一緒に保存します。ソフト通貨をメモリ内だけに保持しないでください。
• FileAccess — 経済データを含むセーブデータを読み書きします。プレイヤーが書き込み可能な残高ファイルには、プロジェクトの user:// パスを組み合わせてください。
• JSON — currency_id → amount の辞書を JSON 互換の構造としてシリアライズし、透明性の高いセーブ／ロードや分析データの出力に利用します。
• 乱数の生成 — 重み付き戦利品やドロップの抽選には、独自の剰余演算による小細工ではなく、Godot の RNG API（randf、シード付き RNG）を使用します。
• RandomNumberGenerator — シード可能な RNG インスタンスを使うと、戦利品テーブルのモンテカルロテストや決定論的なバランステストを再現できます。
• ハイレベルマルチプレイヤー — 支出／付与の検証はサーバー側で行う必要があります。クライアントはトランザクションをリクエストし、確認済みの残高 RPC のみを反映します。

関連スキル

前提条件

• godot-resource-data-patterns — Currency、ShopItem、LootTable、TradeContract の定義は Resource を優先しているため、価格やドロップに別のデータ形式を導入する前に読み込んでください。
• godot-autoload-architecture — Autoload としての WalletManager には、経済状態が何でも詰め込まれた巨大なオブジェクトにならないよう、適切な所有権、初期化順序、名前空間が必要です。
• godot-signal-architecture — 残高と取引のシグナルでは「シグナルは上へ／呼び出しは下へ」を徹底し、UI がウォレットを直接変更しないようにする必要があります。
• godot-gdscript-mastery — 型付き Resource、Dictionary 型のウォレット、アトミックな購入ヘルパーには、堅実な GDScript のパターン（減算前のガード、金額に float を使わないこと）が前提となります。

補完

• godot-inventory-system — 売買や物々交換はウォレットとインベントリ間のアトミックな交換です。在庫と容量の確認は、価格計算だけでなくインベントリ側で行う必要があります。
• godot-save-load-systems — 経済データの永続化ハンドラーは、プロジェクトのセーブスキーマ（バージョン管理、移行、必要に応じたプレミアム残高の暗号化）に組み込む必要があります。
• godot-rpg-stats — 魅力や評判による割引、支出先（修理費）には、ショップ UI に倍率を直接ハードコードせず、一貫した修正レイヤーが必要です。
• godot-ui-containers — ショップ画面と通貨 HUD のレイアウトはウォレットのシグナルにバインドしてください。コンテナは表示を担い、WalletManager は正しい状態を管理します。
• godot-quest-system — クエストのゴールド報酬と納品時の支出先は、主要な通貨の獲得源・消費先です。gold += を場当たり的に使わず、取引 API を通じて報酬を処理してください。
• godot-combat-system — 戦利品ドロップの連携処理は戦闘・戦利品イベントを監視して資金を付与し、ダメージ処理のパイプラインに経済ルールを組み込まないようにします。

下流 / 利用側

• godot-monte-carlo-balancer — 支出先、戦利品の重み付け、ショップの価格差を Resource 駆動にした後、モンテカルロによるファーム・キャリアのシミュレーションで、ゲーム内経済のカーブをリリースする前にインフレと購入可能になるまでの時間の幅を検証できます。
• godot-multiplayer-networking — UI 上の予測支出と、権威サーバー側の付与・支出 RPC は、ウォレットのリクエスト／検証／適用の分離を基盤とします。
• godot-genre-idle-clicker — 放置型／プレステージ通貨と消費ループをこのスキルと組み合わせ、長期的なバランス調整とオフライン蓄積のジャンル固有の連携処理を構成します。
• godot-genre-action-rpg — アクション RPG のショップ、クラフトの支出先、ドロップ経済を、ウォレット、インベントリ、戦利品テーブルと組み合わせて、進行のペースを調整します。

マスター

• godot-master — ライブラリのルーター兼ミラー化されたモジュールのエントリです。関連スキルの検索や、Domain Skill の編集後に共有スクリプトのミラーを同期する際に使用してください。