命令与配置文件

文件位置与生效

这里的 config 指当前游戏实例或服务器根目录中的 config 文件夹，不一定是系统默认的 .minecraft。整合包启动器通常为每个实例单独保存配置。

config/
├── valemetry/
│   ├── item_values.json
│   ├── item_bans.json
│   └── background-….png
└── valemetry-client.toml

先进入一次世界或启动服务器，让模组初始化价格配置，再去找两个 JSON。文件不存在时会生成默认文件；已有文件不会被默认内容覆盖。多人游戏要改服务器端文件，修改自己的客户端副本不会改变服务器报价。

编辑、保存、生效

1. 用纯文本编辑器打开 JSON，先复制一份备份。不要用 Word 等富文本编辑器。
2. 保留 UTF-8 编码及准确文件名。确认文件没有变成 item_values.json.txt。
3. 按下文格式修改并保存，再由有权限的人执行 /valem reload。
4. 查看命令返回信息，再查询目标物品的价格和禁售状态。

查看重载命令与错误处理

物品价格

item_values.json 的最外层是对象 {}。每项左边是带英文双引号的 ID，右边是无需引号的数字；项目之间用英文逗号，最后一项后面不加逗号。

{
  "minecraft:diamond": 1200,
  "minecraft:iron_ingot": 32.5,
  "minecraft:elytra": 0
}

• 1200 和 32.5 是每件物品的基础买入单价。卖出返还额由世界的卖出比例进一步计算。
• 0 表示明确移除该 ID 的价格，并阻止它再次通过配方推导出价格，不是免费购买。
• 文件里没有写到的物品，继续使用内置或受支持配方推导的价格；无法推导时保持无价格。
• 把整个文件写成 {}，表示没有手动覆盖，不会清空内置价格。删除文件会在下次加载时重新生成默认配置。

数字怎么写？

支持普通十进制整数或最多两位小数。正价最小是 0.01；例如 100、100.5、100.50。不要加 $、K、M、千位逗号、正负号或科学计数法，也不要把数字放进引号。

例如 "32.5"、-1、1e3、0.001、01、null 都不合法。同一价格文件不能重复定义同一个 ID；diamond 与 minecraft:diamond 也会被视为重复。minecraft:air 不能定价或清除。

禁售名单

item_bans.json 使用数组 []，每一项是物品 ID 字符串。名单中的物品不能买入或卖出，禁售优先于手动价格与配方推导。

[
  "minecraft:emerald",
  "minecraft:emerald_block"
]

首次生成的默认名单包含绿宝石和绿宝石块。想取消全部额外禁售，请保存空数组 []；不要删除文件，否则下次加载会重新生成默认名单。重复的禁售 ID 会去重，但建议每个只写一次。

调整世界交易规则

打开终端的“设置 → 交易设置”。单人世界拥有者可编辑；多人服务器需要管理员权限。这些规则保存在世界中，对该世界所有玩家统一生效，不放在 item_values.json 或客户端 TOML 中。

调整后点击“保存设置”，即可保存到当前世界，无需 /valem reload。取消则不提交。多人同时编辑时，如果别人已经先保存，请重新打开设置读取最新内容再修改。保存新规则会取消仍在等待的物品交易，请在调整后重新核对订单。

外观与客户端配置

配色、圆角、透明度和背景优先通过“设置 → 通用设置”修改：可以即时预览，点击应用/保存后持久化，取消则返回之前保存的外观。这里只改变自己的显示，不影响队友或服务器价格。

手动编辑 valemetry-client.toml

需要手工编辑时，先完整退出游戏并备份文件，再修改、保存、重新启动。不要在游戏运行时反复改这个文件；/valem reload 不会刷新客户端外观缓存。下面是默认字段示例，不是要求覆盖你已有的收藏与偏好。

[catalog]
sort = "ADDED"
ascending = false

[terminal]
lastTools = []

[stocks]
watchlists = []
buyByAmount = true
sellByAmount = false

[appearance]
accent = 2152939
backgroundOpacity = 95
backgroundImage = ""
backgroundFocusX = 0.5
backgroundFocusY = 0.5
style = "CLASSIC"

TOML 中字符串用英文双引号，true/false 不加引号，数字也不加引号；与 JSON 不同，TOML 使用 [分组] 和 key = value，不在每行末尾添加逗号。保留生成文件中的其他已有记录。

自定义背景如何缩放？

导入本地 PNG 或 JPEG，文件不超过 20 MiB、总像素不超过 16,777,216，最长原始边不超过 16,384 像素。导入时会等比缩小至最长边最多 2048，小图不会被放大保存。显示时按窗口比例铺满，超出部分裁切，再用取景位置选择重点，不会把图片拉伸变形。

导入并保存后，模组会在 config/valemetry 中保留受管理的 PNG 副本，只在本机使用，不上传给服务器。备份或迁移外观时，连同 valemetry-client.toml 与对应背景 PNG 一起保留。清除当前背景或恢复默认不会自动清理所有旧图片。

执行命令与权限

谁可以执行命令？

在聊天框输入带 / 的命令并回车。服务器控制台执行价格、禁售和重载命令时通常省略开头的 /；转账和团队命令需要玩家身份，不能直接在控制台执行。

/valem

代码框中的示例可直接复制，按需替换物品 ID、玩家名 Alex、队名和金额，保留参数顺序及命令本身。每行是一条独立命令。

准确获取物品 ID

物品 ID 是游戏识别物品的内部名称，通常写成“模组命名空间:物品名”，例如 minecraft:iron_ingot。中文显示名、模组页面上的英文标题，都不能直接当作 ID。

1. 在当前世界输入 /valem price show，再输入一个空格。
2. 输入 minecraft: 或目标模组的命名空间，查看游戏给出的物品建议，用 Tab 补全实际存在的物品。
3. 回车查询。即使该物品还没有价格，也可以从当前注册物品中选取；把完整 ID 复制进配置。

安装了某个模组，并不代表它的所有历史 ID 或联动物品都存在。Minecraft 版本、模组版本和可选联动会影响实际物品列表。不要按照英文翻译自行拼写 ID。

配置是按物品 ID，不是按物品状态

JSON 键只接受单个物品 ID，不接受 #forge:ingots/iron 这样的标签、modid:* 通配符、中文名称或带 NBT 的字符串。命令中即使输入可解析的 NBT，最终也只按注册 ID 操作，不能给同一种物品的不同品质、药水内容或附魔分别定价。

价格命令

/valem price show minecraft:iron_ingot

/valem price set minecraft:iron_ingot 32.5

/valem price clear minecraft:elytra

/valem price reset minecraft:iron_ingot

通过命令成功修改后通常已经自动生效，不必再执行 reload。直接编辑 JSON 后才需要手动重载。调整原料价格可能影响由它继续推导的其他商品；保存后要同时检查相关产物。

禁售命令

/valem ban add minecraft:emerald

/valem ban remove minecraft:emerald

/valem ban check minecraft:emerald

/valem ban list

重载与常见错误

/valem reload

怎样判断成功？

先看返回消息，再执行 price show 与 ban check。存在被跳过的未注册正价条目时，其他有效配置仍可应用，并附带警告；不要把出现任何提示都当成整次失败。

如果当前运行期间已经成功加载过价格，失败重载会继续使用上一次有效结果。本次文件修改并未生效，文件也不会自动恢复。若这次运行从未有过有效目录，物品交易会暂停，修复后可直接重载恢复。

按这个顺序排错

1. 确认改的是当前实例或服务器的文件，文件名及扩展名正确，并且已经保存。
2. 检查对象 {} 与数组 [] 有没有用反；只用英文双引号和逗号，不加注释、不留末尾逗号。
3. 用游戏内物品补全核对 ID，不要按名字猜测。
4. 查看执行端 logs/latest.log，搜索 Valemetry、item_values.json 或 item_bans.json，找到文件、条目与原因。
5. 一次可能不止一处错误。修完后再次 /valem reload，再查目标价格及禁售状态。

日志中的 item is not registered 表示当前游戏没有注册这个 ID，不是在帮你创建新物品。游戏内总提示会跟随客户端语言，但物品 ID、文件名和底层英文错误原因不会全部翻译。

若命令提示“配置已保存，但重新加载失败”，不要重复盲目设价：先修文件，再 reload。若价格有效但仍无法购买，检查是否成功出售解锁、是否被禁售、余额与交易限额是否足够；无法出售带状态物品时，还要考虑物品安全规则。

个人转账

/valem pay Alex 100.50

金额必须大于 0，最多两位小数，例如 100、100.5、0.01。不接受 all、$100、1K、1,000、负数、0 或科学计数法。转账只移动已有余额，不生成钱，也不转移商品解锁。

目标离线、余额不足、金额无效或收款余额达到上限时，整笔转账失败，不会自动少转一部分。

团队与钱包

每位玩家最多加入一个团队。创建或加入团队不会合并个人余额；选择团队钱包也只是切换交易使用的钱包，不会自动搬钱。

创建、邀请与加入

/valem team create "晨星工坊"

/valem team invite Alex

/valem team accept "晨星工坊"

/valem team decline "晨星工坊"

查看与管理团队

/valem team info

/valem team members

/valem team leave

/valem team kick Alex

/valem team transfer-owner Alex

/valem team disband

选择钱包与调拨资金

/valem team wallet status

/valem team wallet use personal

/valem team wallet use team

/valem team wallet deposit 500

/valem team wallet deposit all

/valem team wallet withdraw 200

/valem team wallet withdraw all

/valem team wallet pay Alex 80.25

金额格式与个人转账一致。all 只存在于 deposit 和 withdraw 中，不能写成 team wallet pay Alex all。资金不足或收款方超出余额上限时，整笔操作失败。