StashScanner

StashScanner — read-only stash census

Walks a stash of shulker boxes (stored inside chests / barrels), opens each container, reads every shulker's contents from the item's CONTAINER component (it never places a shulker to read it), classifies each as a kit type, and writes a snapshot to Postgres. This is the scan half of the Order System — it builds the stock database the OrderFiller draws from.

Command: .stashscanner (alias .ss).

Requires the stash database. Enable database.enabled and database.stashEnabled first (Postgres + Redis). See Order System → setup. Without it the module pauses with a message.

What it does

• Region or list mode. Region mode discovers every chest / trapped chest / barrel in a box around an origin (or the bot's feet) within a radius and Y band. List mode re-scans the storage chests already in the database.
• Reads shulkers without placing them. Contents come through 2b2t in the item's data, so each shulker is read straight from the open chest window — the same primitive KitMaker uses. No shulker is ever set on the ground.
• Classifies by content signature first. A canonical hash of the sorted (item, count) pairs is matched against the kit catalog; an unset/ambiguous shulker is recorded as unknown/ambiguous with its exact contents for later relabelling — no re-walk needed.
• Never breaks or places. The whole walk runs with allowBreak=false / allowPlace=false. A chest it can't reach (or open) is marked unreachable, logged, and skipped — never dug or pillared to. The gaps show up on the scan report.
• Dry run by default. Records the snapshot and emphasises the signature dump so you can seed the real catalog from what's actually in the stash.

Setup guide

1. Stand up the data layer and enable it (database stash on) — see Order System → setup.
2. Seed a placeholder catalog (optional): .ss seed loads the bundled example, or .ss seed kits.json loads your own.
3. Point it at the stash: .ss region <x> <y> <z> <radius> (use 0 0 0 to centre on the bot's feet), tune .ss band <down> <up>.
4. Walk it: .ss scan. With dryRun on, then .ss dump to list the unknown signatures, label them into a kits.json, .ss seed kits.json, and re-scan — unknowns reclassify in place.
5. The latest complete scan becomes "current stock" for .order stock and order reservations.

Commands

.stashscanner on/off | scan        # scan = enable + start a walk
.ss mode region/list
.ss region <x> <y> <z> <radius>    # 0 0 0 = use the bot's feet as the origin
.ss band <down> <up>               # Y band around the origin (feetY-down .. feetY+up)
.ss dryrun on/off                  # default on: classify + dump for catalog seeding
.ss seed [path]                    # load kits.json into the catalog (default: bundled example)
.ss dump                           # print unmatched content signatures to label
.ss status

It never withdraws or places anything — fulfilment is the OrderFiller's job.