Piggy Admin
一款旨在帮助管理和强制执行兼容的客户端模组(如 Piggy Build 和 Piggy Inventory)设置的服务器端管理模组。目前,它作为管理反作弊选项、日志记录和检测的中心点,但未来将扩展以包含更多管理工具。
⚠️ 免责声明
这是一个个人项目。 它按原样提供,可能会导致问题。
- 无支持: 不要指望获得常规支持或错误修复。
- 无 Forge 移植版: 没有计划将此模组移植到 Forge。
- 使用风险自负。
如果您想贡献修复或功能,请随意 Fork 该项目或提交 Pull Request!
功能
?️ 反作弊执行
- 集中控制:配置您的服务器上是否允许“作弊”功能(如快速放置、工具切换)。
- 自动同步:当玩家加入时,服务器的反作弊配置会自动发送到其客户端。
- 严格执行:如果服务器禁用作弊,客户端端的覆盖将被忽略,确保公平竞争。
- 细粒度控制:单独启用/禁用特定功能(例如,允许工具切换但禁止快速放置)。
?️ 高级 X-Ray 检测
Piggy Admin 使用多层启发式引擎来检测可疑的挖掘模式,同时避免分支挖矿带来的误报。
- 矿石缓存管理器:异步跟踪有价值矿石的位置,使用高效的
ConcurrentHashMap,将对主线程的影响降至最低。
- 向量相关性:使用
HeuristicsMathUtil 计算玩家的视线向量与不可见矿石距离之间的数学相关性。
- 混合检测器:结合原始挖掘比率与对“可疑转向”和“直达矿石路径”的语义分析。
- 灵敏度级别:从
LOW(宽松)到 PARANOID(严格),可通过 xraySensitivity 进行配置。
- 管理员警报:实时通知管理员,并提供可点击的传送链接以跳转到嫌疑人的坐标。
? 法医数据与归因
该模组充当了针对恶意破坏的强大调查工具。
- 爆炸归因:追踪 TNT 的真正所有者,即使是由燧石和铁锹、火球或其他实体点燃的。
- 苦力怕所有权:识别故意点燃苦力怕(使用燧石和铁锹)以摧毁领土的玩家。
- 熔岩与火灾责任:流体流动和方块火势蔓延的专业跟踪器。即使原始源方块已消失,模组也会维护谁放置它的历史记录。
- 发射器跟踪:在发射器级别的自定义 mixins 将所有发射的投射物或桶操作归因于放置或最后与发射器交互的玩家。
- 交互式通知:
AdminNotifier 向 OP 发送丰富的、可悬停的聊天组件,允许直接从警报中进行即时“责任追究查询”。
? 审核引擎
- AI 驱动审核:集成 Google Gemini AI 以自动过滤有毒或不适宜的聊天和告示牌文本。
- 动态规则系统:定义自定义审核规则和类别(例如,脏话、骚扰、仇恨言论)。
- 性能优化:包括高性能缓存和速率限制系统,以最小化 API 延迟并优雅地处理免费 tier API 限制。
- 混合检查:结合快速的本地 Regex 检查与来自 Gemini 的深度语义分析。
- 分类日志:所有被阻止的消息都按其特定类别记录,以便轻松审查。
? Gemini AI 设置
要使用 AI 审核功能,您需要一个 Google Gemini API 密钥。
- 获取 API 密钥:访问 Google AI Studio 并创建一个免费的 API 密钥。
- 配置模组:
- 启动服务器一次以生成配置文件。
- 打开
config/piggy-admin-server.json。
- 将您的密钥粘贴到
"geminiApiKey" 字段中。
- 设置
"moderationEnabled": true。
- 高级选项:
geminiModel:默认为 gemini-1.5-flash(推荐用于速度和成本)。
geminiSystemPrompt:您可以在此处自定义 AI 的“个性”和严格程度。
[!NOTE]
Gemini 的免费 tier 有速率限制(每分钟约 15 次请求)。模组内置了缓存和速率限制器,以优雅地处理这些限制,而不会导致服务器卡顿。
? 历史与日志
- 告示牌历史:追踪谁放置了告示牌以及上面写了什么。
- 聊天历史:记录所有聊天消息以供管理员审查。
- 爆炸日志:详细的 TNT 放置、点燃和爆炸日志,尽可能包括玩家归因。
- 责任追究工具:检查现有的告示牌/方块,查看谁与之交互过以及何时交互。
- 持久存储:历史数据在服务器重启后依然存在(保存至
config/piggy-admin-history.json)。
命令
所有命令都需要 OP 等级 2 或更高。
通用管理
/piggy cheats <allow|forbid>:全局允许或禁止所有玩家的“作弊”功能。
/piggy feature list:列出所有可控功能及其当前状态。
/piggy feature <id> <enable|disable>:启用或禁用特定功能(例如 flexible_placement, tool_swap)。
/piggy sync:手动触发将所有管理设置和审核规则同步到所有连接的客户端。
调查与日志记录
-
/blame: 观察一个方块或告示牌并运行此命令,以查看其交互历史。
-
/logs <玩家>: 查看某位玩家的分类历史记录(聊天、告示牌、火焰、爆炸、管理)。
- 可点击传送:日志条目包含坐标,你可以点击这些坐标以前往现场进行调查。
-
/piggy xray <clear|stats>:管理 X 射线启发式缓存或查看当前玩家排名。
配置
该模组会在 config/piggy-admin-server.json(服务器端)生成一个配置文件。
{
"allowCheats": false,
"features": {
"flexible_placement": true,
"fast_place": false,
"tool_swap": true
},
"xrayCheck": true,
"xrayMaxRatio": 0.15,
"xrayMinBlocks": 20,
"moderationEnabled": true,
"geminiApiKey": "YOUR_KEY",
"geminiModel": "gemini-1.5-flash"
}
"allowCheats": false: 强制所有已连接客户端禁用受限功能。
"allowCheats": true: 允许客户端使用其本地设置。
"features": 对各个功能进行细粒度控制。
"xrayMaxRatio": 稀有矿石占总方块的最大允许比例(默认 15%)。
"xrayMinBlocks": X-Ray 检测激活前最少挖掘的方块数(默认 20)。
"xrayCheck": 切换 X-Ray 检测系统。
"moderationEnabled": 切换 AI 和正则表达式审查引擎。
"geminiApiKey": 你的 Google Gemini API 密钥。
"geminiModel": 要使用的 Gemini 模型(默认:gemini-1.5-flash)。
依赖与安装
要求
- Minecraft: ~1.21.1
- Fabric Loader: >=0.18.1
- Java: >=21
必需模组
安装方法
- 从 Releases 下载
.jar 文件。
- 为 Minecraft 1.21.1 安装 Fabric Loader。
- 将
piggy-admin jar 文件(连同 Fabric API 和 Piggy Lib)放入服务器的 mods 文件夹中。
- 启动服务器!
待办事项 / 未来功能
- 检测 XRay:实现启发式算法/检查机制,以检测使用 XRay 资源包或模组的玩家。
- 审查告示牌文本:添加工具来检查和过滤告示牌上的文本,以防止不当内容。
灵感来源
本模组受到以下项目的启发:
许可证: CC0-1.0
Piggy Admin
A server-side administration mod designed to help manage and enforce settings for compatible client-side mods (like Piggy Build and Piggy Inventory). Currently, it serves as a central point for managing anti-cheat options, logging, and detection, but it will evolve to include more administration tools.
⚠️ Disclaimer
This is a personal project. It comes AS IS and might cause issues.
- No Support: Do not expect regular support or bug fixes.
- No Forge Port: There are NO plans to port this mod to Forge.
- Use at your own risk.
Feel free to fork the project or submit a Pull Request if you want to contribute fixes or features!
Features
?️ Anti-Cheat Enforcement
- Centralized Control: Configure whether "cheat" features (like fast placement, tool swapping) are allowed on your server.
- Automatic Sync: When a player joins, the server's anti-cheat configuration is automatically sent to their client.
- Strict Enforcement: If the server disables cheats, client-side overrides are ignored, ensuring fair play.
- Granular Control: Enable/disable specific features individually (e.g., allow tool swapping but forbid fast placement).
?️ Advanced X-Ray Detection
Piggy Admin uses a multi-layered heuristic engine to detect suspicious mining patterns without false positives from branch mining.
- Ore Cache Manager: Asynchronously tracks valuable ore locations in an efficient
ConcurrentHashMap, minimizing main-thread impact.
- Vector Correlation: Uses
HeuristicsMathUtil to calculate the mathematical correlation between a player's look vector and the distance to invisible ores.
- Hybrid Detector: Combines raw mining ratios with semantic analysis of "suspicious turns" and "direct-to-ore" paths.
- Sensitivity Levels: From
LOW (relaxed) to PARANOID (strict), configurable via xraySensitivity.
- Admin Alerts: Real-time notifications for admins with clickable teleport links to the suspect's coordinates.
? Forensic Data & Attribution
The mod acts as a powerful investigation tool for griefing.
- Explosion Attribution: Tracks the true owner of TNT, even if sparked by a flint-and-steel, fire charge, or other entities.
- Creeper Ownership: Identifies players who intentionally ignite creepers (using Flint & Steel) to destroy territory.
- Lava & Fire Blame: Specialized trackers for fluid flow and block-fire spread. Even if the original source block is gone, the mod maintains a history of who placed it.
- Dispenser Tracking: Custom mixins at the dispenser level attributes all dispensed projectiles or bucket operations to the player who placed or last interacted with the dispenser.
- Interactive Notifications:
AdminNotifier sends rich, hoverable chat components to OPs, allowing for instant "Blame Lookup" directly from an alert.
? Moderation Engine
- AI-Powered Moderation: Integrates with Google Gemini AI to automatically filter toxic or inappropriate chat and sign text.
- Dynamic Rule System: Define custom moderation rules and categories (e.g., Profanity, Harassment, Hate Speech).
- Performance Optimized: Includes a high-performance cache and rate-limiting system to minimize API latency and handle free-tier API limits gracefully.
- Hybrid Checking: Combines fast local Regex checks with deep semantic analysis from Gemini.
- Categorized Logs: All blocked messages are logged with their specific category for easy review.
? Gemini AI Setup
To use the AI moderation features, you need a Google Gemini API Key.
- Get an API Key: Visit the Google AI Studio and create a free API key.
- Configure the Mod:
- Start the server once to generate the config file.
- Open
config/piggy-admin-server.json.
- Paste your key into the
"geminiApiKey" field.
- Set
"moderationEnabled": true.
- Advanced Options:
geminiModel: defaults to gemini-1.5-flash (recommended for speed and cost).
geminiSystemPrompt: You can customize the AI's "personality" and strictness here.
[!NOTE]
The free tier of Gemini has rate limits (approx. 15 requests per minute). The mod includes a built-in cache and rate-limiter to handle these limits gracefully without lagging the server.
? History & Logging
- Sign History: Tracks who placed a sign and what was written on it.
- Chat History: Logs all chat messages for administrative review.
- Explosion Logging: Detailed logs for TNT placement, ignition, and explosions, including player attribution whenever possible.
- Blame Tool: Inspect existing signs/blocks to see who interacted with them and when.
- Persistent Storage: History survives server restarts (saved to
config/piggy-admin-history.json).
Commands
All commands require OP level 2 or higher.
General Administration
/piggy cheats <allow|forbid>: Globally allow or forbid "cheat" features for all players.
/piggy feature list: List all controllable features and their current status.
/piggy feature <id> <enable|disable>: Enable or disable a specific feature (e.g., flexible_placement, tool_swap).
/piggy sync: Manually trigger a synchronization of all admin settings and moderation rules to all connected clients.
Investigation & Logging
/blame: Look at a block or sign and run this to see the interaction history.
- Works on: Fire, Lava, Signs, Containers, and exploded regions.
/logs <player>: View a categorized history for a player (Chat, Sign, Fire, Explosion, Moderation).
- Clickable Teleports: Log entries include coordinates that you can click to investigate the scene.
/piggy xray <clear|stats>: Manage the X-Ray heuristic cache or view current player standings.
Configuration
The mod generates a configuration file at config/piggy-admin-server.json (server-side).
{
"allowCheats": false,
"features": {
"flexible_placement": true,
"fast_place": false,
"tool_swap": true
},
"xrayCheck": true,
"xrayMaxRatio": 0.15,
"xrayMinBlocks": 20,
"moderationEnabled": true,
"geminiApiKey": "YOUR_KEY",
"geminiModel": "gemini-1.5-flash"
}
"allowCheats": false: Forces all connected clients to disable restricted features.
"allowCheats": true: Allows clients to use their own local settings.
"features": Granular control over individual features.
"xrayMaxRatio": Maximum allowed ratio of rare ores to total blocks (default 15%).
"xrayMinBlocks": Minimum blocks mined before X-Ray detection activates (default 20).
"xrayCheck": Toggle the X-Ray detection system.
"moderationEnabled": Toggle the AI and Regex moderation engine.
"geminiApiKey": Your Google Gemini API Key.
"geminiModel": The Gemini model to use (default: gemini-1.5-flash).
Dependencies & Installation
Requirements
- Minecraft: ~1.21.1
- Fabric Loader: >=0.18.1
- Java: >=21
Required Mods
Installation
- Download the
.jar file from Releases.
- Install Fabric Loader for Minecraft 1.21.1.
- Place the
piggy-admin jar (along with Fabric API and Piggy Lib) into your server's mods folder.
- Launch the server!
Todo / Future Features
- Detect XRay: Implement heuristics/checks to detect players using XRay texture packs or mods.
- Moderate Sign Text: Add tools to inspect and filter text on signs to prevent inappropriate content.
Inspiration
This mod was inspired by:
- ItemSwapper - For the concept of server-side item management and swapping mechanics.
License: CC0-1.0
评论 0
登录后参与评分
还没有评论,来抢沙发吧