CustomItemsLib

CustomItemsLib

CustomItemsLib provides the shared item, reward, storage and security infrastructure used by the maintained releases of BagOfGold and MobHunting.

It is a library plugin. Installing CustomItemsLib by itself does not add an economy, hunting rewards or other gameplay mechanics.

Maintained fork

This project is maintained by Becerritoo and continues the work originally created by Rocologo. The original author remains fully credited.

Plugin relationship

CustomItemsLib 1.4.0
        |
        +-- BagOfGold 4.8.0
        +-- MobHunting 8.7.1

CustomItemsLib provides general infrastructure. BagOfGold and MobHunting own their respective economy and gameplay behavior.

Features

• Creates, identifies, signs and validates shared reward items.
• Combines, splits, places, breaks, drops and collects reward items safely.
• Maintains reward-token security records to prevent a spent token from being accepted more than once.
• Provides signed metadata for consumer-owned items that must remain separate from normal rewards or currency.
• Exposes public APIs, events and Bukkit service interfaces for consumer plugins.
• Provides shared player settings, presentation helpers and storage services.
• Provides textured player heads without incorrectly attaching reward metadata.
• Supplies a shared Hangar update service for maintained companion plugins.
• Preserves compatibility entry points required by earlier consumer releases.

Requirements

Paper 1.21.11 is the currently tested server version. Compatibility with other Minecraft versions is not guaranteed unless explicitly listed on a release.

CustomItemsLib can start and stop without BagOfGold or MobHunting, but it does not provide standalone gameplay features.

Installation

1. Place CustomItemsLib-1.4.0.jar in the server's plugins directory.
2. Install the matching BagOfGold or MobHunting release that requires it.
3. Remove older duplicate JAR files for the same plugin.
4. Start or fully restart the server.

The recommended maintained combinations are:

• CustomItemsLib 1.4.0 with BagOfGold 4.8.0.
• CustomItemsLib 1.4.0 with MobHunting 8.7.1.
• All three companion releases together.

Responsibility boundaries

CustomItemsLib owns general reward-item behavior, shared security records and library services.

BagOfGold owns:

• Physical-currency balances and policy.
• Debt and bank accounts.
• Vault economy registration.
• Shopkeepers payments and price templates.
• Citizens banker NPCs.

MobHunting owns:

• Kill detection and reward calculation.
• Penalties, achievements and bounties.
• Leaderboards and mob integrations.
• Hunting statistics and gameplay configuration.

Consumer-specific services are registered through Bukkit's ServicesManager. CustomItemsLib does not require implementation classes from either consumer in order to start.

Signed item infrastructure

CustomItemsLib distinguishes normal reward items from signed data owned by a consumer plugin. This allows BagOfGold to create secure currency and Shopkeepers price templates without those objects being treated as generic rewards.

Existing metadata keys and serialized values are retained where compatibility requires them. Changes to item signatures or storage formats are documented by the consumer plugin that owns the affected data.

Update service

The shared updater checks Hangar for releases that are:

• Public and reviewed.
• Published in the stable release channel.
• Compatible with the server's exact Paper version.

Before staging an update, it validates the download filename, declared file size and SHA-256 checksum. The installed JAR filename is preserved when the update is placed in Bukkit's update directory.

Optional integrations

CMI and CMILib are separate optional integrations:

• CMI provides its hologram API when enabled and available.
• CMILib provides action-bar and boss-bar message support.

Each integration has its own configuration setting. Neither is required for CustomItemsLib to start.

Other optional compatibility hooks may remain available for consumer plugins. Their presence in the source does not imply that every integration received runtime testing for this release.

Basic commands

• /cil version — Displays the installed version and checks for updates.
• /cil reload — Reloads the CustomItemsLib configuration.
• /cil update — Checks Hangar for a compatible reviewed release.
• /cil debug — Enables or disables diagnostic logging.

Administrative commands require their corresponding customitemslib.* permissions.

Developer documentation

The maintained architecture and service boundaries are documented in the source repository:

• Architecture
• Release notes

Support and source code

• Maintained source code
• Bug reports and feature requests
• Original source code
• Original SpigotMC project

If you are the original author and would like to coordinate maintenance or project access, please contact me through GitHub.