# The Admin GUI ## The admin GUI `/tcpvc gui` opens an in-game admin console. You can do almost everything you'd otherwise do by editing `crates.yml` directly, without leaving the game. This guide walks through every screen. ### Opening the GUI ``` /tcpvc gui ``` Requires `tcpvc.admin` (default: OP). If you're not an op and don't have the permission, you'll get a "You don't have permission to use this command" message. The plugin re-checks the permission on every click — so if a player has the permission stripped while their GUI is open, the next click closes the menu. #### First-run welcome The very first time an admin runs `/tcpvc gui` on a given player profile, a welcome **Dialog** appears with the plugin version, a quick-reference of the four most-used commands, and three buttons: * **Open GUI** — proceed to the crate list. * **Open docs** — print the docs URL in chat. * **Close** — dismiss. Any button records a `tcpvc:welcomed` PDC tag on the player so the welcome never repeats. You can pull it up again any time with `/tcpvc about`. ### The crate list The first regular screen is a paginated list of every crate in `crates.yml`: ``` ┌─────────────────────────────────────────┐ │ [common] [legendary] [empty][empty] │ │ [empty] [empty] [empty][empty] │ │ ... │ │ [← Prev] [+ Add] [Next →][X] │ └─────────────────────────────────────────┘ ``` * **Click a crate tile** → enter that crate's editor. * **Shift + Right-click a crate tile** → open the delete confirm (a Dialog, not a chest GUI — see below). * **Click `+ Add`** → a Dialog opens asking for a new crate id. Type the id (lowercase letters, digits, `_`, `-`) and click **Create**; on success a blank crate is created and you're dropped straight into its editor. Click **Cancel** to abort. * **Click `← Prev` / `Next →`** → navigate pages (45 crates per page). * **Click `X`** → close. Crate tiles show: id, current display name, reset mode, and which tiers are configured. A crate with no tiers configured is flagged in red — players can't open it; you need to set up at least one tier before it does anything useful. ### The crate editor Click a crate from the list: ``` ┌─────────────────────────────────────────┐ │ [name] [.] [.] [.] [⏰] [.] [.] [📣] │ │ [.] [N-key][N-loot] [.][.][O-key][O-loot] │ [.] [reset] [.] [delete] [.] │ │ [.] [.] [.] [.] [.] [.] │ │ [← Back] [.] [.] [.] [.] [.] [.] [X] │ └─────────────────────────────────────────┘ ``` #### Identity + scheduling * **Display name** (`name tag`) — Click to open a Dialog with a single text field pre-filled with the current name. Edit, click **Apply** or **Cancel**. MiniMessage tags supported. * **Reset mode** (`repeater`) — Click to open a Dialog with all three modes listed as radio options (Per-player / Server-wide / One-time). Per-option descriptions appear inline in the body. Pick + Apply. * **Cooldown** (`clock`) — Click to open a Dialog with one slider spanning 60 seconds to 30 days. Drag to set, the label updates live with the value. Disabled in one-time mode (the button shows a greyed-out lore line and click is a no-op). * **Broadcast on every open** (`lever` / `redstone torch`) — Instant toggle, no dialog. Lever icon = OFF, redstone torch (lit) = ON. #### Per-tier configuration * **Normal-tier key** — Open the key editor for the normal tier (preview slot + Modify Key wizard). * **Normal-tier loot pool** — Open the loot pool editor. * **Ominous-tier key** — Same as Normal-tier key, for the ominous side. * **Ominous-tier loot pool** — Same as Normal-tier loot pool. A tier showing `(not configured)` lacks both a key and a pool. Drop an item onto the key's preview slot to bootstrap, or open the loot pool editor to start adding entries. #### Destructive * **Delete this crate** (`TNT`) — Opens a Dialog confirmation ("Delete crate 'X'?") with an inline warning showing how many registered vaults would become orphaned. Confirm or Cancel. #### Bottom row * **← Back** — return to the crate list. * **X** — close. #### Auto-save Every change you make in the editor commits to disk after a 250ms quiet period. Toggle reset mode 5 times in a second → one save, not five. Closing the editor flushes any pending save immediately. If two operators edit the same crate simultaneously, the last save wins — there's no concurrent-edit detection. In practice this isn't a problem since admin GUI sessions are usually one-at-a-time. ### The loot pool editor Click **Normal-tier loot pool** or **Ominous-tier loot pool** from the crate editor: ``` ┌──────────────────────────────────────────────────┐ │ [iron][gold][diam][book][...] │ │ [...] │ │ [...] │ │ [...] │ │ [← Back][+ Add stamp][+ Add custom][.][.][X] │ └──────────────────────────────────────────────────┘ ``` Each tile in the top rows is one entry from the pool's `entries` list. **The icon reflects what the entry actually gives the player**: * Vanilla entries show the item itself (iron ingot, diamond block, etc.). * `give` commands show the item the command would hand out. * `key-reward` entries show the linked crate's key material. * `wild-spawner` entries show a spawner item. * Any other command shows a command-block icon. The icon's **stack count** reflects `amount.last` (the max possible drop), clamped to the material's max stack size, so admins see drop magnitude at a glance. The tile tooltip lists the entry's describe string (`iron_ingot x2-5`), weight, effective draw percentage, and a click-hint. #### Adding a vanilla item by stamping Shift-click any item in your own inventory while the loot pool is open. The item's **material** is recorded as a new vanilla entry with amount = 1..1 (always, regardless of the stack you shift-clicked). **The item is not consumed** — only its material identity is read. You can also drag-drop the item onto the **`+ Add stamp`** slot (lime dye) for the same effect. Adjust the entry's amount range via the per-entry editor (see below); shift-clicking is intentionally a "1 of this please" affordance to avoid 64-beacon entries by accident. #### Adding any entry type via Dialog — `+ Add custom` Click **`+ Add custom`** (lime concrete) to open the entry-type picker Dialog: ``` Add a loot entry Pick the kind of entry to add: • Vanilla item — give an item by material. • Command — run a console command on roll. • Key reward — mint another crate's key. • Wild Spawner — give a TCP-WildSpawners preset item. • From template — pre-configured starter entries. [Vanilla item] [Command] [Key reward] [Wild Spawner] [From template] [Cancel] [Next] ``` Pick an option, click **Next**. A second Dialog opens with the form fields appropriate to your choice: * **Vanilla item** — material text input + amount slider (1..64). * **Command** — command text input + description text input. `{player}` in the command is replaced with the opener's name at give-time. * **Key reward** — crate single-option (populated from your configured crates) + tier single-option (Normal / Ominous). * **Wild Spawner** — preset id text input. * **From template** — single-option picker listing every entry from `loot-templates.yml` (see the loot templates reference). Each second-stage Dialog has **Add** and **Cancel** buttons. Validation runs at Apply time: unknown materials, missing crate ids, and missing preset ids surface a clear chat error and reopen the loot pool. #### Removing an entry Shift-click any entry tile to remove it. Auto-save fires immediately. #### Editing an existing entry Click the entry tile to open the **loot-entry editor**: ``` ┌──────────────────────────────────────────────────┐ │ [.] [.] [.] [.] [name] [.] [.] [.] [.] │ │ [.] [.] [.] [.] [lore] [.] [.] [.] [.] │ │ [.] [chance] [.] [.] [📣] [.] [.] [amount] [.] │ │ [.] [.] [.] [.] [model] [.] [.] [.] [.] │ │ [.] [.] [.] [.] [.] [.] [.] [.] [.] │ │ [← Back] [.] [.] [delete] [.] [.] [.] [X]│ └──────────────────────────────────────────────────┘ ``` The middle "info" row holds **clickable** information panes: * **Chance** (`gold ingot`) — Click to open a Dialog with a 0–99% slider. Drag to set the exact drop chance. Behind the scenes the plugin solves for the weight that produces your target % — other entries' weights are untouched, but their displayed % shifts so the pool still totals 100%. Single-entry pools have the click disabled (chance is always 100%). * **Broadcast on roll** (`lever` / `redstone torch`) — Instant toggle. * **Amount** (`paper`) — Click to open a Dialog with **two sliders** (Min + Max, each 1..64). Min ≤ Max validated at Apply. The central column holds the type-specific Dialog buttons: * **Display name** — text input Dialog (vanilla entries only). * **Lore lines** — multi-line text input Dialog, up to 12 lines, 96px tall (vanilla entries only). * **Resource-pack model ID** — number-slider Dialog 0..999999, 0 = unset (vanilla entries only). * **Description** — for Command entries, the short label shown in preview / open-result lines. Non-applicable fields show grey glass panes ("vanilla only") — for example a Command entry's preview shows the description field but the lore/model slots are inert. * **Delete this entry** (`TNT`) — Opens a Dialog confirmation ("Delete this entry? Item: "). Confirm or Cancel. ### The key editor Click **Normal-tier key** or **Ominous-tier key** from the crate editor: ``` ┌──────────────────────────────────────────────────┐ │ [.] [.] [.] [.] [key preview] [.] [.] [.] [.] │ │ [.] [.] [.] [.] [Modify Key] [.] [.] [.] [.] │ │ [.] [.] [info] [.] [.] [.] [clear tier] [.] [.]│ │ [← Back] [.] [.] [.] [.] [.] [.] [.] [X] │ └──────────────────────────────────────────────────┘ ``` #### Preview slot Slot 4 shows the configured key item exactly as it appears in players' inventories. Two affordances: * **Drop / shift-click any item onto the preview** — fast-path "I just want to change the material". The new material is stamped in, and the display name auto-syncs when it looks material-derived (e.g. "Dirt Key" becomes "Amethyst Shard Key" automatically when you stamp an amethyst shard). Customised names that don't reference the old material are preserved. When a tier has no key configured, the preview slot becomes a grey glass placeholder — stamp any item to create the tier with defaults. #### Modify Key wizard Click **Modify Key** (writable book) for the full editor. Opens a single Dialog with three input fields and three buttons: ``` Modify Normal key for legendary Edit any field below. • Apply commits + gives a test key. • Preview rebuilds the item above with what you've typed. Display name [Legendary Key] Lore (one line per row) [The rarest of keys. Open exactly once. ] Model ID: 1001 [Apply] [Preview] [Cancel] ``` * **Apply** — saves the changes, mints a fresh test key in your inventory, and posts a chat note. If your inventory was full it posts a clickable `[click to claim once free]` link that runs `/tcpvc key give`. Reopens the key editor on the same tier. * **Preview** — closes the current Dialog, reopens it with the same values still in the fields BUT the body's preview item rebuilt from those values. Iterate as many times as you want until happy, then click Apply. No save happens during Preview. * **Cancel** — closes, reopens the key editor with no changes. Esc-dismissal is **disabled** on the wizard so you can't accidentally strand yourself without an inventory open. Use Cancel. #### Info pane Shows the current configuration as plain text: material, display name, lore line count, model id. Read-only. #### Clear tier Click **Clear tier** (red terracotta) to open a Dialog confirmation that removes the key + loot pool for this tier entirely. Existing player-held keys continue to work — they're PDC-tagged, the tag survives the config change — but you won't be able to mint new ones or open the vault with that tier until you reconfigure. ### The delete-crate confirm From the crate list, shift + right-click a crate tile: ``` Delete crate 'legendary'? This removes the crate from config. 3 registered vault(s) will become orphaned and need manual cleanup with /tcpvc unset. [Delete crate] [Cancel] ``` Native Dialog — Confirm-on-the-right, Cancel-on-the-left (or Esc). One click each, no arming, no timeout. When you commit: * The crate is removed from `crates.yml`. * Any vaults registered as this crate type are flagged as orphaned — their PDC tag still points at the now-missing crate. The plugin force-resets each orphaned vault (clears rewarded-players) and removes the hologram. * You get a chat message listing the orphan count and a hint to visit each one and run `/tcpvc unset` to clean up the PDC. The orphaned PDC tags don't break anything — the next chunk-scan just logs a warning ("vault tagged crate 'X' but X is not in crates.yml") and skips them. But cleaning up keeps the world tidy. ### Keyboard tips * The GUI doesn't intercept chat — admins can `/back`, `/spawn`, and type freely while any TCPVC GUI or Dialog is open. The plugin no longer subscribes `AsyncChatEvent` for prompts. * Shift-clicking entries in the crate list / crate editor / loot pool triggers the relevant action (delete confirm, stamp-add, remove entry). Shift-click in the bottom inventory while the loot pool is open routes the item identity to the `+ Add stamp` slot. * Drag-drops onto stamp-accepting slots are stamp affordances, not transfers. The dragged item stays in your inventory. *** Next: **Commands & permissions →** --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://darkstarworks.gitbook.io/plugins/mc/tcp-documentation/tcp-vaultcrates/the-admin-gui.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.