StockMarket wAPI

模组

· 作者 morwapi

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

0 本站下载 0 关注 更新于 8 个月前

最新 1.21.1-0.1.2 · 1.21.1 · NeoForge

一键开服(送7天)
  1. 英文 / 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 错误

  1. /dbwapi ai errors — 检查最近的错误历史(HTTP 状态码/原因)。
  2. /dbwapi model list — 查看所有模型的状态(启用/禁用,惩罚点数)。
  3. /dbwapi model enable <KeyName>.<ModelName> — 恢复因身份验证错误等原因自动禁用的模型。
  4. /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 中。

物品交换安全机制

  1. 预库存扫描: 为防止因原版规格导致的部分消耗错误,在交换过程开始之前,会扫描玩家的全部库存以检查持有总量是否满足所需数量。
  2. 超限阻断: 如果交换会导致余额超过限额(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 通信与数据库基础)
  • 端: 服务器和客户端均需安装

安装步骤:

  1. 确保已设置好 aidbwapi_core(已注册 AI 提供商并配置模型)。
  2. 将此模组 (stock_wapi-x.x.x.jar) 放入服务器或客户端的 mods 文件夹并启动游戏。
  3. 首次启动时,将自动生成三个演示预设代码(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 错误发生时的确认步骤

  1. /dbwapi ai errors — 查看最近错误历史(HTTP 状态码及原因)
  2. /dbwapi model list — 一览查看所有模型状态(启用/禁用、惩罚值)
  3. /dbwapi model enable <注册名>.<模型名> — 恢复因认证错误等自动禁用的模型
  4. /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 中。

物品兑换安全机制

  1. 预背包扫描: 为防止原版机制导致的部分消耗错误,在处理交换前会扫描玩家整个背包,预先检查持有总量是否达到所需数量。
  2. 超限阻断: 若交换导致持有金额超过上限(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 通信与数据库基础)
  • 运行环境: 服务端与客户端均需安装

安装步骤:

  1. 请确认已完成 aidbwapi_core 的设置(已注册 AI 提供商并设定好模型)。
  2. 将本模组 (stock_wapi-x.x.x.jar) 放入服务器或客户端的 mods 文件夹中启动游戏。
  3. 首次启动时,将自动生成用于演示的预设 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。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源