市场 API

Market Demand API - External Event Integration

概述

MarketManager 提供完整的 API，供外部系统（如事件、任务、世界事件）直接操作市场需求，实现对游戏内事件的动态市场反应。

可用函数

1. 增加买入需求

func add_buy_demand(commodity_id: int, quantity: float) -> void

# 示例：干旱事件增加水需求
GlobalData.market_manager.add_buy_demand(5, 500.0)

2. 增加卖出需求

func add_sell_demand(commodity_id: int, quantity: float) -> void

# 示例：丰收增加供应，造成卖压
GlobalData.market_manager.add_sell_demand(3, 1000.0)

3. 设置净需求

func set_net_demand(commodity_id: int, net_demand: float) -> void
# 正值 = 买压，负值 = 卖压，零 = 中性

# 示例：战争突然造成武器需求大增
GlobalData.market_manager.set_net_demand(12, 5000.0)

4. 清除市场需求

func clear_market_demand(commodity_id: int) -> void

# 重置特定商品的所有需求数据

5. 获取市场需求

func get_market_demand(commodity_id: int) -> Dictionary
# 返回:
# {
#     "buy_volume": float,
#     "sell_volume": float,
#     "net_demand": float,
#     "last_update": float
# }

事件系统集成示例

干旱事件

func trigger_drought():
    GlobalData.market_manager.add_buy_demand(5, 800.0)    # 水
    GlobalData.market_manager.add_sell_demand(3, 500.0)   # 小麦

func end_drought():
    GlobalData.market_manager.remove_buy_demand(5, 400.0)
    GlobalData.market_manager.remove_sell_demand(3, 250.0)

节日事件

func start_festival():
    GlobalData.market_manager.add_buy_demand(10, 600.0)   # 丝绸
    GlobalData.market_manager.add_buy_demand(11, 400.0)   # 酒

func end_festival():
    GlobalData.market_manager.clear_market_demand(10)
    GlobalData.market_manager.clear_market_demand(11)

需求如何影响价格

  1. 净需求：buy_volume - sell_volume
    • 正值 = 买压 → 价格上涨
    • 负值 = 卖压 → 价格下跌
  2. 价格影响公式： 
    price_change = net_demand × price_sensitivity × current_price
    默认 price_sensitivity = 0.0015 (0.15%)
  3. 价格变动限制：
    • 每 tick 最大变化：±5%
    • 价格不能偏离基础值 ±50% 以上
  4. 需求衰减：每 tick 需求值衰减 5%，防止无限累积

市场参数

GlobalData.market_manager.set_market_parameters({
    "demand_decay_rate": 0.95,          # 需求衰减率 (0-1)
    "price_sensitivity": 0.0015,        # 需求对价格的影响
    "max_price_change_per_tick": 0.05,  # 每次更新最大价格变化 (5%)
    "demand_smoothing": 0.3             # 平滑系数 (0-1)
})

调试命令

# 打印所有商品的详细需求信息
GlobalData.market_manager.debug_print_market_demand()

# 获取特定商品需求
var demand = GlobalData.market_manager.get_market_demand(5)
print("水需求: ", demand)

最佳实践

  1. 渐进变化：使用 add_* 函数实现逼真的渐进变化
  2. 剧烈事件：使用 set_net_demand() 实现突然的市场剧变
  3. 事件清理：事件结束时始终清理或逆转需求
  4. 测试：使用 debug_print_market_demand() 监控事件影响