原创 付费 [1.13-1.21+|Folia] WarZGuild - 一款支持TacZ无友伤的高级公会插件|全Gui自定义|商店|任务|签到|称号| 1.7.9

# WarZGuildClaim 官方文档

WarZGuildClaim 是一个功能丰富、高度可配置的 Minecraft 公会插件，专为 RPG 和生存服务器设计。它集成了领地占领、公会经济、商店系统和自定义 GUI 等核心玩法。
本插件支持 Spigot 1.13+ 及 Folia 核心。

## 目录
- [安装与依赖](#安装与依赖)
- [核心功能](#核心功能)
- [指令列表](#指令列表)
- [权限节点](#权限节点)
- [配置文件详解](#配置文件详解)
- [GUI 自定义](#gui-自定义)
- [PlaceholderAPI 变量](#placeholderapi-变量)
- [更新日志](#更新日志)

---

## 安装与依赖

### 前置插件
为了确保插件正常运行，请安装以下前置插件：
1. **Vault**: 用于经济系统支持（必须）。
2. **WorldGuard** (及 WorldEdit): 用于领地占领功能（必须）。
3. **PlaceholderAPI**: (可选) 用于在计分板或聊天中显示公会变量。

### 安装步骤
1. 将 `WarZGuildClaim-1.4.jar` 放入服务器的 `plugins` 文件夹。
2. 重启服务器。
3. 插件将自动生成配置文件和默认 GUI 布局。

---

## 核心功能

1. **公会管理系统**
   - 创建、邀请、踢出、职位管理（会长/管理员/成员）。
   - 公会等级系统：升级可提升最大人数和商店物品上限。
   - 支持公会转让、解散及公告设置。

2. **领地占领 (WorldGuard 集成)**
   - 公会可以消耗资金占领 WorldGuard 区域。
   - 占领后可定期获得收益（可配置）。
   - 支持占领冷却和覆盖保护。

3. **公会经济与商店**
   - **公会银行**: 成员存钱，会长/管理员取钱。
   - **公会商店**: 玩家上架物品，全服可见（需权限），交易资金可流入公会或个人。
   - **图标商店**: 管理员上架图标，公会购买后可设置为公会标志（支持自定义模型数据）。

4. **每日签到**
   - 成员每日签到可为公会增加资金。
   - 签到成功会有炫酷的 Title 和音效反馈。

5. **高度自定义 GUI**
   - 所有界面（大厅、成员列表、商店等）均可通过 YAML 文件自定义布局、材质和动作。

6. **Folia 支持**
   - 完美支持 Folia 多线程服务端核心。

---

## 指令列表

### 玩家通用指令
| 指令 | 描述 |
| --- | --- |
| `/guild create <名称>` | 创建一个新公会 (需花费金币) |
| `/guild join <公会名>` | 申请/加入一个公会 |
| `/guild leave` | 离开当前公会 |
| `/guild list` | 打开公会大厅 GUI |
| `/guild info [公会名]` | 查看自己或他人的公会信息 |
| `/guild status` | 查看当前公会简要状态 (PVP等) |
| `/guild signin` | 进行每日签到 |
| `/guild shop` | 打开公会商店 |
| `/guild bank` | 查看公会银行余额 |
| `/guild deposit <金额>` | 向公会银行存入资金 |
| `/guild denyinvite <公会名>` | 拒绝公会邀请 |

### 公会管理指令 (会长/管理员)
| 指令 | 描述 |
| --- | --- |
| `/guild invite <玩家>` | 邀请玩家加入公会 |
| `/guild kick <玩家>` | 将玩家踢出公会 |
| `/guild promote <玩家>` | 将成员提升为管理员 |
| `/guild demote <玩家>` | 将管理员降级为成员 |
| `/guild transfer <玩家>` | (仅会长) 将会长职位转让给其他成员 |
| `/guild disband` | (仅会长) 解散公会 |
| `/guild upgrade` | 升级公会等级 |
| `/guild announcement <内容>` | 设置公会公告 (别名: `setannouncement`) |
| `/guild claim` | 消耗公会资金占领当前 WorldGuard 区域 |
| `/guild unclaim` | 放弃当前区域的占领权 |
| `/guild withdraw <金额>` | 从公会银行提取资金 |
| `/guild pvp <on/off>` | 开启或关闭公会成员间的 PVP |
| `/guild seticon <材质> [数据]` | 设置公会图标 (需先在图标商店购买) |
| `/guild buyicon <材质> <数据> <价格>` | (通常通过 GUI 操作) 购买公会图标 |
| `/guild sell <价格>` | 将手中物品上架到公会商店 |
| `/guild shop remove <ID>` | (在 GUI 中操作) 下架商店物品 |

### 管理员 (OP) 指令
| 指令 | 描述 |
| --- | --- |
| `/guild admin addicon <价格>` | 将手中物品上架到图标商店 |
| **Shift + 左键** (GUI) | 在图标商店中强制下架图标 |
| `/guild shop remove` | 强制下架公会商店中的违规物品 (需 `warzguildclaim.admin.removeshop` 权限) |
| `/guild shop <公会名>` | 查看指定公会的商店 (需 `warzguildclaim.admin.viewshop` 权限) |

---

## 权限节点

### 玩家权限
- `warzguildclaim.create`: 允许创建公会。
- `warzguildclaim.claim`: 允许使用占领指令。
- `warzguildclaim.withdraw`: 允许从公会银行取款。
- `warzguildclaim.seticon`: 允许更改公会图标。
- `warzguildclaim.pvp`: 允许切换公会 PVP 状态。

### 管理员权限
- `warzguildclaim.admin`: 拥有所有管理权限。
- `warzguildclaim.admin.viewshop`: 允许查看其他公会的商店 (用于监管)。
- `warzguildclaim.admin.removeshop`: 允许下架任何公会商店的物品。

---

## 配置文件详解

插件的主要配置位于 `config.yml`，以下是关键部分说明：

### 公会升级 (Upgrades)
你可以自定义每个等级的升级费用、最大人数和商店容量：
```yaml
upgrades:
  max_level: 5
  level_2:
    cost: 500000.0       # 升级费用
    max_members: 10      # 最大成员数
    max_shop_items: 10   # 商店格数
    broadcast: true      # 升级公告
```

### 数据库 (Database)
支持 SQLite (默认) 和 MySQL。如果你是群组服或需要网页后台，建议使用 MySQL。
```yaml
database:
  type: 'mysql'
  mysql:
    host: 'localhost'
    ...
```

---

## GUI 自定义

所有 GUI 界面都位于 `plugins/WarZGuildClaim/gui/` 目录下。你可以修改 `.yml` 文件来调整界面布局。

### 常用动作 (Actions)
在 GUI 配置中，`actions` 列表支持以下操作：
- `[CLOSE]`: 关闭当前菜单。
- `[OPEN] <gui_name>`: 打开另一个 GUI (如 `dashboard`, `members`)。
- `[COMMAND] <指令>`: 以玩家身份执行指令 (支持占位符)。
- `[PAGE] next/previous`: 翻页操作。

### 示例：添加一个按钮
在 `dashboard.yml` 中添加一个打开商店的按钮：
```yaml
shop_button:
  slot: 22
  material: EMERALD
  name: "&a公会商店"
  lore:
    - "&7点击浏览商品"
  actions:
    - "[OPEN] guild_shop"
```

---

## PlaceholderAPI 变量

如果服务器安装了 PlaceholderAPI，可以使用以下变量：

| 变量名 | 描述 | 示例返回值 |
| --- | --- | --- |
| `%warzguildclaim_in_guild%` | 玩家是否在公会中 | true / false |
| `%warzguildclaim_guild_name%` | 公会名称 | 龙之军团 |
| `%warzguildclaim_guild_leader%` | 会长名称 | Notch |
| `%warzguildclaim_guild_level%` | 公会等级 | 3 |
| `%warzguildclaim_guild_balance%` | 公会资金余额 | 1000.00 |
| `%warzguildclaim_guild_member_count%` | 公会总人数 | 15 |
| `%warzguildclaim_guild_claim_count%` | 占领领地数量 | 2 |
| `%warzguildclaim_guild_pvp%` | 公会 PVP 状态 | on / off |
| `%warzguildclaim_guild_announcement%` | 公会公告 | 欢迎加入! |

---

## 更新日志 (v1.4)

**新增功能**:
- **公会转让与解散**: 新增 `/guild transfer` 和 `/guild disband` 指令，方便会长管理公会。
- **公会公告**: 新增 `/guild announcement` 指令，会长可设置公会内部公告。
- **Folia 支持**: 全面适配 Folia 多线程服务端核心。
- **公会状态查询**: 新增 `/guild status` 快速查看公会状态。
- **拒绝邀请**: 新增 `/guild denyinvite` 指令。
- **管理员商店监管**: 管理员现在可以查看任意公会商店并下架违规物品。

**修复与优化**:
- 修复了公会人数上限计算问题。
- 优化了 WorldGuard 区域判定逻辑。
- 完善了权限节点控制。
[CENTER]

# WarZGuildClaim Configuration
# 核心配置文件

# ==============================================================================
# 调试设置 (Debug Settings)
# ==============================================================================
debug: false

# ==============================================================================
# 数据库设置 (Database Settings)
# ==============================================================================
database:
  # 数据库类型: 'sqlite' (本地文件) 或 'mysql' (远程数据库)
  type: 'sqlite'
 
  # MySQL 连接设置 (仅当 type: mysql 时生效)
  mysql:
    host: 'localhost'
    port: 3306
    database: 'warzguildclaim'
    username: 'root'
    password: 'password'
    
  # SQLite 文件名 (仅当 type: sqlite 时生效)
  sqlite:
    file: 'database.db'

# ==============================================================================
# 公会基础设置 (Guild Settings)
# ==============================================================================
guild:
  # 创建公会所需费用 (金币)
  creation_cost: 2000
 
  # 默认最大成员数量 (1级公会)
  # 注意: 后续等级的成员上限在 upgrades 部分配置
  max_members: 5
 
  # 公会名称最小长度
  min_name_length: 3
 
  # 公会名称最大长度
  max_name_length: 16
 
  # 公会名称允许的字符 (正则表达式)
  # 默认允许中英文和数字
  name_regex: '[a-zA-Z0-9\u4e00-\u9fa5]+'

  # 每日签到奖励 (金币)
  # 玩家签到后，公会银行将获得此数量的资金
  sign_in_reward: 100.0
 
  # 占领区域所需费用 (金币)
  # 每次使用 /guild claim 占领 WorldGuard 区域时扣除的公会资金
  claim_cost: 1000.0

  # ============================================================================
  # 公会升级设置 (Guild Upgrades)
  # ============================================================================
  upgrades:
    # 公会最高等级
    max_level: 5
    
    # 2级公会配置
    level_2:
      cost: 500000.0       # 升级费用
      max_members: 10      # 最大成员数
      max_shop_items: 10   # 公会商店最大上架物品数
      broadcast: true      # 升级是否全服公告
      
    # 3级公会配置
    level_3:
      cost: 1000000.0
      max_members: 20
      max_shop_items: 20
      broadcast: true
      
    # 4级公会配置
    level_4:
      cost: 2000000.0
      max_members: 30
      max_shop_items: 30
      broadcast: true
      
    # 5级公会配置
    level_5:
      cost: 5000000.0
      max_members: 40
      max_shop_items: 40
      broadcast: true

# ==============================================================================
# 领地占领设置 (Claim Settings)
# ==============================================================================
claim:
  # 领地收益间隔 (分钟)
  # 公会占领区域后，每隔多久获得一次收益
  income_interval: 15
 
  # 每次收益金额 (金币)
  income_amount: 100
 
  # 占领冷却时间 (分钟)
  # 两次占领操作之间的冷却时间
  claim_cooldown: 60
 
  # 是否允许覆盖占领
  # false: 无法占领已被其他公会占领的区域
  allow_override: false

# ==============================================================================
# 权限节点参考 (Permissions)
# ==============================================================================
permissions:
  admin: 'warzguildclaim.admin'        # 管理员权限 (如下架任意商品)
  create: 'warzguildclaim.create'      # 创建公会
  claim: 'warzguildclaim.claim'        # 占领领地
  withdraw: 'warzguildclaim.withdraw'  # 提取公会资金

# ==============================================================================
# 其他设置 (Other Settings)
# ==============================================================================
# 是否启用 PlaceholderAPI 变量支持
papi_enabled: true

# 调试模式 (建议关闭，除非需要排查问题)
debug: false