BanItems 模组
English | 简体中文
一款专为服务器管理员设计的 Minecraft Forge 模组,用于灵活管理和限制游戏内物品。它支持软禁和硬禁两种模式,以维护服务器平衡与游戏规则。
核心功能
BanItems 提供针对特定物品的控制,并配备易于使用的管理工具,在确保服务器规则被执行的同时,不会破坏玩家的游戏体验:
- 双模式禁令:
- 软禁(Soft Ban):限制物品功能(例如防止放置方块、使用工具),但允许玩家将其保留在背包中。
- 硬禁(Hard Ban):完全阻止玩家获取、持有或使用该物品(若检测到则自动移除)。
- NBT 感知限制:通过识别 NBT 数据而非仅基础物品 ID,禁止特定的物品变体(例如附魔剑、自定义命名的药水)。
- 直观的管理界面 (GUI):
- 采用游戏内库存风格的 GUI 来添加或移除被禁物品(无需手动编辑配置文件)。
- 显示被禁物品的视觉预览及其详细信息(例如禁令类型、NBT 标签)。
- 全面的命令集:通过游戏内命令快速访问禁令管理、列表查看和配置重载功能。
- 持久化配置:被禁物品列表保存在 JSON 文件中,确保规则在服务器重启后依然有效。
命令
所有命令均需 banitems.admin 权限(默认授予服务器操作员)。在游戏中使用 /banitem help 可快速查阅参考信息:
| 命令 |
描述 |
/banitem soft |
打开 GUI 将物品添加到软禁列表 |
/banitem hard |
打开 GUI 将物品添加到硬禁列表 |
/banitem list soft [page] |
查看所有被软禁的物品(支持分页,例如 /banitem list soft 2) |
/banitem list hard [page] |
查看所有被硬禁的物品(支持分页) |
/banitem reload |
重新加载配置文件(无需重启服务器即可应用更改) |
/banitem help |
显示所有可用命令及使用说明 |
安装
BanItems 是一款 Forge 模组——请确保你的服务器/客户端使用的是兼容的 Minecraft Forge 版本(有关版本详情,请参阅 Releases 页面):
- 安装 Forge:为你的目标 Minecraft 版本下载并安装 Minecraft Forge(例如 1.20.1-forge-47.1.0)。
- 下载模组:从 GitHub Releases 或你喜欢的模组平台获取最新的 BanItems JAR 文件。
- 添加到 Mods 文件夹:
- 对于服务器:将 JAR 文件放入服务器的
mods/ 目录中。
- 对于客户端(单人游戏或加入服务器):将 JAR 文件放入本地
.minecraft/mods/ 目录中。
- 启动服务器/客户端:启动 Minecraft——BanItems 将自动初始化并创建默认配置文件。
配置
BanItems 使用人类可读的 JSON 配置文件来存储禁令规则,以便在需要时轻松进行手动编辑:
配置文件路径
- 服务器/客户端:
config/banitems/banitems.json
配置结构
该文件包含三个关键部分(首次启动时自动生成):
{
"softBannedItems": [], // 功能受限的物品(例如 ["minecraft:ender_pearl"])
"hardBannedItems": [], // 禁止使用/拥有的物品(例如 ["minecraft:creative_only_item"])
"excluded": [] // 豁免在被禁物品箱中替换的物品 ID(例如 ["minecraft:wooden_chest"])
}
- 编辑提示:建议使用游戏内 GUI/命令进行更安全的操作——手动编辑后需执行
/banitem reload 才能生效。
开发
BanItems 遵循 Minecraft Forge 的最佳实践,代码结构受到社区标准启发,并参考了 itembarriers
本地构建设置
- 克隆仓库:
git clone https://github.com/YuWan-030/BanItems.git
cd BanItems
- 使用 Gradle 构建:
- Windows:
gradlew.bat build
- Linux/macOS:
./gradlew build
获取构建好的 JAR:编译后的模组 JAR 文件将位于 build/libs/ 中(查找没有 -sources 或 -dev 后缀的文件)。
贡献指南
- Fork 仓库并创建一个功能分支(例如
feature/add-whitelist)。
- 遵循现有的代码风格(与 Forge 模组开发规范保持一致)。
- 在提交拉取请求之前,先在本地测试更改。
许可证
BanItems 根据 MIT 许可证授权——请参阅 LICENSE 文件以获取完整条款。你可以自由地:
- 在公开/私有服务器上使用该模组。
- 为个人用途修改代码。
- 在注明出处的情况下分发修改后的版本。
鸣谢
- 框架:基于 Minecraft Forge 构建,这是 Minecraft 事实上的模组开发框架。
- 灵感:模组设计与功能汲取了社区反馈以及 itembarriers 中引用的模组开发概念。
- 维护:该项目由 YuWan-030 积极维护(请访问 GitHub 仓库查看最新更新)。
如有问题、功能请求或需要支持,请在 GitHub 上提交 Issue!
BanItems Mod
English | 简体中文
A Minecraft Forge mod designed for server administrators to flexibly manage and restrict in-game items, supporting both soft bans and hard bans to maintain server balance and gameplay rules.
Core Features
BanItems provides targeted item control with user-friendly management tools, ensuring server rules are enforced without disrupting player experience:
- Dual Ban Modes:
- Soft Ban: Restrict item functionality (e.g., prevent placing blocks, using tools) while allowing players to keep the item in their inventory.
- Hard Ban: Fully block players from obtaining, holding, or using the item (automatically removes the item if detected).
- NBT-Aware Restrictions: Ban specific item variants (e.g., enchanted swords, custom-named potions) by recognizing NBT data, not just base item IDs.
- Intuitive GUI Management:
- In-game inventory-style GUI for adding/removing banned items (no manual config editing required).
- Visual previews of banned items with details (e.g., ban type, NBT tags).
- Comprehensive Command Set: Quick access to ban management, list viewing, and config reloading via in-game commands.
- Persistent Configuration: Banned item lists are saved to a JSON file, ensuring rules persist across server restarts.
Commands
All commands require the banitems.admin permission (granted to server operators by default). Use /banitem help in-game for a quick reference:
| Command |
Description |
/banitem soft |
Open GUI to add an item to the soft ban list |
/banitem hard |
Open GUI to add an item to the hard ban list |
/banitem list soft [page] |
View all soft-banned items (supports pagination, e.g., /banitem list soft 2) |
/banitem list hard [page] |
View all hard-banned items (supports pagination) |
/banitem reload |
Reload the configuration file (applies changes without restarting the server) |
/banitem help |
Show all available commands and usage instructions |
Installation
BanItems is a Forge mod—ensure your server/client uses a compatible Minecraft Forge version (check the Releases page for version details):
- Install Forge: Download and install Minecraft Forge for your target Minecraft version (e.g., 1.20.1-forge-47.1.0).
- Download Mod: Get the latest BanItems JAR from the GitHub Releases or your preferred mod platform.
- Add to Mods Folder:
- For servers: Place the JAR in your server’s
mods/ directory.
- For clients (single-player or server access): Place the JAR in your local
.minecraft/mods/ directory.
- Start Server/Client: Launch Minecraft—BanItems will auto-initialize and create default config files.
Configuration
BanItems uses a human-readable JSON config file to store ban rules, making manual edits easy if needed:
Config Path
- Server/Client:
config/banitems/banitems.json
Config Structure
The file includes three key sections (auto-generated on first launch):
{
"softBannedItems": [], // Items with restricted functionality (e.g., ["minecraft:ender_pearl"])
"hardBannedItems": [], // Items blocked from use/ownership (e.g., ["minecraft:creative_only_item"])
"excluded": [] // Item IDs exempt from being replaced in banned item boxes (e.g., ["minecraft:wooden_chest"])
}
- Edit Tips: Use the in-game GUI/commands for safer management—manual edits require a
/banitem reload to take effect.
Development
BanItems follows Minecraft Forge best practices, with code structure inspired by community standards and references from itembarriers
Local Build Setup
- Clone Repository:
git clone https://github.com/YuWan-030/BanItems.git
cd BanItems
- Build with Gradle:
- Windows:
gradlew.bat build
- Linux/macOS:
./gradlew build
Retrieve Built JAR: The compiled mod JAR will be in build/libs/ (look for the file without -sources or -dev suffix).
Contribution Guidelines
- Fork the repository and create a feature branch (e.g.,
feature/add-whitelist).
- Follow the existing code style (consistent with Forge modding conventions).
- Test changes locally before submitting a pull request.
License
BanItems is licensed under the MIT License—see the LICENSE file for full terms. You are free to:
- Use the mod on public/private servers.
- Modify the code for personal use.
- Distribute modified versions with attribution.
Credits
- Framework: Built with Minecraft Forge, the de facto modding framework for Minecraft.
- Inspiration: Mod design and functionality draw from community feedback and modding concepts referenced at itembarriers.
- Maintenance: The project is actively maintained by YuWan-030 (check the GitHub repository for latest updates).
For issues, feature requests, or support, please open an issue on GitHub!
评论 0
登录后参与评分
还没有评论,来抢沙发吧