Skip to content

Document character market and loot payments #197

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 1 commit into from
Oct 12, 2026
Merged

Document character market and loot payments #197

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
26 changes: 25 additions & 1 deletion projects/MarketBlock/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,34 @@ TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](..

See the [shared API versions](../../PLATFORM.md#shared-api-versions) for the matching provider dependency set.

## Character payments

A sale credits the seller's current character pouch through DenarEconomy 0.3.0.
Realm tax is part of the same ledger posting. Without an active character, the
sale is refused. Goods are removed only after the ledger confirms payment;
refused or unavailable payments leave the goods untouched.

Before posting, MarketBlock saves the operation ID, owner account, character,
gross cents and inventory plan in `plugins/MarketBlock/pending-sales/<owner>.properties`.
Completed and refused intents are removed. An unavailable payment or interruption
keeps its intent and blocks new sales for that account until staff reconcile it.
Repeating the same click does not create another sale.

To reconcile an interrupted sale, stop further sales for that player and inspect
the saved operation in the DenarEconomy ledger alongside the player's inventory.
An applied operation already paid the captured character; never credit it again.
Resolve any outstanding item removal before archiving the intent. An operation
absent from the ledger has not paid; retain the goods and archive the intent only
after confirming that state. Do not delete pending files as routine cleanup.

The payment is transactional, but Minecraft inventory saves and ledger commits
are separate. A crash can leave an applied payment with goods still present;
this requires reconciliation rather than automatic replay.

## Build and dependencies

From the MarketBlock source checkout, install the shared plugin versions pinned
in `pom.xml`, then verify with Java 21:
in `pom.xml` (TLibs 2.4.0 and DenarEconomy 0.3.0), then verify with Java 21:

```sh
python3 path/to/TLibs/tools/install-plugins.py --pom pom.xml --mode pinned &&
Expand Down
2 changes: 1 addition & 1 deletion projects/TrialRooms/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](..

TrialRooms builds with Java **21** against
`io.papermc.paper:paper-api:1.21.10-R0.1-SNAPSHOT`. Install the pinned TLibs
`2.0.1` and DenarEconomy `0.2.1` release artifacts with the shared dependency
`2.4.0` and DenarEconomy `0.3.0` release artifacts with the shared dependency
installer. The build also prepares a checksum-verified MythicMobs
`5.13.1-SNAPSHOT` input from the private ServerAssets repository.

Expand Down
22 changes: 19 additions & 3 deletions projects/TrialRooms/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,9 +100,25 @@ health from saturation and cannot damage each other. Leaving through the exit,
dying, or disconnecting clears the flag.

Items matching a `conversions` line gain "converts on exit" lore when picked up.
Leaving through the exit removes them and credits their Denar value through
DenarEconomy. When any player dies, convertible items are removed from their
drops and inventory.
Leaving through the exit credits their value to the current character's pouch
through DenarEconomy. Realm tax is included in the same ledger posting. The loot
is removed only after payment is applied. With no active character, a refused
payment or an unavailable ledger, the player still exits and keeps the loot.
When any player dies, convertible items are removed from their drops and inventory.

Each conversion saves its operation ID, owner account, character, gross cents
and inventory slots in `plugins/TrialRooms/pending-conversions/<owner>.properties`
before posting. Completed and refused intents are removed. Interrupted or
unavailable payments leave the file in place and block further conversions for
that account. Exit polling cannot start another payment for that pending intent.

Staff must reconcile a pending file against the DenarEconomy ledger and the
player's inventory before archiving it. An applied operation has already paid the
captured character: resolve the remaining item removal without crediting again.
If the operation is absent, confirm that no payment occurred and retain the loot
before archiving its intent. Do not clear pending files as routine cleanup.
Minecraft inventory saves and ledger commits are separate; crash recovery is not
an automatic item-for-money transaction.

## Commands and permissions

Expand Down