EcoTale RandomReward

🎲EcoTale RandomReward

Daily Mystery Board · Weighted Loot · Admin GUI

Engaging daily reward mini-game for Hytale servers.

---

Overview

EcoTale RandomReward adds a daily mystery board to your server — a grid of hidden tiles that players can pick once per day for a random prize. Rewards are drawn from a weighted loot pool with 5 rarity tiers. Everything is fully configurable through JSON or the in-game Admin GUI — no server restarts required.

---

Features

Mystery Tile Board

• Configurable grid size (up to 6×6)
• One pick per day — players choose a mystery tile
• Animated reveal with rarity-colored feedback
• Auto-opens GUI on first daily login
• Minimum online time requirement (anti-abuse)

Weighted Loot System

• 4 reward types: Coins, XP, Items, Mixed
• Probability weights per entry (higher = more frequent)
• 5 rarity tiers: Common, Uncommon, Rare, Epic, Legendary
• Per-rarity color coding in the UI
• Mixed rewards combine coins + XP + items

In-Game Admin GUI

• Full reward pool editor — add, edit, delete entries
• Direct text input for name, chance, coins, XP values
• Type & rarity cycling buttons
• Item selection via searchable dropdown (all server items)
• Grid size, language, debug mode settings
• Save & reload config without leaving the game

Soft Dependencies

• EcotaleAPI — coin deposits (optional)
• RPG Leveling — XP integration (optional)
• Endless Leveling — XP integration (optional)
• LuckPerms — permission resolution (optional)
• Falls back gracefully when any dependency is missing

Other

• Multi-language — English, Russian, German, Spanish, French, Portuguese built-in
• Player stats — total claims, last reward, claimed-today status
• JSON storage — per-player files with auto-save
• Permission system — 3-tier resolution: LuckPerms → HyperPerms → permissions.json fallback

---

Project Structure

EcoTaleRandomReward/
├── src/main/java/com/crystalrealm/ecotalerandomreward/
│   ├── EcoTaleRandomRewardPlugin.java        — Plugin lifecycle & event registration
│   ├── commands/
│   │   └── RandomRewardCommandCollection.java  — /randomreward command tree
│   ├── config/
│   │   ├── ConfigManager.java                — JSON config loading/saving
│   │   └── RandomRewardConfig.java           — Configuration POJO
│   ├── gui/
│   │   ├── AdminRewardGui.java               — Admin panel (reward editor + settings)
│   │   ├── DailyRewardGui.java               — Player-facing mystery board
│   │   ├── PageOpenHelper.java               — ECS page opener utility
│   │   └── ReflectiveCodecBuilder.java       — UI codec builder via reflection
│   ├── lang/
│   │   └── LangManager.java                  — i18n with per-player locale
│   ├── model/
│   │   └── PlayerRewardData.java             — Per-player persistent data
│   ├── provider/
│   │   ├── EconomyBridge.java                — Reflection-based economy adapter
│   │   └── leveling/
│   │       ├── LevelProvider.java            — Leveling provider interface
│   │       ├── LevelBridge.java              — Auto-detecting provider router
│   │       ├── RPGLevelingProvider.java      — Zuxaw RPG Leveling adapter
│   │       └── EndlessLevelingProvider.java  — Airijko EndlessLeveling adapter
│   ├── reward/
│   │   └── RewardService.java                — Random selection & reward issuance
│   ├── storage/
│   │   ├── JsonRewardStorage.java            — Per-player JSON persistence
│   │   └── RewardStorage.java               — Storage interface
│   └── util/
│       ├── MessageUtil.java                  — Chat message utilities
│       ├── MiniMessageParser.java            — MiniMessage formatting
│       ├── PermissionHelper.java             — 3-tier permission resolution
│       └── PluginLogger.java                 — Structured logging
├── src/main/resources/
│   ├── default-config.json                   — Default configuration (13 rewards)
│   ├── manifest.json                         — Hytale plugin manifest
│   └── lang/
│       ├── en.json       — English
│       ├── ru.json       — Russian
│       ├── de.json       — German
│       ├── es.json       — Spanish
│       ├── fr.json       — French
│       └── pt_br.json    — Portuguese (Brazil)
└── src/stubs/java/                           — Hytale API compile-time stubs

---

Commands

Command	Permission	Description
/randomreward	ecotalerandomreward.use	Open the mystery board GUI
/randomreward open	ecotalerandomreward.use	Open the mystery board GUI
/randomreward pick	ecotalerandomreward.use	Pick a random tile (CLI)
/randomreward info	ecotalerandomreward.use	View your reward stats
/randomreward admin	ecotalerandomreward.admin	Open the admin GUI
/randomreward reload	ecotalerandomreward.admin	Reload configuration
/randomreward langen	ecotalerandomreward.use	Switch to English
/randomreward langru	ecotalerandomreward.use	Switch to Russian
/randomreward help	ecotalerandomreward.use	Command reference

---

Permissions

Permission	Description	Default
ecotalerandomreward.use	Board access, pick, info, language	All players
ecotalerandomreward.admin	Admin GUI, reload	OP

---

Dependencies

Plugin	Type	Purpose
Ecotale ≥1.0.0	Required	Core server plugin
EcotaleAPI	Optional	Economy integration (coin rewards)
RPG Leveling	Optional	XP reward integration
Endless Leveling	Optional	XP reward integration
LuckPerms	Optional	Group-based permission resolution

All optional APIs are accessed via reflection — the plugin runs without them.

---

Installation

1. Copy EcoTaleRandomReward-1.0.0.jar to your server's Mods/ folder.
2. Start the server — the default config auto-generates with 13 sample rewards.
3. Use /randomreward admin to manage rewards in-game, or edit the JSON directly.
4. /randomreward reload to apply config changes.

---

Configuration

The config file is generated automatically on first run.

General Settings

{
  "General": {
    "DebugMode": false,
    "Language": "en",
    "MessagePrefix": "<gold>[DailyReward]</gold> ",
    "AutoSaveIntervalMinutes": 5,
    "EconomyProvider": "ecotale",
    "LevelProvider": "",
    "AutoOpenGuiOnJoin": true,
    "GridRows": 5,
    "GridColumns": 5,
    "MinOnlineMinutes": 0,
    "GuiTitle": "DAILY REWARD"
  }
}

Field	Description
Language	Default language (en, ru, de, es, fr, pt_br)
EconomyProvider	Economy API to use (ecotale or blank for auto-detect)
LevelProvider	XP provider (rpgleveling, endlessleveling, or blank for auto-detect)
AutoOpenGuiOnJoin	Open the board automatically on first daily login
GridRows / GridColumns	Board size (1–6 each)
MinOnlineMinutes	Minimum time online before claiming

Reward Entry Format

{
  "Id": "coins_jackpot",
  "DisplayName": "Jackpot!",
  "Type": "coins",
  "Coins": 2000.0,
  "Xp": 0,
  "Item": "",
  "Weight": 2,
  "Rarity": "legendary",
  "IconColor": "#ffaa00"
}

Field	Description
Type	Reward type: coins, xp, item, mixed
Coins	Coin amount (for coins and mixed types)
Xp	XP amount (for xp and mixed types)
Item	Item ID in namespace:item:count format (for item and mixed types)
Weight	Probability weight — higher = more likely to be picked
Rarity	common, uncommon, rare, epic, legendary
IconColor	Hex color for the tile display

Item Format

Items use Hytale's internal identifiers:

hytale:weapon_sword_wood:1
hytale:tool_pickaxe_iron:1
hytale:armor_bronze_head:1

---

LuckPerms Integration

The plugin checks permissions in order: LuckPerms API → HyperPerms → permissions.json fallback.

Example setup:

/lp group default permission set ecotalerandomreward.use true
/lp group admin permission set ecotalerandomreward.admin true