Skip to main content

Features

Detailed documentation of the SellGui Addon's feature set.

The Sell GUI​

The GUI is a 54-slot chest:

 0  1  2  3  4  5  6  7  8      ┐
 9 10 11 12 13 14 15 16 17      │
18 19 20 21 22 23 24 25 26      │  Deposit area (slots 0-44)
27 28 29 30 31 32 33 34 35      │
36 37 38 39 40 41 42 43 44      ┘
[RETURN ALL] [ - filler - ... ] [SELL]
     45         46 ... 52         53
  • Items can be placed with a normal click, a drag across several slots, or a shift-click from the player's inventory
  • The bottom row is locked: filler panes and buttons cannot be picked up, and drags touching them are cancelled
  • Clicks inside the player's own inventory behave normally

Order Matching​

When SELL is pressed, the addon fetches all active orders once and builds a catalog of every order line that still has items left to deliver, skipping:

  • The player's own orders
  • Order lines that are already fully delivered

Each deposited stack is then compared against that catalog using the core plugin's item validation — the same check a manual delivery uses, so any item requirements on the order apply.

Splitting a Stack​

A stack is delivered sequentially to its matching orders in strategy order. If the first order can only take part of the stack, the remainder continues to the next matching order, and so on. Only the amount the core reports as actually delivered is deducted at each step, so an order that fills up (or is filled by another player) a moment earlier simply accepts less and the addon moves on to the next candidate.

Strategies​

match-strategyOrder of candidates
BEST_PRICEHighest price per item first (default)
FIFOOldest order first (orders with no creation date go last)
ANYThe order the core returned them in

The strategy is read at the moment SELL is pressed, so /sellgui reload applies to the next sale.

Delivery & Payment​

Every delivery calls the core plugin's delivery routine. That means everything the core enforces still applies:

CheckResult
Order belongs to the sellerRefused — never auto-filled
Alt-account protection (same IP as the order owner)Refused unless the seller has sigmaorders.bypass.altprotection
Order cancelled or completedRefused
Order expiredRefused unless the core allows deliveries to expired orders
Delivery blacklistRefused
Order needs fewer items than offeredOnly the needed amount is taken; the rest goes to the next candidate

A refused candidate is simply skipped and the next one is tried. Payment is items delivered x order price per item, paid from the order's escrow in the order's currency, exactly as for a manual delivery. The order owner is notified through the core's normal notification settings.

Concurrency-safe

Deliveries to the same order are serialized by the core, and each call is capped at what the order still needs. Several players (or add-ons) selling to the same order at once cannot over-fill it.

Sale Summary​

After every sale the player receives:

  1. A summary — sold-summary, or sold-summary-with-leftover if anything was returned
  2. An earnings line — sold-earnings — with one formatted amount per currency, using the core's currency formatting (multi-currency aware)

The earnings figure is what the matched orders pay per item multiplied by the items delivered.

Leftovers & Returns​

Anything that no order accepted comes back:

  • Returned into the player's inventory, using the core's safe give routine so enchanted, named, and NBT items are placed without merging into unrelated stacks
  • Overflow that does not fit is dropped at the player's feet
  • RETURN ALL returns everything in the deposit area without selling

Safety​

The addon is designed so items are either delivered or returned — never duplicated and never lost.

SituationWhat happens
SELL clickedThe deposit area is read and cleared in the same tick, before any database work starts. From then on the items exist only in the sale itself.
Second click / drag while a sale runsCancelled — the GUI is frozen until the sale finishes
GUI closed (Esc, click outside) with items still depositedItems are returned automatically
GUI closed while a sale is runningThe sale finishes and returns any unsold items itself
Player disconnects while a sale is running (including on Folia)Unsold items are dropped at their last location
Addon disabled or reloaded with GUIs openDeposit areas are emptied and returned to their owners
Core plugin not readyThe sale is refused and everything is returned
Unexpected error during a saleEverything is returned rather than risk losing items
warning

If the addon is disabled while a sale is already in progress, that sale's unsold items cannot be returned. Avoid disabling it during peak play.

Permissions​

The sell GUI requires both sellgui.use and the core sigmaorders.fulfill. The core checks sigmaorders.fulfill in its own GUI and commands, so this addon repeats the check to make sure restrictions you place on delivering orders cannot be bypassed with /sell. See Commands.

Version Policy​

Like the other Sigma addons, SellGui Addon checks a small remote manifest at startup to confirm the installed version is allowed to run. The last successful result is cached in plugins/SellGuiAddon/manifests/policy-cache.json, so the addon still starts when the manifest host is unreachable.

Folia Support​

The addon declares folia-supported: true:

  • Per-player inventory work runs on the player's entity scheduler
  • World work (dropping unsold items for players who left) runs on the region scheduler at the player's last location
  • Database and order matching work is asynchronous and never blocks a region thread

See Also​