feat: major update v1.1.0 - improved documentation, configuration and compatibility
- Add comprehensive documentation in docs/ folder - Update README.md with modern design and badges - Improve configuration with new options (GUI, limits, notifications) - Add support for Minecraft 1.19.2-1.21.4 and Java 17+ - Create GPL-3.0 license - Add modrinth/ folder with project description for publishing - Add CONTRIBUTING.md for contributors - Update plugin.yml with aliases and better permissions - Improve build.gradle.kts with better compatibility and encoding - Update .gitignore for cleaner repository
This commit is contained in:
loki5512344
parent
da356e491c
commit
55df7d97b2
14 changed files with 1582 additions and 73 deletions
293
docs/api.md
Normal file
293
docs/api.md
Normal file
|
|
@ -0,0 +1,293 @@
|
|||
# API для разработчиков
|
||||
|
||||
## Подключение к проекту
|
||||
|
||||
### Maven
|
||||
```xml
|
||||
<repository>
|
||||
<id>codeberg</id>
|
||||
<url>https://codeberg.org/api/packages/loki5512344/maven</url>
|
||||
</repository>
|
||||
|
||||
<dependency>
|
||||
<groupId>dev.loki</groupId>
|
||||
<artifactId>loreport</artifactId>
|
||||
<version>1.0.0</version>
|
||||
<scope>provided</scope>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
### Gradle
|
||||
```kotlin
|
||||
repositories {
|
||||
maven("https://codeberg.org/api/packages/loki5512344/maven")
|
||||
}
|
||||
|
||||
dependencies {
|
||||
compileOnly("dev.loki:loreport:1.0.0")
|
||||
}
|
||||
```
|
||||
|
||||
## Основные классы
|
||||
|
||||
### LorepPlugin
|
||||
Главный класс плагина, предоставляет доступ к основным компонентам.
|
||||
|
||||
```java
|
||||
LorepPlugin plugin = LorepPlugin.getInstance();
|
||||
DatabaseManager db = plugin.getDatabaseManager();
|
||||
ConfigManager config = plugin.getConfigManager();
|
||||
```
|
||||
|
||||
### DatabaseManager
|
||||
Интерфейс для работы с базой данных репортов.
|
||||
|
||||
```java
|
||||
public interface DatabaseManager {
|
||||
void addReport(Report report);
|
||||
List<Report> getReports(String playerName);
|
||||
List<Report> getAllReports();
|
||||
int getReportCount(String playerName);
|
||||
boolean hasReported(String reporter, String reported);
|
||||
void initialize();
|
||||
void close();
|
||||
}
|
||||
```
|
||||
|
||||
### Report
|
||||
Класс представляющий репорт.
|
||||
|
||||
```java
|
||||
public class Report {
|
||||
private final String reporter;
|
||||
private final String reported;
|
||||
private final String reason;
|
||||
private final long timestamp;
|
||||
|
||||
// Конструкторы и геттеры
|
||||
}
|
||||
```
|
||||
|
||||
## События (Events)
|
||||
|
||||
### ReportSubmitEvent
|
||||
Вызывается при отправке нового репорта.
|
||||
|
||||
```java
|
||||
@EventHandler
|
||||
public void onReportSubmit(ReportSubmitEvent event) {
|
||||
Player reporter = event.getReporter();
|
||||
String reported = event.getReported();
|
||||
String reason = event.getReason();
|
||||
|
||||
// Ваша логика
|
||||
|
||||
// Отменить репорт
|
||||
event.setCancelled(true);
|
||||
}
|
||||
```
|
||||
|
||||
### ReportViewEvent
|
||||
Вызывается при просмотре репортов через GUI.
|
||||
|
||||
```java
|
||||
@EventHandler
|
||||
public void onReportView(ReportViewEvent event) {
|
||||
Player viewer = event.getViewer();
|
||||
List<Report> reports = event.getReports();
|
||||
|
||||
// Ваша логика
|
||||
}
|
||||
```
|
||||
|
||||
## Примеры использования
|
||||
|
||||
### Добавление репорта программно
|
||||
|
||||
```java
|
||||
public void addCustomReport(String reporter, String reported, String reason) {
|
||||
LorepPlugin plugin = LorepPlugin.getInstance();
|
||||
DatabaseManager db = plugin.getDatabaseManager();
|
||||
|
||||
Report report = new Report(reporter, reported, reason, System.currentTimeMillis());
|
||||
db.addReport(report);
|
||||
|
||||
// Отправить в Discord если настроен
|
||||
DiscordWebhook webhook = plugin.getDiscordWebhook();
|
||||
if (webhook != null) {
|
||||
webhook.sendReport(report);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Получение статистики игрока
|
||||
|
||||
```java
|
||||
public void showPlayerStats(Player admin, String targetPlayer) {
|
||||
LorepPlugin plugin = LorepPlugin.getInstance();
|
||||
DatabaseManager db = plugin.getDatabaseManager();
|
||||
|
||||
List<Report> reports = db.getReports(targetPlayer);
|
||||
int count = reports.size();
|
||||
|
||||
admin.sendMessage("У игрока " + targetPlayer + " " + count + " репортов");
|
||||
|
||||
for (Report report : reports) {
|
||||
admin.sendMessage("- " + report.getReason() + " (от " + report.getReporter() + ")");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Интеграция с системой наказаний
|
||||
|
||||
```java
|
||||
@EventHandler
|
||||
public void onReportSubmit(ReportSubmitEvent event) {
|
||||
String reported = event.getReported();
|
||||
|
||||
// Получаем количество репортов
|
||||
DatabaseManager db = LorepPlugin.getInstance().getDatabaseManager();
|
||||
int reportCount = db.getReportCount(reported);
|
||||
|
||||
// Автоматические действия
|
||||
if (reportCount >= 5) {
|
||||
// Временный бан на 1 час
|
||||
Bukkit.dispatchCommand(Bukkit.getConsoleSender(),
|
||||
"tempban " + reported + " 1h Множественные репорты");
|
||||
} else if (reportCount >= 3) {
|
||||
// Предупреждение
|
||||
Player player = Bukkit.getPlayer(reported);
|
||||
if (player != null) {
|
||||
player.sendMessage("§cВнимание! На вас поступают жалобы от других игроков.");
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Кастомные команды
|
||||
|
||||
```java
|
||||
public class CustomReportCommand implements CommandExecutor {
|
||||
|
||||
@Override
|
||||
public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
|
||||
if (!(sender instanceof Player)) return false;
|
||||
|
||||
Player player = (Player) sender;
|
||||
LorepPlugin plugin = LorepPlugin.getInstance();
|
||||
|
||||
if (args.length < 2) {
|
||||
player.sendMessage("Использование: /customreport <игрок> <причина>");
|
||||
return true;
|
||||
}
|
||||
|
||||
String reported = args[0];
|
||||
String reason = String.join(" ", Arrays.copyOfRange(args, 1, args.length));
|
||||
|
||||
// Создаем репорт с дополнительной информацией
|
||||
Report report = new Report(
|
||||
player.getName(),
|
||||
reported,
|
||||
"[CUSTOM] " + reason,
|
||||
System.currentTimeMillis()
|
||||
);
|
||||
|
||||
plugin.getDatabaseManager().addReport(report);
|
||||
player.sendMessage("§aКастомный репорт отправлен!");
|
||||
|
||||
return true;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Хуки для других плагинов
|
||||
|
||||
### PlaceholderAPI
|
||||
|
||||
```java
|
||||
public class LorepPlaceholders extends PlaceholderExpansion {
|
||||
|
||||
@Override
|
||||
public String getIdentifier() {
|
||||
return "loreport";
|
||||
}
|
||||
|
||||
@Override
|
||||
public String getAuthor() {
|
||||
return "loki5512344";
|
||||
}
|
||||
|
||||
@Override
|
||||
public String getVersion() {
|
||||
return "1.0.0";
|
||||
}
|
||||
|
||||
@Override
|
||||
public String onPlaceholderRequest(Player player, String params) {
|
||||
if (player == null) return "";
|
||||
|
||||
DatabaseManager db = LorepPlugin.getInstance().getDatabaseManager();
|
||||
|
||||
switch (params) {
|
||||
case "reports_count":
|
||||
return String.valueOf(db.getReportCount(player.getName()));
|
||||
case "reports_total":
|
||||
return String.valueOf(db.getAllReports().size());
|
||||
default:
|
||||
return null;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### DiscordSRV интеграция
|
||||
|
||||
```java
|
||||
@EventHandler
|
||||
public void onReportSubmit(ReportSubmitEvent event) {
|
||||
// Отправляем в Discord через DiscordSRV
|
||||
String message = String.format(
|
||||
"🚨 **Новый репорт!**\n" +
|
||||
"**Отправитель:** %s\n" +
|
||||
"**Нарушитель:** %s\n" +
|
||||
"**Причина:** %s",
|
||||
event.getReporter().getName(),
|
||||
event.getReported(),
|
||||
event.getReason()
|
||||
);
|
||||
|
||||
DiscordSRV.getPlugin().getMainTextChannel().sendMessage(message).queue();
|
||||
}
|
||||
```
|
||||
|
||||
## Лучшие практики
|
||||
|
||||
1. **Всегда проверяйте доступность плагина:**
|
||||
```java
|
||||
if (!Bukkit.getPluginManager().isPluginEnabled("Loreport")) {
|
||||
// Плагин не загружен
|
||||
return;
|
||||
}
|
||||
```
|
||||
|
||||
2. **Используйте асинхронные операции для БД:**
|
||||
```java
|
||||
Bukkit.getScheduler().runTaskAsynchronously(yourPlugin, () -> {
|
||||
// Работа с базой данных
|
||||
List<Report> reports = db.getReports(playerName);
|
||||
|
||||
Bukkit.getScheduler().runTask(yourPlugin, () -> {
|
||||
// Обновление UI в главном потоке
|
||||
updateGUI(reports);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
3. **Обрабатывайте исключения:**
|
||||
```java
|
||||
try {
|
||||
db.addReport(report);
|
||||
} catch (Exception e) {
|
||||
getLogger().severe("Ошибка при добавлении репорта: " + e.getMessage());
|
||||
}
|
||||
```
|
||||
55
docs/commands.md
Normal file
55
docs/commands.md
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
# Команды и права
|
||||
|
||||
## Команды
|
||||
|
||||
### `/report <игрок> <причина>`
|
||||
Отправить репорт на игрока.
|
||||
|
||||
**Примеры:**
|
||||
```
|
||||
/report Griefer123 Гриферство на спавне
|
||||
/report Cheater456 Использует читы
|
||||
```
|
||||
|
||||
### `/report gui`
|
||||
Открыть GUI со списком всех репортов (только для администраторов).
|
||||
|
||||
### `/report stats <игрок>`
|
||||
Показать статистику репортов на конкретного игрока (только для администраторов).
|
||||
|
||||
**Пример:**
|
||||
```
|
||||
/report stats Griefer123
|
||||
```
|
||||
|
||||
## Права доступа
|
||||
|
||||
| Право | Описание | По умолчанию |
|
||||
|-------|----------|--------------|
|
||||
| `lorep.report` | Позволяет отправлять репорты | `true` |
|
||||
| `lorep.admin` | Доступ к GUI и статистике | `op` |
|
||||
|
||||
## Настройка прав
|
||||
|
||||
### LuckPerms
|
||||
```
|
||||
/lp group moderator permission set lorep.admin true
|
||||
/lp group default permission set lorep.report true
|
||||
```
|
||||
|
||||
### PermissionsEx
|
||||
```
|
||||
/pex group moderator add lorep.admin
|
||||
/pex group default add lorep.report
|
||||
```
|
||||
|
||||
### GroupManager
|
||||
```yaml
|
||||
groups:
|
||||
moderator:
|
||||
permissions:
|
||||
- lorep.admin
|
||||
default:
|
||||
permissions:
|
||||
- lorep.report
|
||||
```
|
||||
129
docs/configuration.md
Normal file
129
docs/configuration.md
Normal file
|
|
@ -0,0 +1,129 @@
|
|||
# Конфигурация
|
||||
|
||||
## Основной файл конфигурации
|
||||
|
||||
Файл `config.yml` находится в папке `plugins/Loreport/`.
|
||||
|
||||
```yaml
|
||||
# Discord Webhook URL для уведомлений
|
||||
webhook-url: "https://discord.com/api/webhooks/YOUR_WEBHOOK_URL"
|
||||
|
||||
# Настройки базы данных
|
||||
database:
|
||||
# Тип БД: sqlite или postgresql
|
||||
type: "sqlite"
|
||||
|
||||
# Настройки SQLite
|
||||
sqlite:
|
||||
file: "reports.db"
|
||||
|
||||
# Настройки PostgreSQL
|
||||
postgresql:
|
||||
host: "localhost"
|
||||
port: 5432
|
||||
database: "loreport"
|
||||
username: "loreport"
|
||||
password: "your_password"
|
||||
pool-size: 10
|
||||
|
||||
# Настройки GUI
|
||||
gui:
|
||||
# Количество репортов на странице
|
||||
reports-per-page: 45
|
||||
# Автообновление GUI (в тиках, 20 тиков = 1 секунда)
|
||||
auto-refresh: 100
|
||||
|
||||
# Ограничения
|
||||
limits:
|
||||
# Максимальная длина причины репорта
|
||||
max-reason-length: 100
|
||||
# Кулдаун между репортами (в секундах)
|
||||
report-cooldown: 30
|
||||
|
||||
# Сообщения
|
||||
messages:
|
||||
report-sent: "&aРепорт успешно отправлен!"
|
||||
already-reported: "&cВы уже отправляли репорт на этого игрока!"
|
||||
self-report: "&cВы не можете отправить репорт на себя!"
|
||||
player-not-found: "&cИгрок не найден!"
|
||||
no-permission: "&cУ вас нет прав на эту команду!"
|
||||
usage: "&eИспользование: /report <ник> <причина>"
|
||||
no-reports: "&eУ этого игрока нет репортов."
|
||||
stats-header: "&6=== Статистика репортов: %player% ==="
|
||||
stats-count: "&eВсего репортов: &f%count%"
|
||||
stats-last-online: "&eПоследний онлайн: &f%time%"
|
||||
stats-report-entry: "&7- %reason% &8(%time% назад)"
|
||||
gui-title: "Репорты - Страница %page%"
|
||||
cooldown: "&cПодождите %time% секунд перед следующим репортом!"
|
||||
reason-too-long: "&cПричина слишком длинная! Максимум %max% символов."
|
||||
```
|
||||
|
||||
## Discord Webhook
|
||||
|
||||
### Создание Webhook
|
||||
|
||||
1. Откройте настройки канала в Discord
|
||||
2. Перейдите в "Интеграции" → "Вебхуки"
|
||||
3. Нажмите "Создать вебхук"
|
||||
4. Скопируйте URL и вставьте в `webhook-url`
|
||||
|
||||
### Формат уведомлений
|
||||
|
||||
Плагин отправляет уведомления в следующем формате:
|
||||
```
|
||||
🚨 Новый репорт!
|
||||
Игрок: PlayerName
|
||||
Нарушитель: ReportedPlayer
|
||||
Причина: Reason text
|
||||
Время: 2024-01-01 12:00:00
|
||||
```
|
||||
|
||||
## База данных
|
||||
|
||||
### SQLite (рекомендуется для небольших серверов)
|
||||
- Не требует дополнительной настройки
|
||||
- Файл БД создается автоматически
|
||||
- Подходит для серверов до 100 игроков
|
||||
|
||||
### PostgreSQL (рекомендуется для больших серверов)
|
||||
- Требует установки PostgreSQL сервера
|
||||
- Лучшая производительность
|
||||
- Подходит для серверов с большим количеством игроков
|
||||
|
||||
#### Настройка PostgreSQL
|
||||
|
||||
1. Установите PostgreSQL
|
||||
2. Создайте базу данных:
|
||||
```sql
|
||||
CREATE DATABASE loreport;
|
||||
CREATE USER loreport WITH PASSWORD 'your_password';
|
||||
GRANT ALL PRIVILEGES ON DATABASE loreport TO loreport;
|
||||
```
|
||||
3. Обновите конфигурацию плагина
|
||||
|
||||
## Цветовые коды
|
||||
|
||||
Плагин поддерживает стандартные цветовые коды Minecraft:
|
||||
- `&0` - черный
|
||||
- `&1` - темно-синий
|
||||
- `&2` - темно-зеленый
|
||||
- `&3` - темно-бирюзовый
|
||||
- `&4` - темно-красный
|
||||
- `&5` - темно-фиолетовый
|
||||
- `&6` - золотой
|
||||
- `&7` - серый
|
||||
- `&8` - темно-серый
|
||||
- `&9` - синий
|
||||
- `&a` - зеленый
|
||||
- `&b` - бирюзовый
|
||||
- `&c` - красный
|
||||
- `&d` - светло-фиолетовый
|
||||
- `&e` - желтый
|
||||
- `&f` - белый
|
||||
|
||||
А также форматирование:
|
||||
- `&l` - жирный
|
||||
- `&m` - зачеркнутый
|
||||
- `&n` - подчеркнутый
|
||||
- `&o` - курсив
|
||||
- `&r` - сброс форматирования
|
||||
108
docs/faq.md
Normal file
108
docs/faq.md
Normal file
|
|
@ -0,0 +1,108 @@
|
|||
# Часто задаваемые вопросы (FAQ)
|
||||
|
||||
## Установка и настройка
|
||||
|
||||
### Q: Плагин не загружается, что делать?
|
||||
A: Проверьте:
|
||||
- Версию Java (требуется 17+)
|
||||
- Версию сервера (Paper 1.19.2+)
|
||||
- Логи сервера на наличие ошибок
|
||||
- Правильность названия файла плагина
|
||||
|
||||
### Q: Как настроить Discord уведомления?
|
||||
A:
|
||||
1. Создайте webhook в настройках Discord канала
|
||||
2. Скопируйте URL webhook
|
||||
3. Вставьте его в `config.yml` в поле `webhook-url`
|
||||
4. Перезагрузите плагин командой `/reload confirm`
|
||||
|
||||
### Q: Какую базу данных выбрать?
|
||||
A:
|
||||
- **SQLite** - для серверов до 100 игроков, не требует настройки
|
||||
- **PostgreSQL** - для больших серверов, лучшая производительность
|
||||
|
||||
## Использование
|
||||
|
||||
### Q: Игроки не могут отправлять репорты
|
||||
A: Проверьте права доступа:
|
||||
- Убедитесь что у игроков есть право `lorep.report`
|
||||
- Проверьте настройки плагина прав (LuckPerms, PermissionsEx и т.д.)
|
||||
|
||||
### Q: GUI не открывается
|
||||
A: Проверьте:
|
||||
- Есть ли у вас право `lorep.admin`
|
||||
- Нет ли ошибок в консоли
|
||||
- Правильно ли настроена база данных
|
||||
|
||||
### Q: Как удалить репорт?
|
||||
A: В текущей версии удаление репортов через игру не поддерживается. Можно удалить напрямую из базы данных или ждать следующего обновления.
|
||||
|
||||
### Q: Можно ли изменить сообщения плагина?
|
||||
A: Да, все сообщения настраиваются в секции `messages` файла `config.yml`.
|
||||
|
||||
## Производительность
|
||||
|
||||
### Q: Плагин тормозит сервер
|
||||
A:
|
||||
- Переключитесь на PostgreSQL если используете SQLite
|
||||
- Увеличьте `pool-size` в настройках PostgreSQL
|
||||
- Проверьте логи на ошибки подключения к БД
|
||||
|
||||
### Q: Discord уведомления не приходят
|
||||
A: Проверьте:
|
||||
- Правильность URL webhook
|
||||
- Доступность Discord API с вашего сервера
|
||||
- Логи плагина на наличие ошибок
|
||||
|
||||
## Совместимость
|
||||
|
||||
### Q: Работает ли с Spigot?
|
||||
A: Нет, плагин требует Paper API. Используйте Paper, Purpur или Pufferfish.
|
||||
|
||||
### Q: Поддерживается ли версия 1.18?
|
||||
A: Нет, минимальная поддерживаемая версия - 1.19.2.
|
||||
|
||||
### Q: Работает ли с другими плагинами репортов?
|
||||
A: Плагин независим, но может конфликтовать с другими системами репортов. Рекомендуется использовать только один плагин репортов.
|
||||
|
||||
## Разработка
|
||||
|
||||
### Q: Есть ли API для других плагинов?
|
||||
A: Да, смотрите [документацию API](api.md).
|
||||
|
||||
### Q: Как собрать плагин из исходников?
|
||||
A:
|
||||
```bash
|
||||
git clone https://codeberg.org/loki5512344/Loreport.git
|
||||
cd Loreport
|
||||
./gradlew shadowJar
|
||||
```
|
||||
Готовый jar будет в папке `build/libs/`.
|
||||
|
||||
### Q: Как сообщить об ошибке?
|
||||
A: Создайте issue на [Codeberg](https://codeberg.org/loki5512344/Loreport/issues) с подробным описанием проблемы и логами.
|
||||
|
||||
## Миграция
|
||||
|
||||
### Q: Как перенести данные с другого плагина репортов?
|
||||
A: В текущей версии автоматическая миграция не поддерживается. Обратитесь к разработчику для помощи с миграцией.
|
||||
|
||||
### Q: Как сделать бэкап репортов?
|
||||
A:
|
||||
- **SQLite**: скопируйте файл `plugins/Loreport/reports.db`
|
||||
- **PostgreSQL**: используйте `pg_dump` для создания бэкапа базы данных
|
||||
|
||||
## Поддержка
|
||||
|
||||
### Q: Где получить помощь?
|
||||
A:
|
||||
- [Issues](https://codeberg.org/loki5512344/Loreport/issues) - для багов
|
||||
- [Discussions](https://codeberg.org/loki5512344/Loreport/discussions) - для вопросов
|
||||
- Discord сервер разработчика (ссылка в профиле)
|
||||
|
||||
### Q: Планируются ли новые функции?
|
||||
A: Да! Планируется:
|
||||
- Веб-панель для управления репортами
|
||||
- Система категорий репортов
|
||||
- Автоматические действия (бан, кик)
|
||||
- Интеграция с другими плагинами модерации
|
||||
Loading…
Add table
Add a link
Reference in a new issue