Sauron is a fully customizable open-source plugin that allows you to define groups of items that have to be tracked (for instance: the rares customs items).
Duplicates of those tracked items will be automatically cleared, making it virtually impossible to dupe the tracked items.

What's the point ?

• Automatic tracking of items based on customizable rules: allows you to make items non fungible
• Blacklist groups of items you don't want to see on your server
  
• Refund players without having the fear that they hid the item somewhere (after servers crashes for instance)
  
• Find and contain duplication exploits

Sauron is great in addition with logs plugins such as InventoryRollbackPlus and CoreProtect.
Features

• MySQL, SQLite, MariaDB, postgreSQL, oracle, SQLServer database support
• Full async operations and optimized handling of database requests (see "performance")
• Robust database system: if for any reason some requests had to fail, the plugin won't break.
  
• Fully customizable, from messages to tracking rules.
• Lightweight log system to keep track of incidents (dupe found, blacklisted item found, etc)

Usage

1. Upload the jar to your plugins' folder and restart your server (or load the jar using a plugman)
2. Design your tracking rules (see below) and customize the plugin based on your needs with the config
3. /sauron reload and enjoy !
4. Recommanded: Add the sauron.exempt perm to your (safe) admins to avoid them accidentally updating (like by duplicating) the timestamp of players' item!

Performance
Altough it will highly depend on how many items are tracked on your server, the plugin can handles large amounts of players/items very well. Sauron does not appear in a typical spark profile.


How does it work ?

Sauron keeps an eye on players' inventories. For every item, if it should be track, an unique sauron_id UUID and sauron_date timestamp is added automatically, making it tracked. It then add an entry in the database for that UUID.
Each time a tracked item is scanned, it compares the item's physical timestamp with the database item's timestamp. If item's timestamp is earlier than database's timestamp, then it means that the item has been duplicated in the interval of time between the two timestamps.


/!\ By design, it is not possible to track stacked items. The plugin will never put a tracker on stacked items, except if specially told to do so.

Scanning process

Currently, the plugin scans items in two different ways:

• When an item is taken in hand by the player
• When a player opens a container (plugins containers excluded)
  
• Every now and then, the plugin goes through each player inventories and scan their contents.

The plugin will soon provide an API to add whatever way of scanning you'd like.

Designing Tracking Rules

Here's an example of 2 tracking rules in the config, one for tracking items and one for illegal item that have to be cleared :

Code (YAML):

 items-to-track:
    super-weapons:
      contains :
       - custom
        - OP
      materials :
       - DIAMOND_SWORD
        - DIAMOND_AXE
      flags :
       - HIDE_UNBREAKABLE
      unbreakable : true
      has_nbt :
       - yronusaTest
  illegal-items:
    ruleIllegal:
      unbreakable : true
      materials :
       - DIAMOND_SWORD

 

For an item to "check" a tracking rule, it has to check all of its compounds.
Inside each compound, it need to check at least one of the parameters provided.

You can specify the following parameters (inside a compound):

• contains: does the item contains one of the words of the list?
• materials: does the item is of one of those materials ?
• has_nbt: does the item have that particular nbt :
• unbreakable: is the item unbreakable ?
• flags: has the item one of those flags ?

If the item verify all of those parameters, then it will be tracked.
If a parameter is not specified, the plugin will consider it being verified by default.

Spoiler: Why that design?

Tracking rules are made to be at most inclusive as possible. The idea is to be able to design "groups of items". Indeed in a lot of server there are a lot of different custom rares items and it would be too long to track each of them independently.

Commands

• /sauron : shows the plugin's help page
• /sauron tracked : shows a list of tracked item (not implemented yet)
• /sauron track : tracks the current item you have in hand. Beware, you must not have sauron.exempt perm for it to work.
  
• /sauron refund : With a tracked item in hand, blacklist its UUID and resets it, so you can give it to the player who loose its item.
• /sauron stop : Stop the tracked items automatic update for the command executor. Useful for debugging of to custom items without being annoyed by the plugin.
• /sauron crash <time1> <time2> : must be used if your server crashed. Avoid clearing items if they got rollbacked to a previous state.

Permissions

• sauron.<command> for the command listed before

Settings

Code (YAML):

settings :
## How precise should console outputs be ? HIGH, MEDIUM, LOW or NONE only.
  verbose-level : HIGH
## Does the plugin should automatically updates all players' inventory ? If yes, at which rate between a general lookup, at which rate between each player, and at which rate between items in their inventories ?
  automatic-inventory-updating:
    enabled : true
    delay-between-checks : 300
    delay-between-players : 2
    delay-between-items : 0.5
## Should the database store items' base64 data ? WARNING: can be heavy
  save-item-data : false
## at which rate (in seconds) should the plugin update item's timestamp, when held in hand by a player?
  in-hand-update-interval : 10
## If a container already has been checked within that interval, won't check it again.
  container-update-interval : 10
  track-stacked-items : false
  clear-stacked-items : true

Roadmap

Although fully functional, the plugin is still in development and some features are missing but will be added soon:

• Possibility of design "blacklist rules" to clear item corresponding to that rule directly
• An API to help developers customize the plugin to their needs
• A more efficient tracker that allows to track items more often
• An in-game GUI to visualize the list of tracked items, their last update, etc
• I'm sure people will find much more ideas with that system that I do. Feel free to suggest anything you'd like, or better, make a commit.

Sauron is under GPL-3.0 license. Feel free to do everything you want with the source code. Please, consider contributing to the project, a lot can be improved !