Описание
# BanItems Mod
[English](https://github.com/YuWan-030/BanItems/README.md) | [简体中文](https://github.com/YuWan-030/BanItems/README.zh-CN.md)
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):
1. Install Forge: Download and install Minecraft Forge for your target Minecraft version (e.g., 1.20.1-forge-47.1.0).
2. Download Mod: Get the latest BanItems JAR from the GitHub Releases or your preferred mod platform.
3. 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.
4. 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):
```json
{
"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](https://github.com/linstarowo/itembarriers)
### Local Build Setup
1. **Clone Repository**:
```bash
git clone https://github.com/YuWan-030/BanItems.git
cd BanItems
2. **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](https://github.com/linstarowo/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!