godot-genre-idle-clicker

绝对不要做的事（专家反模式）

经济与数学

• 绝对不要用标准浮点数表示货币；必须实现 BigNumber（尾数/指数）系统（例如 1.5e300），以防在 1e308 时发生 INF 崩溃。
• 绝对不要用 Timer 节点产生收益；必须在 _process(delta) 中使用手动累加器，以防帧率波动导致偏差。
• 绝对不要硬编码生成器成本或增长；必须使用指数公式：Cost = BasePrice * pow(GrowthFactor, OwnedCount)（行业标准为 1.15x）。
• 绝对不要判断浮点数是否精确相等（==）；必须使用 is_equal_approx() 或 >=，以防精度损失导致进度“卡住”。
• 绝对不要用 to_int() 解析科学计数法字符串；必须使用 to_float() 或专用的 BigNumber 解析器。

性能与优化

• 绝对不要每帧更新所有 UI 标签；必须使用 Signals，仅在值发生变化时更新标签，或将更新频率限制为 10 FPS。
• 绝对不要忽略移动设备的 Low Processor Usage Mode；必须启用 OS.low_processor_usage_mode = true，以延长电池续航。
• 绝对不要每秒实例化/删除数百个文本节点；必须使用 Object Pooling 或 MultiMeshInstance 来实现点击反馈。
• 绝对不要通过修改 text 属性来更新大量日志；必须使用 append_text()，以防阻塞主线程。

玩家体验与持久化

• 绝对不要忽略 Offline Progress；必须使用系统 UNIX 时间戳（Time.get_unix_time_from_system()）计算 seconds_offline * total_revenue。
• 绝对不要让“Prestige”重置带来挫败感；必须提供全局倍率，让下一轮速度显著提升（2-5x）。
• 绝对不要使用 Time.get_ticks_msec() 计算离线时间；必须使用持久化 UNIX 时间戳，因为应用重启时计时值会重置。
• 绝对不要用节点层级存放原始数据；必须使用 RefCounted 或 Resource 对象来实现轻量、可序列化的逻辑。

---

🛠 专家组件（scripts/）

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

1. big_number.gd — 超越浮点数 INF 范围的尾数与指数
2. generator.gd — 指数成本 / 速率单位
3. scientific_notation_formatter.gd — K/M/B/T + 科学计数法显示
4. offline_progress_calculator.gd — UNIX 离线进度追赶（不是 ticks_msec）

原始专家模式

• big_number.gd - 用于 e308+ 数值范围的尾数与指数运算。
• generator.gd - 指数成本单位与生产速率计算。
• scientific_notation_formatter.gd - 易读的 K/M/B/T 和科学计数法后缀。

模块化组件

• offline_progress_calculator.gd - 使用 UNIX 时间戳跟踪真实时间差。
• functional_income_reducer.gd - 快速收入求和模式。
• threaded_catchup_simulator.gd - WorkerThreadPool 后台进度追赶。
• precision_cost_validator.gd - 成本曲线 / 可负担性检查。
• scientific_notation_math.gd - 供格式化器共用的尾数辅助函数。
• idle_performance_setup.gd - low_processor_usage_mode + 信号限频 UI。
• decoupled_economy_signal_bus.gd - 限频的经济系统→UI 信号。
• lightweight_upgrade_resource.gd - 升级 .tres 模式。
• big_int_save_parser.gd - 安全持久化大数值。
• thread_safe_ui_updater.gd - 线程化进度追赶后的延迟 UI 更新。

---

核心循环

1. 点击 → 2. 购买生成器 → 3. 闲置收益 → 4. 升级 → 5. 声望

决策树

数值与显示

需求	操作
超过 ~1e308 的数值	必须 big_number.gd
标签 / 缩写	必须 scientific_notation_formatter.gd
~1.15^n 的成本曲线	generator.gd + precision_cost_validator.gd

离线与性能

需求	操作
离线追赶	必须 offline_progress_calculator.gd（UNIX 时间）
长时间追赶	threaded_catchup_simulator.gd
电池 / 闲置 CPU	idle_performance_setup.gd

不要在技能正文中重新内嵌 BigNumber / Offline 教程——请加载上面的脚本。

技能链

阶段	技能	用途
1. 数学	godot-gdscript-mastery	大数运算
2. UI	godot-ui-containers、labels	科学计数法 / 后缀标签
3. 数据	godot-save-load-systems	离线时间戳 + 声望
4. 逻辑	signals	节流更新经济 UI
5. 平衡性	godot-monte-carlo-balancer	达成里程碑所需时间区间

常见陷阱

陷阱	解决方案
Expert Component href 错误	上面的链接指向规范的 big_number / generator / 格式化器
离线时使用 Time.get_ticks_msec	通过离线计算器使用 UNIX 时间
每帧更新 UI	通过经济总线 / 性能设置使用信号节流

专家知识（按需）

大模型无知规则： 如果通用 Agent 在阅读之前不会知道某项内容，就加载参考资料——绝不要删除专家增量内容。

• expert-idle-clicker-patterns.md — 恢复基线教学内容（架构、原因、实现深度）
• big_real.gd
• offline_progression_manager.gd
• click_juice_manager.gd

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接；在转向相关领域时加载相关技能——不要预加载整个技能网络。

官方文档

• 空闲和物理处理 — 收入必须在 _process(delta)（或固定模拟周期）中累积，而不是依赖计时不稳定的 Timer 节点，这样生成器才能独立于帧率运行。
• 时间 — 离线补算使用 Time.get_unix_time_from_system()；绝不要使用 get_ticks_msec()，因为应用重启时它会重置。
• 保存游戏 — 持久化货币、生成器数量、声望倍率和上次保存的 UNIX 时间戳，让离线收益在重启后仍然有效。
• 数据路径 — 将存档数据保存在 user:// 下，确保离线时间戳和大数值字符串在各个平台上都可写入。
• 资源 — 生成器、升级和声望曲线应作为 .tres Resource 保存，这样设计师无需修改代码就能重新调整 cost_growth_factor。
• GDScript 导出变量 — 使用 @export 导出基础成本、收入速率和增长因子，让平衡数据表由 Inspector 驱动。
• 使用信号 — 仅在余额变化时发出 currency_updated，避免 HUD 标签每帧都重写。
• OS — 为大部分时间都在等待生成器的移动端放置会话启用 OS.low_processor_usage_mode（并设置 sleep usec）。
• 使用多线程 — 耗时的离线补算模拟应交给 WorkerThreadPool；重放数千个周期时，UI 不应卡住。
• 线程安全 API — 将模拟结果传递给 Label 时，需要遵循本页所述的 call_deferred／主线程规则。
• 格式化字符串 — K/M/B 后缀和 %.2fe%d 科学计数法显示依赖正确的格式字符串（并在适当情况下使用 String.num_scientific）。
• RefCounted — BigNumber 和升级数据应使用轻量的 RefCounted／Resource 数据，而不是 Node 树。

相关技能

前置要求

• godot-gdscript-mastery — 尾数／指数类、pow 增长和精度安全比较（is_equal_approx）是构建放置经济系统前必须掌握的 GDScript 核心模式。
• godot-resource-data-patterns — 生成器和升级定义应优先使用 Resource，让平衡曲线保持为数据驱动的 .tres 资源。
• godot-signal-architecture — 解耦的货币信号总线必须向上通知 UI，绝不能让 Label 修改模拟钱包。
• godot-save-load-systems — 离线进度和声望状态需要带版本的存档处理器，以安全地保存 UNIX 时间戳和大数值字符串。

补充

• godot-economy-system — 随着游戏加入商店或声望商店，软货币钱包、消耗项和交易 API 可与放置生成器组合使用。
• godot-ui-containers — 生成器列表和升级网格采用 GridContainer/VBoxContainer 布局，并绑定到适合节流更新的标签。
• godot-ui-rich-text — 科学计数法、后缀字符串和只追加日志应采用 Label/RichTextLabel 模式，而不是反复重建庞大的 text 块。
• godot-performance-optimization — 低处理器模式、UI 节流和池化点击特效，让放置循环在移动设备上更省电。
• godot-autoload-architecture — 在场景重新加载后仍需保留的模拟管理器和经济系统总线，应遵循 Autoload 所有权规则。
• godot-particles — 点击反馈爆发效果应使用批处理的 GPUParticles2D.emit_particle，而不是每次点击都生成 Label 节点。

下游 / 使用方

• godot-monte-carlo-balancer — 由 Resource 驱动成本曲线和声望倍率后，蒙特卡洛职业模拟可在发布成长系数前验证达到里程碑所需的时间范围（而非胜率）。
• godot-platform-mobile — 将放置游戏发布到手机时，可采用此类游戏技能中的低处理器模式、后台恢复和离线追赶模式。

主索引

• godot-master — 库路由器和镜像模块入口；用于查找同级技能，或在 Domain Skill 编辑后同步共享脚本镜像。