Skip to content
BranchesTags

Repository files navigation

Lapis-AFKPool

Platform MC Java License

⚠️ 警告

需要 Java 17+，服务端请使用 Spigot/Paper/Folia 1.20.1 或更高版本。 金币/点券奖励为可选钩子：金币需 Vault，点券需 PlayerPoints，占位符需 PlaceholderAPI。

Lapis-AFKPool

高性能、模块化的 Minecraft 挂机池插件 —— 让玩家在划定的区域内挂机，自动获得经验、金币、点券与物品奖励。

支持 Bukkit / Paper / Folia，兼容 Minecraft 1.20.1 - 1.26.2，内置完整的视觉反馈、统计系统、每日上限与审计日志，全程异步存储，任务级性能优化。

为什么选择 Lapis-AFKPool？

Lapis-AFKPool 专为"挂机得奖励"玩法设计，对比同类插件提供：更快的检测、更灵活的奖励、更丰富的展示、更完整的生态联动。

  • O(1) 区域检测 —— 按世界建立区域索引 + 窗口预筛，不再逐帧遍历所有水池。检测/奖励逻辑全部在主线程之外做纯计算，千人服不卡服。
  • 真正的模块化架构 —— 平台（Folia/Bukkit）、存储、奖励、界面、钩子等全部解耦，便于维护与二次开发。
  • 四类奖励 —— 经验、金币（Vault）、点券（PlayerPoints）、命令（物品/权限等），均支持固定值或随机区间、独立结算间隔、概率、倍率与每日上限。
  • 两档每日上限 —— 每个池 + 全局限于一身，可用命令按玩家单独覆盖，跨天按配置时区自动清零。
  • MiniMessage 全套消息 —— 中文/英文双语，所有文本（含物品名、Title、ActionBar、BossBar）支持 <gradient>、<bold>、<#RRGGBB> 等 MiniMessage 标签与 & 颜色码。
  • 多端兼容 —— Folia 线程安全调度，Paper 原生 Adventure API，Spigot 自动降级，一条 jar 通吃。

即使你从其他挂机池插件迁移，也能轻松上手：

  • 环境要求较严格：运行需要 Java 17 及以上。 服务器端请使用 Paper/Spigot/Folia 1.20.1 或更高版本。
  • 金币与点券奖励依赖可选钩子。 使用金币请安装 Vault 及任意经济插件；使用点券请安装 PlayerPoints；使用 PAPI 占位符请安装 PlaceholderAPI。

功能特性

  • 选区工具（金斧）一键圈选并创建挂机池，一个插件同时支持任意数量水池
  • 玩家进出检测：进入/离开 Title 提示、音效、发光高亮（Glow）
  • ActionBar 状态条与 BossBar 奖励倒计时，可自由定制文案
  • 粒子特效（温泉/泡泉效果），粒子不可用时自动回退
  • 奖励汇总提示与细分提示
  • 每日上限：池级 + 全局双上限，玩家级覆盖，按 HH:mm + 时区自动重置
  • 传送拦截（可选）：阻止直接传送进池，权限可绕过
  • 统计查询 /afkp stats：今日/历史经验、金币、点券、挂机时长（玩家级、池级）
  • 存储：YAML（轻量易迁移） / SQLite（单文件数据库），脏标记异步批量落盘
  • 审计日志 audit.log：记录所有管理操作
  • PlaceholderAPI 扩展：%afkpoolplus_% 全量占位符
  • 开发者 API：进出/奖励全套事件与 AFKPoolPlusAPI 访问入口
  • 自动化：缺失配置自动补全、/afkp reload 热重载

功能特性一览（奖励机制）

维度 说明
奖励类型 经验 / 金币(Vault) / 点券(PlayerPoints) / 命令组
取值模式 fixed 固定值 / random 区间随机（min~max）
结算间隔 每类奖励独立 interval（秒），互不干扰
概率 命令奖励支持 chance（0-100）
经验倍率 池级 rate（经验/金币/点券各自独立）
每日上限 池级 daily-max + 全局 limits.*，玩家级覆盖，跨天清零
权限收入 afkpoolplus.reward.xp/money/points/commands 分权限控制

环境要求

  • Java 17 或更高版本（推荐使用服务器软件支持的较新版本）
  • Spigot / Paper / Folia 1.20.1+（1.20.1 - 1.26.2 全版本兼容）
  • 可选前置：Vault、PlayerPoints、PlaceholderAPI
  • 本项目无任何硬性前置，不装可选依赖也能获得经验/命令奖励及全部展示效果

安装

  1. 将 Lapis-AFKPool-1.0.0.jar 放入服务器的 plugins/ 目录。
  2. 重启服务器（或使用 /reload，推荐重启）。
  3. 首次启动会自动生成 plugins/Lapis-AFKPool/ 下的配置与消息文件。
  4. 参照下方「快速开始」创建第一个挂机池。

快速开始

/afkp wand            # 获取选区工具（金斧）
# 左键点击第一个角，右键点击对角第二个角
/afkp create 经验池    # 用选区创建挂机池（默认世界=你所在世界）
/afkp list            # 查看所有挂机池
/afkp info 经验池      # 查看池详情
/afkp toggle 经验池    # 启用/禁用
/afkp reload          # 修改配置后热重载

命令

主命令：/afkp（别名 /afkpool、/afkpoolplus），所有命令均带 Tab 补全。

命令 权限 说明
/afkp help [页数] afkpoolplus.use 查看帮助
/afkp wand / /afkp tool afkpoolplus.tool 获取选区工具
/afkp pos1 / /afkp pos2 afkpoolplus.tool 用脚下位置设置选区点
/afkp create <名称> afkpoolplus.admin 用当前选区创建挂机池
/afkp setregion <池> afkpoolplus.admin 用当前选区覆盖池区域
/afkp delete <池> afkpoolplus.admin 删除挂机池
/afkp list [页数] afkpoolplus.use 列出所有挂机池
/afkp info <池> afkpoolplus.use 查看池详情与奖励
/afkp tp <池> afkpoolplus.admin 传送到池中心
/afkp toggle <池> afkpoolplus.admin 启用/禁用池
/afkp set <池> <属性> <值> afkpoolplus.admin 修改池属性（见下表）
/afkp addcmd <池> <命令> afkpoolplus.admin 添加一条命令奖励
/afkp delcmd <池> <序号> afkpoolplus.admin 删除指定序号命令奖励
/afkp rewards afkpoolplus.use 查看今日已获得奖励
/afkp stats [玩家] afkpoolplus.stats 查看玩家统计
/afkp stats pool <池> afkpoolplus.stats 查看池级统计
/afkp limit set <玩家> <上限> afkpoolplus.limit 覆盖玩家单日奖励次数上限
/afkp limit remove <玩家> afkpoolplus.limit 移除玩家上限覆盖
/afkp limit check <玩家> afkpoolplus.limit 查询玩家上限状态
/afkp reset <玩家> afkpoolplus.admin 重置玩家全部数据
/afkp reload afkpoolplus.reload 热重载全部配置
`/afkp debug [on off]` afkpoolplus.debug
/afkp perf afkpoolplus.admin 查看性能概览与已加载池数

/afkp set 可修改的属性

display-name、world、required-time、permission、join-without-permission、teleport-block、glow-enabled、glow-color、reward-xp-enabled、reward-xp-mode、reward-xp-fixed、reward-xp-min、reward-xp-max、reward-xp-interval、reward-xp-daily-max、reward-xp-rate，以及对应的 reward-money-*、reward-points-*。

teleport-block 可设为 true / false / bypass（仅拦截无 afkpoolplus.bypass.teleport 权限的玩家）。

权限

权限节点 默认 说明
afkpoolplus.admin op 管理员总权限（自动包含 tool/reload/debug/stats/limit/bypass.enter）
afkpoolplus.use 所有玩家 使用基本功能（help/list/info/rewards）
afkpoolplus.tool op 使用选区工具与选区命令
afkpoolplus.reload op 热重载
afkpoolplus.debug op 调试模式
afkpoolplus.stats op 查看统计
afkpoolplus.limit op 管理玩家奖励上限
afkpoolplus.reward.xp 所有玩家 获得经验奖励
afkpoolplus.reward.money 所有玩家 获得金币奖励
afkpoolplus.reward.points 所有玩家 获得点券奖励
afkpoolplus.reward.commands 所有玩家 获得命令奖励
afkpoolplus.bypass.enter op 绕过池进入权限进入任何池
afkpoolplus.bypass.teleport op 绕过传送拦截

池级进入权限示例：afkpoolplus.pool.vip（在 pools.yml 的 permission 字段配置）。

占位符

YAML 占位符（pools.yml 文本中使用）

{player} {pool} {pool_display} {world} {online} {xp_today} {xp_max} {money_today} {money_max} {points_today} {points_max} {countdown}

PlaceholderAPI 占位符（标识符：afkpoolplus）

占位符 说明
%afkpoolplus_afk% 玩家是否在池内（yes / no）
%afkpoolplus_current% 玩家当前所在池 ID（不在池内为空）
%afkpoolplus_countdown% 距下次奖励的秒数（最近的一类奖励）
%afkpoolplus_online% 玩家所在池当前在线人数
%afkpoolplus_today_xp% / %afkpoolplus_today_money% / %afkpoolplus_today_points% 今日累计奖励
%afkpoolplus_total_time% / %afkpoolplus_total_xp% / %afkpoolplus_total_money% / %afkpoolplus_total_points% 历史累计
%afkpoolplus_pool_<池id>_online% 指定池在线人数
%afkpoolplus_pool_<池id>_name% 指定池显示名称
%afkpoolplus_pool_<池id>_enabled% 指定池是否启用
%afkpoolplus_pool_<池id>_world% 指定池所在世界
%afkpoolplus_pool_<池id>_xp-interval% / _xp-max% 指定池经验间隔/单日上限
%afkpoolplus_pool_<池id>_money-interval% / _money-max% 指定池金币间隔/单日上限
%afkpoolplus_pool_<池id>_points-interval% / _points-max% 指定池点券间隔/单日上限
%afkpoolplus_pool_count% 挂机池总数（无玩家上下文）

配置

配置文件位于 plugins/Lapis-AFKPool/，编辑后执行 /afkp reload 热重载（storage.type 修改后需重启）。

config.yml（核心）

节点 说明
core.language 语言：zh_CN / en_US，决定初始 messages.yml
core.check-interval-ticks 玩家位置扫描间隔（tick，默认 20=1 秒）
core.reward-tick-interval 奖励结算节拍（tick）
core.audit-log 管理操作写入 audit.log
storage.type yaml / sqlite（sqlite 为单文件数据库 afkpoolplus.db）
storage.save-interval-seconds 数据异步批量落盘间隔（秒）
limits.daily-reward-count 全局单日奖励次数上限（0=不限）
limits.daily-xp / daily-money / daily-points 全局单日各奖励总量上限（0=不限）
reset.time + reset.timezone 每日重置时刻与时区（默认 00:00 + Asia/Shanghai）
selection.max-distance 选区最大边长（防误选，0=不限）
selection.tool 选区工具材质/名称/Lore（支持 MiniMessage）
display.actionbar-update-ticks / bossbar-update-ticks ActionBar/BossBar 刷新间隔

pools.yml（挂机池）

推荐用命令创建（见快速开始），也可手写。结构与关键字段：

pools:
  经验池:
    display-name: "<gold><bold>经验挂机池</bold></gold>"
    world: world
    pos1: { x: 0, y: 64, z: 0 }
    pos2: { x: 10, y: 74, z: 10 }
    enabled: true
    required-time: 0            # 进入后需挂机秒数才开始发放
    permission: ""              # 进入权限（留空=所有玩家）
    join-without-permission: true
    teleport-block: false       # 拦截传送到池内（可 bypass）
    glow: { enabled: true, color: YELLOW }
    ui:
      actionbar: true
      actionbar-template: "<aqua>{pool_display} <dark_gray>| <green>经验 {xp_today}/{xp_max}"
      bossbar: { enabled: false, color: GREEN, style: SEGMENTED_10,
                 template: "<aqua>{pool_display} <dark_gray>| <green>下次奖励 {countdown}s" }
      enter: { title: ..., subtitle: ..., fade-in: 10, stay: 40, fade-out: 10 }
      leave: { title: ..., subtitle: ... }
      sounds:
        enter: { id: ENTITY_PLAYER_LEVELUP, volume: 1.0, pitch: 1.2 }
    effects:
      - { enabled: true, particle: CLOUD, rate: 10, count: 1,
          offset-x: 1.0, offset-y: 1.0, offset-z: 1.0 }
    reward:
      message: "<green>挂机奖励：<white>经验 +{exp} <dark_gray>| <gold>金币 +{money} <dark_gray>| <light_purple>点券 +{points}"
      xp: { enabled: true, mode: fixed, fixed: 10, min: 5, max: 20,
            interval: 60, daily-max: 0, rate: 1.0 }
      money: { enabled: false, mode: fixed, fixed: 5, min: 1, max: 10,
               interval: 60, daily-max: 0, rate: 1.0 }
      points: { enabled: false, mode: fixed, fixed: 2, min: 1, max: 5,
                interval: 60, daily-max: 0, rate: 1.0 }
      commands:
        - { command: "give {player} diamond 1", interval: 300, chance: 100 }

常见问题 (FAQ)

金币/点券奖励不生效？ 请确认安装了 Vault（金币）或 PlayerPoints（点券），且对应 enabled 为 true。

消息显示红色 {key} 或没生效？ 消息文件版本与插件不一致。删除 plugins/Lapis-AFKPool/messages.yml 后 /afkp reload 重新生成即可。

粒子特效没有或报错？ 服务器版本不支持该粒子时自动回退 CLOUD；也可在 effects 中自行增删/关闭。

玩家被"传送拦截"挡住？ 该池开启了 teleport-block。授给玩家 afkpoolplus.bypass.teleport 权限，或将 teleport-block 设为 bypass。

想换 SQLite？ 将 storage.type 改为 sqlite 后重启服务器，数据文件为 afkpoolplus.db。

在您的插件中使用 Lapis-AFKPool

插件在 Bukkit 事件总线 上派发全套事件，监听即可完成联动：

事件 触发时机 可读字段
PlayerEnterPoolEvent 玩家进入池 getPlayer() getPool()
PlayerLeavePoolEvent 玩家离开池（含退出游戏） getPlayer() getPool()
PlayerRewardEvent 玩家获得一次奖励（任意类型结算时均触发） getPlayer() getPool() getExp() getMoney() getPoints() isCommand()

另提供 API 入口 AFKPoolPlusAPI，通过 AFKPoolPlus#getAPI() 获取（实例方法，非静态）：getPool(id)、getPools()、getPoolAt(Location)、getPlayerPool(player)、getOnlineInPool(id)、getStats(uuid)、fireReward(...)。getPoolModule() / getPlayerTracker() / getStorageModule() 等模块均通过 AFKPoolPlus 单例暴露。

构建

需要 JDK 17 与 Gradle 9.5+：

gradle build

产物输出于 build/libs/Lapis-AFKPool-1.0.0.jar。构建过程会自动 shade Adventure（MiniMessage）与 SQLite 驱动，无需额外依赖。

支持与贡献

  • 使用遇到问题，可在配置中开启 core.debug 后复现，并将 日志片段 + pools.yml + 操作步骤 一并反馈。
  • 欢迎提交 Bug 反馈与功能建议（Pull Request / Issue）。
  • 若本插件的功能对您有帮助，欢迎为项目点赞支持。

About

高性能模块化挂机池插件：选区圈定、经验/金币/点券/命令四类奖励、每日上限、审计日志，Bukkit/Paper/Folia（Java）

Resources

Readme
MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages