物品封禁

物品封禁

为服务器管理员设计的Minecraft Forge模组，用于灵活管理和限制游戏内物品，同时支持软封禁和硬封禁以维护服务器平衡与游戏规则。

游戏机制

BanItems 模组

English | 简体中文

一个为服务器管理员设计的 Minecraft Forge 模组，用于灵活管理和限制游戏内物品，支持软禁用和硬禁用两种模式，以维护服务器平衡和游戏规则。

核心功能

BanItems 提供针对性的物品控制以及用户友好的管理工具，确保服务器规则得以执行而不影响玩家体验：

  • 双模式禁用：
    • 软禁用：限制物品功能（例如，禁止放置方块、使用工具），同时允许玩家在物品栏中保留该物品。
    • 硬禁用：完全阻止玩家获得、持有或使用该物品（检测到时会自动移除该物品）。
  • 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 页面）：

  1. 安装 Forge：为您的目标 Minecraft 版本下载并安装 Minecraft Forge（例如，1.20.1-forge-47.1.0）。
  2. 下载模组：从 GitHub Releases 或您偏好的模组平台获取最新的 BanItems JAR 文件。
  3. 添加到 Mods 文件夹：
    • 服务器：将 JAR 文件放入服务器的 mods/ 目录。
    • 客户端（单人游戏或访问服务器）：将 JAR 文件放入本地 .minecraft/mods/ 目录。
  4. 启动服务器/客户端：启动 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 的参考实现。

本地构建设置

  1. 克隆仓库：
    git clone https://github.com/YuWan-030/BanItems.git
cd BanItems
  2. 使用 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！