经济桥接

CoreLib 统一处理经济来源，让业务模块可以用相似配置完成扣费、收费、奖励和价格公式。这样 Forge、Strengthen、Gem、Skills 等模块不需要分别适配每个经济插件。

支持的经济 Provider

Provider ID	对应插件	注册条件	说明
vault	Vault	Vault 插件已启用	通过 Vault API 对接任何 Vault 兼容经济插件。
excellenteconomy	ExcellentEconomy	ExcellentEconomy 插件已启用	支持多货币系统。

实际可用 provider 取决于服务器安装的插件。CoreLib 启动时会自动检测并注册可用的 provider。

自动选择逻辑

当配置中 provider 为空或 auto 时，CoreLib 按以下规则自动选择：

条件	选择结果
provider 为空或 auto，且 currency 非空	优先选择 ExcellentEconomy（支持多货币）。
provider 为空或 auto，且 currency 为空	选择 Vault（默认货币）。
指定了具体 provider	直接按 ID 查找，不可用则返回失败。

注意：auto 模式不会自动推断 ExcellentEconomy 的默认货币。如果使用 ExcellentEconomy，必须明确指定 currency。

常见配置字段

业务模块中经济相关的常见字段：

字段	类型	默认值	说明
economy.enabled	boolean	true	是否启用经济消耗或奖励。
economy.provider	string	auto	使用哪个经济来源。可选值：auto、vault、excellenteconomy。
economy.currency	string	""	货币 ID。Vault 默认货币留空；ExcellentEconomy 必须指定。
economy.base_cost	number	—	基础价格。
economy.cost_formula	string	—	动态价格公式，支持表达式变量。

基础配置示例

economy:
  enabled: true
  provider: vault
  base_cost: 100

动态价格公式

economy:
  enabled: true
  provider: vault
  cost_formula: '100 + %star% * 50'

公式中的变量由调用模块注入。例如强化模块会注入 %star%（当前星级）、%level%（目标等级）等。

ExcellentEconomy 多货币

economy:
  enabled: true
  provider: excellenteconomy
  currency: gems
  cost_formula: '50 + %level% * 10'

多货币消耗

部分模块支持同时消耗多种货币：

economy:
  enabled: true
  currencies:
    - provider: vault
      currency: ''
      amount: 500
    - provider: excellenteconomy
      currency: gems
      amount: 10

含义：同时消耗 500 金币（Vault 默认货币）和 10 宝石（ExcellentEconomy gems 货币）。

物品货币

部分模块可能支持物品作为货币：

economy:
  enabled: true
  currencies:
    - provider: vault
      amount: 1000
    - provider: item
      item:
        type: vanilla
        id: EMERALD
      amount: 3

物品货币的具体支持取决于模块实现。

扣费时机

不同业务流程扣费时机不同：

模块	扣费时机	说明
EmakiStrengthen	尝试开始前	无论成功失败都扣费（可配置）。
EmakiForge	确认执行时	点击确认按钮后扣除。
EmakiSkills	释放前	满足条件后消耗，释放失败不退还。
EmakiGem	操作确认时	开孔、镶嵌、提取、升级分别配置费用。

配置时要明确：

• 玩家失败是否也要付费。
• 取消操作是否返还。
• 余额不足时是否阻止操作（通常是）。

经济动作

CoreLib 动作系统提供三个经济动作：

动作 ID	参数	说明
give_money	amount（必填）、provider（默认 auto）、currency（默认空）	给玩家增加余额。
take_money	amount（必填）、provider（默认 auto）、currency（默认空）	扣除玩家余额。
set_money	amount（必填）、provider（默认 auto）、currency（默认空）	设置玩家余额。

示例：

actions:
  - 'give_money amount=100 provider=vault'
  - 'take_money amount=25.5 provider=excellenteconomy currency=gems'
  - 'set_money amount=0 provider=vault'

价格公式写法

# 线性增长（温和）
cost_formula: '100 + %star% * 50'

# 多项式增长（中等）
cost_formula: '100 + pow(%star%, 1.5) * 20'

# 指数增长（激进，慎用）
cost_formula: '100 * pow(1.5, %star%)'

• 考虑服务器经济通胀：价格应与玩家收入水平匹配。
• 测试极端值：检查 star=0 和 star=max 时的价格是否合理。

避免出现负数价格时，可以用 max 兜底：

cost_formula: 'max(10, 100 + %star% * 50 - %bonus%)'

生产服不建议允许负数价格，以免被玩家利用刷钱。

常见问题

ExcellentEconomy 报错

ExcellentEconomy 必须提供非空 currency。如果 currency 为空，CoreLib 会报错。确认配置中明确指定了货币 ID：

economy:
  provider: excellenteconomy
  currency: coins  # 必须指定

动作中经济操作失败但没有提示

管道里没有"忽略失败"的开关，失败语义由段自身决定，因此要按失败原因排查：

情况	段的结果
当前目标不是玩家	跳过，不是失败。
经济服务不可用	失败（MISSING_CONTEXT）。
provider 找不到、currency 不存在、参数非法	失败（INVALID_CONFIG）。
余额不足	失败（REJECTED）。

"跳过"不会阻断整条管道，所以目标不是玩家时最容易看起来"什么都没发生"。确认目标流里确实是玩家，再核对 provider 与 currency。