Skip to content

BarterShops: estates and /bartershops intent (stage 6b) #214

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ryanbarlow97 merged 2 commits into from
Oct 13, 2026
Merged

BarterShops: estates and /bartershops intent (stage 6b) #214

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ca3fa0a
BarterShops: estates and /bartershops intent (stage 6b)
ryanbarlow97 Oct 13, 2026
582f379
BarterShops: estates reconcile as soon as shops are ready
ryanbarlow97 Oct 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 70 additions & 10 deletions projects/BarterShops/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.

Expand Down Expand Up @@ -87,21 +87,81 @@ 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 <shopId> show the trade record and its posting
/bartershops intent <shopId> clear clear it when no money moved
/bartershops intent <shopId> 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/<shopId>.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/<shopId>.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/<deathId>.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 <deathId> 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

`tfmc-mvn -o -B --no-transfer-progress clean verify` runs the tests using the
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.

Expand Down