zMClans
适用于 Paper / Purpur 1.20+ 的宗族系统
高性能 · 完全可配置 · 毫无妥协
现代、轻量且完全可定制的宗族插件。
无需强制依赖,不阻塞主线程,无限制。
为什么选择 zMClans?
你将获得
- 真正的性能 —— 默认异步处理
- 带渐变的 Modtag —— MiniMessage + Hex 颜色
- 每个宗族多个出生点 —— 支持预热和冷却时间
- 联盟与敌对关系 —— 支持按等级设置上限
- 等级系统 —— 积分、击杀数、KDR(击杀死亡比)
- SQLite 和 MySQL 数据库 —— 集成 HikariCP 连接池
- 公共 API —— 提供事件接口和 Java Facade
- 100% YAML 图形界面 —— 类似 DeluxeMenus 的风格
|
你将避免的问题
- 强制性的插件依赖
- 同步保存导致的卡顿
- 使用过时 API 发送聊天消息
- 标签中的点击/悬停注入攻击
- 晦涩难懂的配置文件
- 缺乏面向开发者的 API
- 硬编码的图形界面
- 重复邀请导致的 Bug
|
功能特性
完整的宗族管理
- 创建时支持设置标签及可选的 Modtag
- 邀请功能支持异步过期处理
- 接受、拒绝或取消邀请
- 自愿退出(保护领导者不被踢出)
- 按权限等级层级式踢人
- 安全确认解散宗族
- 公开加入 —— 通过
/clan join <clan> 加入开放宗族
命名出生点系统
- 每个宗族拥有多个出生点(数量上限随等级可扩展)
- 可配置的预热时间,支持实时取消(忽略视角旋转)
- 冷却时间机制,可通过权限绕过 (
zmclans.clan.bypass.cooldown)
- 基于设置与盟友共享可见性
- 专用图形界面 + 直接指令访问
home:
max-homes: 3
teleport-cooldown: 30
teleport-warmup: 5
cancel-on-move: true
支持渐变和 Hex 颜色的 ModTag
原生支持 Adventure MiniMessage:
<bold><gradient:#9A23FF:#7C09DE:#9A23FF>ZEPHY</gradient></bold>
传统 Hex 颜色支持:
	A23FF&lZB16EF&lEC09DE&lPB16EF&lH	A23FF&lY
绝对安全 —— 拦截 click、hover 及命令注入。仅允许视觉样式。
联盟、敌对关系与友军伤害
- 可配置有效期的互惠请求
- 按等级设定的盟友/对手上限
- 盟友间的交互:
- 成员友军伤害设置:
- 可通过
/clan ff 或图形界面切换
私人氏族聊天
- 集成 Paper 的现代 API (
AsyncChatEvent) —— 无弃用警告
- 切换模式 (
/clan chat) 或直接发送 (/clan chat <msg>)
- 可配置格式,包含标签、阶级和前缀
format: "{tag} &7| {rank_prefix}{player} &8» &f{message}"
积分、等级与排名
可配置以下行为的积分获取:
自定义公式:
progression:
base-points: 100
exponent: 1.5
start-level: 1
max-level: 50
level-limits:
1:
members: 10
homes: 1
allies: 2
rivals: 3
10:
members: 30
homes: 5
allies: 8
rivals: 10
支持筛选的分页排行榜:
- 成员
- 积分
- 击杀数
- 死亡数
- 击杀死亡比 (KDR)
通知系统
每个事件均可独立控制以下选项:
- 标题 / 副标题(含淡入/淡出效果)
- Action Bar
- 音效(音量和音调)
包含的事件:
| 类别 |
事件 |
| 进度 |
clan-points-earned, clan-levelup, clan-create, clan-disband |
| 成员 |
member-promote, member-demote, member-kick, member-join, member-leave, member-joined, member-left, member-kicked, transfer-leader |
| 邀请 |
invite-sent, invite-received, invite-accepted |
| 家园 / 联盟 |
home-teleport, home-set, ally-accepted |
100% 可配置 GUI(YAML)
数据驱动架构 —— 无需编写 Java 代码即可自定义。
| 文件 |
描述 |
general.yml |
启动和主菜单 |
members.yml |
分页成员列表 |
member_manage.yml |
单个成员管理 |
clanlist.yml |
排名和氏族浏览器 |
invite.yml |
一键邀请 |
invites.yml |
收到的邀请 |
settings.yml |
设置面板 |
clan_info.yml |
信息 + 统计 |
homes.yml |
家园管理 |
confirm.yml |
关键操作确认 |
支持的操作:
- CLOSE
- CANCEL
- PAGE_NEXT / PAGE_PREV
- OPEN_GUI:<name>
- CREATE_CLAN
- SHOW_HELP
- TOGGLE_CHAT
- CLAN_HOME_OR_SETHOME
- TOGGLE_SETTING:<key>
- MEMBER_PROMOTE / MEMBER_DEMOTE / MEMBER_KICK / MEMBER_TRANSFER_LEADER
- CMD_PLAYER:<cmd>
- CMD_CONSOLE:<cmd>
强大的存储支持(SQLite / MySQL)
- HikariCP 实现高效连接池
- 定期异步保存
- 单线程写入以保留操作顺序
- 增量迁移(无数据丢失)
- 关闭前执行最终保存
storage:
type: "MYSQL" # or SQLITE
auto-save-interval: 5
mysql:
host: "localhost"
port: 3306
database: "zmclans"
pool-size: 10
useSSL: false
公共 API 与 Bukkit 事件
Plugin candidate = Bukkit.getPluginManager().getPlugin("zMClans");
if (candidate instanceof zMClans clans && clans.isEnabled()) {
ZMClansAPI api = clans.getAPI();
api.getClanByPlayer(player.getUniqueId()).ifPresent(clan ->
player.sendMessage(clan.name() + " | level " + clan.level() + " | KDR " + clan.kdr()));
}
可用事件:
ClanCreatedEvent
ClanMemberJoinEvent
ClanMemberLeaveEvent
ClanPointsChangeEvent
ClanLevelChangeEvent
所有调用必须在主线程上执行。
命令
玩家(/clan, /c, /clans)
查看完整的玩家命令表
| 命令 |
描述 |
/clan |
打开主交互菜单 |
/clan create <name> [tag] |
创建氏族 |
/clan info [clan] |
氏族信息 |
/clan list |
排行榜菜单 |
/clan invite <player> |
邀请玩家 |
/clan invites |
邀请 GUI |
/clan accept [clan] |
接受邀请 |
/clan deny [clan] |
拒绝邀请 |
/clan join <clan> |
加入公开氏族 |
/clan members |
成员 GUI |
/clan setrank <player> <rank> |
分配职位 |
/clan kick <player> |
踢出成员 |
/clan leave |
离开氏族 |
/clan disband [confirm] |
解散氏族 |
/clan home [name] |
GUI 或传送 |
/clan homes |
出生点 GUI |
/clan sethome [name] |
创建/更新出生点 |
/clan delhome <name> |
删除出生点 |
/clan chat [message] |
氏族聊天 |
/clan ff |
切换友军伤害 |
/clan desc <text> |
更改描述 |
/clan modtag <tag> |
使用格式修改标签 |
/clan settings |
设置 GUI |
/clan ally add|accept|deny|cancel|remove <clan> |
管理联盟 |
/clan rival add|remove <clan> |
管理敌对关系 |
/clan relation remove <clan> |
移除关系 |
/clan stats |
综合氏族信息 |
/clan help |
帮助 |
管理员(/zmclan, /zmclans, /clanadmin)
| 命令 |
描述 |
权限 |
/zmclan help |
列出管理员命令 |
zmclans.admin.help |
/zmclan reload |
重新加载配置 |
zmclans.admin.reload |
/zmclan list [page] |
列出氏族 |
zmclans.admin.list |
/zmclan members <clan> |
查看成员 |
zmclans.admin.members |
/zmclan info <clan> |
氏族详情 |
zmclans.admin.info |
/zmclan disband <clan> |
行政解散 |
zmclans.admin.disband |
/zmclan setleader <clan> <player> |
转移领导权 |
zmclans.admin.setleader |
/zmclan points <add|set|remove> <clan> <n> |
调整积分 |
zmclans.admin.points |
特殊权限
| 权限 |
描述 |
zmclans.clan.bypass.cooldown |
绕过出生点传送冷却 |
zmclans.clan.bypass.cost |
绕过氏族创建费用 |
默认情况下,所有 zmclan.player.* 节点均被拒绝。请单独授予它们或使用 zmclan.player 作为父节点。
默认职位 (ranks.yml)
| 职位 |
优先级 |
权限 |
member |
1 |
USE_HOME, USE_CHAT |
officer |
2 |
+ INVITE |
admin |
3 |
+ KICK, PROMOTE, SET_HOME, EDIT_DESCRIPTION, MODTAG |
leader |
4 |
全部(受保护职位 is-leader: true) |
查看完整的职位权限列表
USE_HOME — 使用 /clan home
USE_CHAT — 氏族聊天
INVITE — 邀请玩家
KICK — 踢出低职位成员
PROMOTE — 更改低职位成员的职位
SET_HOME — 修改氏族出生点
EDIT_DESCRIPTION — 编辑描述
EDIT_SETTINGS — 管理设置(联盟、共享出生点、友军伤害...)
TRANSFER_LEADER — 转移领导权
DISBAND — 解散氏族
MODTAG — 使用颜色修改标签
占位符 (PlaceholderAPI)
查看完整的占位符列表
识别
%zmclans_hasclan% · %zmclans_hasclan_formated% · %zmclans_hasclan_formated_nocolor% · %zmclans_clan% · %zmclans_name% · %zmclans_clanid%
标签
%zmclans_modtag% · %zmclans_tag% · %zmclans_tag_formated% · %zmclans_tag_nocolor%
成员
%zmclans_leader% · %zmclans_is_leader% · %zmclans_members% · %zmclans_onlinemembers% · %zmclans_slots%
排名(前几名)
%zmclans_points% · %zmclans_top% · %zmclans_top:<N>% · %zmclans_top_points:<N>% · %zmclans_top_kdr:<N>%
状态
%zmclans_is_ff% · %zmclans_isopen% · %zmclans_chat_active%
出生点与日期
%zmclans_hashome% · %zmclans_home% · %zmclans_creation_date%
玩家统计
%zmclans_player_role% · %zmclans_player_kills% · %zmclans_player_kdr%
关系
%rel_zmclans_relation_relboolean_member% · %rel_zmclans_relation_relcolor% · %rel_zmclans_relation_reltype%
安装
# 1. 下载 zMClans-1.0.0.jar
# 2. 将其放入 /plugins/ 目录
# 3. 重启服务器
# 4. 配置 config.yml, ranks.yml, guis/, langs/
# 5. 应用更改:
/zmclan reload
要求
| 组件 |
版本 |
| 服务器 |
Paper / Purpur 1.20+ |
| Java |
21+ |
| Vault |
可选 — 经济系统 |
| PlaceholderAPI |
可选 — 变量 |
创建经济
| 模式 |
要求 |
VAULT |
Vault + 经济提供商 |
CUSTOM |
PlaceholderAPI + balance-placeholder + take-command |
NONE |
无收费 |
economy:
enabled: true
mode: "VAULT"
allow-cost-bypass: true
如果整合缺失、余额不足或提现失败,创建将被拒绝。未支付的情况下,氏族永远不会被创建。
兼容性与说明
- 族长无法退出——必须转移或解散
- 迁移为增量操作——数据不会丢失
- 减少限制时,现有数据会被保留(不允许新增)
/clan stats 与信息视图保持兼容
- 自动更新需要有效的资源 ID
统计
zMClans
Clan system for Paper / Purpur 1.20+
High performance · Fully configurable · No compromises
Modern, lightweight and fully customizable clans.
No mandatory dependencies, no main-thread blocking, no limits.
Why zMClans?
What you get
- Real performance — Async by default
- Modtags with gradients — MiniMessage + Hex
- Multi-home per clan — With warmup and cooldown
- Alliances and rivalries — With per-level limits
- Level system — Points, kills, KDR
- SQLite and MySQL — With HikariCP
- Public API — Events and Java facade
- 100% YAML GUIs — DeluxeMenus style
|
What you avoid
- Mandatory dependencies
- Sync-save lag spikes
- Chat using deprecated API
- Click/hover injections in tags
- Cryptic configs
- No API for developers
- Hardcoded GUIs
- Duplicate invitation bugs
|
Features
Complete Clan Management
- Creation with tag and optional modtag
- Invitations with async expiration
- Accept, deny and cancel
- Voluntary leave (leader protected)
- Hierarchical kick by rank
- Disband with safe confirmation
- Public join — Open clans via
/clan join <clan>
Named Homes System
- Multiple homes per clan (limit scalable by level)
- Configurable warmup with real-time cancellation (ignores camera rotations)
- Cooldown with bypass permission (
zmclans.clan.bypass.cooldown)
- Shared visibility with allies based on settings
- Dedicated GUI + direct commands
home:
max-homes: 3
teleport-cooldown: 30
teleport-warmup: 5
cancel-on-move: true
ModTag with Gradients and Hex
Native Adventure MiniMessage support:
<bold><gradient:#9A23FF:#7C09DE:#9A23FF>ZEPHY</gradient></bold>
Legacy hex support:
	A23FF&lZB16EF&lEC09DE&lPB16EF&lH	A23FF&lY
Guaranteed safety — Blocks click, hover and command injections. Only allows visual styles.
Alliances, Rivalries and Friendly Fire
- Reciprocal requests with configurable expiration
- Per-level ally/rival limits
- Interactions between allies:
- Share homes
- Ally chat
- Configurable ally PvP
- Friendly Fire for members:
- Blocks melee damage
- Blocks projectiles (arrows, tridents, etc.)
- Toggleable via
/clan ff or GUI
Private Clan Chat
- Integrated with Paper's modern API (
AsyncChatEvent) — no deprecations
- Toggle mode (
/clan chat) or direct send (/clan chat <msg>)
- Configurable format with tag, rank and prefix
format: "{tag} &7| {rank_prefix}{player} &8» &f{message}"
Points, Levels and Ranking
Configurable points for:
- Clan creation
- Member join
- Kills / Deaths
- Rank changes
Customizable formula:
progression:
base-points: 100
exponent: 1.5
start-level: 1
max-level: 50
level-limits:
1:
members: 10
homes: 1
allies: 2
rivals: 3
10:
members: 30
homes: 5
allies: 8
rivals: 10
Paginated leaderboard with filters:
- Members
- Points
- Kills
- Deaths
- KDR
Notification System
Each event has independent control over:
- Title / Subtitle (with fade-in/out)
- ActionBar
- Sound (volume and pitch)
Included events:
| Category |
Events |
| Progression |
clan-points-earned, clan-levelup, clan-create, clan-disband |
| Members |
member-promote, member-demote, member-kick, member-join, member-leave, member-joined, member-left, member-kicked, transfer-leader |
| Invitations |
invite-sent, invite-received, invite-accepted |
| Homes / Alliances |
home-teleport, home-set, ally-accepted |
100% Configurable GUIs (YAML)
Data-driven architecture — zero Java code needed to customize.
| File |
Description |
general.yml |
Start and main menu |
members.yml |
Paginated member list |
member_manage.yml |
Individual management |
clanlist.yml |
Ranking and clan browser |
invite.yml |
One-click invite |
invites.yml |
Received invitations |
settings.yml |
Settings panel |
clan_info.yml |
Info + statistics |
homes.yml |
Home management |
confirm.yml |
Critical confirmation |
Supported actions:
- CLOSE
- CANCEL
- PAGE_NEXT / PAGE_PREV
- OPEN_GUI:<name>
- CREATE_CLAN
- SHOW_HELP
- TOGGLE_CHAT
- CLAN_HOME_OR_SETHOME
- TOGGLE_SETTING:<key>
- MEMBER_PROMOTE / MEMBER_DEMOTE / MEMBER_KICK / MEMBER_TRANSFER_LEADER
- CMD_PLAYER:<cmd>
- CMD_CONSOLE:<cmd>
Robust Storage (SQLite / MySQL)
- HikariCP for efficient pooling
- Periodic async saving
- Single writer to preserve operation order
- Additive migrations (no data loss)
- Final save before shutdown
storage:
type: "MYSQL" # or SQLITE
auto-save-interval: 5
mysql:
host: "localhost"
port: 3306
database: "zmclans"
pool-size: 10
useSSL: false
Public API and Bukkit Events
Plugin candidate = Bukkit.getPluginManager().getPlugin("zMClans");
if (candidate instanceof zMClans clans && clans.isEnabled()) {
ZMClansAPI api = clans.getAPI();
api.getClanByPlayer(player.getUniqueId()).ifPresent(clan ->
player.sendMessage(clan.name() + " | level " + clan.level() + " | KDR " + clan.kdr()));
}
Available events:
ClanCreatedEvent
ClanMemberJoinEvent
ClanMemberLeaveEvent
ClanPointsChangeEvent
ClanLevelChangeEvent
All calls must be executed on the main thread.
Commands
Player (/clan, /c, /clans)
View full player command table
| Command |
Description |
/clan |
Opens the main interactive menu |
/clan create <name> [tag] |
Creates a clan |
/clan info [clan] |
Clan information |
/clan list |
Leaderboard menu |
/clan invite <player> |
Invites a player |
/clan invites |
Invitations GUI |
/clan accept [clan] |
Accepts an invitation |
/clan deny [clan] |
Denies an invitation |
/clan join <clan> |
Joins a public clan |
/clan members |
Members GUI |
/clan setrank <player> <rank> |
Assigns a rank |
/clan kick <player> |
Kicks a member |
/clan leave |
Leaves the clan |
/clan disband [confirm] |
Disbands the clan |
/clan home [name] |
GUI or teleport |
/clan homes |
Homes GUI |
/clan sethome [name] |
Creates/updates a home |
/clan delhome <name> |
Deletes a home |
/clan chat [message] |
Clan chat |
/clan ff |
Toggles friendly fire |
/clan desc <text> |
Changes the description |
/clan modtag <tag> |
Changes tag with formatting |
/clan settings |
Settings GUI |
/clan ally add|accept|deny|cancel|remove <clan> |
Manages alliances |
/clan rival add|remove <clan> |
Manages rivalries |
/clan relation remove <clan> |
Removes a relation |
/clan stats |
Consolidated clan info |
/clan help |
Help |
Administrator (/zmclan, /zmclans, /clanadmin)
| Command |
Description |
Permission |
/zmclan help |
List admin commands |
zmclans.admin.help |
/zmclan reload |
Reload configuration |
zmclans.admin.reload |
/zmclan list [page] |
List clans |
zmclans.admin.list |
/zmclan members <clan> |
View members |
zmclans.admin.members |
/zmclan info <clan> |
Clan details |
zmclans.admin.info |
/zmclan disband <clan> |
Administratively disband |
zmclans.admin.disband |
/zmclan setleader <clan> <player> |
Transfer leadership |
zmclans.admin.setleader |
/zmclan points <add|set|remove> <clan> <n> |
Adjust points |
zmclans.admin.points |
Special Permissions
| Permission |
Description |
zmclans.clan.bypass.cooldown |
Bypasses home teleport cooldown |
zmclans.clan.bypass.cost |
Bypasses clan creation cost |
All zmclan.player.* nodes are denied by default. Grant them individually or use zmclan.player as the parent node.
Default Ranks (ranks.yml)
| Rank |
Priority |
Permissions |
member |
1 |
USE_HOME, USE_CHAT |
officer |
2 |
+ INVITE |
admin |
3 |
+ KICK, PROMOTE, SET_HOME, EDIT_DESCRIPTION, MODTAG |
leader |
4 |
All (protected rank is-leader: true) |
View full list of rank permissions
USE_HOME — Use /clan home
USE_CHAT — Clan chat
INVITE — Invite players
KICK — Kick lower-ranked members
PROMOTE — Change ranks of lower members
SET_HOME — Modify clan home
EDIT_DESCRIPTION — Edit description
EDIT_SETTINGS — Manage settings (alliances, shared homes, FF...)
TRANSFER_LEADER — Transfer leadership
DISBAND — Disband clan
MODTAG — Modify tag with colors
Placeholders (PlaceholderAPI)
View full list of placeholders
Identification
%zmclans_hasclan% · %zmclans_hasclan_formated% · %zmclans_hasclan_formated_nocolor% · %zmclans_clan% · %zmclans_name% · %zmclans_clanid%
Tags
%zmclans_modtag% · %zmclans_tag% · %zmclans_tag_formated% · %zmclans_tag_nocolor%
Members
%zmclans_leader% · %zmclans_is_leader% · %zmclans_members% · %zmclans_onlinemembers% · %zmclans_slots%
Ranking (Top)
%zmclans_points% · %zmclans_top% · %zmclans_top:<N>% · %zmclans_top_points:<N>% · %zmclans_top_kdr:<N>%
States
%zmclans_is_ff% · %zmclans_isopen% · %zmclans_chat_active%
Home and Dates
%zmclans_hashome% · %zmclans_home% · %zmclans_creation_date%
Player Statistics
%zmclans_player_role% · %zmclans_player_kills% · %zmclans_player_kdr%
Relational
%rel_zmclans_relation_relboolean_member% · %rel_zmclans_relation_relcolor% · %rel_zmclans_relation_reltype%
Installation
# 1. Download zMClans-1.0.0.jar
# 2. Place it in /plugins/
# 3. Restart the server
# 4. Configure config.yml, ranks.yml, guis/, langs/
# 5. Apply changes:
/zmclan reload
Requirements
| Component |
Version |
| Server |
Paper / Purpur 1.20+ |
| Java |
21+ |
| Vault |
Optional — Economy |
| PlaceholderAPI |
Optional — Variables |
Creation Economy
| Mode |
Requirements |
VAULT |
Vault + economy provider |
CUSTOM |
PlaceholderAPI + balance-placeholder + take-command |
NONE |
No charge |
economy:
enabled: true
mode: "VAULT"
allow-cost-bypass: true
If the integration is missing, the balance is insufficient or the withdrawal fails, creation is rejected. The clan is never created without payment.
Compatibility and Notes
- The leader cannot leave — they must transfer or disband
- Additive migrations — data is never lost
- If you reduce limits, existing data is preserved (no new additions allowed)
/clan stats keeps compatibility with the info view
- Automatic updates require a valid resource ID
Statistic
评论 0
登录后参与评分
还没有评论,来抢沙发吧