HiddenGifts

Turn your Hytale server into a treasure hunt.
Admins hide a chest anywhere in the world, players get proximity hints as they explore,
and the first to find it claims tiered loot rewards — all broadcast live to the server.

Features

Admin-placed treasure chests — Use /hiddengift place for a random tier or /hiddengift place rare to pick one
Proximity notifications — Players get a toast alert when they're within range of the hidden chest
Tiered reward system — Common, Rare, and Legendary tiers with weighted random selection, each with configurable item pools and quantity ranges
Server-wide announcements — Placement and discovery broadcast via event titles, toast notifications, and chat messages
Indestructible chest — The gift chest cannot be damaged or broken by players
Finder cooldown — Prevent the same player from claiming back-to-back (configurable duration)
Fully configurable — All tiers, items, messages, radius, cooldowns, and the chest block ID are editable in config.json

How It Works

An admin runs /hiddengift place [tier] while looking at a block
A chest appears on top of that block and the server is notified a treasure has been hidden
Players exploring the world receive a proximity toast when they get close
The first player to walk up to the chest claims the loot — items go straight to inventory
Everyone sees who found it, what tier it was, and what they won

Commands

Command	Permission	Description
`/hiddengift place [tier]`	`hiddengifts.place`	Hide a gift chest (random or specific tier)
`/hiddengift remove`	`hiddengifts.place`	Remove the active gift
`/hiddengift stats`	Everyone	View your total finds

Requirements

PlayerData-Core (required) — Tracks per-player find stats and cooldowns. Must be installed and loaded before HiddenGifts.

Installation

Install PlayerData-Core
Drop the HiddenGifts .jar into your server's plugins folder
Start the server — a default config.json is generated automatically
Edit config.json to customize tiers, rewards, and messages

Configuration Guide

A config.json file is generated in the plugin's data folder on first run. Below is every setting explained.

General Settings

Key	Type	Default	Description
`hintRadius`	Integer	`30`	How close (in blocks) a player must be to the hidden chest before they receive a proximity toast notification. Range: 5–200.
`finderCooldownMinutes`	Integer	`10`	After finding a treasure, how many minutes a player must wait before they can claim another one. Set to `0` to disable. Range: 0–1440.
`placerCanClaim`	Boolean	`false`	Whether the admin who placed the chest is allowed to claim it themselves.
`chestBlockId`	String	`"Furniture_Christmas_Chest_Small"`	The block ID used for the visible chest in the world. Can be any valid Hytale block or furniture ID.

Tier System

Tiers are defined under the "tiers" key as a map. Each tier name (e.g. "common", "rare", "legendary") maps to a tier object. You can add, remove, or rename tiers freely.

Tier Object

Key	Type	Description
`weight`	Integer	How likely this tier is chosen during random placement. Higher = more frequent. A tier with weight `60` is picked 6x more often than one with weight `10`.
`pickCountMin`	Integer	Minimum number of items to award from this tier's pool.
`pickCountMax`	Integer	Maximum number of items to award. The actual count is rolled randomly between min and max. Capped to the number of items in the pool.
`items`	Array	The pool of possible reward items (see below).

Item Object (inside `items` array)

Key	Type	Description
`item`	String	The Hytale item ID to give (e.g. `"Ingredient_Bar_Iron"`, `"Tool_Pickaxe_Cobalt"`).
`min`	Integer	Minimum quantity of this item to give.
`max`	Integer	Maximum quantity. Rolled randomly between min and max. Set both to the same value for a fixed amount.

How Tier Selection Works

With weights common: 60, rare: 30, legendary: 10 (total = 100):

Common — picked ~60% of the time
Rare — picked ~30% of the time
Legendary — picked ~10% of the time

How Rewards Are Rolled

Example: A rare tier with pickCountMin: 2, pickCountMax: 3 and 4 items in the pool:

Roll a number between 2 and 3 → e.g. 3
Randomly pick 3 items from the pool
For each picked item, roll a quantity between its min and max

Messages

All display text is configurable. Use the placeholders shown below — they are replaced at runtime.

Placement Messages (shown to the whole server when a chest is hidden)

Key	Default	Placeholders
`messageHiddenPlaced`	`"A {tier} treasure has been hidden somewhere in the world!"`	`{tier}` — tier name
`messagePlacedToast`	`"Treasure Hidden!"`	—
`messagePlacedToastHint`	`"A {tier} gift is waiting to be found!"`	`{tier}` — tier name

Proximity Messages (shown to individual players near the chest)

Key	Default	Placeholders
`messageProximityToast`	`"Treasure Nearby!"`	—
`messageProximityHint`	`"You sense a hidden treasure nearby..."`	—

Discovery Broadcast (shown to the whole server when someone finds it)

Key	Default	Placeholders
`messageFoundTitle`	`"{player} Found It!"`	`{player}`
`messageFoundSubtitle`	`"A {tier} treasure has been claimed!"`	`{tier}`
`messageFoundToast`	`"{player} found a hidden treasure!"`	`{player}`
`messageFoundToastHint`	`"They claimed the {tier} reward!"`	`{tier}`
`messageFoundChat`	`"--- {player} found a {tier} treasure! ---"`	`{player}`, `{tier}`
`messageRewardFormat`	`"Reward: {reward}"`	`{reward}` — formatted reward list

Personal Feedback (shown only to the finder)

Key	Default	Placeholders
`messagePersonalFoundTitle`	`"Treasure Found!"`	—
`messagePersonalFoundToast`	`"Reward Collected!"`	—
`messagePersonalFoundChat`	`"+ {reward} added to your inventory!"`	`{reward}`
`messagePersonalFoundStats`	`"Total treasures found: {found}"`	`{found}` — lifetime find count

Cooldown Messages (shown when a player on cooldown gets near a chest)

Key	Default	Placeholders
`messageCooldownToast`	`"On Cooldown"`	—
`messageOnCooldown`	`"You found one recently! Wait {minutes} minutes."`	`{minutes}`

Misc Messages (used in commands)

Key	Default	Placeholders
`messageNoGiftActive`	`"No hidden gift is currently active."`	—
`messageAlreadyActive`	`"A hidden gift is already active!"`	—
`messageStats`	`"You have found {found} hidden treasures!"`	`{found}`

Full Default Config

{
  "hintRadius": 30,
  "finderCooldownMinutes": 10,
  "placerCanClaim": false,
  "chestBlockId": "Furniture_Christmas_Chest_Small",
  "tiers": {
    "common": {
      "weight": 60,
      "pickCountMin": 1,
      "pickCountMax": 2,
      "items": [
        { "item": "Ingredient_Bar_Iron", "min": 2, "max": 5 },
        { "item": "Ingredient_Bar_Copper", "min": 3, "max": 8 }
      ]
    },
    "rare": {
      "weight": 30,
      "pickCountMin": 2,
      "pickCountMax": 3,
      "items": [
        { "item": "Ingredient_Bar_Cobalt", "min": 1, "max": 3 },
        { "item": "Tool_Pickaxe_Iron", "min": 1, "max": 1 }
      ]
    },
    "legendary": {
      "weight": 10,
      "pickCountMin": 3,
      "pickCountMax": 5,
      "items": [
        { "item": "Tool_Pickaxe_Cobalt", "min": 1, "max": 1 },
        { "item": "Weapon_Sword_Iron", "min": 1, "max": 1 }
      ]
    }
  },
  "messageHiddenPlaced": "A {tier} treasure has been hidden somewhere in the world!",
  "messagePlacedToast": "Treasure Hidden!",
  "messagePlacedToastHint": "A {tier} gift is waiting to be found!",
  "messageProximityHint": "You sense a hidden treasure nearby...",
  "messageProximityToast": "Treasure Nearby!",
  "messageFoundTitle": "{player} Found It!",
  "messageFoundSubtitle": "A {tier} treasure has been claimed!",
  "messageFoundToast": "{player} found a hidden treasure!",
  "messageFoundToastHint": "They claimed the {tier} reward!",
  "messageFoundChat": "--- {player} found a {tier} treasure! ---",
  "messageRewardFormat": "Reward: {reward}",
  "messagePersonalFoundTitle": "Treasure Found!",
  "messagePersonalFoundToast": "Reward Collected!",
  "messagePersonalFoundChat": "+ {reward} added to your inventory!",
  "messagePersonalFoundStats": "Total treasures found: {found}",
  "messageCooldownToast": "On Cooldown",
  "messageOnCooldown": "You found one recently! Wait {minutes} minutes.",
  "messageNoGiftActive": "No hidden gift is currently active.",
  "messageAlreadyActive": "A hidden gift is already active!",
  "messageStats": "You have found {found} hidden treasures!"
}

Hidden Gifts