📥 安装与目录

环境要求

安装步骤

1. 放入 AdventureLib.jar + AdventureShop-1.2.2.jar
2. 按需安装 Vault / AdventureManage / AdventureMail
3. 启动服务器自动生成配置
4. 编辑 config.yml 和 items/*.yml
5. /ashopadmin reload

目录结构

plugins/AdventureShop/
  config.yml          # 主配置
  messages.yml        # 消息文本
  gui.yml             # GUI 布局
  items/
    weapons.yml       # 武器物品池
    blocks.yml        # 建材物品池
    misc.yml          # 杂货物品池
  Translations/
    items_CN.yml      # 物品名中文翻译
  data/
    adventureshop.db  # SQLite 数据库

🏪 商店类型

商店由刷新周期和交易方向两个维度组合，共 8 种：

⭐ 稀有度系统

每件物品必须指定稀有度，影响抽取概率和价格系数。

权重覆盖

daySell-weapon:
  rarity-weights:
    normal: 5        # 权重越高越容易出现
    advanced: 3
    rare: 2
    mythical: 0      # 0 = 不出现

📦 物品池

物品池位于 items/ 目录，一个 YAML 文件 = 一个类别。

字段说明

示例

# items/weapons.yml
iron_sword:
  material: IRON_SWORD
  category: weapon
  rarity: normal
  base-price: 50
  price-variance: 0.15
  currency: vault
  global-stock: 10
  player-limit: 2
  delivery: INVENTORY

diamond_sword:
  material: DIAMOND_SWORD
  category: weapon
  rarity: rare
  base-price: 500
  price-variance: 0.2
  currency: vault
  global-stock: 3
  player-limit: 1
  delivery: INVENTORY
  discount:
    enabled: true
    rate: 0.85
    permission: "adventureshop.discount.weapon"

mace:
  material: MACE
  category: weapon
  rarity: mythical
  base-price: 10000
  currency: gem
  global-stock: 1
  delivery: MAIL_180D

💲 定价与刷新

三层定价引擎

例：钻石剑 base-price=500, RARE (×1.5), variance=0.2

最低 = 500 × 1.5 × 0.8 = 600
最高 = 500 × 1.5 × 1.2 = 900
收购价 = 出售价 × buy-back-ratio (默认 0.5)

自动刷新

玩家手动刷新

第 N 次费用 = base-cost × cost-increase ^ (N-1)

示例 (base=500, increase=1.5):
第1次: 500 / 第2次: 750 / 第3次: 1125

📬 物品发放

兜底机制

INVENTORY 通道降级链：

1. 放入背包
2. 背包满 → 检查 AdventureMail
3. AM 可用 → 发邮箱 (默认 3 天)
4. 邮件失败 → SafeGiveUtil 安全掉落

💰 多货币与折扣 v1.1.0

多货币系统

currencies:
  vault:
    display-name: "银币"
    backend: vault
  point:
    display-name: "金币"
    backend: playerpoints
  acoin:
    display-name: "A币"
    backend: item
    item-material: GOLD_NUGGET
    item-name: "&eA币"
  gem:
    display-name: "宝石"
    backend: item
    item-material: EMERALD

三层折扣

叠加规则

discount:
  enabled: true
  stack-mode: best
  min-rate: 0.5      # 不低于5折
  permission-discounts:
    vip:
      permission: "adventureshop.discount.vip"
      rate: 0.9
      priority: 10
    svip:
      permission: "adventureshop.discount.svip"
      rate: 0.8
      priority: 20

货币抵扣 v1.1.0

主货币不足时按比例用其他货币补差，聊天框弹出 [点击确认抵扣] 按钮。

currency-fallback:
  enabled: true
  rules:
    - from: vault      # 银币不足时
      to: point        # 用金币抵扣
      rate: 10.0       # 1金币 = 10银币
      max-ratio: 0.5   # 最多抵扣50%
    - from: vault
      to: gem
      rate: 100.0
      max-ratio: 1.0

🔗 插件联动

AdventureManage 联动

• 金币交易自动走 AM 的 takeMoney / giveMoney
• 交易记录带原因字符串
• 出售给收购商店时自动按 AM 扣税
• 未安装 AM 回退到 Vault 直接扣款

AdventureMail 联动

• MAIL_7D / 30D / 180D 通道直接发送到邮箱
• INVENTORY 背包满时自动转存邮箱 (默认 3 天)
• 邮件标题自动标注商城信息

delivery:
  inventory-fallback:
    enabled: true
    mail-expire-days: 3
    mail-source: "§6[冒险商城] §7背包已满自动转存"

⌨️ 命令列表

玩家命令 /ashop

管理命令 /ashopadmin

⚙️ config.yml

核心设置

core:
  timezone: "Asia/Shanghai"

经济设置

economy:
  buy-back-ratio: 0.5
  rarity-price-multiplier:
    normal: 1.0
    advanced: 1.2
    rare: 1.5
    rarer: 2.0
    epic: 3.0
    mythical: 5.0

刷新设置

refresh:
  daily-time: "00:00"
  weekly-day: "MONDAY"
  monthly-day: 1
  player-refresh:
    cost-type: vault
    base-cost: 500
    cost-increase: 1.5
    max-per-day: 3

商店定义

shops:
  daySell-weapon:
    type: daySell
    category: weapon
    display-name: "今日热销-武器"
    item-count: 8
    rarity-weights:
      normal: 5
      advanced: 3
      rare: 2
      rarer: 1
      epic: 0.5
      mythical: 0

数据库

database:
  type: sqlite        # sqlite / mysql
  mysql:
    host: localhost
    port: 3306
    database: adventure_shop
    username: root
    password: ""
    pool-size: 5

🖥️ GUI 与消息配置

gui.yml

# 分类选择界面
category-gui:
  title: "§0§l冒险商城 §8| §r§6选择商店"
  size: 54

# 商店浏览界面
shop-gui:
  title-format: "§0§l冒险商城 §8| §r{shop_name} §7({page}/{total})"
  rows: 6
  item-slots: 45
  prev-page: { slot: 45, material: ARROW }
  next-page: { slot: 53, material: ARROW }
  refresh-button: { slot: 49, material: SUNFLOWER }
  info-button: { slot: 47, material: BOOK }

# 商品 Lore
item-display:
  name-format: "{rarity_color}[{rarity_name}] {item_name}"
  lore:
    sell:
      - "§7价格: §e{price} {currency}"
      - "§7全服库存: §f{global_stock}"
      - "§7个人限购: §f{purchased}/{player_limit}"
      - "§a▶ 左键购买"
    buy:
      - "§7收购价: §e{price} {currency}"
      - "§a▶ 左键出售"

messages.yml v1.2.2

所有用户可见消息、GUI 文本、日志、枚举显示名均可自定义。

prefix: "&6[冒险商城] &r"

shop:
  buy-success: "{prefix}&a成功购买 &e{item} &a! 花费 &e{price} {currency}"
  fallback-prompt: "{prefix}&e{currency}不足! ..."
  fallback-confirm-button: "&a&l[点击确认抵扣]"

enum:
  shop-type:
    day-sell: "今日热销"
  rarity:
    epic: "史诗"

🎨 GUI 界面

分类选择 GUI

/ashop 打开。每个商店一个图标：

商店浏览 GUI

54 格界面 (6 行)：第 1-5 行商品展示，第 6 行控制栏。

🔑 权限节点

🗄️ 数据库与安全

存储引擎

SQLite (默认，零配置) 或 MySQL (HikariCP 连接池)。

数据表

安全机制

GUI 防护

• Shift / NumberKey / DoubleClick / Drop / SwapOffhand / Middle 全部拦截
• InventoryDragEvent 阻止拖入
• 只处理上方 GUI 区域点击

频率限制

库存原子操作

AtomicInteger + CAS 循环，并发安全不扣负。

交易安全

• 购买：扣库存 → 扣钱 → 发物品，失败回滚
• 出售：先给钱 → 成功后扣物品
• 掉落：SafeGiveUtil 避开岩浆/虚空

📝 更新日志

v1.2.2 最新

• NEW 消息外置 — 所有文本移至 messages.yml
• NEW 枚举显示名 — 商店类型/稀有度可自定义名称

v1.1.0

• NEW 多货币系统 — Vault/PlayerPoints/物品货币
• NEW 三层折扣 — 全局/商店级/商品级
• NEW 货币抵扣 — 主货币不足自动补差
• NEW 4 种发放通道 — 背包/邮件 7/30/180 天
• NEW AdventureMail 兜底 — 背包满自动转存

v1.0.0

• NEW 初始发布 — 随机商品、稀有度、GUI、Vault 经济