Add Coal Cents economy

coalgov-wiki-pages/admin.txt

@@ -0,0 +1,115 @@
+====== Admin Guide ======
+
+===== Permissions =====
+
+  * coalgov.admin - admin commands; default op. Gameplay bypass is toggled with ''/coalgov admin bypass on''.
+  * 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.police - police fine commands; default op.
+
+===== Creating Land Regions =====
+
+Stand at the center of the intended area and run:
+
+  /land create <name> <landClass> <radius>
+
+Examples:
+
+  /land create ministry-yard GOVERNMENT 24
+  /land create north-pit MINING_CONCESSION 40
+  /land create wall-east BORDER_ZONE 12
+  /land create old-grove PROTECTED_PRESERVE 32
+
+The command creates a square X/Z region centered on the admin.
+
+===== Spawn Setup =====
+
+Stand where the public spawn should be and run:
+
+  /coalgov admin spawn setup
+
+This sets the world spawn to your current block, creates or replaces a GOVERNMENT land region named ''spawn'', and places guide signs nearby. Normal players cannot modify the spawn guide because unclaimed government land is protected.
+
+Default spawn guide text can be changed in ''plugins/CoalGov/config.yml'' under ''spawn.guide.lines''.
+
+===== Starter Homesteads =====
+
+By default, each player gets one free homestead if it fits within radius 12 and they do not already own a claim:
+
+  claims:
+    homestead:
+      first_claim:
+        free: true
+        max_radius: 12
+
+Free starter homesteads store purchase value 0. Their resale appraisal can still count resources left on the property, but extracted or damaged land can create a depletion charge.
+
+===== Economic Controls =====
+
+Admins can inspect and modify balances:
+
+  /coalgov admin balance <player>
+  /coalgov admin grant <player> <amount>
+  /coalgov admin take <player> <amount>
+
+Money amounts accept whole coal, decimal coal, or a ''cc'' suffix. For example, ''1.25'' and ''125cc'' are both 1 coal 25cc.
+
+Admins can inspect and spend the treasury:
+
+  /coalgov admin treasury balance
+  /coalgov admin treasury grant <player> <amount>
+
+Admins can exempt players from transaction taxes:
+
+  /coalgov admin tax exempt <player> on
+  /coalgov admin tax exempt <player> off
+  /coalgov admin tax exempt <player> status
+
+Police can issue payable fines:
+
+  /police fine <player> <amount> <reason>
+
+Admins can grant a divining rod for testing:
+
+  /coalgov admin rod
+
+===== Admin Bypass Mode =====
+
+Admins normally play under the same build, marker, and mining restrictions as citizens.
+
+Use bypass mode only when you need the old god-power behavior:
+
+  /coalgov admin bypass on
+  /coalgov admin bypass off
+  /coalgov admin bypass status
+
+Bypass mode is per-player and lasts until it is turned off or the plugin/server restarts.
+
+===== Market Controls =====
+
+The market is configured in ''plugins/CoalGov/config.yml'' under ''market''. Admins can tune base prices, target stock, the starting stock for new materials, min/max price movement, and the buy/sell spread.
+
+After editing market config, run:
+
+  /coalgov admin reload
+
+Existing market stock is stored in SQLite and is not reset by reload.
+
+===== Reloading Config =====
+
+After editing plugins/CoalGov/config.yml, run:
+
+  /coalgov admin reload
+
+===== Server Files =====
+
+The plugin stores data in:
+
+  plugins/CoalGov/coalgov.db
+
+The plugin config is:
+
+  plugins/CoalGov/config.yml

coalgov-wiki-pages/commands.txt

@@ -0,0 +1,74 @@
+====== Command Reference ======
+
+===== Player Economy =====
+
+  * /coal balance - show your coal balance.
+  * /coal deposit - deposit all coal items and coal blocks from inventory.
+  * /coal withdraw <amount> - withdraw a whole-coal amount into coal items.
+  * /coal pay <player> <amount> - pay another online player; accepts decimal coal or cc.
+  * /coal fines - list unpaid fines.
+  * /coal fines pay <id|all> - pay one fine or all unpaid fines.
+
+===== Market =====
+
+  * /market - open the Ministry Exchange resource trading menu.
+
+===== Claims =====
+
+  * /claim wand - receive a claim wand for polygon selection.
+  * /claim buy <homestead|industrial> <radius> - buy a rectangular claim centered on you.
+  * /claim buy <homestead|industrial> - buy the currently selected wand polygon.
+  * /claim info - show claim and land info at your current location.
+  * /claim list - list your claims.
+  * /claim show <id> - display a temporary particle outline.
+  * /claim appraise [id] - estimate resale value for an owned claim.
+  * /claim sell [id] - sell an owned claim back to the Ministry at appraised value.
+  * /claim transfer <id> <player> - transfer an owned claim to another player.
+  * /claim abandon <id> - delete a claim you own without a refund.
+
+===== Permits =====
+
+  * /permit buy mining <regionName> - buy a mining permit for a mining concession.
+  * /permit list - list your active permits.
+
+===== Divining Rod =====
+
+  * /diviningrod - receive a CoalGov Divining Rod.
+
+Right-click the rod to test nearby ground for ore signals below and around you.
+
+===== Super Furnace =====
+
+Craft a CoalGov Super Furnace with a furnace in the center and stone in the eight surrounding slots. It smelts 5x as fast and burns fuel 4x faster.
+
+===== Land =====
+
+  * /land info - show land region or default land class at your location.
+  * /land create <name> <landClass> <radius> - admin command to create a land region.
+  * /land delete <name> - admin command to delete a land region.
+  * /land list - list land regions.
+
+===== Admin =====
+
+  * /coalgov admin balance <player> - show a player balance.
+  * /coalgov admin grant <player> <amount> - grant coal or Coal Cents.
+  * /coalgov admin take <player> <amount> - remove coal or Coal Cents.
+  * /coalgov admin reload - reload config.yml.
+  * /coalgov admin bypass <on|off|status> - toggle admin gameplay bypass for yourself.
+  * /coalgov admin rod - grant yourself a divining rod for testing.
+  * /coalgov admin treasury balance - show treasury balance.
+  * /coalgov admin treasury grant <player> <amount> - grant coal from the treasury.
+  * /coalgov admin tax exempt <player> <on|off|status> - manage transaction tax exemption.
+
+===== Police =====
+
+  * /police fine <player> <amount> <reason> - issue a payable fine.
+
+===== NPCs =====
+
+  * /cgnpc zone create <name> - create an NPC polygon zone from the current claim wand selection.
+  * /cgnpc create <trader|worker> <name> <zone> - create a Citizens-backed CoalGov NPC.
+  * /cgnpc stock <id> <material> <amount> - add inventory to an NPC.
+  * /cgnpc funds <id> <amount> - add coal or Coal Cents to an NPC account.
+  * /cgnpc haggle <id> <buy|sell> <material> <amount> <offer> - negotiate with a trader.
+  * /cgnpc list - list NPC zones and CoalGov NPCs.

coalgov-wiki-pages/economy.txt

@@ -0,0 +1,71 @@
+====== Coal-backed Economy ======
+
+CoalGov uses Coal Cents for sub-coal transactions. Balances are stored as integer cents, cannot go negative, and display as coal plus ''cc'' when needed. 100cc equals 1 coal.
+
+===== Conversion =====
+
+  * 1 coal item = 100cc.
+  * 1 coal block = 900cc when deposited.
+  * Plain command amounts are coal, so ''2.5'' means 2 coal 50cc.
+  * A ''cc'' suffix enters cents directly, so ''75cc'' means 75 Coal Cents.
+  * Withdrawals always return coal items, not coal blocks, and must be whole-coal amounts.
+
+===== Player Balances =====
+
+Each player has one balance stored by UUID in SQLite. A player row is created automatically when they join the server.
+
+===== Deposits =====
+
+Players run:
+
+  /coal deposit
+
+The plugin scans the player inventory, removes all enabled deposit items, and credits the account. By default, both COAL and COAL_BLOCK are accepted.
+
+===== Withdrawals =====
+
+Players run:
+
+  /coal withdraw <amount>
+
+The command fails if the amount is not positive, the amount is not whole coal, the balance is too low, or the inventory lacks space.
+
+===== Payments =====
+
+Players run:
+
+  /coal pay <player> <amount>
+
+The target player must be online. Payments accept whole coal, decimal coal, or a ''cc'' suffix. The transfer is recorded in the transactions table.
+
+===== Fines =====
+
+Players can inspect and pay unpaid fines:
+
+  /coal fines
+  /coal fines pay <id>
+  /coal fines pay all
+
+Paid fines go into the government treasury.
+
+===== Resource Market =====
+
+Players run:
+
+  /market
+
+The market lets players sell configured resources for coal or Coal Cents and buy stacks from Ministry stock. Prices are dynamic: scarce resources cost more, oversupplied resources pay less, and market stock persists in SQLite.
+
+Market purchases and sales can charge a configured government tax. Tax-exempt players do not pay transaction tax.
+
+===== Treasury =====
+
+The treasury receives market transaction tax and paid fines. Admins can inspect the treasury and issue treasury-funded grants.
+
+===== NPC Economic Agents =====
+
+CoalGov NPCs have their own coal accounts and inventory. Trader NPCs buy and sell from their own stock and balance. Worker NPCs move inside an assigned polygon zone and periodically produce configured goods into their own inventory.
+
+===== Transactions =====
+
+CoalGov records deposits, withdrawals, player payments, admin grants, admin takes, permit purchases, claim purchases, land sales, market sales, market purchases, market refunds, fine payments, and treasury grants in the transactions table.

coalgov-wiki-pages/land.txt

@@ -0,0 +1,92 @@
+====== Land, Claims, and Government Regions ======
+
+CoalGov separates land into government-defined land regions and player-owned claims. Land regions describe what the government says the land is. Claims describe who owns a specific private plot.
+
+===== Land Classes ======
+
+  * FREEHOLD - private land can exist here. If no land region matches, this is the default unless config changes it.
+  * LEASE - reserved for lease and expiration rules.
+  * GOVERNMENT - state land. Coal mining is denied unless the player has admin permission.
+  * PUBLIC - public government land. It is protected and cannot be privately claimed.
+  * MINING_CONCESSION - coal mining requires a valid mining permit for that named region.
+  * PROTECTED_PRESERVE - protected land. Coal mining is denied unless the player has admin permission.
+  * BORDER_ZONE - border land. Coal mining is denied unless the player has admin permission.
+
+===== Claim Types =====
+
+  * HOMESTEAD
+  * INDUSTRIAL
+  * MINING_CONCESSION
+
+The current player commands support buying homestead and industrial claims. Admins define mining concessions as land regions.
+
+===== Radius Claims =====
+
+Players can buy a rectangular claim centered on their current location:
+
+  /claim buy <homestead|industrial> <radius>
+
+The plugin rejects overlapping claims and land classes that cannot be privately claimed, such as government land, public land, protected preserves, border zones, and mining concessions.
+
+Claim cost comes from config:
+
+  cost = base_cost + area * cost_per_block
+
+===== Starter Homestead =====
+
+Each player can receive one small starter homestead for free if they do not already own a claim. By default, the free starter size is radius 12, or a 25x25 block square. Polygon starter claims are also free if their bounding box fits inside that size.
+
+Free starter land cannot be flipped for land value. CoalGov stores the actual purchase price on the claim. A free starter homestead has purchase value 0, so selling it refunds only resource value left on the property, minus any depletion charge for extracted or damaged land.
+
+===== Polygon Wand Claims =====
+
+Players can draw a claim shape with a wand:
+
+  /claim wand
+
+Right-click blocks to add polygon points. The plugin displays temporary particles between points and temporary gold marker block previews at selected points so the player can see the outline while drawing. Sneak right-click with the wand to clear the current selection.
+
+After selecting at least three points, buy the claim without a radius:
+
+  /claim buy homestead
+  /claim buy industrial
+
+The claim uses the polygon itself for ownership checks. The bounding box must still fit within the configured maximum size for the claim type.
+
+===== Claim Markers =====
+
+Purchased claims place protected marker blocks at their corners or polygon vertices. These marker blocks are immutable for normal players and make boundaries visible without needing claim IDs.
+
+Players can also run:
+
+  /claim show <id>
+
+This displays a temporary particle outline for the claim.
+
+===== Protected Unclaimed Land =====
+
+Players can only build or break inside claims they own. Unclaimed land is protected by default. Admins with ''coalgov.admin'' follow the same rules unless they enable bypass mode with ''/coalgov admin bypass on''.
+
+===== Claim Info =====
+
+Players run:
+
+  /claim info
+
+This reports the land class or named land region at the current location, plus any claim at the same spot.
+
+===== Appraisal and Sale =====
+
+Players can appraise or sell land without remembering IDs if they stand inside their own claim:
+
+  /claim appraise
+  /claim sell
+
+The command also accepts an ID when needed:
+
+  /claim appraise <id>
+  /claim sell <id>
+
+Sale value depends on land condition and configured resources stored on the property. Intact land keeps more of its original purchase value. Extracted or damaged land refunds less. Counted resources on the property add value according to configured resource prices.
+
+For free starter homesteads, extracted land value can become a charge instead of a refund. This discourages claiming free land, stripping it, and selling it back.

coalgov-wiki-pages/market.txt

@@ -0,0 +1,95 @@
+====== Resource Market ======
+
+CoalGov includes a vanilla-client trading menu at:
+
+  /market
+
+The menu is a normal server-side inventory GUI, so players do not need Forge, Fabric, client mods, resource packs, or custom launchers.
+
+===== What It Does =====
+
+  * Players can sell configured resources from their inventory.
+  * Players can buy configured resources one at a time by default.
+  * Click buys 1, and shift-click buys 64.
+  * Buying charges the fractional unit price times the batch size in Coal Cents, with a 1cc minimum for the whole click.
+  * The Ministry keeps a persisted stock count for each traded material.
+  * Selling resources increases Ministry stock.
+  * Buying resources decreases Ministry stock.
+  * Prices move with stock pressure.
+  * Bulk sales are priced against rising simulated stock as the sale is counted.
+  * Coal-equivalent materials have a floor based on coal, charcoal conversion, or fuel value.
+  * Arbitrary/generated materials such as cobblestone do not have a forced 1-coal floor.
+
+===== Dynamic Prices =====
+
+Every traded material has a base price in config. The live price is adjusted by comparing current stock to target stock.
+
+  * If stock is low, the multiplier rises and items become more expensive.
+  * If stock is high, the multiplier falls and items become cheaper.
+  * The config has minimum and maximum multipliers to prevent runaway prices.
+  * The buy price is higher than the sell price because the market has a spread.
+
+This keeps the economy simple while still reacting to player behavior. If everyone sells cobblestone, cobblestone becomes less valuable. If everyone buys out iron, iron becomes more expensive until players sell more into the market.
+
+When a player sells a full inventory, the whole batch does not receive the first high scarcity price. CoalGov prices the sale as if each sold item is added to Ministry stock before pricing the next item in that batch.
+
+Food items start with Ministry stock 0 by default, so players must sell food into the market before anyone can buy it back out.
+
+===== Default Dynamic Settings =====
+
+  market:
+    dynamic:
+      initial_stock: 1024
+      target_stock: 1024
+      min_multiplier: 0.35
+      max_multiplier: 3.0
+      sell_multiplier: 0.85
+      buy_multiplier: 1.15
+    initial_stock:
+      BREAD: 0
+      COOKED_BEEF: 0
+
+===== Default Traded Resources =====
+
+  * DIRT
+  * COBBLESTONE
+  * SAND
+  * GRAVEL
+  * OAK_LOG
+  * SPRUCE_LOG
+  * BIRCH_LOG
+  * TORCH
+  * COAL
+  * COAL_BLOCK
+  * RAW_COPPER
+  * COPPER_INGOT
+  * RAW_IRON
+  * IRON_INGOT
+  * RAW_GOLD
+  * GOLD_INGOT
+  * DIAMOND
+  * EMERALD
+  * WHEAT
+  * BREAD
+  * APPLE
+  * CARROT
+  * POTATO
+  * BAKED_POTATO
+  * BEETROOT
+  * MELON_SLICE
+  * SWEET_BERRIES
+  * GLOW_BERRIES
+  * COOKIE
+  * PUMPKIN_PIE
+  * COOKED_CHICKEN
+  * COOKED_PORKCHOP
+  * COOKED_BEEF
+  * COOKED_MUTTON
+  * COOKED_RABBIT
+  * COOKED_COD
+
+Default diamond pricing is 32 coal before market pressure adjustments.
+
+===== Persistence =====
+
+Market stock is stored in SQLite in the ''market_stock'' table. Restarting the server does not reset market pressure.

coalgov-wiki-pages/start.txt

@@ -0,0 +1,36 @@
+====== CoalGov ======
+
+CoalGov is a server-side Paper/Bukkit plugin for a vanilla-client Minecraft server. It adds a coal-backed economy, land ownership, mining permits, protected government land, regulated coal mining, claim marker blocks, polygon claim selection, and a resource market inside a walled coal basin.
+
+The premise is simple: players live inside a walled coal basin where land ownership, mining rights, and political status are controlled by a coal-backed government.
+
+===== What Players Can Do =====
+
+  * Deposit coal items and coal blocks into a coal-backed balance.
+  * Use Coal Cents for transactions smaller than 1 coal.
+  * Withdraw whole-coal amounts back into coal items.
+  * Pay other players in coal or Coal Cents.
+  * Buy homestead or industrial land claims.
+  * Receive one small starter homestead claim for free.
+  * Draw polygon claims with a claim wand.
+  * See claim boundaries with marker blocks and particles.
+  * Sell land back to the Ministry at appraised value.
+  * Trade appraised resources through a vanilla inventory market.
+  * Inspect land and claim status at their location.
+  * Buy mining permits for government-designated mining concessions.
+  * Mine coal legally when their land or permit status allows it.
+
+===== Server Compatibility =====
+
+CoalGov is a Paper plugin, not a client mod. Players use unmodified vanilla Minecraft clients. The server must run Paper or another Bukkit-compatible server implementation.
+
+===== Quick Links =====
+
+  * [[economy|Coal-backed economy]]
+  * [[market|Resource market]]
+  * [[land|Land classes and claims]]
+  * [[mining|Mining law and permits]]
+  * [[commands|Command reference]]
+  * [[admin|Admin guide]]
+  * [[technical|Technical notes]]
+  * [[testing|Manual test checklist]]

coalgov-wiki-pages/technical.txt

@@ -0,0 +1,40 @@
+====== Technical Notes ======
+
+===== Plugin Type =====
+
+CoalGov is a server-side Paper/Bukkit plugin. It is not a Forge mod, Fabric mod, resource pack, datapack, or custom launcher. Vanilla clients can join normally.
+
+===== Java Package =====
+
+  com.librewiki.coalgov
+
+===== Architecture =====
+
+The plugin is split into commands, listeners, models, services, storage repositories, and small utilities. The goal is boring, maintainable Java rather than one giant plugin class.
+
+===== Persistence =====
+
+CoalGov uses SQLite at:
+
+  plugins/CoalGov/coalgov.db
+
+Tables:
+
+  * players
+  * claims
+  * claim_vertices
+  * land_regions
+  * permits
+  * transactions
+  * market_stock
+
+===== Important Runtime Behavior =====
+
+  * Player rows are created on join.
+  * SQL uses PreparedStatement.
+  * Timestamps are stored as epoch milliseconds.
+  * Database access is synchronous because the target server is tiny.
+  * Money columns are stored as integer Coal Cents. The ''schema_meta'' table records the one-time migration from old whole-coal ledger units.
+  * Admin permission allows admin commands. Coal mining, build protection, and marker protection are bypassed only while the admin has enabled ''/coalgov admin bypass on''.
+  * Polygon claims store their vertices separately from the claim bounding box.
+  * The market stores stock separately from transaction history.

coalgov-wiki-pages/testing.txt

@@ -0,0 +1,37 @@
+====== Manual Test Checklist ======
+
+Use this checklist after install or upgrade.
+
+  * Server starts without errors.
+  * Database file is created.
+  * Player joining creates a players row.
+  * /coal balance works.
+  * /coal deposit removes coal from inventory and increases balance.
+  * /coal withdraw decreases balance and gives coal items.
+  * /coal pay transfers balance.
+  * /market opens the Ministry Exchange inventory menu.
+  * Selling resources through /market increases balance and market stock.
+  * Buying resources through /market decreases balance and market stock.
+  * Market prices change after stock changes.
+  * /land create creates a region.
+  * /land info reports current land class.
+  * /claim buy creates a radius claim and charges coal.
+  * A new player's first small homestead costs 0 coal.
+  * Selling a free starter homestead does not refund land value.
+  * Damaging or extracting from a free starter homestead can create a sale charge.
+  * /claim wand gives a claim wand.
+  * Right-clicking blocks with the wand draws a particle polygon.
+  * /claim buy homestead after wand selection creates a polygon claim.
+  * Claim marker blocks appear at rectangle corners or polygon vertices.
+  * Marker blocks cannot be broken by normal players.
+  * Unclaimed land cannot be built on or broken by normal players.
+  * /claim appraise reports land condition and resource value.
+  * /claim sell refunds the appraised value and deletes the claim.
+  * 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 mining, build, or marker restrictions.
+  * /coalgov admin bypass on bypasses mining, build, and marker restrictions for that admin.
+  * /coalgov admin bypass off restores normal gameplay restrictions for that admin.
+  * /coalgov admin spawn setup creates protected spawn guide signs.