godot-genre-simulation

切勿采用的做法（专家级反模式）

模拟与经济

• 切勿使用浮点数表示主要货币；必须使用整数分（或定点数运算），以避免金融模型中的累计精度误差。
• 切勿在 _process() 中逐个处理 1000 个或更多实体；必须使用Tick 管理器批量更新，或在轮转池中处理实体。
• 切勿依赖线性成本增长；必须使用指数增长（Base * pow(1.15, Level)），以保持挑战性和策略张力。
• 切勿向玩家隐藏关键指标；必须提供详细明细（收入与支出），让玩家能够基于优化做出决策。
• 切勿允许资源无限堆叠；必须严格执行物流容量上限（仓库／筒仓），打造有意义的空间管理玩法循环。
• 切勿让游戏前期变成“等待模拟器”；必须将决策前置，并提供快速的前期胜利来增强玩家的动力。
• 切勿直接修改共享资源；必须使用 duplicate()，以免无意中更新该类型的所有建筑。
• 切勿将模拟逻辑绑定到视觉帧率；必须使用 _physics_process() 或 delta 累加器，以确保模拟结果具有确定性。

性能与线程

• 切勿每帧都更新 UI 标签；必须使用事件驱动信号，仅在底层数据发生变化时刷新 UI。
• 切勿同步运行高负载的经济循环；必须使用 WorkerThreadPool 分担复杂计算，避免 UI 卡顿。
• 切勿将大量资源数据存储为 Nodes；必须使用 RefCounted 或数据资源，避免 SceneTree 的内存／CPU 开销。
• 切勿忽略 OS.low_processor_usage_mode；在静态管理界面中必须启用此功能，以大幅节省 CPU／电池电量。
• 切勿从后台线程操作 SceneTree；必须使用 call_deferred() 进行线程安全的 UI 更新。
• 切勿在主线程解析大型 JSON 存档文件；必须使用线程化序列化或经过优化的二进制 .res 格式。
• 切勿对需求使用标准相等运算（==）；必须使用 is_equal_approx()，以避免逻辑门中的浮点抖动错误。

---

🛠 专家组件（scripts/）

实现对应系统前，必须阅读：

1. tycoon_economy.gd — 整数分／离散库存
2. sim_tick_manager.gd — _physics_process Tick 累加器
3. simulation_tick_controller.gd — 速度／暂停控制界面

原创专家模式

• tycoon_economy.gd - 多资源经济系统，使用整数货币（分）。
• sim_tick_manager.gd - 基于物理帧、与帧率解耦的游戏小时 Tick。

模块化组件

• simulation_tick_controller.gd - Tick 管理器的 UI／速度连接。
• economy_graph_manager.gd - 生产者／消费者图边。
• npc_schedule_agent.gd - 按时间表驱动、在 Tick 上运行的 NPC Agent。
• simulation_patterns.gd - CSV→Resource 烘焙、AStarGrid2D 物流、低处理器占用辅助工具。

---

核心循环

1. 放置／建造 → 2. 推进经济 Tick → 3. 查看收入与支出 → 4. 解锁／扩张 → 5. 优化物流

决策树

货币与时间（必须符合“切勿采用”规则）

需求	操作
资金／钱包	必须使用 tycoon_economy.gd — 整数分，主要货币绝不使用浮点数
模拟时钟	必须使用 sim_tick_manager.gd — 在 _physics_process 中使用累加器
速度 UI	simulation_tick_controller.gd

Tick 速率、UI 与线程

实体 / 负载	策略
< ~200 个实体	Tick 信号 → 直接更新；仅通过 resource_changed 更新 UI
数百个 Agent	每个 tick 轮换池；npc_schedule_agent.gd
重型图 / 路径物流	使用 WorkerThreadPool 卸载任务；通过 call_deferred 更新 UI——参见 simulation_patterns.gd / economy_graph_manager.gd
固定的管理界面	启用 OS.low_processor_usage_mode

不要重复内嵌 TycoonEconomy / SimulationTime / Worker 教程——加载脚本即可。

技能链

阶段	技能	用途
1. 数据	resources、godot-economy-system	库存 / 消耗端
2. 时间	tick 管理器	确定性小时
3. Agent	日程 / 导航	NPC 与物流
4. 性能	WorkerThreadPool	重型 tick
5. 平衡	godot-monte-carlo-balancer	破产 / 增长区间

常见问题

问题	解决方案
浮点数货币	在 tycoon_economy 中使用整数分
用 _process 作为模拟步骤	使用物理帧累加器 tick 管理器
每帧更新 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:// 下。
• 使用多个线程 — 复杂的生产图和维护计算应放在 WorkerThreadPool 中，而不是主线程的 UI 循环中。
• 线程安全 API — 将模拟结果传递给 Label／Tree 时，必须遵循 call_deferred／主线程 SceneTree 规则。
• WorkerThreadPool — 用于批量处理经济刻度而不阻塞管理界面的 API。
• OS — 在静止的经营类 UI 上启用 OS.low_processor_usage_mode，以降低 CPU 和电池消耗。
• AStarGrid2D — 无需手动连接 AStar 点，即可在工厂地面上实现网格物流和工人路径。
• 使用 NavigationServers — 对由日程驱动的 NPC 直接调用 NavigationServer3D.map_get_path 进行查询，无需为每个 Agent 增加节点开销。

相关技能

前置要求

• godot-project-foundations — 在构建刻度管理器和经济图之前，先了解自动加载、资源和场景结构。
• godot-gdscript-mastery — 掌握类型化 Dictionary、信号、is_equal_approx，以及适用于货币和需求的定点安全数学运算。
• godot-resource-data-patterns — 生产配方和解锁表应优先使用 Resource .tres 资源，而不是硬编码的 Node 树。
• godot-signal-architecture — 刻度和 resource_changed 总线必须驱动 UI，不能让 Label 修改模拟钱包。

补充技能

• godot-economy-system — 软货币钱包、消耗渠道和交易账本，可与模拟经营游戏的多资源库存组合使用。
• godot-save-load-systems — 用于大型世界状态的版本化序列化、二进制 store_var，以及多线程存档/读档。
• godot-navigation-pathfinding — 在存在刻度时钟后，为工人任务和日程 Agent 提供 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 — 技能库路由器和镜像模块入口；用于发现同级技能，或在领域技能编辑后同步共享脚本镜像。