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”——选定一列并坚持使用。

经济系统中绝不可做的事

• 绝不要跳过买卖差价——买入价和卖出价相同会导致无限刷钱。
• 绝不要跳过货币回收机制——维修、税费、手续费和消耗品能防止通货膨胀。
• 绝不要只在客户端验证消费——多人游戏中，服务端 / 主机才是事实来源。
• 绝不要在脚本中硬编码战利品权重——使用 Resources（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	—
拾取特效	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] 日志行计算每分钟金币数。
• 价值估算器：item_value_estimator.gd — 由稀有度决定的出售价格曲线；售价始终低于买价。

对于 GPM 日志记录、动态估值以及移植后的商店／战利品教程，必须查阅：economy-elite-patterns.md。仅针对钱包 + 交易黄金路径时不要加载。

参考资料

渐进式披露：仅在研究特定 API 时打开官方文档链接；在切换到相关领域时加载相关技能——不要预加载整个知识体系。

官方文档

• 资源 — 货币、商店物品、战利品表和交易合同都应作为可共享的 Resource 资源，以便设计师无需更改代码即可重新调整价格和掉落权重。
• Resource — 应用运行时价格修正或商人独有的库存时使用 duplicate()，这样一家商店就不会修改所有商贩共用的 .tres 模板。
• GDScript 导出变量 — 使用 @export 导出买卖价差、库存上限、货币 ID 和战利品权重，让经济平衡保持由 Inspector 驱动。
• 单例（Autoload） — WalletManager Autoload 是引擎支持的模式，适用于必须在场景切换（世界 ↔ 商店 ↔ 菜单）后仍保留的余额。
• Autoload 与常规节点的区别 — 将全局钱包状态保存在 Autoload 中；将商人 UI 和一次性商店逻辑作为场景节点，以便测试和多人游戏权限保持可组合。
• 使用信号 — 发出 balance_changed / transaction_failed 信号，让 HUD 标签和拾取特效订阅，而无需通过 UI 写入钱包余额。
• 保存游戏 — 将钱包字典（以及商店库存状态）与其他进度数据一同持久化；切勿只将软货币保存在内存中。
• 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 — 将 WalletManager 设为 Autoload 时，需要严格管理所有权、初始化顺序和命名空间，避免经济状态变成一个臃肿的全能对象。
• godot-signal-architecture — 余额和交易信号必须遵循“信号向上／调用向下”原则，确保 UI 不会直接修改钱包。
• godot-gdscript-mastery — 类型化的 Resource、Dictionary 钱包和原子化购买辅助函数都依赖扎实的 GDScript 编写模式（扣款前先检查，不用浮点数表示货币）。

补充

• godot-inventory-system — 买卖和以物易物都是钱包与库存之间的原子化交换；库存和容量检查应由库存系统负责，而不应只依赖价格计算。
• godot-save-load-systems — 经济系统的持久化处理程序应接入项目的存档架构（版本控制、迁移，并在需要时加密高级货币余额）。
• godot-rpg-stats — 魅力／声望折扣和货币消耗项（维修）需要统一的修正层，而不是在商店 UI 中硬编码乘数。
• godot-ui-containers — 商店界面和货币 HUD 布局应绑定到钱包信号；容器负责呈现，WalletManager 负责维护真实状态。
• godot-quest-system — 任务金币奖励和交付任务时的消耗是货币的重要来源与消耗项；应通过交易 API 发放奖励，而不是临时使用 gold +=。
• godot-combat-system — 战利品掉落桥接应监听战斗／战利品事件并发放资金，而不应将经济规则嵌入伤害处理流程。

下游／使用方

• godot-monte-carlo-balancer — 在消耗项、战利品权重和商店差价由 Resource 驱动后，通过蒙特卡洛刷取／职业模拟验证通胀情况和可购买时间区间，再发布经济曲线。
• godot-multiplayer-networking — 预测式 UI 消费和权威发放／消费 RPC 都建立在钱包的请求／验证／应用分离机制之上。
• godot-genre-idle-clicker — 放置／转生货币和消耗循环将此技能与长期经济平衡及离线累积等类型机制结合起来。
• godot-genre-action-rpg — 动作 RPG 商店、制作消耗和掉落经济结合钱包、库存与战利品表，以控制成长节奏。

主索引

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