Release v1.0.1

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 kpAjun@HyenaMC
+Copyright (c) 2025 kpAjun@HyenaMC and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,67 +1,122 @@
-# Horde — Velocity Chat Plugin
+# Horde — Velocity 聊天插件 | Velocity Chat Plugin
 
+一款轻量、零折腾的 Velocity 聊天插件。Horde 提供全局与本地聊天、简洁可配的模板、基于权限的前缀，并尽量减少复杂度。
 A lightweight, zero-fuss chat plugin for Velocity. Horde provides global and local chat with clean, configurable templates, permission-based prefixes, and minimal moving parts.
 
+- 平台：Velocity
 - Platform: Velocity
+- Java：21+
 - Java: 21+
 
-## Features
+## 功能 | Features
+- 全局与本地聊天：可在整个代理广播，或仅限当前子服本地。
 - Global and local chat: broadcast across the proxy or keep it server-local.
+- 玩家默认模式：使用不带参数的 `/broadcast` 或 `/local` 在个人默认全局/本地之间切换。
 - Per-player default mode: toggle with `/broadcast` or `/local` without arguments.
-- Minimal config: sensible defaults, yet still extremely customizable
+- 极简配置：开箱即用的合理默认，同时保持高度可定制。
+- Minimal config: sensible defaults, yet still extremely customizable.
+- 灵活格式：本地化、模板和聊天文本支持 MiniMessage 或传统颜色码（Legacy §/&）。
 - Flexible formatting: MiniMessage or Legacy (§/&) style for localizations, templates and chat.
+- 基于权限的前缀：通过 `prefix.yml` 在聊天模板中注入前缀。
 - Prefixes by permission: inject prefixes via `prefix.yml` in your chat templates.
+- 名称映射：为服务器名展示易读的别名（如 `survival` -> `Survival`）。
 - Name mappings: show pretty server names (e.g., `survival` -> `Survival`).
+- 可选的发送者 UUID 转发：提升与某些客户端模组的兼容性。
 - Optional sender UUID forwarding: better compatibility with some client mods.
+- 可选的消息日志：将聊天镜像到代理控制台日志。
 - Optional message logging: mirror chat into the proxy logs.
 
-## Requirements
+## 环境要求 | Requirements
+- Velocity 代理 3.x
 - Velocity proxy 3.x
+- Java 21 及以上
 - Java 21+
 
-## Installation
+## 安装 | Installation
+1. 构建或下载插件 JAR。
+2. 将 JAR 放入 Velocity 的 `plugins/` 目录。
+3. 启动一次 Velocity 以在 `plugins/horde/` 生成配置文件。
+4. 按需编辑 `config.yml`、`localization.yml` 与 `prefix.yml`。
+5. 使用 `/horde reload` 重载或重启代理。
 1. Build or download the plugin JAR.
 2. Place the JAR into your Velocity `plugins/` folder.
 3. Start Velocity once to generate config files at `plugins/horde/`.
 4. Edit `config.yml`, `localization.yml`, and `prefix.yml` to taste.
 5. Reload with `/horde reload` or restart the proxy.
 
-## Configuration
+## 配置 | Configuration
+除特别说明外，配置文件位于 `plugins/horde/`。
 Files live under `plugins/horde/` unless otherwise noted.
 
 ### `config.yml`
+- `default-global-chat`（布尔，默认 `true`）：
+  - 为 `true` 时玩家默认全局聊天；为 `false` 时默认本地聊天。
+  - 玩家可通过不带消息的 `/broadcast` 或 `/local` 覆盖自己的默认模式。
 - `default-global-chat` (boolean, default `true`):
   - When true, players chat globally by default; when false, locally.
   - Players can override their own default using `/broadcast` or `/local` with no message.
+- `log-messages`（布尔，默认 `false`）：同时将聊天输出到代理控制台日志。
 - `log-messages` (boolean, default `false`): also log chat to the proxy console.
+- `enable-legacy-chat-formatting`（布尔，默认 `true`）：
+  - 仅作用于玩家输入的原始聊天内容。
+  - 为 `true` 时允许使用 `&` 颜色码（如 `&aHello`），按 Legacy (§) 解析。
+  - 为 `false` 时原始消息按 MiniMessage 解析。
 - `enable-legacy-chat-formatting` (boolean, default `true`):
   - Applies only to raw messages players type (the message content).
   - When true, players can use `&` codes (e.g., `&aHello`). Parsed as Legacy (§) via Adventure.
   - When false, raw messages are parsed as MiniMessage.
+- `enable-legacy-localization-formatting`（布尔，默认 `false`）：
+  - 作用于 `localization.yml` 与 `prefix.yml` 中的本地化字符串与模板。
+  - 为 `true` 时按 Legacy (§) 解析；否则为 MiniMessage。
+  - 注意：默认模板基于 MiniMessage。
 - `enable-legacy-localization-formatting` (boolean, default `false`):
   - Applies to localization strings and templates in `localization.yml` and `prefix.yml`.
   - When true, those files are parsed as Legacy (§); otherwise MiniMessage.
   - Note: default templates assume MiniMessage.
+- `forward-sender-uuid`（布尔，默认 `false`）：
+  - 启用后通过 Adventure Identity 附带作者 UUID 发送消息。
+  - 可提升与 Chat Heads 等客户端模组的兼容性。
+  - Mojang 安全档案可能阻止未签名身份；如需完整生效，后端需设置 `enforce-secure-profiles=false`（风险自负）。
 - `forward-sender-uuid` (boolean, default `false`):
   - Sends messages with the author UUID using Adventure Identity when enabled.
   - Can improve compatibility with client mods like Chat Heads.
   - Mojang secure profiles may block unsigned identities; requires `enforce-secure-profiles=false` on backends to fully function (use at your risk).
 
 ### `localization.yml`
+- 存放通用消息与聊天模板。
+- 占位符以 `{key}` 表示，并在运行时替换。
+- Horde 在格式化聊天时提供的内置占位符：
+  - `{server}`：来自 `SERVER_NAME_MAPPINGS` 的美化服务器名称。
+  - `{player}`：发送者用户名。
+  - 你在 `prefix.yml` 中定义的任意键（见下）也可在此使用。
 - General messages and chat templates.
 - Placeholders are denoted `{key}` and replaced at runtime.
 - Built-in placeholders provided by Horde when formatting chat:
   - `{server}`: pretty server name from `SERVER_NAME_MAPPINGS`.
   - `{player}`: the sender’s username.
   - Any keys you define in `prefix.yml` (see below) can appear here.
+- 关键模板键：
+  - `GLOBAL_CHAT_TEMPLATE`：全局消息的模板前缀。
+  - `LOCAL_CHAT_TEMPLATE`：本地消息的模板前缀。
 - Key templates:
   - `GLOBAL_CHAT_TEMPLATE`: template prefix for global messages.
   - `LOCAL_CHAT_TEMPLATE`: template prefix for local messages.
+- 示例（默认）：
+  ```
+  GLOBAL_CHAT_TEMPLATE: "[{server}]{player}:" # 模板后会追加消息内容
+  LOCAL_CHAT_TEMPLATE: "{player}:"           # 模板后会追加消息内容
+  ```
 - Example (default):
   ```
   GLOBAL_CHAT_TEMPLATE: "[{server}]{player}:" # message appended after template
   LOCAL_CHAT_TEMPLATE: "{player}:"           # message appended after template
   ```
+- 名称映射：
+  ```yaml
+  SERVER_NAME_MAPPINGS:
+    lobby: "<aqua>Lobby</aqua>"
+    survival: "<green>Survival</green>"
+  ```
 - Name mappings:
   ```yaml
   SERVER_NAME_MAPPINGS:
@@ -70,8 +125,20 @@ Files live under `plugins/horde/` unless otherwise noted.
   ```
 
 ### `prefix.yml`
+- 定义一个或多个以前缀占位符名为键的前缀集合。
+- 每个集合是按顺序进行的权限检查，首个匹配的权限决定所用前缀。
 - Define one or more prefix sets keyed by a placeholder name.
 - Each set is an ordered list of permission checks; the first matching permission wins.
+- 示例：
+  ```yaml
+  any_permission_prefix_set:
+    - permission: "horde.prefix.moderator"
+      prefix: "<red>[MOD]</red>"
+    - permission: "horde.prefix.member"
+      prefix: "<gray>[MEMBER]</gray>"
+    - permission: "horde.prefix.default"
+      prefix: "<white>[PLAYER]</white>"
+  ```
 - Example:
   ```yaml
   any_permission_prefix_set:
@@ -82,58 +149,82 @@ Files live under `plugins/horde/` unless otherwise noted.
     - permission: "horde.prefix.default"
       prefix: "<white>[PLAYER]</white>"
   ```
+- 在 `localization.yml` 模板中使用 `{any_permission_prefix_set}` 插入解析出的前缀（无匹配则为空）。
 - Use `{any_permission_prefix_set}` in your `localization.yml` templates to insert the resulting prefix (or empty if none matched).
 
-### Data file
+### 数据文件 | Data file
+- `data/preferences.yml`：按 UUID 存储玩家默认聊天模式（全局/本地），由插件自动管理。
 - `data/preferences.yml`: per-player defaults (global vs local) stored by UUID. Automatically managed.
 
-## Commands
-- `/horde help` — Show help.
-- `/horde reload` — Reload configs. Permission: `horde.command.reload`.
-- `/broadcast [message…]` (aliases: `/b`, `/bc`)
-  - With message: send a global chat message now.
-  - Without message: set your default chat mode to Global.
-  - Requires `horde.command.broadcast`.
-- `/local [message…]` (aliases: `/l`, `/lc`)
-  - With message: send a local (same-server) chat message now.
-  - Without message: set your default chat mode to Local.
-  - Requires `horde.command.local`.
-
-## How chatting works
+## 指令 | Commands
+- `/horde help` — 显示帮助。
+  - _Show help._
+- `/horde reload` — 重载配置。权限：`horde.command.reload`。
+  - _Reload configs. Permission: `horde.command.reload`._
+- `/broadcast [message…]`（别名：`/b`、`/bc`）
+  - 带消息：立即发送全局聊天。
+  - 不带消息：将你的默认聊天模式设为“全局”。
+  - 权限：`horde.command.broadcast`
+  - _With message: send a global chat message now. Without message: set your default chat mode to Global. Permission: `horde.command.broadcast`._
+- `/local [message…]`（别名：`/l`、`/lc`）
+  - 带消息：立即发送本地（同服）聊天。
+  - 不带消息：将你的默认聊天模式设为“本地”。
+  - 权限：`horde.command.local`
+  - _With message: send a local (same-server) chat message now. Without message: set your default chat mode to Local. Permission: `horde.command.local`._
+
+## 工作原理 | How chatting works
+- Horde 监听玩家聊天事件并替换原版的聊天投递逻辑。
+- 如果你的默认模式是“全局”且拥有 `horde.command.broadcast`，消息将代理范围广播。
+- 如果你的默认模式是“本地”且拥有 `horde.command.local`，消息只会发送到当前服务器的玩家。
+- 若所选模式缺少对应权限，Horde 会拦截消息并提示没有权限。
 - Horde listens to player chat events and replaces vanilla chat delivery.
 - If your default mode is Global and you have `horde.command.broadcast`, your messages broadcast proxy-wide.
 - If your default mode is Local and you have `horde.command.local`, your messages deliver only to your current server.
 - If you lack the needed permission for your selected mode, Horde blocks the message and shows a no-permission notice.
 
-## Permissions
-- `horde.command.reload`: use `/horde reload`.
-- `horde.command.broadcast`: use `/broadcast` or chat globally when set to global.
-- `horde.command.local`: use `/local` or chat locally when set to local.
-- Prefix examples you might grant via your permissions plugin:
-  - `horde.prefix.moderator`, `horde.prefix.member`, `horde.prefix.default`, etc. (you choose names/values)
-
-## Formatting notes
+## 权限 | Permissions
+- `horde.command.reload`：使用 `/horde reload`。
+  - _Use `/horde reload`._
+- `horde.command.broadcast`：使用 `/broadcast` 或在默认全局模式下进行全局聊天。
+  - _Use `/broadcast` or chat globally when set to global._
+- `horde.command.local`：使用 `/local` 或在默认本地模式下进行本地聊天。
+  - _Use `/local` or chat locally when set to local._
+- 可在权限插件中自定义授予的前缀权限示例：
+  - `horde.prefix.moderator`、`horde.prefix.member`、`horde.prefix.default` 等（名称与权限值由你决定）。
+  - _Prefix examples you might grant via your permissions plugin: `horde.prefix.moderator`, `horde.prefix.member`, `horde.prefix.default`, etc. (you choose names/values)._ 
+
+## 格式化说明 | Formatting notes
+- 模板/本地化：默认使用 MiniMessage；将 `enable-legacy-localization-formatting: true` 可切换为 Legacy (§)。
 - Templates/localizations: MiniMessage by default; set `enable-legacy-localization-formatting: true` to switch to Legacy (§).
+- 玩家原始消息：`enable-legacy-chat-formatting: true` 允许使用 `&` 颜色码；否则按 MiniMessage 解析。
 - Raw player message: `enable-legacy-chat-formatting: true` lets players use `&` codes; otherwise raw content is MiniMessage.
+- 避免重复着色：除非确有需要，不要在模板与名称映射/前缀中同时添加颜色代码。
 - Avoid double-formatting: don’t add color codes both in templates and in the mapped names/prefixes unless intended.
 
-## Build From Source
+## 从源码构建 | Build From Source
+需要 JDK 21 与 Maven。
 Requires JDK 21 and Maven.
 
 ```powershell
-# From the project root
+# 在项目根目录执行 / From the project root
 mvn -V -B clean package
 ```
 
+- 构建产物 JAR 位于 `target/`。
+- 将其复制到你的 Velocity 代理的 `plugins/` 目录并启动服务器。
 - The built JAR will be in `target/`.
 - Copy it into `plugins/` on your Velocity proxy and start the server.
 
-## Compatibility
+## 兼容性 | Compatibility
+- Velocity API：使用 Velocity 3.x 的 `PlayerChatEvent` 与指令 API。
 - Velocity API: uses `PlayerChatEvent` and command APIs from Velocity 3.x.
+- 身份转发：在安全档案场景下被 Velocity 标记为不推荐；请谨慎使用 `forward-sender-uuid`。
 - Identity forwarding: marked deprecated by Velocity for secure profiles; toggle `forward-sender-uuid` with care.
 
-## License
+## 许可证 | License
+MIT 许可证 —— 见 `LICENSE`。
 MIT License — see `LICENSE`.
 
 ---
+需要帮助或有建议？欢迎提交 Issue 或 PR。祝你聊天愉快！
 Need help or have suggestions? Open an issue or PR. Enjoy the chat!

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>com.evermc</groupId>
     <artifactId>horde</artifactId>
-    <version>1.0.0</version>
+    <version>1.0.1</version>
     <packaging>jar</packaging>
 
     <name>horde</name>

src/main/java/com/evermc/horde/Horde.java

@@ -22,7 +22,7 @@
 
 import java.nio.file.Path;
 
-@Plugin(id = "horde", name = "Horde", version = "1.0.0",
+@Plugin(id = "horde", name = "Horde", version = "1.0.1",
         authors = {"kpAjun@HyenaMC"},
         url = "https://minecraft.teamhyena.org",
         description = "A light-weight chat plugin with minimal configurations.")