股市 wAPI

适用于Minecraft 1.21.1(NeoForge)的虚拟股票市场模组,具有AI驱动的新闻和基于玩家需求的实时价格变化。使用自定义货币(KABU),并依赖aidbwapi_core进行AI和数据存储。

经济

  1. English / 2. 日本語

StockMarket wAPI Mod (stock_wapi)

一个面向 Minecraft 1.21.1 (NeoForge) 的真正的虚拟股票市场 Mod,股价会根据 AI 生成的经济新闻以及玩家的供需关系实时波动。 它具备独特的货币“KABU”与任意物品之间的双向兑换机制,任何人都可以通过告示牌 UI 或命令轻松享受股票交易。 所有 AI 处理和数据持久化都委托给 AI DataBase wAPI Core,本 Mod 因此可以专注于“股票市场逻辑与游戏体验”。

项目 值
Mod ID stock_wapi
显示名称 StockMarket wapi mod
版本体系 1.21.1-x.y.z(MC 版本-SemVer,独立于 core)
安装要求 aidbwapi_core 必需
许可证 Apache License 2.0

🚀 核心功能与架构

1. AI 驱动的股价波动系统(市场引擎)

股价在定期更新时,通过合计以下四个要素来决定。AI 并不直接决定价格,而是作为影响要素之一发挥作用。

  • 内部随机波动: 基于每个股票代码设定的基础波动率(volatility)产生的自然价格变动。
  • 趋势倾向: 基于每个股票代码设定的“上涨倾向/下跌倾向/中性”初始倾向,在每次定期更新时以一定概率(8%)动态改变趋势,形成繁荣与衰退的浪潮。
  • 玩家供需影响: 汇总更新间隔期间玩家的买入、卖出数量,并基于对数函数 $log_{10}(1 + |netDemand|)$ 反映到价格中。在抑制剧烈波动的同时,使市场参与者的行为影响价格。供需的反映时机是“定期更新时”,并非交易瞬间立即变动股价。
  • AI 市场心理影响: 通过 aidbwapi_core 将市场动向数据发送给 LLM,并将 AI 返回的“市场心理分数(-N 至 +N)”归一化后转换为价格影响。

价格安全机制

  • 股价以整数管理。每次更新的波动幅度被限制在最大 ±10%(可通过 config 修改)。
  • 每个股票代码都设定了最低价格(minPrice)和最高价格(maxPrice),价格始终被限制在此范围内。
  • 反弹机制: 在接近最低价格时减弱下跌压力、增强上涨修正,以防止价格接近零。不会发生破产或退市。

自适应需求缩放(Adaptive Demand Scaling)

将服务器过去 5 天(默认 120 次更新)的总交易量保存为移动平均,用于自动归一化供需影响。即使玩家数量或交易规模发生变化,也无需手动调整 config 即可维持适当平衡。

2. AI 新闻生成(市场新闻)

在定期更新时,将市场动向数据(各股票代码的波动概要、世界观设定等)发送给 aidbwapi_core,由 AI 生成经济新闻文本和市场心理分数。

  • 定期更新时,以 [StockWapi] 格式将新闻通过聊天广播给服务器内所有玩家。如果 AI 生成失败,则改为广播回退新闻(“由于通信故障,未能获取 AI 市场新闻。市场正仅由技术性因素驱动。”),市场价格更新本身仍正常进行。
  • 可通过 /stockwapi news 查看最新新闻+过去新闻历史(最多 30 条,带时间戳,按从新到旧排序)。
  • 新闻历史永久保留(存储在 GlobalDB 中)。

AI 失败时的行为

如果 AI 请求失败(例如所有模型不可用),则以 AI 影响为零(sentiment=0)的状态,仅使用其他要素计算股价。回退新闻会广播给所有玩家。

面向管理员:AI 错误发生时的确认步骤

  1. /dbwapi ai errors — 确认最近的错误历史(HTTP 状态码/原因)。
  2. /dbwapi model list — 列出所有模型的状态(启用/禁用、惩罚值)。
  3. /dbwapi model enable <KeyName>.<ModelName> — 恢复因认证错误等被自动禁用的模型。
  4. /dbwapi model reset <KeyName>.<ModelName> — 重置惩罚和冷却时间。

3. AI 公司说明自动生成(公司说明)

当管理员添加股票代码时,会将股票代码名称发送给 aidbwapi_core,由 AI 自动生成公司说明并保存到 DB。此处理仅在注册时执行。 如果 AI 生成失败,则自动将回退说明(“当前无法获取公司说明。”)保存到 DB。 玩家可通过 /stockwapi info <ticker> 命令或告示牌查看公司说明。 如需手动修正或替换公司说明,请直接编辑 DB 文件(stock_wapi_GlobalDatabase.json)中的 companyDesc_XXX 键。 将现有公司说明设为空字符串("")并重启服务器,将触发 AI 自动重新生成新的说明。

4. 独特货币“KABU”与物品兑换(货币与兑换)

本 Mod 不依赖外部经济 Mod,使用独特货币“KABU”。

  • 货币名称: KABU(仅整数,初始持有 0)。
  • 余额与交易上限: 每位玩家的持有金额上限,以及单次全部交易(包括股票买卖、物品兑换等所有交易)的上限为 20 亿 KABU (2,000,000,000)(为防止整数溢出和经济平衡崩溃)。
  • 玩家可以将任意物品(包括原版以及任何 Mod 的物品)与 KABU 进行双向兑换。兑换可通过告示牌 UI 或命令执行。
  • 可注册多个物品并分别设定不同汇率(例如:钻石=100 KABU、金锭=10 KABU)。兑换对象的注册通过管理员命令(/stockwapi admin setrate)进行,汇率信息保存在 config/stock_wapi-exchange.json 中。

物品兑换的安全机制

  1. 预先扫描物品栏: 为防止因原版机制导致的部分消耗错误,在兑换处理前扫描玩家的整个物品栏,预先检查持有总量是否达到所需数量。
  2. 超过上限阻止: 如果兑换会导致持有金额超过上限(20 亿 KABU),则不消耗物品并完全阻止处理。

5. 内幕交易对策与市场公正性(市场诚信)

为使新闻公开前的交易在结构上不可能发生,更新处理按以下严格顺序执行:

锁定交易 → 更新价格 → 保存新闻 → 广播 → 更新告示牌 → 解除锁定

如果在锁定期间尝试交易,会通知玩家交易已被阻止。

6. 手续费系统(佣金)

  • 可在买卖时收取手续费。买入和卖出可分别以百分比单独设定。默认为 0%。
  • 手续费收入的去向可以是“消失(默认)”或“服务器整体的管理账户(可通过 config 修改)”。管理账户不绑定到特定玩家 UUID。
  • 可通过 /stockwapi admin balance 查看管理账户的余额。

7. 告示牌 UI(告示牌界面)

通过将功能绑定到管理员放置的告示牌方块上,玩家只需右键即可进行买卖、兑换、查看新闻。

  • 仅管理员可放置(/stockwapi admin sign <type> [<arg1>] [<arg2>])。
  • 股价更新时自动更新。可直接从告示牌进行直接买卖(右键即时执行)。
  • 管理员以外的人无法破坏(如果 OP 破坏,则自动解除注册)。

告示牌类型(共 7 种)

类型 设置命令示例 告示牌显示 右键动作
price sign price RDM 股票代码+价格 在聊天中显示股票代码详情
list sign list 股票列表标题 在聊天中显示所有股票代码+价格
buy sign buy RDM 5 股票代码+数量+价格 即时购买指定数量
sell sign sell RDM 5 股票代码+数量+价格 即时卖出指定数量
exchange sign exchange diamond 10 物品名+数量+KABU 金额 物品→KABU 即时兑换
buyitem sign buyitem diamond 10 物品名+数量+KABU 金额 KABU→物品即时购买
news sign news 最新新闻标题 在聊天中显示 1 条最新新闻(命令版带 30 条历史)

解除注册:/stockwapi admin unsign(管理员看着告示牌执行)


💻 运行要求与安装

  • Minecraft: 1.21.1
  • Mod Loader: NeoForge 21.1.219 或更高
  • Java: Java 21 或更高
  • 必需依赖 Mod: aidbwapi_core(AI 通信・数据库基础)
  • 端: 服务器与客户端均必需

安装:

  1. 确认 aidbwapi_core 已完成设置(已注册 AI 提供商并配置模型)。
  2. 将本 Mod (stock_wapi-x.x.x.jar) 放入服务器或客户端的 mods 文件夹并启动。
  3. 首次启动时,会自动生成 3 个演示预设股票代码(RDM, END, OAK)。

📖 使用方法

服务器管理员:初始设置

Step 1: 准备 aidbwapi_core

本 Mod 的运行必须完成 aidbwapi_core 的设置。请按以下步骤完成。

1-1. 注册 AI 提供商

将 AI 服务(OpenAI 兼容 API)的连接信息注册为“注册名(KeyName)”。

/dbwapi keyname add <KeyName> <API_Endpoint_URL> <API_Key>

⚠️ 安全警告: 由于 Minecraft 的机制,你在聊天栏输入的完整命令(明文 API 密钥)会原样记录到服务器的 logs/latest.log 中。 为安全起见,强烈建议使用文本编辑器直接编辑 config/aidbwapi_core-keynames.json,然后在游戏内执行 /dbwapi reload。

1-2. 注册模型

向已注册的提供商添加要使用的 AI 模型。

/dbwapi model add <KeyName>.<ModelName> <DailyLimit> <MinuteLimit>

如果省略上限值或设为 -1,则注册为无限制。注册多个提供商/模型后,发生故障时会自动切换到下一个模型(故障转移)。

1-3. 运行确认
/dbwapi ai test

如果收到 AI 的响应,则准备完成。如果出现错误,请通过 /dbwapi ai errors 确认错误内容。

Step 2: 首次启动与自动设置

将本 Mod 放入 mods 文件夹并启动服务器后,会自动执行以下操作:

  • 在 config/stock_wapi-stocks.json 中生成 3 个演示预设股票代码(RDM, END, OAK)的定义。
  • 异步自动生成并保存各股票代码的 AI 公司说明。
  • 启动市场定期更新调度器(默认:每 1 小时)。

Step 3: 注册物品兑换汇率

设置物品兑换汇率,以便玩家获取 KABU。

/stockwapi admin setrate diamond 100
/stockwapi admin setrate gold_ingot 10

这样即可进行“1 颗钻石 = 100 KABU”“1 个金锭 = 10 KABU”的兑换。

Step 4: 放置告示牌(可选)

可设置告示牌 UI,使玩家只需右键即可操作。放置告示牌方块,并看着它执行以下命令:

/stockwapi admin sign price RDM             ← 显示 RDM 价格
/stockwapi admin sign buy RDM 5             ← 购买 5 股 RDM
/stockwapi admin sign sell RDM 5            ← 卖出 5 股 RDM
/stockwapi admin sign exchange diamond 10   ← 将 10 颗钻石兑换为 KABU
/stockwapi admin sign buyitem diamond 1     ← 用 KABU 购买 1 颗钻石
/stockwapi admin sign list                  ← 显示所有股票代码
/stockwapi admin sign news                  ← 显示最新新闻

Step 5: 添加/自定义股票代码(可选)

添加自定义股票代码:

/stockwapi admin add ABC "Alpha Beta Corp" 50000

股票代码定义将追加到 config/stock_wapi-stocks.json。如需微调波动率、趋势或市场类型,请在服务器停止时直接编辑此 JSON 文件。

玩家:基本玩法

1. 获取 KABU

首先通过物品兑换获取 KABU。

/stockwapi exchange diamond 10

(如果管理员设置了告示牌,右键即可即时兑换。)

2. 调查股票代码

/stockwapi list                ← 查看所有股票代码的当前价格
/stockwapi info RDM            ← 查看 RDM 的详细信息
/stockwapi news                ← 查看 AI 生成的最新经济新闻

3. 买卖股票

/stockwapi buy RDM 10          ← 购买 10 股 RDM
/stockwapi sell RDM 5           ← 卖出 5 股 RDM

交易完成后,会在聊天中详细显示(股票代码、数量、单价、总额、手续费、支付/收取金额、持有数量、平均成本)。

4. 查看资产

/stockwapi myinfo              ← 查看余额、持仓和盈亏

5. 将 KABU 换回物品

如果盈利,可以消耗 KABU 购买物品(如钻石)。

/stockwapi buyitem diamond 1        ← 支付 KABU 获得 1 颗钻石

运营技巧

  • 暂停市场: 维护时可通过 /stockwapi admin pause 停止所有交易和定期更新。通过 /stockwapi admin resume 恢复。
  • 删除股票代码: 可通过 /stockwapi admin remove ABC <Your_UUID> 删除股票代码。如果存在持有者,其股份将按当前价格强制清算。为防止误操作,必须输入你自己的 UUID。
  • 使用手续费: 如需抑制投机性大规模交易,请在 TOML 配置中设置 buyFeePercent / sellFeePercent。设置 feeToAdminAccount = true 可将手续费归集到管理账户。

⚙️ 配置与目录结构

  • config/stock_wapi-common.toml:整个 Mod 的基础设置文件。

    [general] 部分:

    • commandPermissionLevel:管理员命令所需的 OP 权限等级(默认:2)。
    • debugLogging:启用调试日志(默认:false)。通常无需更改。

    [market] 部分:

    • updatesPerDay:每天的市场更新次数(默认:24,每 1 小时实时)。
    • maxPriceChangePercent:每次更新的最大波动幅度(默认:10,±10%)。
    • tradingPausedOnUpdate:更新处理期间是否暂停交易(默认:true)。设置为 false 将禁用内幕交易锁定机制。

    [trading] 部分:

    • buyFeePercent / sellFeePercent:买入・卖出的手续费率(默认:0)。
    • feeToAdminAccount:是否将手续费归集到管理账户(默认:false,消失)。
    • allowShortSelling:卖空许可标志(配置项存在,但当前未实现,设为 true 也不会生效)。
    • minTradeUnit:最低交易单位(默认:1)。
    • maxTradeAmount:单次最大交易数量(默认:-1,无限制)。
    • maxHoldingPerPlayer:每位玩家每个股票代码的持有上限(默认:-1,无限制)。

    [ai] 部分:

    • sentimentScoreRange:AI 心理分数范围(默认:100,-100 至 +100)。
    • newsLanguage:AI 生成新闻的语言(默认:ja)。
    • worldSetting:传递给 AI 的世界观设定文本(默认:"A fictional stock market in the Minecraft world")。
  • config/stock_wapi-stocks.json:所有股票代码详细参数的定义文件(以数组形式存储在一个文件中)。 执行添加股票代码命令时,会以默认值自动追加。如需微调初始价格以外的参数(波动率、趋势、反弹强度、市场类型等),请在服务器停止时直接编辑此文件。

    {
      "ticker": "RDM",
      "name": "Redstone Dynamics Mining",
      "initialPrice": 15000,
      "volatility": 0.03,
      "stability": 0.9,
      "trend": "neutral",
      "marketType": "stable",
      "minPrice": 1000,
      "maxPrice": 100000,
      "reboundStrength": 0.1,
      "tradeImpactFactor": 0.4,
      "aiImpactFactor": 0.05,
      "description": ""
    }
    
  • config/stock_wapi-exchange.json:物品兑换汇率的保存文件。 保存通过管理员命令(/stockwapi admin setrate)注册的汇率信息。

  • [世界保存根目录]/aidbwapi_core/stock_wapi/:运营数据的保存位置(使用 aidbwapi_core 的分类 DB 机制)。

    • global.json:当前价格、价格历史(全部历史)、新闻历史、市场心理值、供需汇总数据、更新次数计数器、交易量移动平均历史等。
    • players/<UUID>.json:每位玩家的 KABU 余额、持有股数、平均成本、买卖历史。

🛠️ 命令参考

所有命令均以 /stockwapi 开头。 指定股票代码时使用股票代码符号,但即使以小写输入,内部也会自动转换为大写后处理。 <ticker> 和 <item> 参数支持 Tab 补全。

📌 玩家命令(无需权限)

命令 说明
/stockwapi list 列出所有股票代码及其当前价格
/stockwapi info <ticker> 查看股票代码详细信息(价格、市场类型、供需、公司说明)
/stockwapi myinfo 查看自己的 KABU 余额、持仓和盈亏
/stockwapi portfolio 与 myinfo 同义(别名)
/stockwapi buy <ticker> <quantity> 购买指定数量的指定股票代码(按当前价格即时成交)
/stockwapi sell <ticker> <quantity> 卖出指定数量的指定股票代码(按当前价格即时成交)
/stockwapi news 查看最新市场新闻+过去新闻历史(最多 30 条)
/stockwapi exchange <item> <count> 将指定物品兑换为 KABU
/stockwapi buyitem <item> <count> 使用 KABU 购买指定物品

📌 管理员命令(需要 OP 权限,默认 permission level 2)

命令 说明
/stockwapi admin add <ticker> <name> <initialPrice> 注册并初始化新股票代码。自动生成 AI 公司说明。详细参数可在生成的 JSON 文件中调整
/stockwapi admin remove <ticker> <executorUUID> 删除股票代码。为防止误删,必须提供执行者 UUID。对持有者执行强制清算(按当前价格自动卖出并返还 KABU)
/stockwapi admin pause 暂停市场交易和定期更新
/stockwapi admin resume 恢复市场交易和定期更新
/stockwapi admin balance 查看管理账户(买卖手续费的归集处)的余额
/stockwapi admin setrate <item> <kabuRate> 添加或更新物品兑换汇率(例如:diamond 100)
/stockwapi admin removerate <item> 删除物品兑换汇率
/stockwapi admin listrates 列出所有物品兑换汇率
/stockwapi admin sign <type> [<arg1>] [<arg2>] 将功能绑定到告示牌方块(看着告示牌执行)。参数因 type 而异
/stockwapi admin unsign 解除告示牌方块的功能注册(看着告示牌执行)

🏗️ 内部架构补充

市场更新调度器

计时器本身运行在 ScheduledExecutorService 的守护线程上,但为确保数据库访问和状态变更的安全性,实际的更新处理始终同步到主服务器线程(MinecraftServer.execute())执行。 更新计时器基于实时时间,服务器重启时从上次的进度继续。

交易结果处理(TradeResult Enum)

为防止命令处理过于复杂,内部交易处理结果以具有 10 种以上状态(成功、余额不足、持有数量不足、股票代码未注册、市场更新中锁定等)的 Enum(TradeResult)返回,面向玩家的警告消息也由该 Enum 统一管理。

DB 结构(使用 aidbwapi_core 分类 DB)

  • 分类名: stock_wapi
  • GlobalDatabase: 当前价格、价格历史(全部历史)、市场心理值、新闻历史、供需汇总数据、更新次数计数器、交易量移动平均历史(volumeHistory)。
  • PlayerDatabase: KABU 余额(balance)、持有股数(holdings)、平均成本(avgPrices)、买卖历史(tradeHistory)。

异步处理的线程安全性

对于 AI 公司说明的异步生成回调等来自异步线程的 DB 访问,通过 MinecraftServer.execute() 委托给主线程,以保证线程安全。


⚖️ 许可证(License)

本 Mod 的源代码及提供的二进制文件在 Apache License, Version 2.0 下提供和发布。 在许可证条款范围内,可自由创建和再分发使用或修改本 Mod 的商业或非商业 Mod。