EmberGold

EmberGold is a premium Gold currency and configurable GUI shop built for EmberPvP on Spigot 1.8.8. It has no runtime dependencies.

Player features

• /gold opens the Gold dashboard.
• /gold balance shows the player's balance.
• /gold shop opens the category shop.
• Five free Gold can be claimed every rolling 24 hours by default.
• Purchases use a confirmation screen and are processed on the main server thread.
• Every menu uses full &6&lEMBER&e&lPVP branding with animated gold/orange borders.
• Menu openings, animation ticks, errors, purchases, and rewards have configurable sounds.
• Successful purchases and daily claims play 1.8.8-compatible visual effects.
• Physical-item purchases check inventory capacity before taking Gold.
• Shop rewards can deliver items, execute console commands, or both (when configured manually).

Staff features

• /goldadmin menu opens the settings GUI.
• Give, take, or set Gold from the GUI using the prompted player amount syntax.
• Create a category using id|Display Name.
• Hold an item and use the category editor to turn it into a shop offer.
• Enter price to sell the held item itself.
• Enter price|console command to use the held item as an icon and run a reward command.
• Left-click an offer to change its price.
• Shift-right-click an offer or category to delete it.
• Every daily claim, purchase, store grant, and balance change is recorded in audit.log.

Commands

The target player must have joined the server at least once. The grant command remembers transaction IDs in players.yml; retrying the same transaction does not add Gold twice.

Example Tebex delivery command:

goldadmin grant {username} 100 {transaction}

Use the transaction placeholder supported by your store package/system.

Permissions

• embergold.use — player menu and shop (default: everyone)
• embergold.admin — staff command and settings GUI (default: operators)
• embergold.admin.balance — change balances
• embergold.admin.shop — edit shop
• embergold.admin.reload — reload files

Manual shop configuration

plugins/EmberGold/shop.yml is hot-reloadable with /goldadmin reload. A human-readable command offer can be added beneath any category:

offers:
  ember_rank:
    material: DIAMOND_CHESTPLATE
    name: "&6&lEmber Rank"
    lore:
      - "&7Permanent Ember rank."
    amount: 1
    data: 0
    price: 500
    deliver-item: false
    commands:
      - "lp user %player% parent set ember"

Available command placeholders are %player%, %uuid%, and %price%. Material names and data values must be valid for Minecraft 1.8.8.

Installation and building

1. Put EmberGold-1.3.0.jar in the server's plugins directory.
2. Start the server once to generate configuration.
3. Assign staff permissions and edit the shop from /goldadmin menu.
4. Configure the store to use the idempotent grant command.

To build from source, install Java 8 and Maven, then run:

mvn clean package

The resulting jar will be under target/.

Branding, animations, and sounds

The branding, animations, and sounds sections of config.yml control the presentation. Sound names must be valid Bukkit Sound enum names from Spigot 1.8.8. Set either animations.enabled or sounds.enabled to false to disable that system globally.

PlaceholderAPI

PlaceholderAPI is an optional soft dependency. When it is installed, EmberGold registers its internal expansion automatically—no eCloud download is required.

Shop console commands support %player%, %uuid%, and %price% natively. When PlaceholderAPI is present, they can also use placeholders from any installed expansion.

Developer API

EmberGold registers GoldService through Bukkit's services manager:

GoldService gold = Bukkit.getServicesManager().load(GoldService.class);
long balance = gold.getBalance(player.getUniqueId());
gold.deposit(
    player.getUniqueId(),
    player.getName(),
    25L,
    GoldChangeReason.API
);

Balance mutations must be performed on the primary server thread. Plugins can listen for the cancellable GoldBalanceChangeEvent and inspect its previous balance, requested new balance, player UUID, last known name, and GoldChangeReason.

GoldPurchaseEvent fires after a shop purchase and provides the player, category ID, offer ID, price, display item, delivery-warning state, and unique support receipt.

Supported reasons:

• API
• ADMIN_GIVE, ADMIN_TAKE, and ADMIN_SET
• STORE_GRANT
• DAILY_REWARD
• PURCHASE
• REFUND

Compile integrations against EmberGold and add depend: [EmberGold] or softdepend: [EmberGold] to their plugin.yml. Consumers should use GoldService and the public event classes rather than internal repository or menu classes.

Durability and validation

• players.yml and shop.yml use write-to-temporary-file plus atomic replacement.
• Current .bak recovery copies and one-generation .previous rollback copies are kept by default. A missing primary file is restored automatically from its .bak.
• Paid balance mutations save immediately; the periodic autosave remains as a fallback.
• Physical item delivery snapshots and restores inventory contents if Bukkit reports a failure.
• Every purchase receives an eight-character receipt recorded in audit.log.
• /goldadmin validate checks category slots, offer items, prices, delivery actions, and commands.
• Store transaction IDs are validated and remain idempotent.

Use /goldadmin validate after manually editing shop.yml and before opening a new store offer to players.