diff --git a/CoalGov/README.md b/CoalGov/README.md index 021c848..d7790ef 100644 --- a/CoalGov/README.md +++ b/CoalGov/README.md @@ -1,74 +1,174 @@ # CoalGov -CoalGov is a server-side Paper/Bukkit plugin for vanilla Minecraft clients. It adds a small coal-backed economy, land classes, claims, mining permits, protected government land, and coal ore mining restrictions. +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 ledger uses Coal Cents for sub-coal transactions: `100cc` equals `1 coal`. Commands that accept money still treat plain numbers as coal, so `2.5`, `2.50`, and `250cc` all mean `2 coal 50cc`. +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 ``` -The jar is written to `build/libs/CoalGov-*.jar`. +If the server only has Docker, the project can be built with a Gradle image: -## VPS Install +```bash +docker run --rm -u 0 \ + -v "$PWD":/workspace \ + -w /workspace \ + gradle:8.14.3-jdk21 gradle build +``` -1. Build with `./gradlew build`. -2. Copy `build/libs/CoalGov-*.jar` to `/path/to/server/plugins/`. -3. Restart the Paper server. -4. Edit `plugins/CoalGov/config.yml`. -5. Run `/coalgov admin reload`. +The plugin jar is written to: -This is a Paper/Bukkit plugin only. It does not require Forge, Fabric, resource packs, client mods, or custom launchers. +```text +build/libs/CoalGov-1.0.0.jar +``` -## Commands +## Install -- `/coal balance` -- `/coal deposit` -- `/coal withdraw `; withdrawals must be whole coal because they create coal items -- `/coal pay `; accepts coal decimals or `cc` -- `/coal fines [list|pay ]` -- `/market` -- `/claim wand` -- `/claim buy ` -- `/claim buy ` after selecting a polygon with `/claim wand` -- `/claim info` -- `/claim list` -- `/claim show ` -- `/claim appraise [id]` -- `/claim sell [id]` -- `/claim transfer ` -- `/claim abandon ` -- `/permit buy mining ` -- `/permit list` -- `/diviningrod` -- `/land info` -- `/land create ` -- `/land delete ` -- `/land list` -- `/coalgov admin balance ` -- `/coalgov admin grant ` -- `/coalgov admin take ` -- `/coalgov admin reload` -- `/coalgov admin bypass ` -- `/coalgov admin rod` -- `/coalgov admin treasury >` -- `/coalgov admin tax exempt ` -- `/police fine ` -- `/cgnpc zone create ` -- `/cgnpc create ` -- `/cgnpc stock ` -- `/cgnpc funds ` -- `/cgnpc haggle ` +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 ` 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 ` buys a radius claim +- `/claim buy ` 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 + +The first small homestead can be free, depending on config. + +## 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 +``` + +## NPCs + +CoalGov uses Citizens for NPC agents. + +- Trader NPCs have their own inventory and coal account +- Worker NPCs patrol assigned polygon zones +- Workers periodically produce configured goods into their inventory +- Traders can haggle through `/cgnpc haggle` +- Optional OpenRouter-backed AI can produce trader messages and counters ## Super Furnace -Craft a CoalGov Super Furnace with a furnace in the center and stone in the eight surrounding slots. Placed super furnaces are persisted in SQLite, smelt 5x as fast, and burn fuel 4x faster. +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 +/coal pay +/coal fines [list|pay ] +/market +/claim wand +/claim buy [radius] +/claim info +/claim list +/claim show +/claim appraise [id] +/claim sell [id] +/claim transfer +/claim abandon +/permit buy mining +/permit list +/diviningrod +/land info +``` + +## Admin Commands + +```text +/land create +/land delete +/land list +/coalgov admin balance +/coalgov admin grant +/coalgov admin take +/coalgov admin reload +/coalgov admin bypass +/coalgov admin rod +/coalgov admin treasury > +/coalgov admin tax exempt +/police fine +/cgnpc zone create +/cgnpc create +/cgnpc stock +/cgnpc funds +/cgnpc haggle +``` ## Permissions -- `coalgov.admin`: admin commands, default `op`. Gameplay bypass is available with `/coalgov admin bypass on`. +- `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` @@ -77,121 +177,59 @@ Craft a CoalGov Super Furnace with a furnace in the center and stone in the eigh - `coalgov.diviningrod`: divining rod command, default `true` - `coalgov.police`: police fine commands, default `op` -## Claim Wand +Admin permission alone does not bypass gameplay restrictions. Use `/coalgov admin bypass on` for build, mining, and marker bypass. -Run `/claim wand` to receive a CoalGov claim wand. Right-click blocks to add polygon points. Once at least three points are selected, `/claim buy homestead` or `/claim buy industrial` buys the polygon instead of a radius claim. Sneak right-click with the wand to clear the current polygon. The plugin shows temporary particles between points and client-side gold marker block previews while selecting, and permanent protected marker blocks are placed at claim vertices after purchase. +## Configuration -## Market +Default config lives at: -`/market` opens a vanilla inventory menu. Players can sell configured resources to the Ministry or buy from Ministry stock. A normal click buys 1 item, and shift-click buys 64. Prices are dynamic: each material has a base price, but the live price rises when market stock is low and falls when stock is high. Buying and selling use Coal Cents internally, so cheap blocks like cobblestone can transact below 1 coal without forcing bulk purchases. Selling resources increases stock; buying resources decreases stock. Bulk sales are priced against simulated rising stock so one large sale cannot receive the first scarce-stock quote for every item. Coal-equivalent materials keep a floor based on direct coal value, charcoal conversion, or fuel value; arbitrary/generated resources like cobblestone have no forced 1-coal floor. The stock is persisted in SQLite. - -## Example Config - -```yaml -economy: - starting_balance: 0 - deposit_coal: true - deposit_coal_blocks: true - -claims: - homestead: - base_cost: 32 - cost_per_block: 0.05 - max_radius: 45 - first_claim: - free: true - max_radius: 12 - industrial: - base_cost: 128 - cost_per_block: 0.15 - max_radius: 96 - -permits: - mining: - cost: 64 - duration_hours: 72 - -market: - dynamic: - initial_stock: 1024 - target_stock: 1024 - min_multiplier: 0.35 - max_multiplier: 3.0 - sell_multiplier: 0.85 - buy_multiplier: 1.15 - prices: - DIRT: 0.01 - COBBLESTONE: 0.02 - SAND: 0.05 - GRAVEL: 0.04 - OAK_LOG: 0.25 - SPRUCE_LOG: 0.25 - BIRCH_LOG: 0.25 - TORCH: 0.10 - COAL: 1.0 - COAL_BLOCK: 9.0 - RAW_COPPER: 0.5 - COPPER_INGOT: 1.0 - RAW_IRON: 1.0 - IRON_INGOT: 2.0 - RAW_GOLD: 2.0 - GOLD_INGOT: 4.0 - DIAMOND: 32.0 - EMERALD: 12.0 - -land: - default_land_class: FREEHOLD - deny_mining_in_government: true - deny_mining_in_protected_preserve: true - deny_mining_in_border_zone: true - -spawn: - protection_radius: 32 - guide: - create_government_region: true - lines: - - "COALGOV BASIN" - - "Free first" - - "homestead:" - - "/claim buy" - - "Use /claim wand" - - "for polygons" - - "Coal seams:" - - "redwood ridges" - - "Permits:" - - "/permit buy" - - "mining " - - "/market trades" - -messages: - prefix: "&8[&6CoalGov&8]&r " +```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 errors. -- Database file is created at `plugins/CoalGov/coalgov.db`. -- Player joining creates a `players` row. -- `/coal balance` works. -- `/coal deposit` removes coal from inventory and increases balance by `100cc` per coal item. -- `/coal withdraw` decreases balance and gives coal items for whole-coal amounts. -- `/coal pay` transfers whole coal, decimal coal, and `cc` amounts. -- `/market` opens a vanilla inventory trading menu. -- Selling resources through `/market` increases market stock. -- Buying resources through `/market` decreases market stock and changes future prices. -- `/land create` creates a region. -- `/land info` reports current land class. -- `/claim buy` creates a claim and charges coal. -- `/claim appraise` appraises the claim you are standing in. -- `/claim sell` sells the claim you are standing in back to the government at appraised value. -- `/claim show ` displays a temporary particle outline. -- `/claim wand` draws a temporary polygon with particles and marker block previews. -- `/claim buy homestead` after wand selection creates a polygon claim. -- Claim corners are marked with protected gold blocks. -- Unclaimed land is protected from normal block placement and breaking. -- Overlapping claims are rejected. -- Mining coal in `PROTECTED_PRESERVE` is denied. -- Mining coal in `MINING_CONCESSION` without permit is denied. -- Buying a mining permit allows mining coal in that concession. -- Admin permission alone does not bypass gameplay restrictions. -- `/coalgov admin bypass on` bypasses build, mining, and marker restrictions for that admin session. +- 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 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 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