稳定 • 快速 • 模块化 • API驱动
` | 切换活动语言 (例如 `FRENCH`)。 | 管理员 |
---
## 🔐 权限
(来自 `plugin.yml` 的确切节点，以及观察到的模式。)
| 权限 | 目的 | 默认 |
|------------|---------|---------|
| `homeplugin.command.home` | 使用 `/home` (传送 / GUI) | true |
| `homeplugin.command.sethome` | 使用 `/sethome` | true |
| `homeplugin.command.delhome` | 使用 `/delhome` | true |
| `homeplugin.command.listhome` | 使用 `/listhome` | true |
| `homeplugin.command.spawn` | 使用 `/spawn` | true |
| `homeplugin.command.tpa` | 发送/接受/拒绝 TPA 请求 | true |
| `homeplugin.admin` | 管理员设置/删除重生点、缓存、查看其他玩家的家庭 | op |
| `homeplugin.lang.update` | 更新语言文件 | op |
| `homeplugin.limit.` | 覆盖最大家庭数量 (动态扫描 1..100) | (基于权限) |
附加 (隐式/建议):
| 节点 | 目的 |
|------|---------|
| `homeplugin.bypass.limit` | 如果实现: 忽略基本限制 (否则依赖 limit.) |
| `homeplugin.bypass.validation` | 忽略不公平位置限制 |
| `homeplugin.bypass.cooldown` | 忽略 RTP / 传送冷却时间 (如果实现) |
动态限制: 代码循环 `homeplugin.limit.1` 到 `homeplugin.limit.100`，应用你拥有的最高权限。
---
## 🧩 PlaceholderAPI 集成
在 `HomePluginExpansion` 中实现:
| 占位符 | 描述 |
|-------------|-------------|
| `%homeplugin_homes%` | 逗号分隔的家庭名称或回退 (没有家庭) |
| `%homeplugin_homes_numbers%` | 家庭数量 |
| `%homeplugin_has_homes%` | 如果玩家有 ≥ 1 个家庭，则为 `true` |
| `%homeplugin_home_location_%` | 格式化的位置（使用语言格式） |
| `%homeplugin_home_exists_%` | `true` / `false` |
| `%homeplugin_home_world_%` | 世界名称 |
| `%homeplugin_home_coordinates_%` | 原生坐标 `X Y Z` |
> `` 不区分大小写，传出。
---
## 🌍 语言
通过配置：`Config.Language`
可用（内置）：
- 法语
- 英语
- 西班牙语
语言加载使用枚举 (`Language.valueOf(...)`) 并在无效时回退到法语。
定制化通过发送的语言 YML 文件（和更新/合并命令）提供。
---
## ⚙️ 配置
（来自 `src/main/resources/config.yml` 的确切结构）：
```yaml
Config:
Language: FRENCH
Connector:
TYPE: "YAML" # MYSQL or YAML
# Optional (for MYSQL)
HOST: "localhost"
PORT: 3306
USERNAME: "root"
PASSWORD: ""
DATABASE: "HomePlugin"
Redis:
UseRedis: false
# Optional if enabled
HOST: "localhost"
PORT: 6379
SSL: false
PASSWORD: ""
Home:
DefaultHomeLimit: 3
PreventUnfairLocation: true
DisabledWorlds:
- "world_nether"
- "world_the_end"
Task:
Task-duration: 3 # second
UseTitle: true
UseMessage: false
Add-particles-after-teleport: true
Tpa:
Tpa-duration: 30 # seconds
Rtp:
cooldown-seconds: 1000 # seconds
max-radius: 200
```
关键行为 (来自代码):
- `Config.Home.DefaultHomeLimit` 用于基本家庭计数 (参见 `HomePermissionManager`)。
- TPA 超时：`Config.Tpa.Tpa-duration` (缺失时默认为 30)。
- 只有当 `UseRedis: true` 时才会初始化 Redis；否则跳过。
- 验证使用 `PreventUnfairLocation` 和 `DisabledWorlds`。
- 传送预热 (`Task-duration`) 驱动延迟执行 (标题/消息/粒子可选)。
---
## 🧱 架构与性能
- 静态访问模式（经理存储在主类中，初始化后）
- Redis (JedisPooled) 条件设置缓存；如果未连接则回退路径。
- 如果 `Config.Connector.TYPE == MYSQL` 则调用 MySQL 注册路径。
- 动态插件扩展系统：`PluginLoader` / `PluginManager` 支持加载内部模块化的 HomePlugin 组件。
- PlaceholderAPI 软依赖项：仅在存在时注册扩展；插件会启动，但会发出警告。
- 动态基于权限的家庭限制分辨率 (`homeplugin.limit.` 递增扫描)。
- 基于配置的语言键选择语言管理器于启动时。
- 验证 & 公平性约束限制禁用世界/不公平放置.
- RTP + 预热计时器使用 Bukkit 调度器 (异步延迟用于 TPA 等到期任务)。
---
## 🧑💻 开发者/扩展 API
虽然没有外部 Facade 类（如统一的 `HomePluginAPI`）出现在扫描的片段中，但扩展点确实存在：
### 插件加载器接口
```java
public interface HomePlugin {
String getName();
String getVersion();
String getAuthor();
String[] getAuthors();
void initialize();
void stop();
boolean isSqlStorageEnabled();
boolean isPlaceholderApiHooked();
boolean isCacheEnabled();
}
public interface PluginLoader {
void loadPlugin(HomePlugin homePlugin);
List getHomePlugin();
void unregisterPlugin(HomePlugin homePlugin);
}
```
`PluginManager.getInstance()` 维护加载的 HomePlugin 模块的内部列表。
### 示例（注册内部模块）
```java
PluginManager pm = PluginManager.getInstance();
pm.loadPlugin(new MyExtensionPlugin()); // implements fr.fuzeblocks.homeplugin.plugin.HomePlugin
```
### 示例（访问家庭限制）
```java
int max = HomePermissionManager.getMaxHomes(player);
boolean canSet = HomePermissionManager.canSetHome(player);
```
---
## ✅ 兼容性
- 声明 `api-version: 1.14` (plugin.yml)
- 设计用于现代 Paper/Spigot 衍生品（较新版本通常保持 1.14 API 兼容性）
- 软依赖项：PlaceholderAPI (用于占位符；没有它插件仍然可以加载，并发出警告)
- 存储：YAML (默认) 或 MySQL (启用时)
---
## 🗺️ 路线图
| 特性 | 状态 |
|-----------------------------------|------------|
| 家庭经济成本 | 计划 |
| 离线玩家家庭编辑 | 计划 |
| 编辑现有家庭 | 计划 |
| 添加公共家庭 | 计划 |
欢迎通过问题或 Discord 提出建议。
---
## 🤝 支持与贡献
- 问题：使用 GitHub Issues 对于错误/功能请求
- Discord: [加入](https://discord.gg/5zJyKz6Nfm)
- 拉取请求：遵循清晰的提交消息；提前讨论大型更改
### 贡献流程
1. 分叉
2. 创建功能分支
3. 提交更改
4. 打开 PR 参考任何相关问题
---
> 🛠️ HomePlugin — 用于现代服务器的稳定、快速和可扩展的家庭/重生管理。