UI & HUD

UI & HUD

The Season Pass provides a multi-tab UI accessible via the Season Pass Book item or the /sp command, plus a persistent HUD tracker on screen.

Season Pass Book Item

The Season Pass Book is a physical in-game item (Spellbook model, Rare quality) that opens the Season Pass UI on right-click.

Item Configuration

Configured in config.json under the item section:

Setting	Default	Description
enabled	true	Enable the Season Pass Book item
itemId	"SeasonPass"	Item ID
giveOnFirstJoin	true	Auto-give on first login
giveOnEveryJoin	false	Re-give on every login
hotbarSlot	8	Hotbar slot (0-8)
giveDelaySeconds	3	Delay before giving (allows world load)

The item is only given when a season is active. Duplicate protection prevents multiple copies in inventory.

Season Pass UI Tabs

Tiers Tab

The main progression view showing the free and premium reward tracks.

• 6 tiers per page with pagination (left/right arrows)
• Free Track — Top row, rewards available to all players
• Premium Track — Bottom row, requires premium pass
• Tier Badge — Shows tier number; turns green with “Claim now” text when rewards are claimable
• Lock Overlay — Displayed on tiers not yet reached or premium-only tiers
• Bonus Tiers — Tiers 31-40 shown after the standard 30 tiers
• Rarity Tinting — Reward cards display rarity-based color tinting (Common through Legendary)
• ContainerFullPatch Textures — Native Hytale card textures with decorative borders on reward cards
• Current Tier Highlight — Active tier has a visual glow effect

Claiming Rewards:

1. Reach the required tier through XP progression
2. Click the green “Claim now” badge on the tier
3. Rewards are automatically granted (items, commands, lootbags, tokens)
4. Badge returns to showing the tier number after claim
5. Claim All button appears when 2+ rewards are claimable — claims all at once

Prestige Badge:

• After reaching max tier with prestigeEnabled, a prestige badge shows the current level
• Prestige level and XP boost percentage displayed

:::note Premium Track If the player doesn’t have premium, premium rewards show a lock overlay. Purchasing premium retroactively unlocks all earned premium tiers for claiming. :::

Challenges Tab

Displays active daily and weekly challenges with progress tracking.

• 3 Daily Challenges — Reset at midnight
• 3 Weekly Challenges — Reset every Monday
• Each challenge shows: name, progress bar with percentage, X/Y count, XP reward, currency reward
• Time Urgency Colors — Challenge timers change color as deadlines approach
• Completed challenges display a green checkmark
• Reset countdown per section (“Resets in: Xh Ym”)

Premium Challenges:

• 2 extra daily + 1 extra weekly challenge below the regular challenges
• Non-premium players see a lock box with hint text instead
• Premium challenges show the same progress tracking UI

Shop Tab

Daily rotating token shop with purchasable items.

• 4 Item Cards per day with ContainerFullPatch card textures and decorative borders
• Each card shows: icon, name, description, price in configured currency, buy button
• Rarity Tinting — Shop cards display rarity-based color tinting
• Currency Balance displayed in the header with configured currency name and icon
• Refresh Timer — Countdown until next rotation
• SOLD Badge — Dark overlay on already-purchased items
• Buy button disabled when insufficient tokens

Premium Shop:

• 2 extra shop slots below the regular items
• Non-premium players see a lock box with hint text

History Tab

Archive of past season progress.

• Up to 5 entries from previous seasons
• Each entry shows: season name, max tier reached, total XP earned, tokens earned, premium status
• Displayed when no season is active or for reference

Settings Page

Accessible from the Season Pass UI via a settings button.

Available Settings

Setting	Options	Default	Description
HUD Enabled	On / Off	On	Toggle the HUD tracker
HUD Position	4 presets	Top Right	Position preset selection
XP Notifications	All / Large / Off	Large	Chat notification mode
Tier-Up Notifications	On / Off	On	Chat notification on tier-up
Challenge Notifications	On / Off	On	Chat notification on challenge complete

XP Notification Modes

Mode	Description
All	Show every XP gain in chat
Large	Only show XP gains above threshold (default: 50 XP)
Off	No XP notifications in chat

HUD Tracker

A persistent on-screen display showing season progress at a glance.

Display Information

• Season name
• Current tier / Max tier
• XP progress toward next tier (smoother bar with 5% steps and percent overlay)
• Currency balance with configured currency icon

Position Presets

Preset	X	Y
top_left	16	100
top_right	1580	100
middle_right	1580	430
bottom_right	1580	700

Features

• Auto-hide when the world map is opened
• MHUD Compatible — Works alongside other mods using the MHUD system
• Real-time Updates — Refreshes on XP gain, tier-up, and token changes
• Per-Player Toggle — Each player can enable/disable via settings
• Global Toggle — Server admin can disable for all players in config.json

:::info Element ID Prefix All HUD element IDs use the #SP prefix (e.g., #SPTier, #SPXp) to avoid conflicts with other mods’ HUDs. This follows the global HUD element ID convention. :::

Premium Info Page

A modal page shown when clicking the premium button (if not already premium):

• Lists premium benefits (1.5x XP boost, exclusive rewards, premium badge)
• Shows current premium status (owned or not)
• Displays premium cost and currency
• Directs players to use /sp buy for purchase

:::warning No Accidental Purchases The premium button opens an info page instead of directly purchasing. Players must explicitly use /sp buy to complete the purchase. This prevents accidental premium purchases. :::

Admin Panel

The admin panel is a full in-game configuration editor opened via /spadmin panel. It provides 11 tabs organized into three categories:

CONFIG Tabs

• General — Core settings (language, debug, timezone, auto-save)
• Season — Season metadata, timing, tier scaling
• Currency — Currency mode, name, icon, provider settings
• Premium — Premium pass cost, XP boost, command-only mode
• XP Sources — All XP source weights editable inline
• Prestige — Prestige toggle, boost percent, max level

CONTENT Tabs

• Tiers — Create, edit, and delete tier definitions with rewards
• Challenges — Manage the challenge pool (daily/weekly)
• Shop — Configure shop items, costs, weights, and rewards

MANAGEMENT Tabs

• Players — View and manage individual player season data
• Events — Start/stop Double XP events, start/end/pause seasons

All changes made in the admin panel take effect immediately without server restart.