ViScriptShop Market

ViScriptShop Market 是一个基于 NeoForge、LDLib2、ViScriptLib 和 ViScriptShop 的玩家寄售市场附属模组。它提供一个全服玩家市场：玩家可以创建自己的店铺，把背包或兼容容器中的物品按“每组数量 + 库存组数”上架出售，其他玩家使用 ViScriptShop 金币购买。商品收入会先存入店铺余额，店主可以在管理界面中领取。

当前状态

当前版本已经具备基础可玩框架：

• 可以通过 /vss_market open 打开市场。
• 可以通过 /vss_market open <玩家ID> 直接打开指定玩家的店铺；这里的玩家 ID 来自店铺数据里的店主名。
• 服主可以通过 /vss_market delete <玩家ID> 删除指定玩家的店铺，该命令需要权限等级 4。
• 支持创建、重命名、删除玩家店铺。
• 支持上传商品、补货、改价、下架和购买。
• 支持店铺待领取金币与领取操作。
• 支持按店铺名、店主名、物品名、物品 ID 搜索商品。
• UI 使用 LDLib2 默认 GDP 主题，并带有玩家头像、店铺列表、商品 grid、详情页和确认弹窗。

下一阶段主要建议做多人交易实测和 UI 细节打磨，具体见“后续建议”。

功能介绍

• 玩家店铺：每个玩家最多拥有一个店铺，店铺名可修改。
• 组合售卖：商品以“每组数量 + 库存组数”上架。例如每组 5 个羊毛、库存 3 组，会从卖家物品来源中扣除 15 个羊毛；买家每次购买会获得 5 个羊毛。
• 金币交易：买家使用 ViScriptShop 金币支付，卖家收入进入店铺待领取金币。
• 库存管理：上架和补货会扣除卖家物品；下架和删除店铺会返还剩余库存。
• 安全删除：删除店铺前会弹出确认框，确认后返还剩余库存并领取店铺余额。
• 兼容物品来源：物品统计和扣除使用 ViScriptLib 的 ItemUtil，用于兼容精妙背包、超越维度等扩展容器逻辑。
• 服务端校验：价格、数量、库存、余额、店铺归属等关键逻辑均在服务端校验。
• 持久化：店铺、商品、库存、价格和待领取金币保存在世界数据中。

依赖

• Minecraft 1.21.1
• NeoForge 21.1.216 或同范围版本
• LDLib2 2.2.13
• ViScriptLib 1.0.3
• ViScriptShop

如何打开市场

进入游戏后执行：

/vss_market open

如果想直接查看某个店铺，可以执行：

/vss_market open <玩家ID>

这里的 玩家ID 是市场保存数据里店铺的店主名，命令补全会列出现有店铺的店主名。目标玩家没有店铺时，会按普通市场入口打开。为了兼容旧用法，直接输入店铺 owner UUID 也能被识别。

打开后，左侧是当前玩家头像、余额、管理入口和店铺列表；右侧是当前店铺或搜索结果中的商品列表。

卖家使用说明

创建店铺

1. 执行 /vss_market open 打开市场。
2. 点击左侧“管理店铺”。
3. 如果还没有店铺，点击“创建店铺”。
4. 创建后可以修改店铺名称，并点击“保存”。

上传商品

1. 进入“管理店铺”。
2. 点击“上传商品”。
3. 点击“选择物品”，从背包中选择出售目标。
4. 输入价格、每组数量和库存组数。
5. 点击“上传商品”。

上传成功后，系统会扣除 每组数量 * 库存组数 个物品。若物品不足，界面会停留在上传页并保留当前输入，方便直接修改数量。

管理商品

在自己的店铺后台点击商品卡片，可以进行：

• 补货：按该商品的每组数量扣除对应物品，并增加库存组数。
• 改价：修改商品的单组售价。
• 下架：移除商品，并返还剩余库存。

领取金币

商品售出后，金币会进入店铺待领取余额。店主需要在“管理店铺”中点击“领取金币”。

删除店铺

点击“删除店铺”后会出现确认弹窗。确认删除会返还所有剩余库存、领取店铺余额，并移除店铺数据。

买家使用说明

1. 执行 /vss_market open 打开市场。
2. 在左侧选择店铺，或使用搜索框搜索店铺和商品。
3. 点击商品卡片进入详情页。
4. 设置购买组数。
5. 点击“购买”。

商品卡片中的物品数量表示每组包含的物品数量；购买组数最大值会限制为当前库存组数。鼠标悬浮商品时会显示库存组数。买家不能购买自己店铺中的商品。

服主命令

删除指定店铺：

/vss_market delete <玩家ID>

该命令需要权限等级 4。这里的 玩家ID 是市场保存数据中的店主名，补全会列出现有店铺的店主名；直接输入店铺 owner UUID 也能兼容。它会直接删除市场保存数据中的店铺记录，适合服主处理异常店铺；不会像店主在 UI 中删除店铺那样返还库存或领取店铺余额。

搜索逻辑

搜索框会在所有店铺中搜索：

• 店铺名
• 店主名
• 物品显示名
• 物品 ID

物品匹配使用 ViScriptLib 的 SimpleItemStackFilter，因此搜索行为会尽量贴近通用物品筛选逻辑。

配置

配置文件位于：

config/vss_market_config.toml

当前可配置项：

• minPrice：商品最低价格，默认 1
• maxPrice：商品最高价格，默认 1000000000
• maxStacksPerOperation：单次上架、购买、补货允许处理的最大数量，默认 100000
• maxListingsPerShop：每个店铺允许拥有的最大商品条目数，默认 200
• maxShopNameLength：店铺名称最大长度，默认 32

测试

详细手动测试清单见：

TESTING.md

建议至少准备两个玩家账号进行测试：一个作为卖家，一个作为买家。重点验证：

• 上架、补货、下架、删除店铺时的物品扣除和返还。
• 购买时金币扣除、库存减少、卖家店铺余额增加。
• 背包和兼容容器物品不足时是否正确拒绝。
• 多人同时购买同一商品时库存和金币是否保持一致。
• 重启世界后店铺数据是否仍然存在。
• 不同 Minecraft GUI Scale 下 UI 是否保持居中且不溢出。

后续建议

当前项目已经可以进入功能测试阶段，后续最值得优先处理的是：

• 多人并发测试：尤其是库存只剩 1 组时，多个买家同时购买的行为。
• 满背包测试：下架、删店、购买返还物品时，背包满了的实际体验需要确认。
• UI 长文本测试：长店铺名、长玩家名、长物品名、大价格数字是否会挤压布局。
• 搜索体验优化：后续可以继续调整搜索结果排序，例如优先展示店铺名匹配、再展示物品匹配。
• 店铺展示美化：基础布局已完成，后续可以再按 ViScriptShop 风格微调商品卡片、详情页和管理页。
• 边界值验证：接近 int 上限的金币、库存和价格需要继续手动测一轮。

构建

本项目需要 Java 21。若系统默认 Java 版本较低，可以显式指定：

JAVA_HOME=/Library/Java/JavaVirtualMachines/corretto-21.0.4/Contents/Home ./gradlew build

构建产物位于：

build/libs/vss_market-1.0.0.jar