Tally Paper Plugin — v0.1.86 (Initial Release)

Minecraft 26.2 · Paper 26.2+ · Requires the Tally datapack (bundled inside the JAR)

This is the first public release of the Tally Paper plugin. The datapack remains the product — 10,255 advancements, reward policy, and payout logic. The plugin installs the bundled zip, exposes /tally commands, and gives staff a searchable chest admin GUI that dispatches the same tally:admin/reward/* functions as the datapack-only operator path.

Prior shipping baseline: Tally datapack + mod v0.1.64. There was no plugin JAR before this release.

---

Highlights

• Bundled datapack install — ships Tally.zip inside the JAR; auto-extract and auto-enable on world save (configurable)
• Chest admin hub — reward policy, maintenance, bulk scopes, status, and advancement browse without typing function paths
• Indexed fuzzy search — ~9,500+ advancement rels built from bundled advancement-reward-index.json into an in-memory inverted + trigram index; sub-millisecond queries after index warm-up
• Ranked search results — relevance scoring; best matches first
• Lazy paginated browse — only 36 entries per page materialized in the GUI (no full-catalog freeze)
• Anvil search with Enter — type a query, press Enter or click the spyglass output; Esc with unchanged text cancels
• Full /tally reward CLI — mirrors datapack admin functions (toggle, set, adjust, clear, global gates, status, test)
• /tally advancement — grant, revoke, and inspect datapack progress for one player
• Clickable help — /tally help and reward help use Adventure components
• On-join bootstrap presence — optional player-facing card (theme, hints, quick-start links)
• Shirecraft admin navigation — soul campfire = up one level; soul torch = back and pagination

---

Install

1. Drop tally-plugin-0.1.86.jar into plugins/ (remove any older tally-plugin-*.jar)
2. Restart the server — Tally never uses /reload for datapack updates
3. Verify:

   /function tally:admin/reward/version
   /function tally:admin/reward/ping
   /tally reward test
   /tally admin
   

Upgrade from datapack-only or mod (v0.1.64)

1. Install the plugin JAR and restart
2. The plugin refreshes world/datapacks/Tally.zip when datapack.auto-install is on (default)
3. Existing storage tally:reward_overrides is preserved
4. Run /function tally:admin/reward/status or /tally reward status to confirm policy after upgrade
5. If you run the mod jar, do not also drop Tally.zip manually — pick mod or plugin-bundled zip, not both

---

Bundled datapack install

• Ships Tally.zip inside the plugin JAR
• On startup: extracts to world/datapacks/Tally.zip (datapack.auto-install, default on)
• Auto-enables on each world save (datapack.auto-enable, default on)
• post-enable-wait-ticks — delay after enable before plugin continues startup (default 100)
• Full server restart after every JAR or zip update

---

Commands (/tally, alias /tallyadmin)

Command	Purpose
/tally admin	Open the chest admin hub
/tally help	Clickable help (Adventure components)
/tally reload	Reload config.yml + rebuild advancement search index
/tally reward …	Full reward policy CLI (datapack function dispatch)
/tally advancement grant|revoke|info <path> [player]	Grant/revoke datapack progress or inspect an entry

/tally reward subcommands

Subcommand	Purpose
status	Datapack policy summary + raw storage dump (in-game player required)
global <items|experience|rewards> <on|off|default|toggle>	Global gate controls
info <path>	Effective payout for one advancement
toggle <rewards|items|experience|advancement> <path>	Per-entry toggles
set <xp|item> <path> <amount>	Set XP or primary item count
adjust <xp|item> <path> <delta>	Adjust XP or item count by delta
clear <path>	Clear per-entry overrides
test [player]	Runs tally:admin/reward/test_grant
help	Clickable reward help

/tally advancement

/tally advancement grant <path> <player>
/tally advancement revoke <path> <player>
/tally advancement info <path> [player]

/tally reload

Reloads config.yml and rebuilds the advancement search index from bundled JSON. Does not replay reward-overrides.yml into the datapack — runtime policy stays in storage tally:reward_overrides.

---

Admin chest GUI

Hub (/tally admin)

Control	Action
Reward policy	Global gates, maintenance, bulk scopes
Reward status (writable book)	Runs tally:admin/reward/status
Browse advancements (spyglass)	Fuzzy search + per-entry controls
Up (soul campfire)	—
Close	—

Reward policy menu

• Global master / items / XP gates — enable, disable, toggle, clear
• Clear global gates and Reset all overrides (wipes global, entries, scopes + completion ledger)
• Bulk scopes — tab, wing, tier, frame bulk toggles
• Status, Help, Test grant
• Maintenance submenu: init, ping, diag_grant, run_reconcile

Browse advancements (~9,500+ indexed entries)

• Paginated — only the current page (~36 slots) is materialized
• Page navigation — ◀ Page 3/42 / Page 3/42 ▶ on soul-torch controls with entry-range lore; center page indicator on multi-page browse
• Fuzzy anvil search — plain text, @tally, #material, !title, $lore, and multi-token queries (shared shirecraft-bukkit-utils search stack)
• Enter or click spyglass output to run search; Esc to cancel without searching
• Ranked results — best relevance first; full match set for pagination (no artificial 500-result browse cap)
• Bulk actions on search results — toggle rewards / items / XP / clear overrides; capped at bulk-max-targets (default 500) with lore when truncated
• Quick toggles from browse: left-click detail, right-click rewards, shift-right items, shift-left XP
• Up (soul campfire) returns to admin hub

Per-advancement detail screen

• Toggle rewards / items / XP / advancement payout gate
• Adjust XP and primary item count (±1, ±10; shift = ×10)
• Anvil set for exact XP / item count
• Storage info — dumps entries."<path>" from datapack storage to chat
• Clear override for that entry
• Back (soul torch) returns to browse at the same page/search

Bulk scope menus

• By tab (obtain, craft, sets, combat, explore, progression)
• By wing (obtain + craft wing families)
• By tier (discover → hoard hold tiers)
• By frame (task, goal, challenge)
• Scope detail Up returns to the correct scope list (not the bulk hub)

---

Advancement search (technical)

Stage	Behaviour
Index build (on enable + /tally reload)	Reads advancement-reward-index.json; builds inverted index per field + trigram lane on body text
Query	Posting-list lookup → fuzzy verify/score on candidates only (not a full 9.5k scan)
Pagination	Reuses memoized result list per distinct query string
Browse materialization	Snapshots built lazily — 36 per page

Search query syntax

Input	Matches
Plain text	Title, lore, material, catalog path (multi-token fuzzy)
@tally …	Namespace + optional path filter
#material	Material field
!title	Display name field
$lore	Lore field

---

Architecture (operators)

Rule	Detail
Source of truth	storage tally:reward_overrides in the datapack
Plugin writes	Dispatches named tally:admin/reward/* functions only — no parallel Java policy engine, no direct data modify on reward storage
GUI labels	Action-only — buttons describe what a click does, not live ON/OFF state (use Status or /tally reward status)
reward-overrides.yml	Backup/replay artifact; synced from storage when readable after toggles; /tally reload does not push YAML into the datapack
Resolver	/tally advancement info and command-side labels use storage when readable; on some Paper 26.2 builds rely on datapack Status / info functions

---

Player-facing bootstrap

Optional on-join presence card via config.yml → bootstrap.presence:

• Theme, icon, edition label, rotating hints
• Quick-start links (/tally help, advancement browse)
• Community links through shared Shirecraft runtime

---

Permissions (default: op)

tally.*
  └── tally.admin
        ├── tally.admin.gui
        ├── tally.admin.reload
        ├── tally.admin.reward
        └── tally.admin.advancement

---

Config (plugins/Tally/config.yml)

Datapack

datapack:
  auto-install: true
  auto-enable: true
  post-enable-wait-ticks: 100
  zip-file: Tally.zip

Rewards (plugin-side master switches)

rewards:
  enabled: true
  grant-items: true
  grant-experience: true

Admin GUI search

admin:
  gui:
    search-max-results: 0          # 0 = no cap for browse/pagination
    search-max-cached-queries: 0   # distinct query memo (0 = unlimited)
    bulk-max-targets: 500          # bulk toggle/clear cap per search

Plus customizable search button names, lore, anvil title/prompt, and result messages.

Bootstrap presence

bootstrap:
  presence:
    enabled: true
    on-enable: true
    on-join: true
    community-links: true

---

Dependencies

• shirecraft-bukkit-utils 1.4.19+ (shaded) — search index, fuzzy inventory search tokens, anvil submit helpers, admin GUI layout, bootstrap presence

---

What the plugin does not do

• Edit advancement criteria, hold counts, or tree layout
• Run without the Tally datapack loaded
• Replace /advancement for non-Tally namespaces
• Show fabricated live toggle states when storage cannot be read
• Use /reload instead of a full server restart for datapack updates

---