📥 安装与目录

环境要求

依赖插件

安装步骤

1. 放入 AdventureMonthCard-1.0.0.jar 到 plugins/ 目录
2. 重启服务器
3. 编辑 plugins/AdventureMonthCard/ 下配置文件
4. /monthcard admin reload 重载生效

目录结构

plugins/AdventureMonthCard/
├── config.yml          # 核心配置 (数据库/备份/提醒/音效)
├── passes.yml          # 月卡类型定义 (奖励/价格/里程碑)
├── gui.yml             # GUI面板外观 (日历/商店布局)
├── messages.yml        # 消息文本 (MiniMessage 格式)
├── data.db             # SQLite 数据库 (默认)
└── backUp/
    ├── backup_2026-05-07_04-00-00.sql
    └── ...             # 自动备份文件

💳 月卡体系

AdventureMonthCard 支持多种月卡类型，默认提供普通月卡和精英月卡两级体系。

月卡对比

月卡生命周期

1. 购买 — 玩家在商店 GUI 中选购月卡，扣除对应货币
2. 激活 — 购买后立即激活，从当天起计算有效期
3. 续费 — 若月卡已到期，可重新购买；有效期从当前日期起算
4. 签到 — 月卡有效期内，每天可在日历 GUI 中签到一次
5. 到期 — 到期后无法签到，需重新购买

includes 继承机制

精英月卡设置 includes: "normal"，签到时自动额外发放普通月卡的当日奖励。这意味着精英月卡玩家一次签到获得两份奖励（精英 + 普通）。

📅 签到日历

54 格 (6行 × 9列) 日历面板，7列居中布局，两侧黑色边框填充。

面板布局

┌──┬──┬──┬──┬──┬──┬──┬──┬──┐
│🛒│▓ │▓ │▓ │📖│▓ │▓ │▓ │💎│  行0: 功能栏
├──┼──┼──┼──┼──┼──┼──┼──┼──┤
│▓ │01│02│03│04│05│06│07│▓ │  行1: 日历
│▓ │08│09│10│11│12│13│14│▓ │  行2
│▓ │15│16│17│18│19│20│21│▓ │  行3
│▓ │22│23│24│25│26│27│28│▓ │  行4
│▓ │29│30│31│  │  │  │  │▓ │  行5
└──┴──┴──┴──┴──┴──┴──┴──┴──┘

🛒 = 月卡商店 (Slot 0)    📖 = 月卡信息 (Slot 4)
💎 = 里程碑 (Slot 8)      ▓  = 黑色边框填充

4 种日期状态

功能按钮

日期格子自定义

每个状态的物品支持以下属性：

可用变量

🛒 月卡商店

27 格 (3行 × 9列) 商店面板，用于购买和查看月卡。

面板布局

┌──┬──┬──┬──┬──┬──┬──┬──┬──┐
│▓ │▓ │▓ │▓ │▓ │▓ │▓ │▓ │▓ │  行0: 边框
├──┼──┼──┼──┼──┼──┼──┼──┼──┤
│▓ │▓ │📄│▓ │▓ │▓ │⭐│▓ │▓ │  行1: 商品
├──┼──┼──┼──┼──┼──┼──┼──┼──┤
│▓ │▓ │▓ │▓ │🔙│▓ │▓ │▓ │▓ │  行2: 功能
└──┴──┴──┴──┴──┴──┴──┴──┴──┘

📄 = 普通月卡 (Slot 11)    ⭐ = 精英月卡 (Slot 15)
🔙 = 返回日历 (Slot 22)    ▓  = 黑色边框填充

商品显示

每个月卡商品自动读取 passes.yml 中的配置：

• 图标 — shop-icon.material + custom-model-data
• 名称 — display-name (支持 MiniMessage)
• 描述 — description 列表
• 价格 — 自动显示价格和货币类型
• 状态 — 已拥有时显示到期日，未拥有时显示「点击购买」

购买流程

1. 点击商品图标
2. 检查是否已拥有该月卡（已拥有则拒绝）
3. 扣除对应货币（Vault 或 PlayerPoints）
4. 给予月卡，播放音效
5. 自动刷新商店界面

🎁 奖励系统

3 层奖励体系

奖励内容

每种奖励包含两部分：

特殊日奖励

以当月第几天为键，覆盖当日的 daily-reward：

special-days:
  7:           # 第7天
    points: 30
    commands:
      - "give %player% diamond 3"
      - "give %player% gold_ingot 5"
  14:          # 第14天
    points: 50
    commands:
      - "give %player% diamond 5"

累计里程碑

当月累计签到达到指定天数时额外触发，每个里程碑仅领取一次：

milestones:
  7:           # 累计7天
    points: 50
    commands:
      - "give %player% emerald 10"
  28:          # 累计28天 (满勤)
    points: 500
    commands:
      - "give %player% elytra 1"

精英月卡继承

设置 includes: "normal" 后，精英月卡签到时自动叠加普通月卡的当日奖励，包括积分和命令。

默认奖励对比

⭐ 积分系统

月卡积分是插件内置的独立积分体系，与 Vault/PlayerPoints 无关。

积分来源

积分管理命令

/mc admin points <玩家> give <数量>   # 给予积分
/mc admin points <玩家> take <数量>   # 扣除积分
/mc admin points <玩家> set <数量>    # 设置积分

积分名称自定义

在 config.yml 中设置：

points-name: "<gradient:#FFD700:#FFA500>月卡积分</gradient>"

PAPI 占位符

积分可通过 %monthcard_points% 在任何支持 PAPI 的地方显示。

⌨️ 命令与权限

主命令

/monthcard (别名: /mc /mcard)

玩家命令

管理命令

权限节点

⚙️ config.yml

完整配置参考

# 数据库设置
database:
  type: sqlite           # sqlite 或 mysql
  mysql:
    host: localhost
    port: 3306
    database: adventuremonthcard
    username: root
    password: ""
    pool-size: 5

# 自动备份
backup:
  enabled: true
  time: "04:00"          # 每天几点备份 (24小时制)
  max-backups: 7         # 最多保留几份

# 签到提醒
reminder:
  on-join: true          # 登录时提醒未签到
  on-join-delay: 60      # 延迟多少ticks后提醒
  scheduled:
    enabled: true        # 定时提醒
    times:
      - "12:00"
      - "20:00"
  type: TITLE            # CHAT / ACTIONBAR / TITLE

# 签到音效
sounds:
  sign-success: "ENTITY_PLAYER_LEVELUP"
  sign-fail: "ENTITY_VILLAGER_NO"
  shop-buy: "BLOCK_NOTE_BLOCK_PLING"
  gui-click: "UI_BUTTON_CLICK"
  gui-open: "BLOCK_CHEST_OPEN"

# 月卡积分名称
points-name: "<gradient:#FFD700:#FFA500>月卡积分</gradient>"

配置项说明

📋 passes.yml

月卡定义结构

passes:
  月卡ID:
    display-name: "显示名称 (MiniMessage)"
    description:
      - "描述行1"
      - "描述行2"
    permission: "monthcard.月卡ID"
    duration-days: 30          # 有效天数
    price: 5000                # 价格
    currency-type: VAULT       # VAULT (银币) 或 PLAYERPOINTS (金币)
    includes: "其他月卡ID"      # 继承 (可选)
    shop-icon:
      material: PAPER          # 商店图标物品
      custom-model-data: 0     # 自定义模型ID
    daily-reward:
      points: 10               # 每日签到积分
      commands:
        - "give %player% diamond 1"
    special-days:
      7:                       # 当月第7天
        points: 30
        commands:
          - "give %player% diamond 3"
    milestones:
      7:                       # 累计签到7天
        points: 50
        commands:
          - "give %player% emerald 10"

字段说明

新增自定义月卡

只需在 passes 下新增一个节点，如 vip：

passes:
  normal: ...
  elite: ...
  vip:                         # 新增 VIP 月卡
    display-name: "<gradient:#FF6B6B:#FF8E53>VIP月卡</gradient>"
    duration-days: 30
    price: 500
    currency-type: PLAYERPOINTS
    includes: "elite"          # 包含精英月卡奖励
    daily-reward:
      points: 50
      commands:
        - "give %player% diamond_block 1"

然后在 gui.yml 的 shop.items 中添加 vip.slot 即可在商店显示。

🎨 gui.yml

日历面板配置

calendar:
  title: "<gradient:#FFD700:#FFA500>✦ 月卡签到 - %month%月 ✦</gradient>"
  size: 54                     # GUI大小: 9/18/27/36/45/54
  day-slots:                   # 7列日期格子布局
    - 10,11,12,13,14,15,16
    - 19,20,21,22,23,24,25
    - 28,29,30,31,32,33,34
    - 37,38,39,40,41,42,43
    - 46,47,48,49,50,51,52
  items:
    available:                 # 今天可签到
      material: SUNFLOWER
      custom-model-data: 0
      name: "<yellow>✦ 第%day%天 - 点击签到!</yellow>"
      lore: [...]
    signed:                    # 已签到
      material: LIME_DYE
    future:                    # 未到日期
      material: GRAY_STAINED_GLASS_PANE
    missed:                    # 已错过
      material: RED_DYE
  buttons:
    info:
      slot: 4
      material: BOOK
    shop:
      slot: 0
      material: GOLD_INGOT
    milestone:
      slot: 8
      material: DIAMOND
    filler:
      material: BLACK_STAINED_GLASS_PANE

商店面板配置

shop:
  title: "<gradient:#FFD700:#FF8C00>✦ 月卡商店 ✦</gradient>"
  size: 27
  items:
    normal:
      slot: 11               # 普通月卡位置
    elite:
      slot: 15               # 精英月卡位置
  back:
    slot: 22
    material: ARROW
    name: "<gray>返回签到日历</gray>"

自定义日期布局

day-slots 定义了每一行的日期 Slot 位置。修改这些数字可以改变日期格子的排列方式。每行 7 个数字对应星期一到星期日。

💬 messages.yml

所有消息支持 MiniMessage 格式标签和 RGB 渐变色。

消息分类

可用变量

前缀自定义

prefix: "<gradient:#FFD700:#FFA500>[月卡]</gradient> "

所有带前缀的消息自动拼接此前缀。

🔗 PlaceholderAPI 占位符

安装 PlaceholderAPI 后自动注册，无需手动下载扩展。

占位符列表

使用场景

• 计分板 — 显示月卡积分、签到天数、连签
• Tab 列表 — 显示月卡类型标识
• 聊天格式 — 显示月卡徽章
• NPC 对话 — 动态显示月卡信息
• 条件判断 — 结合 PAPI 条件变量实现动态逻辑

💰 经济集成

双经济体系

Vault 集成

自动检测 Vault 插件，通过 Economy 服务进行扣款。如果 Vault 不存在，VAULT 类型的月卡将无法购买。

PlayerPoints 集成

通过反射挂钩 PlayerPoints API，无需编译依赖。如果 PlayerPoints 不存在，PLAYERPOINTS 类型的月卡将无法购买。

奖励命令中使用经济

奖励的 commands 可直接调用经济插件命令：

commands:
  - "eco give %player% 500"          # Vault 给银币
  - "points give %player% 100"       # PlayerPoints 给金币

🗄️ 数据库

支持类型

数据表结构

MySQL 配置

database:
  type: mysql
  mysql:
    host: localhost
    port: 3306
    database: adventuremonthcard
    username: root
    password: "your_password"
    pool-size: 5

连接池

使用 HikariCP 高性能连接池 (内置，无需额外安装)。

• 自动重连
• 连接池大小可配置
• 预编译语句缓存

数据缓存

• 玩家上线时异步加载到内存缓存
• 下线时自动保存并移除缓存
• 每 5 分钟自动全量保存 (防止异常丢数据)

💾 自动备份

功能说明

定时将全部数据表导出为 SQL 文件，存储在 plugins/AdventureMonthCard/backUp/ 目录。

配置

backup:
  enabled: true          # 启用自动备份
  time: "04:00"          # 每天凌晨 4 点执行
  max-backups: 7         # 最多保留 7 份

备份文件格式

backUp/
├── backup_2026-05-01_04-00-00.sql
├── backup_2026-05-02_04-00-00.sql
├── ...
└── backup_2026-05-07_04-00-00.sql   # 最新

文件命名: backup_日期_时间.sql，内容为 INSERT 语句。

自动轮替

超过 max-backups 数量后，自动删除最旧的备份文件。

手动备份

/mc admin backup

管理员可随时手动触发备份，异步执行不影响服务器性能。

🌈 颜色与格式

所有配置文件中的文本均支持以下三种颜色格式：

1. MiniMessage 标签

示例: <green>签到成功! <yellow>+10 积分</yellow></green>

2. RGB HEX 颜色

<#FF6B35>橙色文字
<#4ADE80>绿色文字

3. 渐变色

<gradient:#FFD700:#FFA500>金色渐变文字</gradient>
<gradient:#87CEEB:#4682B4>蓝色渐变文字</gradient>

4. 传统颜色码

同时支持 & 颜色码: &a &6 &l 等。

支持颜色的配置位置

• messages.yml — 所有消息文本
• gui.yml — GUI 标题、物品名称、物品描述
• passes.yml — 月卡显示名称、描述
• config.yml — 积分名称

📝 更新日志

v1.0.0 最新

• NEW 月卡体系 — 普通月卡 (Vault) + 精英月卡 (PlayerPoints) 双级体系
• NEW 签到日历 GUI — 54格日历面板，4种日期状态，自定义材质 + CustomModelData
• NEW 月卡商店 GUI — 可视化购买月卡，自动显示价格/状态
• NEW 3层奖励体系 — 每日奖励 / 特殊日奖励 / 累计里程碑，精英包含普通奖励
• NEW 月卡积分 — 独立积分体系，签到累积，管理员可管理
• NEW 连续签到追踪 — 自动记录连签天数，断签重置
• NEW 智能提醒 — 登录提醒 + 定时提醒 (CHAT / TITLE / ACTIONBAR)
• NEW 双经济集成 — Vault (银币) + PlayerPoints (金币) 反射挂钩
• NEW 数据存储 — SQLite / MySQL + HikariCP 连接池
• NEW 自动备份 — 定时 SQL 全量导出 + 自动轮替
• NEW PAPI 变量 — 10 个占位符 (积分/连签/月卡状态/到期日等)
• NEW MiniMessage + RGB — 渐变色 / HEX / 标签全支持
• NEW 完全可配置 — 4个 YAML 配置文件 (config/passes/gui/messages)
• NEW 命令系统 — 玩家命令 + 管理命令 + Tab 补全