CoalGov is a server-side Paper plugin for vanilla Minecraft clients. It adds a coal-backed economy, Coal Cents, dynamic resource markets, land ownership, mining permits, government land classes, protected claim markers, NPC traders/workers, and regulated coal mining.

The plugin is designed for a small survival server built around a governed coal basin. Players can deposit physical coal into a ledger, buy land, trade resources with the Ministry, pay fines, and negotiate with NPC traders without requiring any client mods, resource packs, Forge, or Fabric.

Requirements

Paper 1.21.x
Java 21
Citizens 2.0.42-SNAPSHOT or compatible
SQLite, bundled through sqlite-jdbc

Build

This project is a Gradle Java plugin. If a Gradle wrapper is available, use:

./gradlew build

If the server only has Docker, the project can be built with a Gradle image:

docker run --rm -u 0 \
  -v "$PWD":/workspace \
  -w /workspace \
  gradle:8.14.3-jdk21 gradle build

The plugin jar is written to:

build/libs/CoalGov-1.0.0.jar

Install

Build the jar.
Copy build/libs/CoalGov-1.0.0.jar into the Paper server plugins/ directory.
Install Citizens.jar in the same plugins/ directory.
Start or restart the Paper server.
Edit plugins/CoalGov/config.yml as needed.
Use /coalgov admin reload after config-only changes.

CoalGov creates its SQLite database at:

plugins/CoalGov/coalgov.db

Economy

CoalGov stores money as integer Coal Cents.

100cc equals 1 coal
1 means 1 coal in commands
1.25 means 1 coal 25cc
125cc means 1 coal 25cc
Balances cannot go negative
Existing whole-coal databases are migrated once to Coal Cents and marked in schema_meta

Deposits and withdrawals stay tied to physical Minecraft coal:

/coal deposit converts COAL to 100cc each
/coal deposit converts COAL_BLOCK to 900cc each
/coal withdraw <amount> creates coal items and therefore requires whole-coal amounts

Market

/market opens a server-side inventory menu where players can sell configured resources to the Ministry or buy from Ministry stock.

Market prices are dynamic:

Low stock raises prices
High stock lowers prices
Buy and sell prices use a configurable spread
Cheap resources can transact below 1 coal because settlement uses Coal Cents
Item lore shows per-item buy/sell prices plus batch prices for 1 and 64
Market stock is persisted in SQLite

Coal-equivalent materials keep a value floor based on coal, charcoal conversion, or fuel value. Arbitrary/generated materials such as cobblestone do not have a forced whole-coal floor.

Land And Claims

CoalGov supports rectangular and polygon claims.

/claim wand gives the polygon selection wand
Right-click blocks to add polygon points
Sneak right-click clears the current selection
/claim buy <homestead|industrial> <radius> buys a radius claim
/claim buy <homestead|industrial> buys the selected polygon
Claim corners receive protected marker blocks
/claim appraise estimates resale value from land condition and configured resources
/claim sell sells the claim back to the Ministry
/showpropertylines shows the property lines for the claim you are standing in
/claim trust and /claim untrust grant or revoke claim-scoped access for other players

The first small homestead can be free, depending on config.

Claim owners can grant granular access:

build: place and break blocks
interact: use non-container interactable blocks such as doors, buttons, levers, gates, and similar blocks
container: open inventory blocks such as chests, barrels, furnaces, and hoppers
animal: damage animals inside the claim
manage: manage claim permissions
all: grant or revoke every permission above

Example:

/claim trust 12 Alex build
/claim trust 12 Alex container
/claim untrust 12 Alex build
/claim permissions 12

Unclaimed land does not block animal damage for now. Claimed land blocks animal damage unless the player owns the claim, has animal, has manage, or is using admin bypass.

Land Classes And Mining

Admins can define land regions with classes such as freehold, government land, protected preserves, border zones, and mining concessions.

Coal mining can be denied by land class. Mining concessions require an active mining permit:

/permit buy mining <regionName>

NPCs

CoalGov uses Citizens for NPC agents.

Trader NPCs have their own inventory and coal account
Worker NPCs patrol assigned polygon zones
Worker roles are matched from NPC names, such as Farmer or Baker
Farm workers can harvest mature crops in their assigned zone, collect drops, and replant from their inventory
Workers can consume inputs, pull supplies from same-zone NPCs, produce outputs, and stock same-zone traders
Traders can haggle through /cgnpc haggle
Optional OpenRouter-backed AI can produce trader messages and counters

Default worker chain:

Farmer harvests and replants mature crops in its zone
Baker consumes WHEAT and produces BREAD
Same-zone traders accept worker outputs up to the configured restock target

Super Furnace

CoalGov adds a persisted Super Furnace recipe. Craft a furnace with stone in all eight surrounding slots. Super Furnaces smelt faster and consume fuel faster.

Player Commands

/coal balance
/coal deposit
/coal withdraw <amount>
/coal pay <player> <amount>
/coal fines [list|pay <id|all>]
/market
/claim wand
/claim buy <homestead|industrial> [radius]
/claim info
/claim list
/claim show <id>
/claim appraise [id]
/claim sell [id]
/claim transfer <id> <player>
/claim abandon <id>
/claim trust <id> <player> <build|interact|container|animal|manage|all>
/claim untrust <id> <player> <build|interact|container|animal|manage|all>
/claim permissions <id>
/permit buy mining <regionName>
/permit list
/diviningrod
/showpropertylines
/land info

Admin Commands

/land create <name> <landClass> <radius>
/land delete <name>
/land list
/coalgov admin balance <player>
/coalgov admin grant <player> <amount>
/coalgov admin take <player> <amount>
/coalgov admin reload
/coalgov admin bypass <on|off|status>
/coalgov admin rod
/coalgov admin treasury <balance|grant <player> <amount>>
/coalgov admin tax exempt <player> <on|off|status>
/police fine <player> <amount> <reason>
/cgnpc zone create <name>
/cgnpc create <trader|worker> <name> <zone>
/cgnpc stock <id> <material> <amount>
/cgnpc funds <id> <amount>
/cgnpc haggle <id> <buy|sell> <material> <amount> <offer>

Permissions

coalgov.admin: admin commands, default op
coalgov.coal: coal economy commands, default true
coalgov.claim: claim commands, default true
coalgov.permit: permit commands, default true
coalgov.land.info: land info commands, default true
coalgov.market: market trading, default true
coalgov.diviningrod: divining rod command, default true
coalgov.police: police fine commands, default op

Admin permission alone does not bypass gameplay restrictions. Use /coalgov admin bypass on for build, mining, and marker bypass.

Configuration

Default config lives at:

src/main/resources/config.yml

Important sections:

economy: starting balance and deposit material toggles
government.taxes: market sale and purchase tax percentages
claims: claim prices, size limits, and resale values
permits: mining permit cost and duration
market.dynamic: stock pressure and spread settings
market.prices: base resource prices in coal
land: default land class and mining denial rules
npc: AI, trader, and worker settings
spawn: optional spawn setup guide signs and protected region

Config prices are written in coal units. CoalGov converts them to Coal Cents internally.

Deployment Notes

For the current Docker-based server layout:

cd /opt/mcworldgen-server/CoalGov
docker run --rm -u 0 -v "$PWD":/workspace -w /workspace gradle:8.14.3-jdk21 gradle build
cp build/libs/CoalGov-1.0.0.jar /opt/mcworldgen-server/data/plugins/CoalGov-1.0.0.jar
cd /opt/mcworldgen-server
docker compose restart mc

Always back up the current plugin jar and plugins/CoalGov/coalgov.db before deploying database-affecting changes.

Manual Test Checklist

Server starts without CoalGov errors
plugins/CoalGov/coalgov.db exists
schema_meta.economy_units is coal_cents_v1
Player join creates or updates a players row
/coal balance displays coal and cc
/coal deposit credits 100cc per coal item
/coal withdraw 1 gives one coal item
/coal withdraw 1.25 is rejected
/coal pay <player> 25cc transfers Coal Cents
/market shows per-item and batch prices
Market buy/sell updates stock and balance
/claim buy charges the displayed Coal Cents amount
/claim trust allows another player to use only the granted access
A player without animal access cannot kill animals inside another player's claim
Animals on unclaimed land can still be killed
/showpropertylines displays polygon edges between claim marker points
/claim appraise and /claim sell display formatted money
Mining protected coal is denied
Mining concession coal requires a valid permit
/coalgov admin bypass on bypasses build, mining, and marker restrictions