Coalgov/CoalGov/README.md

# 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`
- 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

```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