diff --git a/projects/BarterShops/README.md b/projects/BarterShops/README.md index 0f4fec1..979ef5e 100644 --- a/projects/BarterShops/README.md +++ b/projects/BarterShops/README.md @@ -10,7 +10,7 @@ TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](.. Run Maven with **JDK 21** from the source checkout. The POM sets `maven.compiler.release=21` and resolves `io.papermc.paper:paper-api:1.21.10-R0.1-SNAPSHOT` with `provided` scope from the PaperMC Maven repository. The plugin descriptor declares `api-version: 1.21.10`. -Install these matching Java 21 TFMC artifacts into local Maven before building: `net.tfminecraft:denareconomy:0.3.0`, `net.tfminecraft:simplefactions:4.0.0`, `me.plugins:tlibs:2.4.0`. Their source repositories use `mvn clean install`; CI uses the pinned dependency setup actions. +Install these matching Java 21 TFMC artifacts into local Maven before building: `net.tfminecraft:denareconomy:0.3.0`, `net.tfminecraft:simplefactions:4.0.0`, `me.plugins:tlibs:2.6.0`. Their source repositories use `mvn clean install`; CI uses the pinned dependency setup actions. Populate `libs/` with the exact files and hashes listed in `.github/dependencies.sha256`. `.github/scripts/prepare-release.sh` downloads those pinned private assets when supplied with the approved dependency token. @@ -36,7 +36,7 @@ Use `mvn clean install` when another plugin needs the result as a Maven dependen Required plugins declared by the manifest: MMOItems, MythicLib, DenarEconomy and TLibs. Character sessions and reviewed legacy heirs come from RPCharacters. When SimpleFactions is installed, use its character-member release (4.0.0). Shops wait for its migration and tax setup before allowing trades; a disabled or failing provider also closes trades. SimpleFactions remains optional when absent. -`ShopEvents` handles sign interactions and posts currency trades through the DenarEconomy character ledger. `ShopEmbargo` provides the SimpleFactions integration. Shop JSON lives under `plugins/BarterShops/Data`; preserve it across upgrades. The manifest declares no commands. +`ShopEvents` handles sign interactions and posts currency trades through the DenarEconomy character ledger. `ShopEmbargo` provides the SimpleFactions integration. Shop JSON lives under `plugins/BarterShops/Data`; preserve it across upgrades. The manifest declares one staff command, `/bartershops intent` (see [interrupted trades](#payments-and-interrupted-trades)). Only the shop's owning character, or staff with `bartershops.admin` (default: op), can break a shop sign or any block the plugin can tell would bring it down: the block the sign is fixed to, every hanging sign above it in a chain, and the block under any sand, gravel or other falling block that holds the sign up. Anyone else is refused with a message. Wall hanging signs stay up when the blocks beside them go, so anyone can break those blocks. @@ -87,13 +87,71 @@ character or inventory between payment and delivery: that leaves a review record instead. A remaining trade file after restart, conflicting intent, or interrupted item -delivery blocks further trades at that shop. Staff must inspect the recorded -operation in the ledger and the actual inventories before compensating or -completing the exchange. Stop the server before archiving a resolved record -outside `trades/`; then restart. Do not simply delete an unresolved record or -replay its delivery: some or all items may already have moved. Item inventories -and the ledger do not share a transaction, so crash rollback of Minecraft item -saves still requires reconciliation; automatic item escrow is not provided. +delivery blocks further trades at that shop. Do not simply delete an unresolved +record or replay its delivery: some or all items may already have moved. Item +inventories and the ledger do not share a transaction, so crash rollback of +Minecraft item saves still requires reconciliation; automatic item escrow is +not provided. + +Staff with `bartershops.admin` resolve a blocked shop in game: + +```text +/bartershops intent show the trade record and its posting +/bartershops intent clear clear it when no money moved +/bartershops intent clear --confirm clear it after settling by hand +``` + +The shop ID is the file name in `Data/` and `trades/`. The command reads the +record's state and asks the ledger for the posting's result: + +| Record | Command | +|---|---| +| `prepared`, posting absent or REFUSED, ledger ready | `clear` removes the record. No money moved. | +| `prepared`, posting APPLIED (or CONFLICT) | Shown only. The customer paid but the items did not move: hand them over, then `clear --confirm`. | +| `delivering` or `conflict` | Shown only. The items may already have moved: check the chest and the customer, put things right, then `clear --confirm`. | +| unreadable | Shown only; `clear --confirm` removes it after staff check by hand. | +| ledger not ready | Nothing clears, even with `--confirm`. | + +Clearing deletes `trades/.json` and the running server's copy of the +trade, so the shop trades again at once without a restart. Every use, viewing +included, is written to the server log and to +`plugins/BarterShops/logs/staff-audit.log` with the record's state, posting +result, operation ID and terms. + +## Death and estates + +A shop whose owning character is not alive is paused: both buying and selling +answer "This shop's owner has died." A shop whose owner cannot be read (an +unreadable or quarantined account) stays closed with the usual closed message. +A revived owner's shop trades again. + +With TLibs 2.6.0 or later, BarterShops takes part in RPCharacters estates as the +`bartershops` participant. When an estate is decided, each shop owned by the +dead character goes to the estate's property recipient (the will heir, or the +death guild's leader): the shop file's `owner` and `owner character` are +rewritten in place in `Data/.json`, keeping the shop ID and terms. +Waiting or frozen property leaves the shops paused with the dead owner until +staff assign it. Moves happen only while the dead character is still dead with +that death and the estate is decided at the current revision; a revived +character keeps whatever had not moved yet. + +Before changing any shop, BarterShops writes `estates/.json` listing the +shops it will move and their recipient, then marks each one moved. A crash +between shops is finished at the next settle, and the outcome reported to the +estate always lists every shop ID moved, which `/estate show` displays. To undo +a move by hand, restore the testator as owner of the shops listed there whose +current owner is still the recipient. + +A shop with an unfinished trade in `trades/` is not moved. Its estate answer is +BLOCKED and names the shop; staff resolve it with `/bartershops intent`, then run +`/estate retry bartershops`. The stock chest's Thievery lock is +separate property and moves at the next restart. The will screen and +`/estate show` list the character's shops and where their signs stand. + +BarterShops settles each decided estate on the first tick after start-up, again +as soon as its own character migration has finished (it waits for that), and then +every hour. It reports to RPCharacters only when its answer changes. On TLibs 2.5.0 it starts +normally without joining estates: shops of dead owners stay paused with them. ## Verification @@ -101,7 +159,9 @@ saves still requires reconciliation; automatic item escrow is not provided. workspace Maven wrapper. The suite covers character ownership, same-account separation, readiness, backup and interrupted migration recovery, embargo character arguments, both taxable trade directions, insufficient funds, -durable operation retries and delivery failures. Plain `mvn clean verify` +durable operation retries and delivery failures, the dead-owner pause, estate +transfers with their journal and crash replay, blocked shops, the hourly +reconcile and every row of the `/bartershops intent` table. Plain `mvn clean verify` also works with Java 21 and prepared dependencies. Live Minecraft persistence and a coordinated data migration rehearsal remain separate checks.