Official Player Guide and Server Handbook

The Black Ledger Admin Guide

This page is for admins/mods only. Players should not see this page because it explains the hidden mechanics.

1. What The Black Ledger Does

The Black Ledger is a cross-kingdom player market using MySQL. Players can list items in one kingdom/server and other players can buy them from another kingdom/server.

It supports:

Global listings through MySQL
Diamonds, diamond blocks, emeralds, and emerald blocks as currency
Hidden service fee from seller payout
Anonymous seller display for players
Listing cancellation
Listing expiration
Expired item reclaiming
Risk events
Dragon Egg confiscation lore event
Suspicious activity alerts
Admin moderation GUI
Admin listing commands

Players should only be told the surface-level version. Admin should understand the full mechanics.

2. Currency

Accepted currencies are:

DIAMOND
DIAMOND_BLOCK
EMERALD
EMERALD_BLOCK

The buyer pays the listed price. The seller receives the listed price minus the hidden Ledger service fee.

The service fee is removed from the economy. It does not go to the Crown or Kingdom Treasury.

3. Hidden Service Fee

Current config recommendation:

market:
  tax:
    enabled: true
    min-percent: 8
    max-percent: 18
    round-up: true
    hide-from-players: true

The fee is randomly chosen when the listing is created and stored with that listing.

Players do not see the fee when listing or buying. Sellers only discover the result when collecting payment.

4. Listing Limits and Cooldowns

Recommended live config:

market:
  max-active-listings-per-player: 5
  max-new-listings-per-week: 10
  listing-cooldown-minutes: 10
  purchase-cooldown-minutes: 30

These are MySQL-backed and apply across the system.

Admin test commands do not count toward player limits.

5. Expiration

Recommended live config:

market:
  expiration:
    enabled: true
    expire-after-days: 14
    cleanup-every-minutes: 60

Expired listings disappear from public listings.

Players can reclaim their own expired listings through:

The Black Ledger > Expired Listings

Admins can force expiration with:

/bladmin listings expire

6. Risk Events

Risk events happen when a player attempts to create a listing.

Current intended behavior:

Normal items have a small chance to be stolen or confiscated.
If a risk event triggers, the listing is not created.
The item is not returned.
The player may receive compensation equal to the hidden service fee amount.
Admin logs record what happened.

Recommended config:

market:
  risk-events:
    enabled: true
    chance-percent: 3.0
    compensate-with-tax-amount: true

Players should only be told:

“As with all things, there are risks involved.”

Do not publicly explain the stolen/confiscated mechanics.

7. Dragon Egg Lore Event

Dragon Eggs are special.

They should not be blocked through blocked-items, because the plugin handles them through a hidden lore event.

Behavior:

Dragon Egg listing attempt triggers a 100% confiscation event.
The listing is not created.
The egg is not returned.
The player receives the configured lore message.
Compensation may be paid.
Staff logs record DRAGON_EGG_CONFISCATED.
Suspicious alert may be sent.

Recommended config:

market:
  risk-events:
    dragon-egg:
      enabled: true
      chance-percent: 100.0

This is connected to Archdruid Mystik’s dragon lore. Do not publicly document this.

8. Access System

The Black Ledger has two access types:

Citizens NPC Ledger Keeper
Lectern/book access points

Current intended cycle:

Ledger Keeper present = NPC works, lecterns are inactive
Ledger Keeper gone = lecterns work, NPC unavailable

This forces players to either find the Keeper or locate hidden Ledger access points.

9. Lectern Access Points

Each kingdom starts with:

3 access points

Controlled by:

access-points:
  lecterns:
    enabled: true
    required-book-name: "The Black Ledger"
    max-per-kingdom: 3

A lectern needs a book named:

The Black Ledger

Admin commands:

/bladmin access list
/bladmin access remove <id>

Players should not know all access point locations unless discovered through roleplay.

10. Ledger Keeper NPC

Uses Citizens.

Admin commands include:

/bladmin npc link <npcId>
/bladmin npc list
/bladmin roam add
/bladmin roam list
/bladmin roam appear
/bladmin roam disappear

The Keeper can roam among configured locations and appear/disappear on a timer.

Recommended behavior:

The Keeper should not always be available.
He should move often enough to feel alive.
Locations should be hidden but discoverable.

11. Suspicious Activity Alerts

Certain groups may receive vague alerts when Black Ledger events happen.

Recommended permission groups:

Royal Council
Nobles
Ladies in Waiting
Knights
Mercenaries

The alerts should be vague. They should never reveal:

Seller name
Buyer name
Exact item
Price
Coordinates
Access point location

Permissions are listed below.

12. Staff Console

Admins with:

blackledger.admin

can access the staff console from inside The Black Ledger GUI.

The Staff Console allows admins to:

Browse listings by status
View seller names
See service fee amounts
Give admin item copies
Refund active listings to online sellers
Remove active listings without refund
Set listings to EXPIRED or REMOVED

This should remain admin-only.

13. Admin Commands

Core admin commands:

/bladmin status
/bladmin reload
/bladmin database status
/bladmin database test
/bladmin logs recent [amount]

Listing commands:

/bladmin listings active [amount]
/bladmin listings inspect <id>
/bladmin listings player <player> [amount]
/bladmin listings givecopy <id>
/bladmin listings forcegive <id>
/bladmin listings remove <id>
/bladmin listings refund <id>
/bladmin listings setstatus <id> <status>
/bladmin listings expire
/bladmin listings testcreate <price> <currency>

Access commands:

/bladmin access list
/bladmin access remove <id>

NPC/roaming commands:

/bladmin npc link <npcId>
/bladmin npc list
/bladmin roam add
/bladmin roam list
/bladmin roam remove <id>
/bladmin roam appear
/bladmin roam disappear

Known users:

/bladmin users list

Permission List

Player Permissions

blackledger.access.use

Allows a player to use valid Ledger access points.

Access Management

blackledger.access.create

Allows creation/binding of lectern access points.

blackledger.access.remove

Allows removing/breaking Ledger access points.

blackledger.access.bypassdormant

Allows bypassing the Keeper/lectern inactive cycle.

Use carefully. Admin only.

Admin Permissions

blackledger.admin

Main admin permission. Allows admin commands and staff console.

Suspicious Alert Permissions

Players/staff receive suspicious alerts if they have any one of these:

blackledger.alerts.receive
blackledger.alerts.royalcouncil
blackledger.alerts.noble
blackledger.alerts.ladyinwaiting
blackledger.alerts.knight
blackledger.alerts.mercenary

Recommended LuckPerms examples:

/lp group royalcouncil permission set blackledger.alerts.royalcouncil true
/lp group noble permission set blackledger.alerts.noble true
/lp group ladyinwaiting permission set blackledger.alerts.ladyinwaiting true
/lp group knight permission set blackledger.alerts.knight true
/lp group mercenary permission set blackledger.alerts.mercenary true