# Necrify
Necrify 是一个惩罚插件，当前适用于
[Velocity](https://velocitypowered.com) (未来可能适用于 [Paper/BungeeCord](https://github.com/users/JvstvsHD/projects/5))。
## 目录
1. [插件安装](#plugin-installation)
2. [静音 (仅影响 Velocity)](#mutes)
3. [时长](#duration)
4. [命令](#commands)
5. [API](#punishment-api)
* [安装](#installation)
* [用法](#usage)
## 插件安装
1. [下载插件的最新版本](https://hangar.papermc.io/JvstvsHD/Necrify) 或下载开发
构建 [此处](https://ci.jvstvshd.de/job/Necrify/) (可能不稳定或无法工作)
2. 将下载的文件放入服务器的 ```plugins``` 文件夹中。
3. (重新)启动服务器。
## 静音
随着 1.19.1，Minecraft 的聊天系统发生了改变
([详细说明](https://gist.github.com/kennytv/ed783dd244ca0321bbd882c347892874))。
此后，由于签名聊天消息，由于 Velocity 中 ChatEvent 无法阻止聊天消息。
因此，聊天监听器不再阻止任何消息，这意味着静音实际上毫无用处。 解决此问题的方法是为实际游戏服务器开发扩展插件，以便在这些消息仍然可以被取消的地方。 此 paper 插件的下载地址在
[发布](https://github.com/JvstvsHD/necrify/releases/latest) 和
[dev 构建](https://ci.jvstvshd.de/job/Necrify/) 在 Jenkins 上。
有关 1.19.1 的更多信息，请参阅
[官方发布说明](https://www.minecraft.net/en-us/article/minecraft-java-edition-1-19-1)
## 命令
所有命令都使用 `/necrify` 前缀注册。 此外，通过设置 `allow-top-level-commands` 为 true (默认情况下启用) 也可以注册顶级命令。
图例:
- \
表示该参数是必需的
- \[arg\] 表示该参数是可选的
- 作为参数名称的玩家表示需要一个玩家名称或 UUID
- 理由是指支持 [MiniMessage](https://docs.advntr.dev/minimessage/format.html) 的理由
- 作为参数名称的时长表示一个 [时长](#duration)
### 命令概览
- **/ban \ \[reason]** 永久封禁玩家，原因为给定或默认原因
- **/mute \ \[reason]** 永久静音玩家，原因为给定或默认原因
- **/tempban [reason]** 封禁该玩家指定时长，原因为给定或默认原因
- **/tempmute [reason]** 静音该玩家指定时长，原因为给定或默认原因
- **/unban ** 解封给定的玩家
- **/unmute ** 解静音给定的玩家
- **/necrify user \ \** 显示玩家的惩罚信息及其白名单状态，
删除此用户包括所有惩罚或反转其白名单状态 (从白名单到黑名单或反之亦然)
- **/necrify punishment \ ** 取消/删除，更改或显示关于
给定的惩罚 (必须是一个 UUID)
### 时长
为了被 `PunishmentDuration#parse(String)` 解析，字符串必须遵循以下模式:
[0-9][s, m, h, d]
s - 秒(s)
m - 分钟(s)
h - 小时(s)
d - 天(s)
这些值可以组合，所有值都可以省略。
示例: 1d12h15m30s 表示一个时长为 1 天、12 小时、15 分钟和 30 秒。
## Punishment API
### 安装
将 ```{version}``` 替换为当前版本，例如 1.2.3。 最新版本可以在 [此处](https://ci.jvstvshd.de/job/Necrify/lastSuccessfulBuild/) 找到。
请注意，您只需要使用 necrify-{platform}- 之后的字符串，并且不需要版本构建号。
#### Gradle (kotlin)
```kotlin
repositories {
mavenCentral()
}
dependencies {
implementation("de.jvstvshd.necrify:necrify-api:{version}")
}
```
#### Gradle (groovy)
```groovy
repositories {
mavenCentral()
}
dependencies {
implementation 'de.jvstvshd.necrify:necrify-api:{version}'
}
```
#### Maven
```xml
de.jvstvshd.necrify
necrify-api
{version}
```
您也可以依赖插件模块或 common 模块。 为了做到这一点，将 artifactId 替换为所需的模块名称。
请注意，API 模块之外的代码始终可能发生变化，并且可能不稳定。 它还设计为不允许
来自插件本身的外部访问和修改，并且通常没有文档。
### 用法
#### 获取 api 实例
如果使用了 [插件](#plugin-installation)，可以使用以下代码片段获取 api 实例：
```java
try {
Necrify api = (Necrify) server.getPluginManager().getPlugin("necrify").orElseThrow().getInstance().orElseThrow();
} catch(NoSuchElementException e) {
logger.error("Punishment API is not available");
}
```
#### 惩罚玩家
所有惩罚都是通过目标用户发出的。 例如，封禁玩家可以这样完成：
```java
//首先，获取用户实例
NecrifyUser user = api.getUserManager().getUser(uuid).orElseThrow(() -> new NoSuchElementException("User not found"));
MiniMessage miniMessage = MiniMessage.miniMessage();
//临时封禁：
Ban temporaryBan = user.ban(PunishmentDuration.parse(miniMessage.deserialize("You broke the server's rules! Don't cheat!"), PunishmentDuration.parse("1d"))).join();//1d 等于 1 天，时长相对于当前时间直到惩罚生效.
//永久封禁：
Ban permanentBan = user.banPermanent(miniMessage.deserialize("You broke the server's rules again! You are not allowed to join someday again!")).join();
//你获得的封禁实例通过 #join 是发出的惩罚。 请注意使用 #join 会阻塞当前
//线程，并且由于数据库操作需要一些时间来完成，因此建议使用 #whenComplete 或其他。
//您现在可以使用此实例来更改或取消惩罚：
temporaryBan.cancel().whenComplete((punishment, throwable) -> {
if(throwable != null) {
logger.error("An error occurred while cancelling the punishment", throwable);
return;
}
logger.info("The punishment was successfully cancelled");
});
//#cancel 应该始终返回你调用的相同实例
//即使永久封禁了无限时间，你仍然可以更改时长和理由：
permanentBan.change(PunishmentDuration.parse("300d"), miniMessage.deseriaize("Okay, you may join again in 300 days!")).whenComplete((punishment, throwable) -> {
if(throwable != null) {
logger.error("An error occurred while changing the punishment", throwable);
return;
}
logger.info("The punishment was successfully changed");
});
```
静音玩家的方式类似，只需将 'ban' 替换为 'mute'。
踢出玩家可以通过调用 `user.kick(Reason).join();` 来完成，其中调用 #join 是安全的，因为没有
执行同步数据库查询。这种惩罚形式不能被更改或取消，因为它只持续一瞬间。
