godot-genre-simulation

絶対に避けること（エキスパート向けアンチパターン）

シミュレーションと経済

• 金額の基準値に浮動小数点数を絶対に使わないでください。金融モデルで精度誤差が蓄積するのを防ぐため、必ず整数セント（または固定小数点演算）を使ってください。
• _process() 内で1000個以上のエンティティを個別に処理しないでください。更新をバッチ処理するか、エンティティをローテーションするプールで処理するため、必ずTick Managerを使ってください。
• コストが線形に増加する方式に頼らないでください。ゲームの難易度と戦略的な緊張感を保つため、必ず指数関数的な成長（Base * pow(1.15, Level)）を使ってください。
• 重要な指標をプレイヤーに隠さないでください。最適化に基づいた判断ができるよう、必ず詳細な内訳（収入と支出）を提示してください。
• リソースを無制限に蓄積できるようにしないでください。意味のある空間管理のゲームプレイループを生み出すため、必ず物流上の上限（倉庫／サイロ）を設けてください。
• 序盤を「待つだけのゲーム」にしないでください。プレイヤーの勢いを生み出すため、必ず序盤に判断の機会と、早い段階で得られる成功体験を用意してください。
• 共有 Resource を直接変更しないでください。同じタイプの建物すべてが意図せず更新されるのを防ぐため、必ず**duplicate()**を使ってください。
• シミュレーションのロジックを描画フレームレートに結び付けないでください。シミュレーション結果を決定論的にするため、必ず**_physics_process()**または delta アキュムレーターを使ってください。

パフォーマンスとスレッド処理

• UI ラベルを毎フレーム更新しないでください。基盤となるデータが変更された場合にのみ UI を更新するため、必ずイベント駆動型シグナルを使ってください。
• 負荷の高い経済処理ループを同期的に実行しないでください。複雑な計算を別スレッドに移し、UI のカクつきを防ぐため、必ずWorkerThreadPoolを使ってください。
• 大量のリソースデータを Node として保存しないでください。SceneTree によるメモリ／CPU のオーバーヘッドを避けるため、必ず**RefCountedまたはData Resources**を使ってください。
• **OS.low_processor_usage_mode**を無視しないでください。CPU とバッテリーを大幅に節約するため、動きのない管理画面では必ず有効にしてください。
• バックグラウンドスレッドから SceneTree を操作しないでください。スレッドセーフな UI 更新には、必ず**call_deferred()**を使ってください。
• 大きな JSON セーブファイルをメインスレッドで解析しないでください。必ずスレッド化されたシリアライズまたは最適化されたバイナリの.res形式を使ってください。
• ニーズの判定に標準の等価演算子（==）を使わないでください。ロジックゲートでの浮動小数点の揺らぎによる誤判定を防ぐため、必ず**is_equal_approx()**を使ってください。

---

🛠 エキスパート向けコンポーネント（scripts/）

対応するシステムの実装前に、必ず以下を読んでください：

1. tycoon_economy.gd — 整数セント／離散的な在庫
2. sim_tick_manager.gd — _physics_processのティックアキュムレーター
3. simulation_tick_controller.gd — 速度／一時停止の操作インターフェース

独自のエキスパート向けパターン

• tycoon_economy.gd - 整数通貨（セント）を使う複数リソース対応の経済システム。
• sim_tick_manager.gd - 物理処理で実行する、フレームレートから独立したゲーム内時間のティック。

モジュール型コンポーネント

• simulation_tick_controller.gd - ティックマネージャーの UI／速度制御。
• economy_graph_manager.gd - 生産者／消費者のグラフエッジ。
• npc_schedule_agent.gd - スケジュールに基づきティックごとに動作する NPC エージェント。
• simulation_patterns.gd - CSV から Resource への変換、AStarGrid2D による物流、low_processor 用ヘルパー。

---

コアループ

1. 配置／建設 → 2. 経済をティック処理 → 3. 収入と支出を確認 → 4. アンロック／拡張 → 5. 物流を最適化

意思決定ツリー

通貨と時間（NEVER の要件に準拠）

必要なもの	対応
お金／ウォレット	必須 tycoon_economy.gd — 整数セントを使用し、基準値に浮動小数点数は使わない
シミュレーションクロック	必須 sim_tick_manager.gd — _physics_process上のアキュムレーター
速度 UI	simulation_tick_controller.gd

ティックレートと UI とスレッド

エンティティ／負荷	方針
エンティティが約 200 未満	ティックシグナル → 直接更新；UI は resource_changed のみを使用
数百のエージェント	ティックごとにプールをローテーション；npc_schedule_agent.gd
大規模なグラフ／経路物流	WorkerThreadPool にオフロード；UI は call_deferred を使用 — simulation_patterns.gd ／ economy_graph_manager.gd を参照
停止状態の管理画面	OS.low_processor_usage_mode を有効化

TycoonEconomy ／ SimulationTime ／ Worker のチュートリアルを再度インライン化しないでください — スクリプトを読み込んでください。

スキルチェーン

フェーズ	スキル	目的
1. データ	resources、godot-economy-system	在庫／シンク
2. 時間	ティックマネージャー	決定論的な時間
3. エージェント	スケジュール／ナビゲーション	NPC と物流
4. パフォーマンス	WorkerThreadPool	高負荷のティック処理
5. バランス調整	godot-monte-carlo-balancer	破産／成長の範囲

よくある落とし穴

落とし穴	解決策
浮動小数点数の金額	tycoon_economy で整数のセントを使用
_process によるシミュレーションステップ	物理処理のアキュムレーターを使うティックマネージャー
毎フレームの UI 更新	resource_changed のシグナルのみを使用

必要に応じた詳細レシピ

トピック	参考資料／スクリプト
経済とウォレット	economy-design.md + tycoon_economy.gd
シミュレーション時計／速度	time-system.md + sim_tick_manager.gd
作業員と施設	entity-management.md + npc_schedule_agent.gd
需要と顧客	customer-demand.md
フィードバックとダッシュボード	feedback-systems.md
アンロックによる進行	progression-unlocks.md
生産グラフ／CSV ベイク	elite-technical-patterns.md + simulation_patterns.gd

参考資料

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

公式ドキュメント

• アイドル処理と物理処理 — シミュレーションのクロックと経済のティックは、フレーム数を前提とせず、delta（または専用のティック）を蓄積する必要があります。
• シグナルの使用 — リソースやティックの変更を通知し、ウォレットや時間が実際に変化したときだけダッシュボードを更新します。
• リソース — レシピ、施設、アンロック用テーブルは .tres リソースとして用意し、コードを編集せずにデザイナーが生産チェーンを調整できるようにします。
• GDScript のエクスポート — 建設コスト、賃金、成長の基準値を @export し、収支表をインスペクターから調整できるようにします。
• ゲームの保存 — 在庫、日付／時刻、アンロック状態、施設のグラフを永続化し、長時間の経営プレイを再起動後も続けられるようにします。
• データパス — 大容量のバイナリ／JSON形式のシミュレーションセーブデータを、プラットフォームを問わず user:// に保存します。
• 複数スレッドの使用 — 負荷の高い生産グラフや維持費の処理は、メインスレッドの UI ループではなく WorkerThreadPool で行います。
• スレッドセーフな API — シミュレーション結果を Label や Tree に反映する際は、call_deferred とメインスレッドの SceneTree に関するルールに従う必要があります。
• WorkerThreadPool — 経営画面をブロックせずに経済のティックをまとめて処理するための API です。
• OS — 固定表示の経営 UI では OS.low_processor_usage_mode を有効にして、CPU とバッテリーの消費を抑えます。
• AStarGrid2D — AStar のポイントを手動で接続せずに、工場の床面におけるグリッド物流と作業員の経路を実現します。
• NavigationServer の使用 — エージェントごとのノードによる負荷をかけずに、スケジュール駆動型 NPC の経路を NavigationServer3D.map_get_path で直接問い合わせます。

関連スキル

前提条件

• godot-project-foundations — ティックマネージャーや経済グラフを構築する前に、オートロード、リソース、シーン構造を理解します。
• godot-gdscript-mastery — 型付き Dictionary、シグナル、is_equal_approx、通貨やニーズに安全な固定小数点演算を扱います。
• godot-resource-data-patterns — 生産レシピとアンロック用テーブルは、ハードコードされた Node ツリーではなく、Resource を基本とした .tres アセットにします。
• godot-signal-architecture — ティックと resource_changed の通知バスで UI を駆動し、Label がシミュレーションのウォレットを変更しないようにします。

補完

• godot-economy-system — 経営シミュレーションの複数リソース在庫と組み合わせられる、ソフト通貨のウォレット、通貨の消費先、取引台帳です。
• godot-save-load-systems — 大規模なワールド状態のバージョン管理付きシリアライズ、バイナリ形式の store_var、スレッドを使ったセーブ／ロードです。
• godot-navigation-pathfinding — ティッククロックが用意された後の作業員の仕事やスケジュールエージェント向けの NavigationServer／グリッド経路探索です。
• godot-performance-optimization — 1000 体以上のシミュレーションエンティティに対応する、エンティティのバッチ処理、低プロセッサモード、スレッドへのオフロード予算です。
• godot-autoload-architecture — シーンを再読み込みしても維持される TimeManager／Economy のオートロードには、明確な所有権ルールが必要です。
• godot-ui-containers — 収入／支出のダッシュボードや施設一覧は、スロットリングされたシグナルにバインドする Tree／VBoxContainer レイアウトです。

下流／利用側

• godot-monte-carlo-balancer — コスト曲線、生産量、CSV→.tres のバランスシートが揃った後、モンテカルロ方式のキャリアシミュレーションで、成長率をリリースする前にマイルストーン到達までの時間と破産リスクの範囲を検証します。
• godot-genre-idle-clicker — オフライン中の進行とプレステージループでは、経営シミュレーションのティック処理と整数通貨のパターンを再利用します。
• godot-genre-rts — 建設順序に基づく経済システムと作業員の物流では、戦闘規模で同じティック／グラフおよび経路探索のプリミティブを利用します。

マスター

• godot-master — ライブラリのルーターおよびミラー化されたモジュールのエントリーポイントです。関連スキルの確認や、ドメインスキルの編集後に共有スクリプトのミラーを同期するときに使用します。