HyFactions

⚔️ Hyfaction - Hytale 完整阵营系统

一个为 Hytale 服务器设计的综合性阵营管理 Mod，包含领地占领、联盟、策略性 PvP、反占领以及高度可定制化。完美适用于寻求组织化阵营战争的竞技服务器。

版本: 1.0.552 - 山丘之王模式（KOTH）制作中 - 排行榜已上线 - UI 修复

---

🌟 概述

Hyfaction 将你的 Hytale 服务器转变为一个动态的基于阵营的环境，玩家可以创建阵营、占领领地、缔结联盟并发起策略性 PvP 战斗。借助直观的 GUI 系统、ECS 集成、反占领机制和广泛的自定义选项，Hyfaction 提供了竞技性阵营游戏所需的一切。

主要命令: /hf | /hyfaction | /faction | /f

---

✨ 核心功能

🏰 高级阵营管理

• 创建和管理阵营，使用独特的名称和随机颜色
• 三层职位体系（拥有者、官员、成员），各有不同权限
• 智能邀请系统，需明确接受
• 全面的活动日志，追踪最近 100 条阵营动态
• 独立的阵营存储，每个阵营有独立的 JSON 文件
• 完全解散，移除所有领地声明和数据文件
• 🆕 成员数量限制系统 - 可配置每个阵营的最大成员数（默认：50）
• 🆕 解散确认 - 新增弹窗以防止误删阵营

🗺️ 智能领地系统

• 基于区块的认领，保护阵营领地
• 可视化地图集成，以阵营颜色显示已认领的区块
• GUI 内集成小地图，提供环境感知
• 15x15 区块网格，便于领地管理
• 基于能量的限制，确保均衡扩张
• 🆕 相邻认领系统 - 强制阵营仅能认领连接在一起的领地
• 🆕 防空洞保护 - 防止取消认领时产生断开的区块组
• 🆕 反占领系统 - 当敌方能量降至 0 时，可夺取其领地！
• 🆕 不活跃阵营衰退 - 自动移除不活跃阵营的领地
• 自动衰退系统，针对不活跃或低能量阵营（可配置）
• 维度限制，防止在临时或受限区域认领

⚡ 动态能量系统

• 每个玩家的个人能量（可配置上限为 20）
• 阵营能量计算为成员能量之和（每位玩家有上限）
• 每自动恢复一个可配置间隔（每位玩家 +1 能量）
• 死亡（-1）或击杀中立玩家（-1）时策略性能量损失
• 🆕 可配置能量消耗 - 设置每次认领所需的能量（默认：2）
• 🆕 战争区域无能量损失 - 自由战斗，无惩罚！
• 实时重新计算，应对成员变动和能量事件
• 能量不足惩罚，触发自动领地衰退

🤝 外交关系系统

• 盟友 - 相互保护、共享领地访问、无友军伤害
• 敌人 - 完全 PvP、双向敌对、可反占领 🔥
• 中立 - 启用 PvP，攻击带有能量惩罚
• 联盟请求系统，包含批准/拒绝机制
• 自动转为敌人，当拒绝联盟请求时
• 颜色编码显示（绿色盟友、红色敌人、白色/灰色中立）

🏠 家园与传送

• 阵营家园，由拥有者在已认领领地内设置
• 精确传送，保留位置和旋转（偏航角/俯仰角）
• 跨维度支持，使用 Hytale 原生传送
• 仅限成员访问，带有权限检查
• 可配置的冷却和延迟系统

⚔️ 高级战斗系统

• 战斗标记，防止下线逃避（默认 15 秒）
• 基于关系的 PvP规则（盟友受保护，敌人可攻击）
• 能量惩罚，针对攻击中立玩家
• 战斗日志，记录所有死亡事件及时间戳
• 🆕 安全区域，管理员指定的受保护区域（绿色）
• 🆕 战争区域，PvP 战斗区域，无能量损失惩罚（红色）
• 死亡检测，通过 ECS DeathComponent 和聊天分析

💬 阵营与联盟聊天系统 - 全新！

• 🆕 聊天切换模式 - 即时切换聊天频道
• 阵营聊天（/hf c）- 切换至阵营聊天模式
• 联盟聊天（/hf a）- 切换至联盟聊天模式
• 普通聊天（/hf g）- 切换回普通聊天
• 可视化确认，切换聊天模式时
• 独特的格式，使用自定义颜色和前缀
• 安全消息 - 仅阵营/联盟成员可参与
• 无消息重复 - 高效消息投递
• 基于权限控制，通过 LuckPerms 集成

🎯 特殊区域系统 - 全新！

🟢 安全区域（绿色）

• 完全保护，免受所有 PvP 战斗
• 不允许破坏或放置方块
• 管理员指定的安全区域，用于出生点、中心或活动
• 在世界地图上以绿色显示
• 最高优先级，在地图显示中

🔴 战争区域（红色）

• 🆕 专属 PvP 战斗区域
• 启用 PvP，死亡无能量损失
• 无惩罚，在战争区域死亡
• 理想选择，用于活动、竞技场和有序战斗
• 在世界地图上以红色显示
• 自动"战争区域"标题提示，进入/离开时
• 可视化指示，在领地 GUI 中："PvP 已启用 - 死亡无能量损失"
• 仅限管理员创建和管理

🛡️ 全面保护

• 方块放置/破坏保护，在已认领区块内
• 交互保护，针对容器、门和机械装置
• 流体放置保护（水、岩浆等）
• 物品拾取保护，在已认领区域内
• 盟友访问友好领地（可配置）
• 创造模式绕过选项，用于建造（可配置）
• 管理员覆盖系统，用于服务器管理
• 🆕 多世界支持 - 在多个世界和维度中正常工作

👑 专业管理工具

• 整合管理菜单，包含所有管理选项
• 无限认领，用于服务器设置和活动
• 绕过模式切换，用于修改任何领地
• 🆕 增强管理员取消认领 - 即使造成断开的区块组也可取消认领
• 🆕 安全区域管理（添加/移除/列出）
• 🆕 战争区域管理 - 新增专用菜单用于创建战斗区域
• 管理员区块 GUI，具有无限制访问权限
• 覆盖系统，用于特殊权限

🎨 现代用户界面

• 交互式主菜单，显示阵营统计、成员和操作
• 区块管理 GUI，集成了小地图和 15x15 网格
• 🆕 自动更新联盟 UI - 实时反映变化
• 联盟管理，带有可视化请求处理
• 阵营浏览器，列出所有阵营，点击可查看成员
• 🆕 解散确认弹窗 - 防止误删阵营
• 多页面 Wiki，包含全面的游戏内文档
• 帮助系统，带有分类命令参考
• 颜色编码徽章，用于职位和关系
• 🆕 战争区域指示器，在领地 GUI 中有清晰提示

---

📋 完整命令参考

基本阵营命令

命令	权限	描述
/hf 或 /hf list	-	打开交互式阵营菜单（GUI）
/hf create <n>	hyfaction.create	创建一个具有独特名称的新阵营
/hf invite <player>	hyfaction.invite	邀请玩家加入阵营（拥有者/官员）
/hf accept	-	接受待处理的阵营邀请
/hf leave	-	离开当前阵营（拥有者不可用）
/hf kick <player>	hyfaction.kick	从阵营中移除玩家
/hf disband	hyfaction.disband	完全解散阵营（仅限拥有者）

家园与传送

命令	权限	描述
/hf sethome	hyfaction.sethome	在当前位置设置阵营家园（仅限拥有者）
/hf home	hyfaction.home	传送至阵营家园，保留精确旋转

成员管理

命令	权限	描述
/hf promote <player>	hyfaction.promote	将成员提升为官员（仅限拥有者）
/hf demote <player>	hyfaction.demote	将官员降级为成员（仅限拥有者）

领地管理

命令	权限	描述
/hf chunk	hyfaction.claim/hyfaction.unclaim	打开带有小地图的区块管理 GUI
/hf overclaim	hyfaction.claim	🆕 全新 - 夺取敌方阵营区块（要求能量 ≤ 0，敌人关系）

注意： 直接的 /hf claim 和 /hf unclaim 命令已弃用。所有领地管理现在使用 /hf chunk GUI。

外交关系

命令	权限	描述
/hf ally <faction>	hyfaction.ally	发送联盟请求（若相互则自动接受）
/hf enemy <faction>	hyfaction.enemy	将阵营宣布为敌人（双向，启用反占领）
/hf neutral <faction>	hyfaction.enemy	设置为中立关系（单方面）
/hf faction	-	查看所有阵营及其关系和统计信息

信息与帮助

命令	权限	描述
/hf logs	-	显示最近 100 条阵营活动条目
/hf help	-	打开包含所有命令的交互式帮助菜单
/hf wiki	-	访问多页面游戏内文档

通讯命令 - 🆕 全新！

命令	权限	描述
/hf c <message>	hyfaction.chat.faction	🆕 切换阵营聊天模式 - 切换到阵营频道
/hf a <message>	hyfaction.chat.ally	🆕 切换联盟聊天模式 - 切换到联盟频道
/hf g	-	🆕 切换普通聊天 - 返回全局聊天

管理命令

命令	权限	描述
/hf admin	hyfaction.admin	打开整合管理菜单
/hf admin-chunk	hyfaction.admin	打开管理员区块 GUI（无限）
/hf admin-claim	hyfaction.admin	认领当前区块（不受限）
/hf admin-unclaim	hyfaction.admin	取消认领当前区块（任何所有者）
/hf admin safezone add	hyfaction.admin	将当前区块添加为安全区域
/hf admin safezone remove	hyfaction.admin	从当前区块移除安全区域
/hf admin safezone list	hyfaction.admin	列出所有安全区域及其坐标
/hf admin warzone add	hyfaction.admin	🆕 全新 - 将当前区块添加为战争区域
/hf admin warzone remove	hyfaction.admin	🆕 全新 - 从当前区块移除战争区域
/hf admin warzone list	hyfaction.admin	🆕 全新 - 列出所有战争区域及其坐标

---

🔑 权限与集成

权限系统集成

Hyfaction 支持多种权限系统，以实现最大灵活性：

LuckPerms

与 LuckPerms 完全集成，实现细粒度权限控制。若无 LuckPerms，所有权限默认为已授予（许可模式）。

HyperPerms ⭐

自动集成 HyperPerms - Hytale 的高级权限管理！

功能：

• 🎨 聊天中自动显示阵营前缀 - 在玩家组前缀前显示阵营名称
• 👑 可选职位显示 - 在聊天中包含阵营职位（拥有者、官员、成员）
• 🔧 聊天占位符 - 在聊天格式中的任何位置使用阵营数据
• ⚙️ 可自定义格式 - 完全控制阵营信息的显示方式

可用占位符：

• {hyfaction_faction_name} - 阵营名称（若无则为空）

  {hyfaction_faction_rank} - 玩家的职位（领导者 / 官员 / 成员）

  {hyfaction_faction_rank_raw} - 原始职位（OWNER / OFFICER / MEMBER）

  {hyfaction_faction_power} - 阵营总能量

  {hyfaction_faction_claims} - 已认领的区块数量

  {hyfaction_faction_claims_max} - 最大可认领数量（基于配置和能量）

  {hyfaction_player_power} - 玩家的个人能量

  {hyfaction_player_power_max} - 每位玩家的最大能量（根据配置）

  {hyfaction_display_name} - 显示名称（在追踪器中使用）

  {hyfaction_has_faction} - 布尔值，表示玩家是否有阵营（"true" 或 "false"）

  {hyfaction_is_owner} - 布尔值，表示玩家是否为拥有者（"true" 或 "false"）

  {hyfaction_is_officer} - 布尔值，表示玩家是否为官员（"true" 或 "false"）

聊天示例：

在 Hyfaction.json 中

"ChatFormat": "&7[&a{hyfaction_faction_name}&7] &f{hyfaction_display_name}&7: "
"ChatFormat": "{prefix} &7| &f{username}&7: "
"ChatFormat": ""

无需配置！ HyperPerms 会自动检测 Hyfaction。只需同时安装两个 Mod，它们即可立即协同工作。

了解更多：HyperPerms HyFactions 集成

核心权限

权限	功能	备注
hyfaction.create	创建阵营	/hf create 所需
hyfaction.invite	邀请玩家	还需要官员+职位
hyfaction.claim	认领区块	用于区块 GUI 和反占领
hyfaction.unclaim	取消认领区块	用于区块 GUI
hyfaction.home	使用阵营家园	传送至家园
hyfaction.sethome	设置阵营家园	仅拥有者 + 权限
hyfaction.kick	踢出成员	拥有者/官员 + 权限
hyfaction.promote	提升为官员	仅拥有者 + 权限
hyfaction.demote	降级为成员	仅拥有者 + 权限
hyfaction.ally	管理联盟	盟友/敌人/中立关系
hyfaction.enemy	管理关系	与盟友权限相同
hyfaction.disband	解散阵营	仅拥有者 + 权限
hyfaction.admin	管理访问	所有管理命令 + 绕过
hyfaction.chat.faction	阵营聊天	🆕 使用 /hf c 进行阵营聊天
hyfaction.chat.ally	联盟聊天	🆕 使用 /hf a 进行联盟聊天

权限层级

• 拥有者： 自动绕过所有阵营权限
• 官员： 基于职位 + LuckPerms 的有限权限
• 成员： 仅通过 LuckPerms 获得基本权限
• 管理员： 使用 hyfaction.admin 权限完全覆盖

---

⚙️ 配置

配置文件：plugins/Hyfaction/config/Hyfaction.json（自动生成，含默认值）

配置选项

设置	类型	默认值	描述
DefaultFactionClaimsAmount	整数	25	新阵营的起始认领数（旧版）
MaxFactionClaims	整数	100	每个阵营的绝对最大区块数
MaxPlayerPower	整数	20	每位玩家的能量上限（阵营贡献限制）
PowerRegenerationHours	整数	1	每次 +1 能量恢复之间的小时数
CombatTagDurationSeconds	整数	15	战斗标记持续时间（下线惩罚期）
ClaimDecaySeconds	整数	600	自动取消超额认领的延迟时间（10 分钟）
EnableOverclaiming	布尔值	true	🆕 启用/禁用反占领系统
PowerPerClaim	整数	2	🆕 每次认领的能量消耗（可自定义）
MaxFactionMembers	整数	50	🆕 每个阵营的最大成员数
OnlyAdjacentClaims	布尔值	false	🆕 强制仅相邻认领（连接在一起的领地）
InactiveFactionDecayDays	整数	7	🆕 从非活跃阵营自动移除认领的天数（设为 0 禁用）
NeutralKillPowerLoss	整数	1	🆕 击杀中立玩家时的能量损失（可配置惩罚）
SafeZoneAllowDoors	布尔值	false	🆕 允许在安全区域内与门交互
SafeZoneAllowChests	布尔值	false	🆕 允许在安全区域内开启箱子
WarZoneAllowDoors	布尔值	false	🆕 允许在战争区域内与门交互
WarZoneAllowChests	布尔值	false	🆕 允许在战争区域内开启箱子
ShowClaimsOnMap	布尔值	true	在世界地图上显示阵营区块
ShowFactionNameInChat	布尔值	true	在聊天消息中添加阵营名称前缀
HidePlayersNotInSameFactionOnMap	布尔值	false	在地图上隐藏非同阵营玩家
HidePlayerNameTags	布尔值	false	在游戏中隐藏玩家名称标签
HidePlayerMarkersOnMap	布尔值	false	在世界地图上隐藏玩家标记
HomeTeleportDelaySeconds	整数	5	家园传送前延迟时间
HomeTeleportCooldownMinutes	整数	5	家园传送之间的冷却时间
ForceHyfactionChunkWorldMap	布尔值	true	对兼容维度强制使用 Hyfaction 地图
CreativeModeBypassProtection	布尔值	false	允许创造模式玩家绕过保护
DefaultFactionBlockPlaceEnabled	布尔值	true	默认允许盟友放置方块
DefaultFactionBlockBreakEnabled	布尔值	false	默认允许盟友破坏方块
DefaultFactionBlockInteractEnabled	布尔值	false	默认允许盟友与方块交互

完整配置示例

{
  "DefaultFactionClaimsAmount": 25,
  "DefaultFactionBlockPlaceEnabled": true,
  "DefaultFactionBlockBreakEnabled": false,
  "DefaultFactionBlockInteractEnabled": false,
  "ForceHyfactionChunkWorldMap": true,
  "CreativeModeBypassProtection": false,
  "ShowClaimsOnMap": true,
  "CombatTagDurationSeconds": 15,
  "PowerRegenerationHours": 1,
  "MaxPlayerPower": 20,
  "ShowFactionNameInChat": true,
  "MaxFactionClaims": 100,
  "ClaimDecaySeconds": 600,
  "HidePlayersNotInSameFactionOnMap": false,
  "HomeTeleportDelaySeconds": 5,
  "HomeTeleportCooldownMinutes": 5,
  "HidePlayerNameTags": false,
  "HidePlayerMarkersOnMap": false,
  "EnableOverclaiming": true,
  "PowerPerClaim": 2,
  "MaxF