Item Filter for Spigot/Paper (AI-Assisted)

An alternative plugin version of KawaMood's original Items Filter datapack.

If you are using GriefPrevention, WorldGuard, or Towny on your server, you might have encountered duplication bugs or land-claim issues with the original datapack. This plugin completely rewrites the system's mechanics to make it fully compatible with your usual region protections.

---

✨ Features

• Simple Filtering: Easily choose which items are allowed or blocked in your automated sorting systems.
• Per-Filter Overflow GUI: Shift + Right-click any filter to toggle between 4 modes:
  • CONTINUE (Green Concrete): Ignores the filter if storage is full.
  • BLOCK (Red Concrete): Freezes the hopper if storage is full.
  • DROP (Blue Concrete): Drops the item on the ground below the filter.
  • TRASH (Black Concrete) [NEW]: Permanently destroys the item immediately at the source.
• Full i18n System: Native localization support (EN/FR) with customizable files inside plugins/ItemsFilter/Message/.
• Easy Installation: Just drop the file into your plugins folder and restart your server.

---

📝 Credits & Origin

This project is based on the original concept of the "Items Filter" datapack created by KawaMood. To convert this concept into a plugin and fix the region-protection bugs, this project was developed with the assistance of an AI.

• Original Concept Creator: KawaMood
• License: CC BY-NC-SA 4.0

---

📥 Installation & Migration

1. Download the .jar file.
2. ⚠️ Migration note: If upgrading from an older version, you must delete the old JAR file from your plugins/ folder before placing the new one to avoid configuration corruption.
3. Place the new JAR into your server's plugins folder.
4. Restart your server.
5. (Optional) You can modify the configuration and localization files generated in the plugin's folder.

---

🎥 Media & Documentation

The plugin functions exactly like the original datapack. To learn how to use it and explore all the filtering possibilities, please refer to the video and documentation created by KawaMood:

• Explaining Video: Watch on YouTube
• Documentation & Source Concept: Original Project Page

---

📘 Commands & Permissions

Main Command: /itemsfilter (aliases: /if, /itemfilter)

Public Commands (default true)

Command	Description	Permission
/if help	Displays the full redesigned section-based help guide ([Commands], [How to Use], etc.)	itemsfilter.help
/if recipe	Gives a 5-page recipe book including instructions for the Overflow GUI	itemsfilter.command.recipe

Admin Core Commands (default op)

Command	Description	Permission
/if info	Target a filter → displays its mode (Lax/Strict), owner, position, and transferred items counter	itemsfilter.command.info
/if debug	Target a filter → full diagnostic: counters, live preview of inventories, remaining cooldown	itemsfilter.command.info
/if give [player]	Gives an Items Filter. If no player is specified, gives it to yourself	itemsfilter.command.give
/if cooldown <ticks>	Sets the transfer cooldown in ticks (default 8)	itemsfilter.command.cooldown
/if list	Lists all loaded filters in the current world (or all worlds from the console)	itemsfilter.command.list
/if reload	Reloads config + restarts tick task + respawns missing display entities	itemsfilter.command.reload

Chunk Management

Command	Description	Permission
/if chunkload on	Enables keep-chunks-loaded (filters will keep their chunks loaded)	itemsfilter.command.chunkload
/if chunkload off	Disables keep-chunks-loaded and removes all active chunk tickets	itemsfilter.command.chunkload
/if chunkload list	Lists all chunks currently kept loaded by the plugin	itemsfilter.command.chunkload
/if chunkload status	Displays tick config status and active tickets count	itemsfilter.command.chunkload
/if chunkload add <world> <chunkX> <chunkZ>	Manually adds a chunk ticket	itemsfilter.command.chunkload
/if chunkload remove <world> <chunkX> <chunkZ>	Manually removes a chunk ticket	itemsfilter.command.chunkload

Uninstallation

Command	Description	Permission
/if uninstall	Displays a confirmation message with the total number of filters to delete	itemsfilter.command.uninstall
/if uninstall confirm	Confirms and executes total deletion (filters + entities + configs)	itemsfilter.command.uninstall

Note on /if uninstall confirm: Forces synchronous loading of chunks to clean up all display/interaction entities, clears filters.yml, and removes active tickets. Chiseled Deepslate blocks remain on the map to be broken manually.

Miscellaneous & Tab Completion

• itemsfilter.use (default: true) - Allows placing an Items Filter.
• itemsfilter.craft (default: true) - Allows crafting an Items Filter.
• itemsfilter.break (default: true) - Allows breaking an Items Filter (GriefPrevention/WorldGuard/Towny remain prioritized).
• itemsfilter.overflow (default: true) - Allows players to interact with the per-filter overflow GUI.
• Tab Completion: Full auto-completion support for sub-commands, online player names, and world names.

================================================================================

🇫🇷 Version Française

Une version Plugin de Item Filter.

Si vous utilisez GriefPrevention, WorldGuard, ou Towny sur votre serveur, vous avez peut-être rencontré des bugs de duplication avec la version originale. Ce plugin remplace le fonctionnement du système pour le rendre compatible avec vos protections habituelles.

---

✨ Ce que vous pouvez faire

• Filtrage Simple : Choisissez facilement quels objets doivent passer ou être bloqués dans vos systèmes de tri.
• Menu d'Overflow par filtre : Faites Maj + clic-droit sur n'importe quel filtre pour basculer entre 4 modes :
  • CONTINUE (Béton vert) : Ignore le filtre si le stockage est plein.
  • BLOCK (Béton rouge) : Bloque l'entonnoir si le stockage est plein.
  • DROP (Béton bleu) : Éjecte l'item au sol sous le filtre.
  • TRASH (Béton noir) [NOUVEAU] : Détruit définitivement et immédiatement l'item à la source.
• Système i18n complet : Support multilingue natif (FR/EN) avec fichiers modifiables dans plugins/ItemsFilter/Message/.
• Installation facile : Mettez simplement le fichier dans votre dossier plugins et redémarrez votre serveur.

---

📝 Crédits et Origine

Ce projet est basé sur l'idée originale du datapack "Items Filter" créé par KawaMood. Pour transformer ce concept en plugin et corriger les bugs rencontrés, ce projet a été réalisé avec l'aide d'une IA.

• Créateur original du concept : KawaMood
• Licence : CC BY-NC-SA 4.0

---

📥 Installation & Migration

1. Téléchargez le fichier .jar.
2. ⚠️ Note de migration : Si vous mettez à jour depuis une version précédente, vous devez supprimer l'ancien fichier JAR du dossier plugins/ avant de mettre le nouveau afin d'éviter les corruptions de données.
3. Placez le nouveau JAR dans le dossier plugins de votre serveur.
4. Redémarrez votre serveur.
5. (Facultatif) Vous pouvez modifier la configuration et les fichiers de langue générés dans le dossier du plugin.

---

🎥 Médias & Documentation

Le fonctionnement du plugin est identique au datapack original. Pour apprendre à l'utiliser et découvrir toutes les possibilités de filtrage, vous pouvez vous référer à la vidéo et à la documentation créées par KawaMood :

• Vidéo explicative : Regarder la vidéo sur YouTube
• Documentation : Page du projet original

---

📘 Commandes & Permissions

Commande principale : /itemsfilter (alias : /if, /itemfilter)

Commandes publiques (default true)

Commande	Description	Permission
/if help	Affiche l'aide complète entièrement refondue par sections claires ([Commandes], [Utilisation], etc.)	itemsfilter.help
/if recipe	Donne un livre de recette étendu à 5 pages (texte noir lisible, intègre les modes d'Overflow)	itemsfilter.command.recipe

Commandes admin (default op)

Commande	Description	Permission
/if info	Vise un filtre → affiche son mode (Lax/Strict), owner, position, date de pose, et compteur d'items	itemsfilter.command.info
/if debug	Vise un filtre → diagnostic complet (compteurs, aperçu live des inventaires, cooldown restant)	itemsfilter.command.info
/if give [joueur]	Donne un Items Filter. Si aucun joueur n'est spécifié, se donne à soi-même	itemsfilter.command.give
/if cooldown <ticks>	Définit le cooldown de transfert en ticks (défaut 8)	itemsfilter.command.cooldown
/if list	Liste tous les filtres chargés du monde courant (ou tous les mondes depuis la console)	itemsfilter.command.list
/if reload	Recharge la config + redémarre le tick task + respawn les display entities manquantes	itemsfilter.command.reload

Gestion des Chunks

Commande	Description	Permission
/if chunkload on	Active keep-chunks-loaded (les filtres maintiendront leurs chunks chargés)	itemsfilter.command.chunkload
/if chunkload off	Désactive keep-chunks-loaded et retire tous les tickets actifs	itemsfilter.command.chunkload
/if chunkload list	Liste tous les chunks actuellement maintenus chargés par le plugin	itemsfilter.command.chunkload
/if chunkload status	Affiche la config tick (keep-chunks-loaded, nombre de tickets actifs, etc.)	itemsfilter.command.chunkload
/if chunkload add <world> <chunkX> <chunkZ>	Ajoute manuellement un chunk ticket	itemsfilter.command.chunkload
/if chunkload remove <world> <chunkX> <chunkZ>	Retire un chunk ticket	itemsfilter.command.chunkload

Désinstallation

Commande	Description	Permission
/if uninstall	Affiche un message de confirmation avec le nombre de filtres à supprimer	itemsfilter.command.uninstall
/if uninstall confirm	Confirms and executes total deletion (filters + entities + configs)	itemsfilter.command.uninstall

Comportement de /if uninstall confirm : Force le chargement synchrone de tous les chunks avec des filtres pour nettoyer proprement les entités orphelines, vide le fichier filters.yml et retire les tickets de chunks. Les blocs Chiseled Deepslate restent sur la map et doivent être cassés manuellement.

Divers & Tab completion

• itemsfilter.use (default: true) - Permet de placer un Items Filter.
• itemsfilter.craft (default: true) - Permet de crafter un Items Filter.
• itemsfilter.break (default: true) - Permet de casser un Items Filter (GriefPrevention/WorldGuard/Towny restent prioritaires).
• itemsfilter.overflow (default: true) - Permet aux joueurs d'ouvrir et d'interagir avec l'interface d'overflow.
• Tab Completion : Support complet de la complétion automatique (touche Tab) pour les sous-commandes, noms de joueurs et noms de mondes.