273 lines
9.1 KiB
Markdown
273 lines
9.1 KiB
Markdown
# CoalGov
|
|
|
|
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:
|
|
|
|
```bash
|
|
./gradlew build
|
|
```
|
|
|
|
If the server only has Docker, the project can be built with a Gradle image:
|
|
|
|
```bash
|
|
docker run --rm -u 0 \
|
|
-v "$PWD":/workspace \
|
|
-w /workspace \
|
|
gradle:8.14.3-jdk21 gradle build
|
|
```
|
|
|
|
The plugin jar is written to:
|
|
|
|
```text
|
|
build/libs/CoalGov-1.0.0.jar
|
|
```
|
|
|
|
## Install
|
|
|
|
1. Build the jar.
|
|
2. Copy `build/libs/CoalGov-1.0.0.jar` into the Paper server `plugins/` directory.
|
|
3. Install `Citizens.jar` in the same `plugins/` directory.
|
|
4. Start or restart the Paper server.
|
|
5. Edit `plugins/CoalGov/config.yml` as needed.
|
|
6. Use `/coalgov admin reload` after config-only changes.
|
|
|
|
CoalGov creates its SQLite database at:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```text
|
|
/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`
|
|
- 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` produces `WHEAT`
|
|
- `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
|
|
|
|
```text
|
|
/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
|
|
|
|
```text
|
|
/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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
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
|