All documentation
Documentation

HyperTebex

Your Tebex store inside Minecraft: a configurable chest GUI with categories, packages, sales, an optional cart and one-time checkout links.

v1.0.2 Paper 1.21 or newerJava 21A Tebex store and its secret keyOfficial Tebex plugin (to deliver purchases)PlaceholderAPI (optional)

Quick start

  1. Put HyperTebex-1.0.2.jar in plugins/ and start the server. It enables with one warning that no key is set.
  2. Get your secret key at creator.tebex.io, Integrations, Game Servers.
  3. Run /hypertebex key <secret_key>, preferably from the console so the key stays out of chat history.
  4. Run /store (or /buy). Your categories and packages appear in a chest GUI.
  5. Optional: turn on the cart with cart.enabled: true and your public token in config.yml, then /ht reload.
  6. Keep the official Tebex plugin installed. HyperTebex is the storefront; Tebex delivers the purchases.

#What it does

HyperTebex shows your Tebex store in game. Players type /store (or /buy, /donate), browse your Tebex categories and packages in a chest GUI, and get a clickable, one-time Tebex checkout link in chat when they buy something.

  • Categories, sub-categories and packages come straight from Tebex, with descriptions cleaned of HTML and word-wrapped.
  • New packages, prices and sales sync automatically (every 5 minutes by default). Open menus update in place and sales count down live.
  • An optional cart lets players add packages with a quantity and pay for everything with one link.
  • Every menu, item and message is configurable, and per-package overrides are filled in for you in store_data.yml.
HyperTebex does not deliver purchases

It is a storefront only. Keep the official Tebex plugin installed so Tebex can run your package commands after a payment.

#Installation and requirements

Requirements

  • Paper 1.21 or newer (the plugin uses api-version 1.21).
  • Java 21.
  • A Tebex store, and its secret key from creator.tebex.io.
  • The official Tebex plugin, to deliver purchases.
  • PlaceholderAPI is optional and only needed for the placeholders.

Install

  1. Put the jar in plugins/ and start the server. With no key set, the plugin still enables and logs one warning.
  2. Go to creator.tebex.io, Integrations, Game Servers, open your server and copy the Secret Key.
  3. Run /hypertebex key <secret_key>. The key is saved, the store is synced and the data is cached to cache/store_data.json.
  4. Run /store to test.
Set the key from the console

Running the key command from the server console keeps the key out of in-game chat history. Anyone with the key can read your store data, so keep it private. You can also paste it into tebex_secret_key in config.yml and run /ht reload.

Files in plugins/HyperTebex/

FileWhat it is
config.ymlKey, sync, price formats, purchase flow, cart, sounds, permissions.
guis.ymlEvery menu: title, size, slots, items, navigation and static items.
messages.ymlEvery message players and admins see.
store_data.ymlPer-category and per-package settings. Filled in automatically after each sync.
store_ids.txtEvery category and package with its ID. Rewritten after each sync.
cache/store_data.jsonLast successful sync. Written by the plugin, so the store opens even if Tebex is down.
cache/carts.jsonSaved player carts. Written by the plugin.

#The store GUI and checkout

The main menu lists your root categories. Clicking a category opens its sub-categories and packages. Big stores get pages, and a page with only a few items keeps them centered. Nobody can take or move items in the menus.

Buying without the cart

With the cart off, what happens when a player clicks a package is set by purchase_action:

# What happens when a player clicks a package (when the cart is disabled):
#   confirmation_gui - opens a confirm/cancel screen, confirming sends the checkout link (default)
#   url_message      - immediately sends the checkout link in chat
purchase_action: confirmation_gui

# Seconds a player must wait between checkout link requests.
checkout_cooldown_seconds: 5
# Close the GUI when a checkout link is being generated.
close_gui_on_checkout: true

The checkout link is created through Tebex and sent in chat. The link expires shortly, and a cooldown stops link spam. The lines of that chat message are set in purchase_url_messages:

purchase_url_messages:
  - ""
  - "&#5B8DEF&lCHECKOUT &8» &7Your secure checkout link for &f%package_name% &7is ready!"
  - "&#5B8DEF&lCHECKOUT &8» &a&n[Click here to complete your purchase]"
  - ""

Every non-empty line is clickable and opens the checkout. Available placeholders: %player_name%, %package_name%, %package_id%, %price%, %checkout_url%, %store_name%. MiniMessage <click:...> tags inside a line still take priority.

Opening a category directly

/store <category id> jumps straight to a category. Find IDs in store_ids.txt or with tab completion. /ht open <player> [category id] opens the store for a player, which is handy for NPCs and menu plugins.

#Cart

The cart lets players add packages with a quantity and pay for everything with one Tebex link. It uses Tebex's Headless API, which needs your store's public token, a different value from the secret key.

  1. Get the public token at creator.tebex.io, Integrations, API Keys.
  2. Set it in config.yml and turn the cart on:
cart:
  enabled: true
  webstore_token: "your-public-token"
  1. Run /ht reload.

Once the cart is on, clicking a package opens an add-to-cart screen with -10, -1, +1 and +10 buttons. Add to cart adds the chosen quantity, and Buy now checks out just that package. In the cart, left-click adds one, right-click removes one, and shift-click removes the whole line. Checkout gives one link for everything.

cart:
  enabled: false
  webstore_token: ""
  # Highest quantity a player can choose for one package (store_data.yml can override per package).
  max_quantity: 64
  # Empty the cart after a checkout link has been created.
  clear_after_checkout: true
  # After "Add to cart", go back to the package list (false = stay on the add-to-cart screen).
  return_after_add: true
  # Where Tebex sends players after paying / cancelling. Blank = your store's website.
  complete_url: ""
  cancel_url: ""
  headless_api_url: "https://headless.tebex.io"

Quantity rules

  • Subscriptions and packages with "disable quantity" ticked in Tebex are limited to 1.
  • You can force this per package with allow_quantity and max_quantity in store_data.yml.
  • Carts are saved in cache/carts.json and survive restarts.

Players open their cart with /cart (alias /basket), /store cart, or the cart item in the menus. /cart is only registered while the cart is enabled.

#Syncing with Tebex

HyperTebex syncs on its own, so new packages, categories, prices and sales show up in game without a reload. Open menus update in place when a sync finishes (gui.refresh_on_sync).

auto_sync:
  enabled: true
  # Minutes between syncs. Minimum: 1.
  interval_minutes: 5
  • /ht sync syncs right now.
  • /ht autosync on|off turns automatic syncing on or off and saves the choice to config.yml.
  • /ht autosync pause [minutes] pauses it, 30 minutes by default and up to 10080. Handy while you make lots of changes on Tebex.
  • /ht autosync resume resumes early, and /ht autosync status shows the current state.
  • /ht info shows the key status, store name, counts, last sync, auto-sync state, cache file and the last error.
  • /ht clearcache closes open menus and deletes the memory and disk cache.

The last good sync is cached on disk, so the store still opens instantly after a restart even if Tebex is down. Sale countdowns in open menus refresh every second by default (gui.title_refresh_seconds).

#Customizing categories and packages

After every sync HyperTebex fills store_data.yml with every category and package from your store, with packages nested under their category. Find the one you want by name, change its values, and run /ht reload. HyperTebex never changes values you set; it only adds new entries and keeps the name line up to date. Leaving a value at "", 0, -1, default or [] means "use the normal look". Turn the auto-fill off with store_data.auto_fill: false.

OptionMeaning
nameThe Tebex name, for your reference. Updated automatically.
hiddentrue hides it in the store (or use /ht hide).
display_itemAn item such as DIAMOND_SWORD or PLAYER_HEAD.
display_nameThe item's name, for example "&b&lVIP Rank".
descriptionLines that replace the Tebex description.
custom_model_dataA number for resource pack models (0 = none).
glowtrue, false or default.
slotA fixed slot in the menu (-1 = automatic).
permissionPermission needed to open (category) or buy (package).
allow_quantityPackages with the cart: true, false or default (follows Tebex).
max_quantityPackages with the cart: highest quantity, 0 = the config.yml default.
skull_owner, skull_texture, amountAlso supported: a player name or base64 texture for PLAYER_HEAD, and the stack amount.
description:
  - "&7Access to /fly"
  - "&7and a chat tag"

Hiding things

/ht hide category 12 or /ht hide package 345 hides it right away (open menus update), and /ht show ... brings it back. IDs are in store_ids.txt and tab complete.

Item sources and defaults

default_category_material: CHEST
default_package_material: PAPER
# Use the "GUI item" you set for packages/categories in the Tebex panel (if it is a valid material).
use_tebex_gui_items: true

# How packages are ordered inside a category GUI: order (Tebex panel order), price_asc, price_desc, name
package_sort: order

#Editing the menus (guis.yml)

Every menu lives in guis.yml: main_category_gui, sub_category_gui, package_list_gui, confirmation_gui, cart_add_gui and cart_gui. Each has a title, row count (1 to 6), slots, item templates, navigation buttons and static_items. Do not change config_version; an older guis.yml is backed up and replaced automatically.

Slots are 0-based, with the top-left at 0. Use a single number (13), a range ("10-16") or a mix ("10-16,19-25,31").

main_category_gui:
  title: "&#5B8DEF&l%store_name% &8» &7Store"
  rows: 5
  category_item_slots: "10-16,19-25,28-34"
  center_items: true
  category_item:
    name: "&#5B8DEF&l%category_name%"
    lore:
      - "&8%package_count% packages"
      - ""
      - "%description%"
      - ""
      - "&7Starting at &a%starting_price%"
      - "&c⌛ &7Sale ends in &f%sale_time_left%"
      - ""
      - "&#5B8DEF» &fClick to browse"

Item options

Available on every item section: material, name, lore, amount, glow, custom_model_data, hide_tooltip, skull_texture, skull_owner, and requires_cart: true/false to show the item only when the cart is enabled or disabled. Per GUI you can set border: false and center_items: false.

Static item actions

Add your own buttons to any menu with static_items and one of these actions: close_gui, back, main_menu, next_page, previous_page, store_link, open_cart, cart_checkout, clear_cart, open_category:<id>, open_package:<id>, player_command:<command>, console_command:<command> (supports %player_name%) and message:<text>.

Placeholders in menus

  • Everywhere: %player_name%, %store_name%, %store_url%, %currency_symbol%, %last_sync%, %page%, %max_pages%, %top_sale_time_left%, %cart_count%, %cart_lines%, %cart_total%.
  • Category items: %category_name%, %category_id%, %package_count%, %subcategory_count%, %starting_price%, %sale_time_left%, %description%, %description_line_<n>%.
  • Package items: %package_name%, %package_id%, %category_name%, %price%, %original_price%, %sale_price%, %original_price_if_on_sale%, %discount%, %discount_percent%, %sale_end%, %sale_time_left%, %action_hint%, %cart_quantity%, %max_quantity%, %description%, %description_line_<n>%.
  • Add-to-cart screen also: %quantity%, %total_price%, %in_cart%. Cart items also: %quantity%, %line_total%, %hint_increase%, %hint_decrease%, %hint_remove%.
Lore shortcuts

A lore line that is exactly %description% expands into the full wrapped description. A lore line containing a placeholder with no value (for example %sale_time_left% when nothing is on sale) is removed automatically, and leftover blank lines are tidied up.

Colors work everywhere: legacy &a, hex &#RRGGBB and MiniMessage like <gradient:...>. Every message players see is in messages.yml.

#Locking packages with permissions

You can require a permission to open a category or buy a package, for example to hide rank upgrades from players who already have the rank. Two ways to set it:

  • Per item: set permission on the entry in store_data.yml.
  • By ID, with these switches in config.yml:
permissions:
  # Require hypertebex.package.<id> to purchase a package.
  enforce_package_permissions: false
  # Require hypertebex.category.<id> to open a category.
  enforce_category_permissions: false
  # Hide packages/categories the player has no permission for (instead of showing them and denying clicks).
  hide_locked_items: false

With enforce_package_permissions: true, a player needs hypertebex.package.<package id> (and hypertebex.category.<category id> for categories when that switch is on). These nodes are not declared in the plugin, so grant them through your permissions plugin, with a wildcard such as hypertebex.package.* if you want everything open by default.

#Commands

The admin command is /hypertebex with the aliases /ht and /tebex. Its help list only shows what you have permission for. The store and cart labels are set under commands: in config.yml:

commands:
  # /store [category id|cart]
  store: [store, buy, donate]
  # /cart (only registered while the cart is enabled)
  cart: [cart, basket]
  # Take these labels over even if another plugin already uses them (for example the official Tebex
  # plugin's /buy). If you later remove a label, the other plugin's command is given back.
  override_existing: true

Add as many labels as you like. With override_existing: true (the default), HyperTebex takes over a name another plugin already uses, such as the official Tebex plugin's /buy. Remove the name again and the other plugin gets it back.

CommandWhat it doesPermission
/store [category id|cart]Opens the store, jumps to a category, or opens the cart. Aliases come from config: /buy, /donate. Players only.hypertebex.store.use
/cartOpens your cart. Alias /basket. Only registered while the cart is enabled.hypertebex.store.use
/hypertebex helpShows help, filtered by permission. Aliases: /ht, /tebex.hypertebex.use
/hypertebex reloadReloads all four config files and re-syncs.hypertebex.admin.reload
/hypertebex key <secret_key>Saves the secret key, connects and syncs.hypertebex.admin.key
/hypertebex syncSyncs with Tebex now.hypertebex.admin.sync
/hypertebex autosync <on|off|pause [minutes]|resume|status>Controls the automatic sync. Pause lasts 30 minutes unless you give a time.hypertebex.admin.sync
/hypertebex hide <category|package> <id>Hides a category or package in the store.hypertebex.admin.hide
/hypertebex show <category|package> <id>Shows a hidden category or package again.hypertebex.admin.hide
/hypertebex clearcacheCloses open menus and clears the memory and disk cache.hypertebex.admin.clearcache
/hypertebex infoShows key, store, sync, cache and last error status.hypertebex.admin.info
/hypertebex open <player> [category id]Opens the store (or a category) for an online player. Useful for NPCs and menus.hypertebex.admin.open

#Permissions

hypertebex.admin.* grants every node below. The optional nodes hypertebex.package.<id> and hypertebex.category.<id> are used only when you turn on the permission switches (see Locking packages with permissions).

PermissionWhat it allowsDefault
hypertebex.useUse /hypertebex (help).everyone
hypertebex.store.useOpen the store with /store, /buy and /cart.everyone
hypertebex.admin.reload/hypertebex reload.op
hypertebex.admin.key/hypertebex key.op
hypertebex.admin.sync/hypertebex sync and autosync.op
hypertebex.admin.clearcache/hypertebex clearcache.op
hypertebex.admin.info/hypertebex info.op
hypertebex.admin.open/hypertebex open.op
hypertebex.admin.hide/hypertebex hide and show.op
hypertebex.admin.updateReceive update notifications on join.op
hypertebex.admin.*Every HyperTebex admin permission.op
hypertebex.package.<id>Buy that package when enforce_package_permissions is on. Not declared in plugin.yml; grant it with your permissions plugin.not set
hypertebex.category.<id>Open that category when enforce_category_permissions is on. Not declared in plugin.yml; grant it with your permissions plugin.not set

#Placeholders

These need PlaceholderAPI and use the identifier hypertebex, for example %hypertebex_store_name%. They are null-safe: with no data they return an empty text, false or 0. <id> is a package ID from store_ids.txt. Prices include the currency symbol and show the sale price when a package is on sale.

PlaceholderValue
%hypertebex_store_ready%true once store data is loaded.
%hypertebex_store_name%Your Tebex store name.
%hypertebex_store_url%Your store's web address.
%hypertebex_currency%Currency code, for example USD.
%hypertebex_currency_symbol%Currency symbol (honors currency_symbol_override).
%hypertebex_package_count%Number of packages.
%hypertebex_category_count%Number of categories.
%hypertebex_sale_count%Number of packages on sale right now.
%hypertebex_last_sync%Time of the last sync, in date_format.
%hypertebex_last_sync_ago%How long ago the last sync was.
%hypertebex_package_name_<id>%Name of a package.
%hypertebex_package_price_<id>%Current price of a package (the sale price if on sale).
%hypertebex_package_original_price_<id>%Regular price before any sale.
%hypertebex_package_on_sale_<id>%true or false.
%hypertebex_package_discount_<id>%Discount percent such as 25%, empty if not on sale.
%hypertebex_package_sale_end_<id>%When the sale ends, empty if not on sale.
%hypertebex_top_sale_name%Name of the package with the best current sale.
%hypertebex_top_sale_discount%Discount percent of that package.
%hypertebex_top_sale_price%Price of that package.
%hypertebex_top_sale_time_left%Time left on that sale.
%hypertebex_recent_purchaser_<1-N>%Player name of the Nth most recent purchase.
%hypertebex_recent_purchase_amount_<1-N>%Amount of the Nth most recent purchase, with currency symbol.

#Configuration

The main settings are in config.yml. Apply changes with /ht reload, no restart needed. Colors work everywhere: legacy &a, hex &#RRGGBB and MiniMessage.

Key and API

tebex_secret_key: ""

# Base URL of the Tebex Plugin API. Only change this if Tebex tells you to.
tebex_api_url: "https://plugin.tebex.io"

developer-settings:
  # Verify Tebex's SSL certificate. Only disable this for debugging behind broken proxies!
  verify-ssl: true
  # Timeout for every Tebex request.
  api-timeout-seconds: 10

Prices and dates

# Overrides the currency symbol supplied by Tebex (e.g. "$", "€", "£"). Leave blank to use Tebex's.
currency_symbol_override: ""

# java.text.DecimalFormat pattern used for every price.
price_format: "#,##0.00"

# java.text.SimpleDateFormat pattern used for sale end dates and the last-sync time.
date_format: "MM/dd/yyyy HH:mm z"
# Time zone used for dates, e.g. "America/New_York" or "UTC". Blank = the server's time zone.
timezone: ""

Price display

price_display:
  on_sale: "&c&m%currency_symbol%%original_price%&r &a&l%currency_symbol%%sale_price% &e(-%discount_percent%%)"
  not_on_sale: "&a%currency_symbol%%price%"
  # Use %original_price_if_on_sale% in a package lore line to show this ONLY when the package is on sale.
  original_price_if_on_sale: "&7Was: &c&m%currency_symbol%%original_price%"
  # Shown instead of a price for free (0.00) packages.
  free: "&a&lFREE"

Available here: %currency_symbol%, %price%, %original_price%, %sale_price%, %discount%, %discount_percent%.

Descriptions

# Package/category descriptions are stripped of HTML and word-wrapped to this many characters per line.
max_description_length_per_line: 40
# Maximum number of description lines shown in an item's lore (0 = unlimited).
max_description_lines: 6

GUI behavior and sounds

gui:
  # Hide categories that have no packages (and no non-empty sub-categories).
  remove_empty_categories: true
  # true  = main menu only shows root categories; sub-categories open in their own menu.
  # false = every category (including sub-categories) is listed in the main menu.
  display_parent_categories_only: true
  # How often (seconds) open GUIs are refreshed so %sale_time_left% counts down live. 0 = disabled.
  title_refresh_seconds: 1
  # Re-render open store GUIs after a successful sync so players see new data immediately.
  refresh_on_sync: true
  # Minimum milliseconds between handled GUI clicks (prevents double-click spam).
  click_cooldown_ms: 150
  sound:
    enabled: true
    open: "block.chest.open:0.4:1.2"
    click: "ui.button.click:0.5:1.0"
    success: "entity.player.levelup:0.6:1.6"
    error: "entity.villager.no:0.7:1.0"

Sounds use the form "key:volume:pitch". Leave one blank to disable just that sound. The decorative border and fill-empty-slots options are in guis.yml under gui_settings.

Recent purchases

recent_payments:
  enabled: true
  limit: 5

Feeds %hypertebex_recent_purchaser_<1-N>% and %hypertebex_recent_purchase_amount_<1-N>% from Tebex's payments list.

Debugging

debug_mode: false

Set to true to print requests, timings and parse warnings to the console.

#Troubleshooting and FAQ

The store says it is still loading.

No data has been synced yet. Run /ht info to see whether a key is set and what the last error was, then /ht sync. If no key is set, run /ht key <secret_key>.

Setting the key says it is invalid.

Copy the Secret Key from creator.tebex.io, Integrations, Game Servers, for the correct server, with no spaces. The public token used for the cart is a different value and will not work here.

Purchases are not delivered to players.

HyperTebex does not deliver anything. The official Tebex plugin must be installed and set up with the same secret key so Tebex can run your package commands.

/buy opens another plugin's store.

Keep commands.override_existing: true and make sure buy is in the commands.store list, then restart. If you want the other plugin to keep the name, remove it from the list.

/cart does not exist.

/cart is only registered while cart.enabled is true. You also need your public token in cart.webstore_token.

The cart fails to create a checkout.

Check that cart.webstore_token is the public token (Integrations, API Keys), not the secret key. Set debug_mode: true to see the request details in the console.

A new package does not appear.

Wait for the next auto sync (5 minutes by default), or run /ht sync. Check that auto sync is not paused or off with /ht autosync status, that the package is not hidden, and that its category is not empty (gui.remove_empty_categories).

My changes to guis.yml or store_data.yml do nothing.

Run /ht reload. A value left at "", 0, -1, default or [] in store_data.yml means the normal look is used.

Players see a cooldown message.

That is checkout_cooldown_seconds (5 by default). It stops players from requesting many checkout links in a row.

I want to hide a package without deleting it on Tebex.

Use /ht hide package <id>. Use /ht show package <id> to bring it back.

Can players buy the same package many times at once?

With the cart on, yes, up to cart.max_quantity. Subscriptions and packages with "disable quantity" in Tebex stay at 1.

#Updating

  1. Replace the jar in plugins/ with the new version and restart.
  2. New config and message keys are added automatically, without their explanation comments. Delete config.yml first (keep a copy of your key and settings) if you want the fully commented version.
  3. An older guis.yml is backed up and replaced automatically when its config_version is outdated.

Update checker

updater:
  enabled: true
  check-on-startup: true
  check-interval-hours: 24
  # Download new versions by itself. They install on the next restart (the old jar is backed up first).
  auto-download: false
  notify: true
  # Leave blank to use the built-in values.
  shared-token: ""
  resource-id: 67311

HyperTebex checks BuiltByBit on startup and every 24 hours and tells the console, and admins with hypertebex.admin.update when they join, when a new version is out. With auto-download: true the update is downloaded into the server's update folder, the current jar is backed up to plugins/HyperTebex/backup/, and the new version installs on the next restart.