EN MerluAIguard 🛡️

MerluAIguard is a cutting-edge anti-cheat system for Minecraft Bedrock (Lumi Core/Nukkit), leveraging deep learning (LSTM neural networks) to analyze player behavior in real-time. 🚀 Key Features

Deep Learning Analysis: Utilizes a 3-layer LSTM neural network to detect complex cheat patterns.

Real-time Detection: Processes 40-tick sequences for precise decision-making.

Telegram Notifications: Instant alerts with cheat probability sent directly to your messenger.

Flexible Punishments: Supports BAN (auto-ban) and REPORT (admin notification) modes.

GPU Acceleration: CUDA support for ultra-fast model training.

Optimized Inference: Powered by ONNX Runtime for minimal CPU overhead on the game server.

🏗️ Architecture

The project is split into two components:

Java Plugin: Data collector (packet sniffer) and communication bridge.

Python Service: FastAPI-based server performing model inference and training.

🛠️ Installation

1. Java Plugin

   Build the project using Maven: Bash

   cd plugin mvn clean package

   Copy target/MerluAIguard-1.0.0.jar to your server's plugins folder.

2. AI Service (Python)

Using Docker (Recommended):

Ensure you have Docker and NVIDIA Container Toolkit installed (for GPU support).

Start the service:
Bash

docker-compose up -d

Manual Setup:

Install dependencies:
Bash

pip install -r ai_service/requirements.txt

Run the server:
Bash

python ai_service/main.py

⚙️ Configuration

After the first launch, edit plugins/MerluAIguard/config.yml with your settings:

python-service-url: Your Python service endpoint.

action-mode: BAN or REPORT.

telegram-token / chat-id: Your Telegram bot credentials for alerts.

🧠 Training Process

The system comes without a pre-trained model, as every server environment is unique.

Data Collection:

    /ai train add <player> 0 — Record legitimate gameplay.

    /ai train add <player> 1 — Record gameplay using cheats.

Training:

    Once enough data is collected, run /ai train start.

Activation:

    After training is complete, enable protection: /ai start.

📊 Feature Engineering

The system analyzes the following parameters:

delta_xyz: Movement speed and velocity.

delta_rotation: Head rotation sharpness (Yaw/Pitch).

cps: Clicks per second.

reach: Combat hit distance.

hitbox_angle: Precision of targeting.

motion_consistency: Movement smoothness and acceleration patterns.

📄 License

MIT License. Created by: merlusha

RU

MerluAIguard 🛡️

MerluAIguard — это современная античит-система для Minecraft Bedrock (Lumi Core/Nukkit), использующая глубокое обучение (LSTM нейросети) для анализа поведения игроков в реальном времени.

🚀 Основные возможности

• Deep Learning Анализ: Использует 3-слойную LSTM нейросеть для выявления сложных паттернов читов.
• Real-time Детекция: Обработка 40-тиковых последовательностей для точного вердикта.
• Telegram Уведомления: Мгновенные алерты с вероятностью чита прямо в ваш мессенджер.
• Гибкие Наказания: Поддержка режимов BAN (автобан) и REPORT (уведомление администрации).
• GPU Ускорение: Поддержка CUDA для сверхбыстрого обучения нейросети.
• Оптимизированный Инференс: Использование ONNX Runtime для минимальной нагрузки на CPU сервера.

🏗️ Архитектура

Проект разделен на две части:

1. Java Plugin: Сборщик данных (Data Collector) и мост связи.
2. Python Service: FastAPI сервер, выполняющий инференс и обучение модели.

🛠️ Установка

1. Java Плагин

1. Соберите проект через Maven:

   cd plugin
   mvn clean package

2. Скопируйте target/MerluAIguard-1.0.0.jar в папку plugins вашего сервера.

2. AI Сервис (Python)

Через Docker (Рекомендуется):

1. Убедитесь, что у вас установлен Docker и NVIDIA Container Toolkit (для GPU).
2. Запустите сервис:

   docker-compose up -d

Вручную:

1. Установите зависимости:

   pip install -r ai_service/requirements.txt

2. Запустите сервер:

   python ai_service/main.py

⚙️ Конфигурация

После первого запуска в plugins/MerluAIguard/config.yml появятся настройки:

• python-service-url: URL вашего Python сервиса.
• action-mode: BAN или REPORT.
• telegram-token / chat-id: Данные вашего бота для уведомлений.

🧠 Процесс обучения

Система поставляется без предобученной модели, так как каждый сервер уникален.

1. Сбор данных:
   • /ai train add <ник> 0 — запись легитной игры.
   • /ai train add <ник> 1 — запись игры с читами.
2. Обучение:
   • Когда соберете достаточно данных, пропишите /ai train start.
3. Запуск:
   • После завершения обучения включите защиту: /ai start.

📊 Feature Engineering

Система анализирует следующие параметры:

• delta_xyz: Скорость перемещения.
• delta_rotation: Резкость поворотов головы.
• cps: Кликов в секунду.
• reach: Дистанция удара.
• hitbox_angle: Точность наведения на цель.
• motion_consistency: Плавность движений.

📄 Лицензия

MIT License. Автор: merlusha