股市 wAPI
适用于Minecraft 1.21.1(NeoForge)的虚拟股票市场模组,具有AI驱动的新闻和基于玩家需求的实时价格变化。使用自定义货币(KABU),并依赖aidbwapi_core进行AI和数据存储。
- 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 错误发生时的确认步骤
/dbwapi ai errors— 确认最近的错误历史(HTTP 状态码/原因)。/dbwapi model list— 列出所有模型的状态(启用/禁用、惩罚值)。/dbwapi model enable <KeyName>.<ModelName>— 恢复因认证错误等被自动禁用的模型。/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中。
物品兑换的安全机制
- 预先扫描物品栏: 为防止因原版机制导致的部分消耗错误,在兑换处理前扫描玩家的整个物品栏,预先检查持有总量是否达到所需数量。
- 超过上限阻止: 如果兑换会导致持有金额超过上限(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 通信・数据库基础) - 端: 服务器与客户端均必需
安装:
- 确认
aidbwapi_core已完成设置(已注册 AI 提供商并配置模型)。 - 将本 Mod (
stock_wapi-x.x.x.jar) 放入服务器或客户端的mods文件夹并启动。 - 首次启动时,会自动生成 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。
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。