# FreeCoreShop

**Repository Path**: freecore-mc/FreeCoreShop

## Basic Information

- **Project Name**: FreeCoreShop
- **Description**: FreeCore 箱子商店
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-30
- **Last Updated**: 2026-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FreeCoreShop

FreeCoreShop 是面向 **Minecraft Java / Paper 26.2** 的箱子商店插件。它提供需要真实库存和店主资金的玩家商店，以及库存无限、可使用市场动态收购价的官方商店。经济功能通过 Vault 接入。

## 环境要求

- Paper 26.2（构建目标：`paper-api 26.2.build.92-stable`）
- Java 25
- Vault
- 任意已向 Vault 注册 `Economy` 服务的经济插件

缺少 Vault 或经济服务时，FreeCoreShop 会拒绝启用，避免出现无资金结算的交易。

## 构建与安装

Windows：

```powershell
.\gradlew.bat clean build
```

Linux/macOS：

```bash
chmod +x gradlew
./gradlew clean build
```

构建产物位于 `build/libs/FreeCoreShop-1.0.16.jar`。将其与 Vault、经济插件一同放入服务端 `plugins` 目录后启动服务端。

仓库内的轻量构建脚本会把 Gradle 9.6.1 与依赖缓存放在本项目目录，不占用系统盘的全局 Gradle 缓存。

## 创建商店

1. 在主手持有交易物品。手持数量就是每次点击交易的批次数量。
2. 左键点击一个单箱或陷阱箱。双箱不接受创建，以免通过另一半绕过库存保护。生存模式不会阻断原版破坏进度；创造模式会取消本次破坏，避免箱子被瞬间移除。
3. 在 30 秒内通过聊天输入每个物品的单价。OP 创建官方商店时也可输入 `Dynamic`；超时或输入任何非法价格内容都会直接取消本次创建。
4. 在确认界面选择“出售模式”或“收购模式”，再点击确认。
5. 插件会在箱子正前方生成木牌。该位置被占用时不会创建商店。

普通玩家默认创建玩家商店；拥有 `freecoreshop.create.official` 的 OP 默认创建官方商店。OP 可先使用 `/fcshop type player` 或 `/fcshop type official` 切换后续创建类型。

`Dynamic` 只适用于**官方商店**。官方收购模式使用物品当前动态收购价；官方出售模式使用对应动态收购价的两倍。

## 交易和补货

- 右键商店箱子或木牌：插件会私聊提示输入本次交易数量；只有合法正整数才会执行交易。
- 输入非数字、零、负数、超出上限的数量或 `cancel`：本次交易取消，输入内容不会广播到聊天栏。
- 左键商店木牌：打开编辑界面。店主可修改静态价格、出售/收购模式以及木牌按个或按 64 个一组显示价格；管理员还可切换玩家/官方类型及 Dynamic。
- 编辑界面点击保存后才会写入商店数据；关闭或点击取消会放弃本次修改。
- 每个商店箱子顶部会显示对应商品的虚拟悬浮图标。图标使用 Java 版和 Geyser 基岩版均可识别的掉落物实体，不可拾取、不会进入漏斗或与其他物品合并，并关闭方块碰撞物理以防遮挡时被随机挤开。
- 出售模式：玩家付钱，从商店买入物品。
- 收购模式：玩家交出物品，从商店获得钱。
- 玩家向收购商店出售时，插件先扣除背包中的指定物品，不足部分再按背包槽位顺序从潜影盒内部扣除；交易失败会将背包和潜影盒恢复到交易前状态。
- 玩家出售商店：创建时无需预先补货，箱子有无指定物品都可以创建；之后由店主潜行右键箱子补货，库存不足时交易会提示缺货。
- 玩家收购商店：店主必须有足够余额，箱子也必须有空间。
- 官方商店：不消耗或存入箱内库存；官方收购由系统发放资金，官方出售所得由系统回收。

交易严格比较完整物品组件。附魔、耐久、名称、Lore 等不同的物品不会混用。任何资金或库存步骤失败时，插件会回滚本次交易。

## 动态市场价格

动态价格严格采用 `FreeCoreShopDynamicPrice.md` 的模型：

```text
E = Σ(w_i × Q_i)
P_std = clamp(E0 / E, RatioMin, RatioMax)
P_item = clamp(K × P_std, max(K × RatioMin, RatioMin), K × RatioMax)
```

- 使用 1 分钟、3 分钟、15 分钟、30 分钟、1 小时、6 小时、1 天、3 天、7 天、14 天共十个窗口，默认权重总和为 1。
- 每种“材质 + 完整组件”物品独立维护最近 14 天的分钟回收量。
- 首次登记物品时，各窗口用 `E0` 基线预填充，所以初始倍率为 `1.00`、初始价格等于 K。
- 成交前异步计算实时价格；成交成功后异步记录回收量。每分钟异步清理、刷新并持久化。
- 动态数据写入 `plugins/FreeCoreShop/dynamic-data.yml`，商店数据写入 `shops.yml`，重启不丢失。
- `/fcshop dynamic` 会列出当前存在官方 Dynamic 收购/出售商店的商品。详情可选择最近 24 小时（每小时）、最近 7 天（每天）、最近 4 周（每周）或最近 12 个月（每月）的价格序列与涨跌走势。动态成交分钟桶保留 365 天，以支持精确的年度月度回看。
- 最终单价和总价四舍五入到两位小数。木牌价格固定显示两位小数；Dynamic 商店第三行显示“动态价格”。
- 每个商店可在编辑界面选择木牌按单个价格显示（`x H币/个`），或按组显示整组总价（`x H币/组`）。按组价格由四舍五入后的单价乘以 64 计算，但木牌不会显示数量 `64`。

首次运行会将 Paper 26.2 当前版本的**全部可用物品**补全到 `config.yml` 的 `dynamic-pricing.item-values`。内置参考值根据资源稀有度、制作成本和装备类别估算，服主可以逐项调整。未识别的新物品仍以 `K=1` 安全回退。

完整组件物品可单独配置 K：看向商店执行 `/fcshop info`，复制显示的 SHA-256 组件指纹，在 `item-values` 中以该指纹为键配置数值。组件指纹优先于材质 ID。

## 命令

| 命令 | 说明 |
|---|---|
| `/fcshop help` | 显示帮助 |
| `/fcshop type <player\|official>` | OP 切换后续创建类型 |
| `/fcshop mode <sell\|buy>` | 修改当前看向商店的模式 |
| `/fcshop info` | 查看商店、实时价格参数与物品组件指纹 |
| `/fcshop dynamic` | 打开 Dynamic 市场，查看官方动态收购/出售价格及历史走势 |
| `/fcshop remove` | 移除当前看向的商店 |
| `/fcshop cancel` | 取消正在进行的创建或交易 |
| `/fcshop reload` | 重载配置、K 值和动态价格参数 |

## 权限

| 权限 | 默认 | 说明 |
|---|---|---|
| `freecoreshop.use` | 所有人 | 使用主命令 |
| `freecoreshop.create` | 所有人 | 创建玩家商店 |
| `freecoreshop.manage.own` | 所有人 | 管理自己的商店 |
| `freecoreshop.create.official` | OP | 创建官方商店 |
| `freecoreshop.manage.any` | OP | 管理任意商店 |
| `freecoreshop.reload` | OP | 重载配置 |
| `freecoreshop.admin` | OP | 包含全部管理员权限 |

## 语言文件

插件首次启动会在 `plugins/FreeCoreShop/lang/` 生成 `zh_CN.json` 和 `en_US.json`。两份文件覆盖命令、聊天提示、确认按钮、交易结果、木牌和控制台日志，并使用整洁的 Minecraft `&0-9a-fk-or` 颜色符号。默认中文文件还包含从 Minecraft 26.2 官方资源同步的完整物品与方块物品名称。

在 `config.yml` 设置 `language.locale: en_US` 即可切换英文；修改 JSON 后执行 `/fcshop reload` 生效。语言文件中的 `{quantity}`、`{price}` 等占位符由插件自动替换。

木牌四行可在语言文件的 `sign.lines` 中完整修改：`first`、`second`、`third-unit`、`third-stack`、`fourth`。可用占位符包括 `{pricing}`、`{type}`、`{mode}`、`{item}`、`{price}`、`{amount}`、`{currency}`、`{quantity}` 和 `{owner}`；其中 `{price}` 已包含两位小数金额及货币名称。

## 主要配置

- `shop.sign-material`：自动木牌材质，必须是墙上木牌。
- `shop.max-unit-price`：静态单价输入上限，默认一万亿，防止经济接口收到无穷值。
- `shop.max-transaction-quantity`：单次聊天确认的最大数量，默认 2304。
- `language.locale`：语言文件名，默认 `zh_CN`，可改为 `en_US`；文件位于插件数据目录的 `lang` 文件夹。
- `shop-icon.enabled`：是否显示箱子顶部的虚拟商品图标。
- 商店木牌按客户端分别显示：Java 版使用语言 JSON `sign` 区块配置的正常颜色且不启用发光描边；安装 Geyser/Floodgate 时，插件在 Geyser 翻译器之后拦截商店木牌更新，向基岩版稳定发送黑色染料、发光状态并保留彩色文字，从而生成黑色描边。
- `shop-icon.height`：图标相对箱子方块底部的悬浮高度，默认 `1.15`。
- `shop-icon.update-interval-ticks`：图标位置和状态检查间隔，默认每 20 tick 检查一次。
- `dynamic-pricing.base-effective-volume`：基准有效回收量 `E0`，默认 `50000`。
- `dynamic-pricing.update-interval`：缓存、木牌和持久化刷新间隔，默认 `1m`。
- `dynamic-pricing.instant-calculation`：成交时是否异步实时计算。
- `dynamic-pricing.price-bounds.min/max`：波动倍率上下限。
- `dynamic-pricing.k-value-system.enabled`：关闭后所有物品按 `K=1` 计算。
- `dynamic-pricing.windows`：十个时间窗口及权重；配置无效或权重和不为 1 时使用规范默认值。
- `dynamic-pricing.item-values`：材质 ID 或组件指纹到 K 值的映射。