📥 安装与目录

环境要求

依赖插件

安装步骤

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

目录结构

plugins/AdventureSignIn/
├── config.yml          # 核心配置 (时区/补签/存储/Redis)
├── messages.yml        # 消息文本 (MiniMessage 格式)
├── gui-settings.yml    # 日历面板外观 (头颅/按钮/布局)
├── rewards.yml         # 奖励配置 (权限组/7种奖励类型)
└── data/
    └── adventuresignin.db  # SQLite 数据库

📅 日历面板

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
└──┴──┴──┴──┴──┴──┴──┴──┴──┘

← = 上月翻页    👤 = 玩家档案    → = 下月翻页
☰ = 返回菜单    ▓ = 琥珀边框      ✕ = 关闭

5 种日期状态

功能组件

头颅材质

每种状态使用独立的 Base64 材质，可从 minecraft-heads.com 获取并替换。

calendar:
  checked:
    item: PLAYER_HEAD
    skull-value: 'eyJ0ZXh0dXJl...'   # Base64 材质
    title: "<#4ADE80>✓ <white>%day%日 <#4ADE80>已打卡"
    glow: false                       # 附魔发光
    auto-close: false                 # 点击后关闭面板

历史月份浏览

• 点击 ◄ 上月 / 下月 ► 翻页
• 命令跳转: /signin gui 3 2026 直接查看 2026年3月
• 历史月份标题自动切换为 ❖ 历史签到 — 3月 格式

🎁 奖励系统

7 种奖励类型

另有 special-weeks (特殊星期) 奖励，1=周一 ~ 7=周日。

奖励内容 (5 种)

命令前缀

override-default-rewards 机制

里程碑/周期/特殊奖励设置 override-default-rewards: true 时，该次签到不发放基础 normal 奖励，仅发放该特殊奖励。用于"大奖替换小奖"场景。

奖励执行顺序

可在 reward-task-sequence 中自定义执行顺序：

reward-task-sequence:
  - ITEMS_REWARD             # 1. 给予物品
  - COMMANDS_EXECUTION       # 2. 执行命令
  - MESSAGES_SENDING         # 3. 发送消息
  - BROADCAST_MESSAGES_SENDING  # 4. 广播消息
  - PLAY_SOUNDS              # 5. 播放音效

🔄 补签系统

4 种补签模式

补签限制

• 每月次数上限: max-per-month: 3 (默认每月 3 次)
• 最远回溯天数: max-days-ago: 30 (最多补 30 天前)
• 不能补签未来日期
• 不能重复补签同一天

补签卡系统

补签卡管理命令

/signin card give <玩家> <数量>   # 给予补签卡
/signin card take <玩家> <数量>   # 扣除补签卡
/signin card set <玩家> <数量>    # 设置补签卡数量

补签奖励控制

补签时可通过 disabled-modules 禁止某些奖励模块触发：

retroactive:
  disabled-modules:
    special-dates: true       # 禁止补签获取特殊日期奖励
    special-weeks: true       # 禁止补签获取特殊星期奖励
    statistics-times: false   # 允许补签触发累计里程碑
    statistics-times-cycle: false

补签与连签

补签成功后会自动重新计算连续签到天数。如果补签的日期恰好填补了断链，连签天数会自动连通。

👥 权限组

通过权限节点实现 VIP 与普通玩家不同的签到奖励。

优先级匹配

groups-priority 从上到下匹配，第一个满足权限的组生效。

groups-priority:
  - VIP        # 优先匹配
  - Default    # 兜底

组配置示例

permission-groups:
  Default:
    # 无 permission 字段 = 所有人匹配
    normal:
      commands:
        - "console:eco give %player% 100"
      items:
        - "diamond:1"
    streak-milestones:
      7:
        commands:
          - "console:eco give %player% 700"
        items:
          - "diamond_sword:1"

  VIP:
    permission: "adventuresignin.group.vip"
    normal:
      commands:
        - "console:eco give %player% 200"
      items:
        - "diamond:2"

每个组支持的奖励模块

• normal — 基础签到
• retroactive — 补签奖励 + disabled-modules
• streak-milestones — 连签里程碑
• streak-cycle — 连签周期
• total-milestones — 累计里程碑
• total-cycle — 累计周期
• special-dates — 特殊日期 (MM-dd)
• special-weeks — 特殊星期 (1=周一 ~ 7=周日)

⌨️ 命令与权限

玩家命令

管理命令

权限节点

⚙️ 配置文件 (config.yml)

完整配置参考

# 时区 (用于判断"今天"是哪天)
timezone: "Asia/Shanghai"

# 自动签到: 玩家上线时自动签到
auto-sign-on-join: false

# 签到冷却提示 (已签到的玩家再次点击签到时)
show-already-signed-message: true

# 补签设置
makeup:
  enabled: true
  mode: CARD           # CARD / VAULT / ITEM / FREE
  max-per-month: 3     # 每月补签上限
  card-cost: 1         # CARD 模式消耗
  cost:
    type: VAULT        # VAULT / ITEM
    amount: 500        # 金额或物品数量
    item: DIAMOND      # ITEM 模式物品
  max-days-ago: 30     # 最远回溯天数

# 补签卡设置
retroactive-card:
  initial-amount: 3    # 新玩家初始卡
  daily-earn: 0        # 每日签到获卡

# 数据存储
storage:
  type: sqlite         # sqlite / mysql
  mysql:
    host: localhost
    port: 3306
    database: minecraft
    username: root
    password: ""
    table-prefix: "asignin_"
  redis:
    enabled: false
    host: localhost
    port: 6379
    password: ""
    channel: "adventuresignin:sync"

messages.yml

所有消息支持 MiniMessage 格式 (<green>, <gradient:#FF6B35:#FFB347>, <hover:show_text:'...'>)。

可用变量: %player% %streak% %total% %cards% %date%

🎨 面板配置 (gui-settings.yml)

面板标题

# 当月标题
title: "<gradient:#FF6B35:#FFB347><bold>✦ 签到日历</bold></gradient> — %date%"
# 历史月标题
title-history: "<gradient:#5B86E5:#36D1DC><bold>❖ 历史签到</bold></gradient> — %view_month%月"
# 跨年标题
title-history-year: "...— %view_year%年%view_month%月"
# 日期格式
date-format: "yyyy年MM月dd日"

日历状态配置

每种状态支持以下属性：

可用变量

功能组件 (widgets)

组件支持 slot (单槽) 或 slots (多槽) 定位，以及 head-owner 渲染玩家头颅。

widgets:
  profile:
    item: PLAYER_HEAD
    head-owner: "%player%"       # 使用玩家头颅
    title: "...我的签到..."
    slot: 3                      # 单槽位
  filler:
    item: ORANGE_STAINED_GLASS_PANE
    title: " "
    slots: [1, 2, 4, 5, 7, ...]  # 多槽位填充

📝 奖励配置 (rewards.yml)

完整示例

permission-groups:
  Default:
    normal:
      messages:
        - "<prefix><green>签到成功！获得每日奖励。"
      commands:
        - "console:eco give %player% 100"
      items:
        - "diamond:1"
        - "gold_ingot:3-5"        # 随机 3~5 个
      sounds:
        - "ENTITY_EXPERIENCE_ORB_PICKUP-1-1-false"

    streak-milestones:
      3:
        override-default-rewards: true
        messages:
          - "<prefix><gold>✦ 连签 3 天！奖励翻倍！"
        broadcast-messages:
          - "<prefix>%player% 连签了 3 天！"
        commands:
          - "console:eco give %player% 300"
      7:
        commands:
          - "console:eco give %player% 700"
        items:
          - "diamond_sword:1"
      30:
        commands:
          - "console:eco give %player% 5000"
        items:
          - "diamond_block:1"

    streak-cycle:
      3:              # 每连续 3 天触发
        items:
          - "golden_apple:1"

    total-milestones:
      10:
        commands:
          - "console:eco give %player% 1000"
      100:
        commands:
          - "console:eco give %player% 10000"

    total-cycle:
      50:             # 每累计 50 天触发
        commands:
          - "console:eco give %player% 5000"

    special-dates:
      '01-01':        # 元旦
        items:
          - "golden_apple:3"
      '12-25':        # 圣诞
        items:
          - "apple:64"

    special-weeks:
      6:              # 周六
        items:
          - "golden_apple:1"
      7:              # 周日
        items:
          - "golden_apple:1"

物品格式

# 固定数量
- "diamond:1"

# 随机数量 (min-max)
- "gold_ingot:3-5"    # 随机 3~5 个

音效格式

# 格式: 音效名-音量-音调-是否广播
- "ENTITY_PLAYER_LEVELUP-1-0-true"    # 全服可听
- "ENTITY_EXPERIENCE_ORB_PICKUP-1-1-false"  # 仅自己

🔗 PlaceholderAPI 占位符

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

占位符列表

使用场景

• 计分板 — 显示连签天数、今日签到状态
• Tab 列表 — 显示 VIP 签到组名
• 聊天格式 — 显示签到徽章
• NPC 对话 — 动态显示签到信息

🌐 Redis 跨服部署

前提

• Velocity / BungeeCord 代理群组
• Redis 实例
• 所有子服连同一个 MySQL（SQLite 不支持跨服）

数据流

配置

storage:
  type: mysql
  mysql:
    host: 127.0.0.1
    port: 3306
    database: adventure_signin
    username: root
    password: "your_password"
    table-prefix: "asignin_"
  redis:
    enabled: true
    host: "127.0.0.1"
    port: 6379
    password: ""
    channel: "adventuresignin:sync"

Pub/Sub

• 频道：adventuresignin:sync
• 消息：UUID:action (如 reload)
• 收到消息后自动刷新该玩家的本地缓存

部署步骤

1. 安装 Redis
2. 每个子服配置同一 MySQL 数据库
3. 设置 redis.enabled: true
4. 重启所有子服
5. 在不同服签到验证数据同步

📝 更新日志

v1.1.0 最新

• NEW GUI 引擎重构 — 7列居中布局、琥珀色边框、渐变标题
• NEW 配置结构优化 — 日历区 (calendar) / 组件区 (widgets) 分离
• NEW 5 种日期状态 — checked/pending/upcoming/skipped/recovered 独立配置
• NEW MiniMessage 全面支持 — 标题/名称/描述/消息均支持渐变色和HEX
• FIX 连签计算修复 — 补签后连签天数正确重算并更新 lastSignDate
• FIX 补签卡存储修复 — 修复每日获卡与数据持久化的时序竞态问题
• FIX 依赖瘦身 — 移除未使用的 triumph-gui，JAR 体积减小

v1.0.0

• NEW 核心签到系统 — 每日签到 + 连签 + 累计统计
• NEW 7 种奖励类型 — 里程碑/周期/特殊日期/星期/基础/补签
• NEW 权限组系统 — 优先级匹配，VIP 差异化奖励
• NEW 补签卡系统 — 4 种模式 (CARD/VAULT/ITEM/FREE)
• NEW 54 格日历面板 — 自定义头颅材质 + 5 种状态
• NEW 物品奖励 — 支持随机数量范围
• NEW 数据存储 — SQLite / MySQL + HikariCP
• NEW Redis 跨服 — Pub/Sub 实时同步
• NEW PAPI 变量 — 7 个占位符