- 英文 / 2. 日本語
StockMarket wAPI Mod (stock_wapi)
一款适用于 Minecraft 1.21.1 (NeoForge) 的真实虚拟股票市场模组,股票价格会根据 AI 生成的经济新闻以及玩家的供需关系实时波动。
该模组具备独特货币“KABU”与任何物品之间的双向兑换机制,允许任何人通过告示牌 UI 或指令轻松享受股票交易。
所有 AI 处理和数据持久化都委托给 AI DataBase wAPI Core,使本模组能够完全专注于“股票市场逻辑和游戏经验”。
| 项目 |
值 |
| 模组 ID |
stock_wapi |
| 显示名称 |
StockMarket wapi mod |
| 版本控制 |
1.21.1-x.y.z(MC 版本号-SemVer,独立于核心) |
| 依赖项 |
aidbwapi_core 必需 |
| 许可证 |
Apache License 2.0 |
? 特性与架构
1. AI 驱动的价格波动系统(市场引擎)
股票价格在定期更新期间通过汇总以下 四个因素 来确定。AI 并不直接决定价格;它作为影响因子之一发挥作用。
- 内部随机波动: 基于每个股票代码设定的基础波动率进行的自然价格变动。
- 趋势倾向: 基于为每个股票代码设定的初始倾向(“看涨 / 看跌 / 中性”),趋势在每个定期更新期间以一定概率(8%)动态变化,形成繁荣与衰退的波浪。
- 玩家供需影响: 聚合更新间隔内的玩家买卖量,并根据对数函数 $log_{10}(1 + |netDemand|)$ 将其反映在价格中。这在抑制剧烈波动的同时反映了市场参与者的行为。需求反映的时机是在“定期更新”,交易发生瞬间价格不会立即移动。
- AI 市场情绪影响: 市场趋势数据通过
aidbwapi_core 发送给 LLM,AI 返回的“市场情绪得分(-N 到 +N)”会被标准化并转换为价格影响。
价格安全机制
- 股票价格以 整数 管理。每次更新的波动范围被限制在 最大 ±10%(可通过配置文件调整)。
- 每个股票代码都有最低价格 (
minPrice) 和最高价格 (maxPrice),价格始终限制在此范围内。
- 反弹机制: 接近最低价格时,下行压力减弱,上行修正增强,以防止价格趋近于零。不会发生破产或退市。
自适应需求缩放 (Adaptive Demand Scaling)
服务器过去 5 天的总交易量(默认:120 次更新)被保存为移动平均值,用于自动标准化供需影响。即使玩家数量或交易规模发生变化,也能保持适当的平衡,无需手动调整配置。
2. AI 新闻生成(市场新闻)
在定期更新期间,市场趋势数据(每个股票代码的波动摘要、世界设置等)被发送到 aidbwapi_core,AI 生成经济新闻文本和市场情绪得分。
- 在定期更新期间,新闻会通过聊天以
[StockWapi] 格式广播给服务器上的所有玩家。如果 AI 生成失败,则广播备用新闻(“由于通信错误无法获取 AI 市场新闻。市场仅基于技术因素运行。”),市场价格更新本身正常进行。
- 最新新闻和历史新闻记录(最多 30 条,带时间戳,最新的在前)可以通过
/stockwapi news 查看。
- 新闻历史记录 无限期保留(存储在 GlobalDB 中)。
AI 失败时的行为
如果 AI 请求失败(例如,所有模型不可用),股票价格将仅使用其他因素计算,AI 影响为零(情绪=0)。备用新闻会广播给所有玩家。
管理员指南:排查 AI 错误
/dbwapi ai errors — 检查最近的错误历史(HTTP 状态码/原因)。
/dbwapi model list — 查看所有模型的状态(启用/禁用,惩罚点数)。
/dbwapi model enable <KeyName>.<ModelName> — 恢复因身份验证错误等原因自动禁用的模型。
/dbwapi model reset <KeyName>.<ModelName> — 重置惩罚和冷却时间。
3. AI 公司简介自动生成(Company Description)
当管理员添加股票代码时,股票代码名称被发送到 aidbwapi_core,AI 自动生成公司简介并保存到数据库。此过程仅在注册时执行。
如果 AI 生成失败,备用简介(“公司简介目前不可用。”)会自动保存到数据库中。
玩家可以通过 /stockwapi info <ticker> 指令或告示牌查看公司简介。
要手动更正或替换公司简介,请直接在数据库文件 (stock_wapi_GlobalDatabase.json) 中编辑 companyDesc_XXX 键。
将现有公司简介设置为空字符串 ("") 并重启服务器将触发 AI 自动重新生成新的简介。
4. 独特货币“KABU”与物品兑换(Currency & Exchange)
本模组不依赖外部经济模组,而是使用自己的货币“KABU”。
- 货币名称: KABU(仅支持整数,初始余额为 0)。
- 余额与交易限额: 每位玩家的最高余额及单笔交易限额(包括股票交易和物品兑换)为 20 亿 KABU(2,000,000,000)(以防止整数溢出和经济崩溃)。
- 玩家可以**双向交换任何物品(包括原版物品和来自任何模组的物品)**与 KABU。可通过告示牌 UI 或命令执行交换。
- 可以注册不同汇率的多种物品(例如:钻石 = 100 KABU,金锭 = 10 KABU)。通过管理员命令 (
/stockwapi admin setrate) 注册交换目标,汇率信息保存在 config/stock_wapi-exchange.json 中。
物品交换安全机制
- 预库存扫描: 为防止因原版规格导致的部分消耗错误,在交换过程开始之前,会扫描玩家的全部库存以检查持有总量是否满足所需数量。
- 超限阻断: 如果交换会导致余额超过限额(20 亿 KABU),则完全阻止该过程且不消耗物品。
5. 内幕交易防范与市场完整性 (Market Integrity)
为了使在新闻披露前的交易在结构上成为不可能,更新过程按以下严格顺序执行:
锁定交易 → 更新价格 → 保存新闻 → 广播 → 更新告示牌 → 解锁交易
如果在锁定期间尝试交易,系统会通知玩家当前交易已被阻止。
6. 佣金系统 (Commission)
- 可以在买卖过程中收取佣金。买入和卖出的百分比可单独设置。默认值为 0%。
- 佣金收入可以选择“消失(默认)”或进入“全服管理账户(可配置)”。管理账户不与任何特定的玩家 UUID 关联。
- 使用
/stockwapi admin balance 查看管理账户的余额。
7. 告示牌界面 (Sign Interface)
通过将功能链接到由管理员放置的告示牌方块,玩家只需右键点击即可进行买卖、兑换和查看新闻。
- 只有管理员可以放置告示牌 (
/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 |
新闻标题 |
在聊天栏显示最新新闻 |
解除链接:/stockwapi admin unsign(注视告示牌时执行)
? 要求与安装
- Minecraft: 1.21.1
- 加载器: NeoForge 21.1.219 或更高版本
- Java: Java 21 或更高版本
- 必需依赖项:
aidbwapi_core(AI 通信与数据库基础)
- 端: 服务器和客户端均需安装
安装步骤:
- 确保已设置好
aidbwapi_core(已注册 AI 提供商并配置模型)。
- 将此模组 (
stock_wapi-x.x.x.jar) 放入服务器或客户端的 mods 文件夹并启动游戏。
- 首次启动时,将自动生成三个演示预设代码(RDM、END、OAK)。
? 使用方法
服务器管理员:初始设置
第 1 步:准备 aidbwapi_core
必须设置 aidbwapi_core 才能使此模组正常运行。请按照以下步骤操作:
1-1. 注册 AI 提供商
将你的 AI 服务(OpenAI 兼容 API)的连接信息作为“KeyName”注册。
/dbwapi keyname add <KeyName> <API_Endpoint_URL> <API_Key>
⚠️ 安全警告: 由于 Minecraft 的规格限制,你在聊天栏中输入的完整命令(纯文本格式的 API Key)将被记录在服务器的 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 检查详细信息。
第 2 步:首次启动与自动设置
将此模组放入 mods 文件夹并启动服务器后,将发生以下情况:
- 三个演示预设代码(RDM、END、OAK)将在
config/stock_wapi-stocks.json 中定义。
- 每个代码对应的 AI 公司描述将以异步方式生成并保存。
- 定期市场更新调度程序将启动(默认:每 1 小时)。
第 3 步:注册物品兑换汇率
设置兑换汇率以便玩家获取 KABU。
/stockwapi admin setrate diamond 100
/stockwapi admin setrate gold_ingot 10
这将启用类似“1 钻石 = 100 KABU”和“1 金锭 = 10 KABU”的兑换。
步骤 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 ← 显示最新新闻
步骤 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 : 整个模组的基本设置。
[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 : 所有股票代码参数的定义文件(存储为数组)。
使用 add 命令时,定义将自动追加默认值。若要微调除初始价格以外的参数(波动性、趋势、反弹强度、市场类型等),请在服务器停止运行时编辑此文件。
{
"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) 的汇率信息。
-
[World Save Root]/aidbwapi_core/stock_wapi/ : 运营数据的存储位置(使用 aidbwapi_core 类别数据库)。
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が必要、デフォルト権限レベル 2)
| 命令 |
説明 |
/stockwapi admin add <ticker> <name> <initialPrice> |
新しい銘柄を登録し初期化。AI による会社説明が自動生成されます。生成された JSON でパラメータを微調整可能 |
/stockwapi admin remove <ticker> <executorUUID> |
銘柄を削除。誤った削除を防ぐために実行者の UUID が必要です。保有者に対して強制的に清算が行われます |
/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() を介してメインスレッドに委任されます。
⚖️ ライセンス
本 Mod のソースコードおよび提供されるバイナリは、Apache License, Version 2.0 の下で提供・公開されます。
ライセンス条項の範囲内であれば、本 Mod を使用または改変する商用・非商用の Mod の作成と再配布は自由に許可されます。
StockMarket wAPI Mod (stock_wapi)
Minecraft 1.21.1 (NeoForge) 向けに、AI が生成する経済ニュースとプレイヤーの需給によって株価がリアルタイムに変動する本格派の仮想株式市場 Mod です。
独自通貨「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 |
? コア機能とアーキテクチャ (Features & Architecture)
1. AI駆動の株価変動システム (Market Engine)
株価は以下の4つの要素を合算して定期更新時に決定されます。AI は価格を直接決定せず、あくまで影響要素の一つとして機能します。
- 内部ランダム変動: 銘柄ごとに設定された基本ボラティリティに基づく自然な価格変動。
- トレンド傾向: 銘柄ごとに設定された「上昇寄り/下降寄り/中立」の初期傾向をもとに、毎回の定期更新時に一定確率(8%)でトレンドが動的に変化し、好景気・不景気の波を形成します。
- プレイヤー需給影響: 更新間隔中のプレイヤーの買い・売り数量を集計し、対数関数 (
log10(1 + |netDemand|)) をベースに価格へ反映。急激な変動を抑制しつつ、市場参加者の行動が価格に影響を与えます。需給の反映タイミングは「定期更新時」であり、売買した瞬間に即座に株価が動くわけではありません。
- AI市場心理影響:
aidbwapi_core 経由で LLM に市場動向データを送信し、AI が返す「市場心理スコア(-N〜+N)」を正規化して価格影響に変換します。
価格の安全装置
- 株価は整数で管理。1回の更新あたりの変動幅は最大±10%(config変更可能)にクランプされます。
- 各銘柄には最低価格(
minPrice)と最高価格(maxPrice)が設定され、価格は常にこの範囲内に制限されます。
- リバウンド機構: 最低価格付近では下落圧力を弱め、上昇補正を強めることで価格が0に近づくことを防ぎます。倒産・上場廃止は発生しません。
自動スケール適応 (Adaptive Demand Scaling)
サーバーの過去5日分(デフォルト120回分)の総取引量を移動平均として保存し、これを用いて需給影響を自動で正規化します。プレイヤー人数や取引規模が変化しても、手動での config 調整なしで適切なバランスが維持されます。
2. AIニュース生成 (Market News)
定期更新時に 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 <注册名>.<模型名> — 恢复因认证错误等自动禁用的模型
/dbwapi model reset <注册名>.<模型名> — 重置惩罚与冷却时间
3. AI 自动生成企业介绍 (Company Description)
当管理员添加股票代码时,系统会将股票代码发送至 aidbwapi_core,由 AI 自动生成企业介绍并保存至数据库。此处理仅在注册时执行。
若 AI 生成失败,则会自动在数据库中保存备用说明文本(「目前无法获取企业介绍。」)。
玩家可以通过 /stockwapi info <ticker> 命令或告示牌查看企业介绍。
若管理员需手动修改或替换企业介绍,请直接编辑数据库文件(stock_wapi_GlobalDatabase.json)中的 companyDesc_XXX 键值。
将现有企业介绍清空为空白字符串("")后重启服务器,AI 将自动重新生成新的介绍。
4. 独立货币「KABU」与物品兑换 (Currency & Exchange)
本模组不依赖外部经济模组,使用独立货币「KABU」。
- 货币名称: KABU(仅整数,初始持有量为 0)
- 余额与交易上限: 单玩家持有资金上限以及单次全部交易(包括股票买卖、物品兑换等所有操作)的上限均为 20亿 KABU (2,000,000,000)。(为防止整数溢出及经济平衡崩溃)
- 玩家可以双向交换任意物品(包括原版物品、任何模组的物品均可)与 KABU。可通过告示牌 UI 或命令执行兑换。
- 可分别以不同汇率注册多种物品(例如:钻石=100KABU、金锭=10KABU)。兑换对象的注册通过管理员命令 (
/stockwapi admin setrate) 进行,汇率信息保存在 config/stock_wapi-exchange.json 中。
物品兑换安全机制
- 预背包扫描: 为防止原版机制导致的部分消耗错误,在处理交换前会扫描玩家整个背包,预先检查持有总量是否达到所需数量。
- 超限阻断: 若交换导致持有金额超过上限(20亿 KABU),则不消耗物品并完全阻止处理。
5. 内幕交易防范与市场公正性 (Market Integrity)
为确保在新闻发布前无法进行交易,更新处理按以下严格顺序执行。
买卖锁定 → 价格更新 → 新闻保存 → 分发 → 告示牌更新 → 解锁
若在锁定期间尝试买卖,系统将向玩家提示被阻断的信息。
6. 手续费系统 (Commission)
- 可在买卖时收取手续费。买入和卖出可分别设置百分比费率,默认为 0%。
- 手续费收益的去向可为「消失(默认)」或「服务器全局管理账户(可更改配置)」。管理账户不与特定玩家的 UUID 绑定。
- 可使用
/stockwapi admin balance 查看管理账户的余额。
7. 告示牌 UI (Sign Interface)
通过将功能关联到管理员放置的告示牌方块,玩家只需右键点击即可进行买卖、换币及浏览新闻。
- 仅管理员可放置(
/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 |
最新新闻标题 |
在聊天栏显示最新一条新闻(命令版附带 30 条历史记录) |
注销方法: /stockwapi admin unsign(管理员面对告示牌执行)
? 运行要求与安装 (Requirements & Setup)
- Minecraft: 1.21.1
- Mod Loader: NeoForge 21.1.219 及以上版本
- Java: Java 21 及以上版本
- 必需依赖模组:
aidbwapi_core(AI 通信与数据库基础)
- 运行环境: 服务端与客户端均需安装
安装步骤:
- 请确认已完成
aidbwapi_core 的设置(已注册 AI 提供商并设定好模型)。
- 将本模组 (
stock_wapi-x.x.x.jar) 放入服务器或客户端的 mods 文件夹中启动游戏。
- 首次启动时,将自动生成用于演示的预设 3 只股票(RDM, END, OAK)。
? 使用方法 (Usage)
服务器管理员:初始设置
步骤 1:准备 aidbwapi_core
本模组运行必须完成 aidbwapi_core 的设置。请按以下步骤操作。
1-1. 注册 AI 提供商
将 AI 服务(兼容 OpenAI API)的连接信息作为“注册名(KeyName)”进行注册。
/dbwapi keyname add <注册名> <API端点URL> <API密钥>
⚠️ 安全警告: 由于 Minecraft 的机制,在聊天栏中输入的命令全文(包括 API 密钥明文)会被原样记录到服务器的 logs/latest.log 文件中。
为了安全起见,强烈建议直接使用文本编辑器编辑 config/aidbwapi_core-keynames.json 文件,然后在游戏内执行 /dbwapi reload 命令。
1-2. 注册模型
向已注册的提供商添加要使用的 AI 模型。
/dbwapi model add <注册名>.<模型名称> <每日上限> <每分钟上限>
如果省略上限值或设置为 -1,则视为无限制注册。
注册多个提供商和模型后,当出现故障时会自动切换到下一个模型(故障转移)。
1-3. 验证运行状态
/dbwapi ai test
如果收到来自 AI 的响应,则表示准备就绪。如果出现错误,请通过 /dbwapi ai errors 查看错误详情。
步骤 2:首次启动与自动设置
将本模组放入 mods 文件夹并启动服务器后,系统将自动执行以下操作:
- 在
config/stock_wapi-stocks.json 中生成 3 个演示用预设股票(RDM, END, OAK)的定义
- 异步自动生成并保存各股票的 AI 公司简介
- 启动市场定期更新调度器(默认:每小时一次)
步骤 3:注册物品兑换汇率
请设置物品兑换汇率,作为玩家获取 KABU 的方式。
/stockwapi admin setrate diamond 100
/stockwapi admin setrate gold_ingot 10
这样即可实现“1 个钻石 = 100 KABU”、“1 个金锭 = 10 KABU”的兑换。
第4步:设置告示牌(可选)
为了让玩家仅通过右键点击即可操作,可以设置告示牌界面。
放置告示牌方块,并站在其面前执行以下命令。
/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 ← 显示最新新闻的告示牌
第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 <你的 UUID> 可以删除股票。如果存在持有者,将以当前价格进行强制清算。为防止误操作,必须输入你自身的 UUID。
- 利用手续费: 如果想抑制投机性的频繁大量买卖,请在 TOML 配置文件中设置
buyFeePercent / sellFeePercent。将 feeToAdminAccount = true 设置为开启后,手续费将会累积到管理员账户中。
⚙️ 配置文件与目录结构 (Configuration)
config/stock_wapi-common.toml : 模组的基础动作配置文件。
[general] 部分:
* commandPermissionLevel: 管理员命令所需的 OP 权限等级(默认 2)。
* debugLogging: 启用调试日志(默认 false)。通常无需更改。
**`[market]` 部分:**
* `updatesPerDay`: 每日市场更新次数(默认 `24`,即现实时间每小时一次)。
* `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 的世界观设定文本(默认 `"Minecraft世界的架空企业的股票市场"`)。
-
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 的分类数据库结构)。
global.json: 当前价格、价格历史、新闻历史、市场心理值、供需汇总数据、更新次数计数器、交易量移动平均历史等。
players/<UUID>.json: 每位玩家的 KABU 余额、持股数、平均买入价格、买卖历史。
?️ 命令参考 (Command Reference)
所有命令均以 /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 |
解除告示牌方块的功能注册(需看着告示牌执行) |
?️ 内部架构补充 (Internal Architecture)
市场更新调度器
计时器本身由 ScheduledExecutorService 的守护线程运行,但为了确保数据库访问和状态变更的安全性,实际的更新处理始终同步执行在主服务器线程 (MinecraftServer.execute()) 上。
更新计时器基于实时时间,服务器重启时会从上次中断的地方继续。
买卖结果处理 (TradeResult Enum)
为了防止命令处理的复杂化,内部的买卖处理结果返回一个包含十多种状态(成功、余额不足、持股不足、股票未注册、因市场更新中而锁定等)的枚举 (TradeResult),玩家警告消息也由该枚举统一管理。
数据库结构 (使用 aidbwapi_core 分类数据库)
- 类别名称:
stock_wapi
- GlobalDatabase: 当前价格、价格历史(全部历史)、市场心理值、新闻历史、供需汇总数据、更新次数计数器、交易量移动平均历史 (
volumeHistory)。
- PlayerDatabase: KABU 余额 (
balance)、持股数 (holdings)、平均买入价格 (avgPrices)、买卖历史 (tradeHistory)。
异步处理的线程安全
对于来自异步线程的数据库访问(如 AI 公司描述的异步生成回调),通过 MinecraftServer.execute() 委托给主线程,从而保证线程安全。
⚖️ 许可证 (License)
本 Mod 的源代码及提供的二进制文件均根据 Apache License, Version 2.0 提供和发布。
在许可条款范围内,您可以自由创建和再分发基于本 Mod 进行利用或修改的商业或非商业 Mod。
- English / 2. 日本語
StockMarket wAPI Mod (stock_wapi)
An authentic virtual stock market mod for Minecraft 1.21.1 (NeoForge) where stock prices fluctuate in real-time based on AI-generated economic news and player supply and demand.
It features a bi-directional exchange mechanism between the unique currency "KABU" and any items, allowing anyone to easily enjoy trading stocks via sign UIs or commands.
All AI processing and data persistence are delegated to AI DataBase wAPI Core, allowing this mod to focus entirely on "stock market logic and game experience."
| Item |
Value |
| Mod ID |
stock_wapi |
| Display Name |
StockMarket wapi mod |
| Versioning |
1.21.1-x.y.z (MC Version-SemVer, independent of core) |
| Requirements |
aidbwapi_core required |
| License |
Apache License 2.0 |
? Features & Architecture
1. AI-Driven Price Fluctuation System (Market Engine)
Stock prices are determined during periodic updates by summing the following four factors. The AI does not decide the price directly; it functions as one of the influential factors.
- Internal Random Fluctuation: Natural price movement based on the base volatility set for each ticker.
- Trend Tendency: Based on the initial tendency ("Bullish / Bearish / Neutral") set for each ticker, the trend dynamically changes with a certain probability (8%) during each periodic update, forming waves of prosperity and recession.
- Player Supply & Demand Impact: Aggregates player buy and sell volumes during the update interval and reflects them in the price based on a logarithmic function: $log_{10}(1 + |netDemand|)$. This reflects the actions of market participants in the price while suppressing rapid fluctuations. The timing of demand reflection is at the "periodic update," and prices do not move instantly at the moment of trade.
- AI Market Sentiment Impact: Market trend data is sent to the LLM via
aidbwapi_core, and the "Market Sentiment Score (-N to +N)" returned by the AI is normalized and converted into price impact.
Price Safety Mechanisms
- Stock prices are managed as integers. The fluctuation range per update is clamped to a maximum of ±10% (configurable via config).
- Each ticker has a minimum price (
minPrice) and a maximum price (maxPrice), and the price is always restricted within this range.
- Rebound Mechanism: Near the minimum price, downward pressure is weakened and upward correction is strengthened to prevent the price from approaching zero. Bankruptcy or delisting does not occur.
Adaptive Demand Scaling (Adaptive Demand Scaling)
The total transaction volume of the server for the past 5 days (default: 120 updates) is saved as a moving average, which is used to automatically normalize the supply and demand impact. Even if the number of players or transaction scale changes, an appropriate balance is maintained without manual config adjustments.
2. AI News Generation (Market News)
During periodic updates, market trend data (fluctuation summaries for each ticker, world settings, etc.) is sent to aidbwapi_core, and the AI generates economic news text and market sentiment scores.
- During periodic updates, news is broadcast to all players on the server in the format
[StockWapi] via chat. If AI generation fails, fallback news ("Failed to retrieve AI market news due to a communication error. The market is moving solely based on technical factors.") is broadcast instead, and the market price update itself proceeds normally.
- Latest news and past news history (up to 30 entries, with timestamps, newest first) can be viewed via
/stockwapi news.
- News history is kept indefinitely (stored in GlobalDB).
Behavior on AI Failure
If an AI request fails (e.g., all models unavailable), the stock price is calculated using only other factors with zero AI impact (sentiment=0). Fallback news is broadcast to all players.
For Admins: Troubleshooting AI Errors
/dbwapi ai errors — Check recent error history (HTTP status codes/causes).
/dbwapi model list — View status of all models (Enabled/Disabled, Penalty points).
/dbwapi model enable <KeyName>.<ModelName> — Restore models automatically disabled due to authentication errors, etc.
/dbwapi model reset <KeyName>.<ModelName> — Reset penalties and cooldowns.
3. AI Company Description Auto-Generation (Company Description)
When an admin adds a ticker, the ticker name is sent to aidbwapi_core, and the AI automatically generates a company description and saves it to the DB. This process is executed only at the time of registration.
If AI generation fails, a fallback description ("Company description is currently unavailable.") is automatically saved to the DB.
Players can view company descriptions via the /stockwapi info <ticker> command or signs.
To manually correct or replace a company description, directly edit the companyDesc_XXX key in the DB file (stock_wapi_GlobalDatabase.json).
Setting an existing company description to an empty string ("") and restarting the server will trigger the AI to automatically regenerate a new description.
4. Unique Currency "KABU" and Item Exchange (Currency & Exchange)
This mod does not depend on external economy mods and uses its own currency, "KABU".
- Currency Name: KABU (Integer only, initial balance 0).
- Balance & Transaction Limits: The maximum balance per player and the limit for a single transaction (including stock trades and item exchanges) is 2 billion KABU (2,000,000,000) (to prevent integer overflow and economic collapse).
- Players can exchange any items (including vanilla and items from any mod) bi-directionally with KABU. Exchanges can be performed via Sign UI or commands.
- Multiple items can be registered with different rates (e.g., Diamond = 100 KABU, Gold Ingot = 10 KABU). Registration of exchange targets is done via admin command (
/stockwapi admin setrate), and rate information is saved in config/stock_wapi-exchange.json.
Item Exchange Safety Mechanisms
- Pre-Inventory Scan: To prevent partial consumption errors due to vanilla specifications, the player's entire inventory is scanned before the exchange process to check if the total amount possessed meets the required amount.
- Limit Overrun Block: If an exchange would cause the balance to exceed the limit (2 billion KABU), the process is completely blocked without consuming items.
5. Insider Trading Prevention & Market Integrity (Market Integrity)
To make trading before news disclosure structurally impossible, the update process is executed in the following strict order:
Lock Trading → Update Prices → Save News → Broadcast → Update Signs → Unlock Trading
If a trade is attempted during the lock, the player is notified that trading is currently blocked.
6. Commission System (Commission)
- Commissions can be collected during buying and selling. Percentages can be set individually for buys and sells. Default is 0%.
- Commission revenue can either "disappear (default)" or go to a "server-wide administrative account (configurable)". The admin account is not linked to any specific player UUID.
- View the balance of the admin account with
/stockwapi admin balance.
7. Sign Interface (Sign Interface)
By linking functions to sign blocks placed by an administrator, players can buy, sell, exchange, and view news with just a right-click.
- Signs can only be placed by administrators (
/stockwapi admin sign <type> [<arg1>] [<arg2>]).
- Signs are automatically updated when stock prices update. Trading can be done directly from signs (executed instantly on right-click).
- Signs cannot be destroyed by anyone other than an administrator (if an OP destroys one, it is automatically unlinked).
Sign Types (7 total)
| Type |
Example Command |
Sign Display |
Right-Click Action |
price |
sign price RDM |
Ticker + Price |
Display ticker details in chat |
list |
sign list |
Market Header |
Display all tickers + prices in chat |
buy |
sign buy RDM 5 |
Ticker + Qty + Price |
Instantly buy the specified quantity |
sell |
sign sell RDM 5 |
Ticker + Qty + Price |
Instantly sell the specified quantity |
exchange |
sign exchange diamond 10 |
Item + Qty + KABU |
Instant Item → KABU exchange |
buyitem |
sign buyitem diamond 10 |
Item + Qty + KABU |
Instant KABU → Item purchase |
news |
sign news |
News Header |
Display the latest news in chat |
Unlinking: /stockwapi admin unsign (execute while looking at the sign)
? Requirements & Setup
- Minecraft: 1.21.1
- Mod Loader: NeoForge 21.1.219 or later
- Java: Java 21 or higher
- Required Dependency:
aidbwapi_core (AI Communication & Database Foundation)
- Side: Required on both Server and Client
Installation:
- Ensure
aidbwapi_core is set up (AI provider registered and model configured).
- Place this mod (
stock_wapi-x.x.x.jar) into the mods folder of your server or client and launch.
- Upon first launch, three demo preset tickers (RDM, END, OAK) will be automatically generated.
? Usage
Server Administrator: Initial Setup
Step 1: Preparing aidbwapi_core
Setup of aidbwapi_core is mandatory for this mod to function. Follow these steps:
1-1. Register AI Provider
Register connection information for your AI service (OpenAI-compatible API) as a "KeyName."
/dbwapi keyname add <KeyName> <API_Endpoint_URL> <API_Key>
⚠️ Security Warning: Due to Minecraft's specifications, the full command you type in chat (the plain text API key) will be recorded in the server's logs/latest.log.
For security, it is strongly recommended to edit config/aidbwapi_core-keynames.json directly with a text editor and then run /dbwapi reload in-game.
1-2. Register Model
Add the AI model you wish to use to the registered provider.
/dbwapi model add <KeyName>.<ModelName> <DailyLimit> <MinuteLimit>
If limits are omitted or set to -1, they are registered as unlimited. Registering multiple providers/models allows the system to automatically switch if one fails (failover).
1-3. Verify Operation
/dbwapi ai test
If you receive a response from the AI, the setup is complete. If an error occurs, check the details with /dbwapi ai errors.
Step 2: First Launch & Auto Setup
After placing this mod in the mods folder and starting the server, the following will happen:
- Three demo preset tickers (RDM, END, OAK) will be defined in
config/stock_wapi-stocks.json.
- AI company descriptions for each ticker will be asynchronously generated and saved.
- The periodic market update scheduler will start (Default: every 1 hour).
Step 3: Register Item Exchange Rates
Set up exchange rates so players can obtain KABU.
/stockwapi admin setrate diamond 100
/stockwapi admin setrate gold_ingot 10
This enables exchanges like "1 Diamond = 100 KABU" and "1 Gold Ingot = 10 KABU."
Step 4: Placing Signs (Optional)
Set up Sign UIs so players can interact with a right-click. Place a sign and execute the following commands while looking at it:
/stockwapi admin sign price RDM ← Displays RDM price
/stockwapi admin sign buy RDM 5 ← Buys 5 shares of RDM
/stockwapi admin sign sell RDM 5 ← Sells 5 shares of RDM
/stockwapi admin sign exchange diamond 10 ← Exchange 10 Diamonds for KABU
/stockwapi admin sign buyitem diamond 1 ← Purchase 1 Diamond with KABU
/stockwapi admin sign list ← Displays all tickers
/stockwapi admin sign news ← Displays latest news
Step 5: Adding/Customizing Tickers (Optional)
To add a custom ticker:
/stockwapi admin add ABC "Alpha Beta Corp" 50000
The ticker definition will be appended to config/stock_wapi-stocks.json. To fine-tune volatility, trend, or market type, edit this JSON file directly while the server is stopped.
Player: Basic Gameplay
1. Obtaining KABU
First, obtain KABU via item exchange.
/stockwapi exchange diamond 10
(If the admin has set up signs, you can exchange instantly by right-clicking.)
2. Researching Tickers
/stockwapi list ← View current prices for all tickers
/stockwapi info RDM ← View detailed info for RDM
/stockwapi news ← View the latest AI-generated economic news
3. Trading Stocks
/stockwapi buy RDM 10 ← Buy 10 shares of RDM
/stockwapi sell RDM 5 ← Sell 5 shares of RDM
Upon trade completion, detailed information (ticker, quantity, unit price, total, commission, payment/receipt, shares owned, average cost) is displayed in chat.
4. Checking Assets
/stockwapi myinfo ← View balance, holdings, and P&L
5. Converting KABU Back to Items
If you make a profit, you can spend KABU to purchase items (like Diamonds).
/stockwapi buyitem diamond 1 ← Pay KABU to obtain 1 Diamond
Operation Tips
- Market Pause: Use
/stockwapi admin pause during maintenance to stop all trading and periodic updates. Resume with /stockwapi admin resume.
- Removing Tickers: Use
/stockwapi admin remove ABC <Your_UUID> to remove a ticker. If there are holders, their shares will be forcibly liquidated at the current price. Your UUID is required to prevent accidental deletion.
- Using Commissions: To suppress speculative large-scale trading, set
buyFeePercent / sellFeePercent in the TOML config. Set feeToAdminAccount = true to pool commissions in the admin account.
⚙️ Configuration & Directory Structure
-
config/stock_wapi-common.toml : Basic settings for the entire mod.
[general] Section:
commandPermissionLevel: Required OP level for admin commands (Default: 2).
debugLogging: Enable debug logs (Default: false). Usually not needed.
[market] Section:
updatesPerDay: Number of market updates per day (Default: 24, every 1 hour real-time).
maxPriceChangePercent: Max fluctuation per update (Default: 10, ±10%).
tradingPausedOnUpdate: Pause trading during update processing (Default: true). If false, the insider trading lock mechanism is disabled.
[trading] Section:
buyFeePercent / sellFeePercent: Commission rates for buying and selling (Default: 0).
feeToAdminAccount: Whether to pool commissions in the admin account (Default: false, disappear).
allowShortSelling: Flag for short selling (Config exists, but currently unimplemented; setting to true has no effect).
minTradeUnit: Minimum trading unit (Default: 1).
maxTradeAmount: Maximum trading amount per trade (Default: -1, unlimited).
maxHoldingPerPlayer: Maximum holdings per ticker per player (Default: -1, unlimited).
[ai] Section:
sentimentScoreRange: Range of AI sentiment score (Default: 100, -100 to +100).
newsLanguage: Language for AI-generated news (Default: ja).
worldSetting: Text describing the world setting passed to the AI (Default: "A fictional stock market in the Minecraft world").
-
config/stock_wapi-stocks.json : Definition file for all ticker parameters (stored as an array).
Definitions are auto-appended with default values when using the add command. To fine-tune parameters other than initial price (volatility, trend, rebound strength, market type, etc.), edit this file while the server is stopped.
{
"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 : Saved file for item exchange rates.
Stores rate info registered via admin command (/stockwapi admin setrate).
-
[World Save Root]/aidbwapi_core/stock_wapi/ : Storage for operational data (uses aidbwapi_core category DB).
global.json: Current prices, price history (full), news history, sentiment values, demand aggregate data, update counters, volume moving average history, etc.
players/<UUID>.json: Per-player KABU balance, shares owned, average purchase cost, and trade history.
?️ Command Reference
All commands start with /stockwapi.
Ticker symbols are used to specify stocks, but inputting them in lowercase will automatically convert them to uppercase internally.
<ticker> and <item> arguments support Tab completion.
? Player Commands (No permission required)
| Command |
Description |
/stockwapi list |
List tickers and current prices for all stocks |
/stockwapi info <ticker> |
View detailed ticker info (Price, Market Type, Demand, Description) |
/stockwapi myinfo |
View your KABU balance, holdings, and P&L |
/stockwapi portfolio |
Synonym for myinfo (Alias) |
/stockwapi buy <ticker> <quantity> |
Purchase specified quantity of a ticker (instantly filled at current price) |
/stockwapi sell <ticker> <quantity> |
Sell specified quantity of a ticker (instantly filled at current price) |
/stockwapi news |
View latest market news + past news history (up to 30 entries) |
/stockwapi exchange <item> <count> |
Exchange specified item for KABU |
/stockwapi buyitem <item> <count> |
Purchase specified item using KABU |
? Administrator Commands (OP required, default permission level 2)
| Command |
Description |
/stockwapi admin add <ticker> <name> <initialPrice> |
Register and initialize a new ticker. Auto-generates AI company description. Fine-tune parameters in the generated JSON |
/stockwapi admin remove <ticker> <executorUUID> |
Remove a ticker. Requires executor's UUID to prevent accidental deletion. Forcibly liquidates shares for holders |
/stockwapi admin pause |
Pause all market trades and periodic updates |
/stockwapi admin resume |
Resume all market trades and periodic updates |
/stockwapi admin balance |
View the balance of the admin account (pool for commissions) |
/stockwapi admin setrate <item> <kabuRate> |
Add or update an item exchange rate (e.g., diamond 100) |
/stockwapi admin removerate <item> |
Remove an item exchange rate |
/stockwapi admin listrates |
List all item exchange rates |
/stockwapi admin sign <type> [<arg1>] [<arg2>] |
Link a function to a sign block (execute while looking at sign). Arguments vary by type |
/stockwapi admin unsign |
Unlink a function from a sign block (execute while looking at sign) |
?️ Internal Architecture Supplemental
Market Update Scheduler
The timer itself runs on a daemon thread of ScheduledExecutorService, but to ensure database access and state change safety, the actual update processing is always synchronized with the main server thread (MinecraftServer.execute()).
The update timer is based on real-time and resumes from where it left off upon server restart.
Trade Result Handling (TradeResult Enum)
To prevent command logic from becoming overly complex, internal trade processing results are returned as an Enum (TradeResult) with over 10 states (Success, Insufficient Balance, Insufficient Shares, Ticker Not Registered, Market Locked for Update, etc.). Warning messages for players are also managed centrally by this Enum.
DB Structure (Using aidbwapi_core Category DB)
- Category Name:
stock_wapi
- GlobalDatabase: Current prices, price history (full), sentiment values, news history, demand aggregate data, update counter, volume moving average history (
volumeHistory).
- PlayerDatabase: KABU balance (
balance), shares owned (holdings), average purchase prices (avgPrices), trade history (tradeHistory).
Thread Safety for Asynchronous Processing
DB access from asynchronous threads, such as the callback for AI company description generation, is delegated to the main thread via MinecraftServer.execute() to guarantee thread safety.
⚖️ License (License)
The source code and provided binaries of this mod are provided and published under the Apache License, Version 2.0.
Creation and redistribution of commercial or non-commercial mods that use or modify this mod are permitted freely within the scope of the license terms.
StockMarket wAPI Mod (stock_wapi)
Minecraft 1.21.1 (NeoForge) 向けの、AIが生成する経済ニュースとプレイヤーの需給によって株価がリアルタイムに変動する本格派の仮想株式市場Modです。
独自通貨「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 |
? コア機能とアーキテクチャ (Features & Architecture)
1. AI駆動の株価変動システム (Market Engine)
株価は以下の4つの要素を合算して定期更新時に決定されます。AIは価格を直接決定せず、あくまで影響要素の一つとして機能します。
- 内部ランダム変動: 銘柄ごとに設定された基本ボラティリティに基づく自然な価格変動。
- トレンド傾向: 銘柄ごとに設定された「上昇寄り/下降寄り/中立」の初期傾向をもとに、毎回の定期更新時に一定確率(8%)でトレンドが動的に変化し、好景気・不景気の波を形成します。
- プレイヤー需給影響: 更新間隔中のプレイヤーの買い・売り数量を集計し、対数関数 (
log10(1 + |netDemand|)) をベースに価格へ反映。急激な変動を抑制しつつ、市場参加者の行動が価格に影響を与えます。需給の反映タイミングは「定期更新時」であり、売買した瞬間に即座に株価が動くわけではありません。
- AI市場心理影響:
aidbwapi_core 経由でLLMに市場動向データを送信し、AIが返す「市場心理スコア(-N〜+N)」を正規化して価格影響に変換します。
価格の安全装置
- 株価は整数で管理。1回の更新あたりの変動幅は最大±10%(config変更可能)にクランプされます。
- 各銘柄には最低価格(
minPrice)と最高価格(maxPrice)が設定され、価格は常にこの範囲内に制限されます。
- リバウンド機構: 最低価格付近では下落圧力を弱め、上昇補正を強めることで価格が0に近づくことを防ぎます。倒産・上場廃止は発生しません。
自動スケール適応 (Adaptive Demand Scaling)
サーバーの過去5日分(デフォルト120回分)の総取引量を移動平均として保存し、これを用いて需給影響を自動で正規化します。プレイヤー人数や取引規模が変化しても、手動でのconfig調整なしで適切なバランスが維持されます。
2. AIニュース生成 (Market News)
定期更新時に 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 <登録名>.<モデル名> — 認証エラー等で自動無効化されたモデルを復帰
/dbwapi model reset <登録名>.<モデル名> — ペナルティ・クールダウンをリセット
3. AI企業説明自動生成 (Company Description)
管理者が銘柄を追加すると、銘柄名を aidbwapi_core へ送信し、AIが企業説明文を自動生成してDBへ保存します。この処理は登録時のみ実行されます。
AI生成が失敗した場合は、フォールバック説明文(「現在、企業説明は取得できません。」)がDBに自動保存されます。
プレイヤーは /stockwapi info <ticker> コマンドや看板から企業説明を閲覧できます。
管理者が企業説明を手動で修正・差し替える場合は、DBファイル(stock_wapi_GlobalDatabase.json)の companyDesc_XXX キーを直接編集してください。
既存の企業説明を空文字("")にしてサーバーを再起動すると、AIが新しい説明を自動再生成します。
4. 独自通貨「KABU」とアイテム交換 (Currency & Exchange)
本Modは外部の経済Modに依存せず、独自通貨「KABU」を使用します。
- 通貨名称: KABU(整数のみ、初期所持0)
- 残高・取引上限: 1プレイヤーの所持金上限、および1回の全取引(株の売買・アイテム交換などすべて含む)の上限は 20億 KABU (2,000,000,000)。(整数オーバーフローおよび経済バランス崩壊防止のため)
- プレイヤーは任意のアイテム(バニラ含む、どのModのアイテムでも可)とKABUを双方向に交換できます。交換は看板UIやコマンドから実行可能です。
- 複数のアイテムをそれぞれ異なるレートで登録可能(例: ダイヤ=100KABU、金インゴット=10KABU)。交換対象の登録は管理者コマンド (
/stockwapi admin setrate) で行い、レート情報は config/stock_wapi-exchange.json に保存されます。
アイテム交換の安全機構
- 事前インベントリスキャン: バニラ仕様による部分消費エラーを防ぐため、交換処理前にプレイヤーのインベントリ全体をスキャンし、所持総量が要求量に達しているかを事前チェック。
- 上限超過ブロック: 交換によって所持金が上限(20億KABU)を超える場合は、アイテムを消費せず処理を完全にブロック。
5. インサイダー対策と市場の公正性 (Market Integrity)
ニュース公開前の取引を構造的に不可能にするため、更新処理は以下の厳格な順序で実行されます。
売買ロック → 価格更新 → ニュース保存 → 配信 → 看板更新 → ロック解除
ロック中に売買を試みた場合は、ブロックされている旨がプレイヤーに通知されます。
6. 手数料システム (Commission)
- 売買時に手数料を徴収可能。買い・売りそれぞれ個別にパーセンテージで設定。デフォルトは0%。
- 手数料収益の行き先は「消滅(デフォルト)」または「サーバー全体の管理口座(config変更可能)」。管理口座は特定プレイヤーUUIDに紐づきません。
/stockwapi admin balance で管理口座の残高を確認できます。
7. 看板UI (Sign Interface)
管理者が設置した看板ブロックに機能を紐付けることで、プレイヤーは右クリックだけで売買・換金・ニュース閲覧が可能になります。
- 設置は管理者のみ可能(
/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(管理者が看板を見ながら実行)
? 動作要件とインストール (Requirements & Setup)
- 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)が自動生成されます。
? 使用方法 (Usage)
サーバー管理者: 初期セットアップ
Step 1: aidbwapi_core の準備
本Modの動作には aidbwapi_core のセットアップが必須です。以下の手順で完了してください。
1-1. AIプロバイダの登録
AIサービス(OpenAI互換API)の接続情報を「登録名(KeyName)」として登録します。
/dbwapi keyname add <登録名> <APIエンドポイントURL> <APIキー>
⚠️ セキュリティ警告: Minecraftの仕様上、チャット欄に入力したコマンド全文(APIキーの平文)はサーバーの logs/latest.log にそのまま記録されます。
安全のため、config/aidbwapi_core-keynames.json をテキストエディタで直接編集し、ゲーム内で /dbwapi reload を実行する運用を強く推奨します。
1-2. モデルの登録
登録したプロバイダに、使用するAIモデルを追加します。
/dbwapi model add <登録名>.<モデル名> <日次上限> <分次上限>
上限値を省略または -1 にすると無制限として登録されます。
複数のプロバイダ・モデルを登録すると、障害時に自動で次のモデルへ切り替わります(フェイルオーバー)。
1-3. 動作確認
/dbwapi ai test
AIからの応答が返ってくれば準備完了です。エラーが出る場合は /dbwapi ai errors でエラー内容を確認してください。
Step 2: 初回起動と自動セットアップ
本Modを mods フォルダに配置してサーバーを起動すると、以下が自動的に行われます。
- デモ用プリセット3銘柄(RDM, END, OAK)の定義が
config/stock_wapi-stocks.json に生成
- 各銘柄の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 ← RDMを5株購入する看板
/stockwapi admin sign sell RDM 5 ← RDMを5株売却する看板
/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 ← RDMを10株購入
/stockwapi sell RDM 5 ← RDMを5株売却
売買完了時には、銘柄名・数量・単価・合計額・手数料・支払/受取額・保有数・平均取得価格が詳細にチャット表示されます。
4. 自分の資産を確認する
/stockwapi myinfo ← 残高・保有銘柄・損益を一覧表示
5. KABUをアイテムに戻す
利益が出たら、KABUを消費してアイテム(ダイヤモンド等)を購入できます。
/stockwapi buyitem diamond 1 ← KABUを支払ってダイヤ1個を入手
運用Tips
- 市場の一時停止: メンテナンス時などは
/stockwapi admin pause で売買と定期更新を一括停止できます。再開は /stockwapi admin resume。
- 銘柄の削除:
/stockwapi admin remove ABC <あなたのUUID> で銘柄を削除できます。保有者がいる場合は現在価格で強制清算されます。誤操作防止のため、あなた自身のUUIDの入力が必須です。
- 手数料の活用: 投機的な大量売買を抑制したい場合は、TOML設定で
buyFeePercent / sellFeePercent を設定してください。feeToAdminAccount = true にすると手数料が管理口座にプールされます。
⚙️ 設定ファイルとディレクトリ構造 (Configuration)
-
config/stock_wapi-common.toml : Mod全体の基礎動作設定ファイル。
[general] セクション:
commandPermissionLevel: 管理者コマンドの要求OP権限レベル(デフォルト 2)。
debugLogging: デバッグログの有効化(デフォルト false)。通常は変更不要。
[market] セクション:
updatesPerDay: 1日の市場更新回数(デフォルト 24、リアルタイム1時間ごと)。
maxPriceChangePercent: 1回の更新あたりの最大変動幅(デフォルト 10、±10%)。
tradingPausedOnUpdate: 更新処理中に売買を一時停止するか(デフォルト true)。false にするとインサイダー対策のロック機構が無効化されます。
[trading] セクション:
buyFeePercent / sellFeePercent: 買い・売りの手数料率(デフォルト 0)。
feeToAdminAccount: 手数料を管理口座にプールするか(デフォルト false、消滅)。
allowShortSelling: 空売りの許可フラグ(Config項目として存在するが、現在未実装のため、trueにしても動作しない)。
minTradeUnit: 最低売買単位(デフォルト 1)。
maxTradeAmount: 1回の最大売買数(デフォルト -1、無制限)。
maxHoldingPerPlayer: 1プレイヤーの銘柄別保有上限(デフォルト -1、無制限)。
[ai] セクション:
sentimentScoreRange: AI心理スコアの範囲(デフォルト 100、-100〜+100)。
newsLanguage: AIが生成するニュースの言語(デフォルト ja)。
worldSetting: AIに渡す世界観設定テキスト(デフォルト "Minecraft世界の架空企業の株式市場")。
-
config/stock_wapi-stocks.json : 全銘柄の詳細パラメータ定義ファイル(1ファイルに配列として格納)。
銘柄追加コマンド実行時にデフォルト値で自動追記されます。初期価格以外のパラメータ(ボラティリティ、トレンド、リバウンド強度、市場タイプ等)を細かく調整したい場合は、サーバー停止時にこのファイルを直接編集してください。
{
"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残高、保有株数、平均取得価格、売買履歴。
?️ コマンドリファレンス (Command Reference)
すべてのコマンドは /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 |
看板ブロックの機能登録を解除(看板を見ながら実行) |
?️ 内部アーキテクチャ補足 (Internal Architecture)
市場更新スケジューラ
タイマー自体は 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の作成および再配布は、ライセンス条項の範囲内で自由に行っていただけます。
评论 0
登录后参与评分
还没有评论,来抢沙发吧