📜 EcoTale Quests

Daily & Weekly quest system for Hytale servers

Give players daily and weekly quests — kill mobs, mine ores, chop trees, harvest crops, earn currency, gain XP — with automatic generation from 46+ quest candidates, wildcard targets, level-scaled rewards, a native GUI panel, an admin settings panel, fully localized quest names, and real-time chat progress notifications.

✨ Features

📦 Requirements

🚀 Getting Started

# 1. Copy JAR files to the server's mods/ folder
cp EcoTaleQuests-1.3.1.jar /server/mods/

# 2. Make sure Ecotale-1.0.7.jar is also in mods/
# 3. Start the server — config & lang files are created automatically
# 4. Customize quest templates if needed
nano mods/com.crystalrealm_EcoTaleQuests/EcoTaleQuests.json

That's it. Quest pools are generated on first startup. Players can immediately browse and accept quests.

🎮 Commands

[!NOTE] Quest IDs use short 8-character identifiers (e.g., a3f7b2c1).

🖥️ GUI Panels

Player Quest Panel (/quests gui)

Native GUI built on Hytale's InteractiveCustomUIPage API with .ui layouts:

• Daily tab — available daily quests with Accept / Abandon / Info buttons
• Weekly tab — available weekly quests with Accept / Abandon / Info buttons
• Progress bar and status displayed for each active quest

The panel auto-refreshes after accepting or abandoning a quest.

Admin Settings Panel (/quests admin)

Admin-only panel for server configuration:

• Toggle modules on/off (mob kills, mining, woodcutting, farming, currency, XP)
• Reload — reload config & lang files
• Refresh — regenerate quest pools
• Save — persist current settings to disk

🔐 Permissions

Base Permissions — all players:

ecotalequests.use              # /quests, available, accept, abandon, info, gui, stats

VIP Tiers (configurable in VipTiers):

ecotalequests.multiplier.vip        # ×1.25 quest reward multiplier (VIP)
ecotalequests.multiplier.mvp        # ×1.50 quest reward multiplier (MVP)
ecotalequests.multiplier.mvp_plus   # ×2.00 quest reward multiplier (MVP+)

Admin:

ecotalequests.admin.reload     # /quests reload
ecotalequests.admin.settings   # /quests admin (settings panel)
ecotalequests.*                # All permissions

⚙️ Configuration

Config file: mods/com.crystalrealm_EcoTaleQuests/EcoTaleQuests.json

📋 General & Limits

{
  "General": {
    "DebugMode": false,
    "Language": "ru",
    "NotifyOnProgress": true,
    "NotifyOnComplete": true,
    "AutoSaveIntervalMinutes": 5
  },
  "QuestLimits": {
    "MaxDailyActive": 4,
    "MaxWeeklyActive": 2,
    "DailyPoolSize": 10,
    "WeeklyPoolSize": 5,
    "MaxAbandonPerDay": 3,
    "DailyResetTime": "00:00",
    "WeeklyResetDay": "MONDAY"
  }
}

🎲 Quest Generation Templates

Each template defines a quest that can appear in the generated pool:

{
  "Generation": {
    "mobTemplates": [
      { "target": "Kweebec",     "minAmount": 5,  "maxAmount": 15 },
      { "target": "Trork",       "minAmount": 3,  "maxAmount": 10 },
      { "target": "Scarak",      "minAmount": 5,  "maxAmount": 20 },
      { "target": "Feran",       "minAmount": 3,  "maxAmount": 12 },
      { "target": "Fen_Stalker", "minAmount": 2,  "maxAmount": 8  },
      { "target": "Void_Dragon", "minAmount": 1,  "maxAmount": 3  }
    ],
    "oreTemplates": [
      { "target": "copper", "minAmount": 10, "maxAmount": 30 },
      { "target": "iron",   "minAmount": 8,  "maxAmount": 25 },
      { "target": "gold",   "minAmount": 5,  "maxAmount": 15 },
      { "target": "cobalt", "minAmount": 3,  "maxAmount": 10 }
    ],
    "woodTemplates": [
      { "target": "oak",    "minAmount": 15, "maxAmount": 40 },
      { "target": "birch",  "minAmount": 15, "maxAmount": 40 },
      { "target": "pine",   "minAmount": 10, "maxAmount": 30 },
      { "target": "ebony",  "minAmount": 5,  "maxAmount": 15 }
    ],
    "cropTemplates": [
      { "target": "wheat",   "minAmount": 20, "maxAmount": 50 },
      { "target": "pumpkin", "minAmount": 10, "maxAmount": 30 },
      { "target": "berry",   "minAmount": 15, "maxAmount": 40 }
    ]
  }
}

The generator picks from these templates randomly, applies level scaling to amounts, and creates quest objectives.

💰 Rewards

{
  "Rewards": {
    "dailyBaseCoins": 15.0,
    "weeklyBaseCoins": 75.0,
    "bonusXpPerQuest": 50,
    "levelScalingFactor": 0.08,
    "vipMultiplier": 1.25,
    "premiumMultiplier": 1.5
  }
}

Reward formula: Final Reward = Base × (1 + level × factor)

🛡️ Protection

{
  "Protection": {
    "acceptCooldownSeconds": 30,
    "allowedWorlds": [],
    "blockAbuseInCreative": true
  }
}

📝 Quest Lifecycle

┌─────────────┐    accept    ┌────────────┐   progress   ┌───────────────┐
│  AVAILABLE   │────────────▶│   ACTIVE    │─────────────▶│   COMPLETED   │
│  (in pool)   │             │ (tracking)  │   (100%)     │  (rewarded!)  │
└─────────────┘             └──────┬──────┘              └───────────────┘
                                   │
                          abandon  │  expire
                                   ▼
                            ┌──────────────┐
                            │  ABANDONED /  │
                            │   EXPIRED     │
                            └──────────────┘

1. Pool Generation — Server generates daily/weekly quest pools from config templates
2. Browse & Accept — Players view available quests (GUI or chat) and accept
3. Progress Tracking — Actions automatically tracked via ECS events and balance polling
4. Notifications — Players receive chat messages on every action + milestones at 25/50/75%
5. Completion & Reward — At 100%, currency is deposited via Ecotale API + bonus XP granted
6. Expiry — Unfinished quests expire at the next daily/weekly reset

Key Design Decisions

• ECS Event Pattern — Block listeners use Hytale's EntityEventSystem<EntityStore, Event> with ArchetypeChunk for player resolution
• Reflection-first — All Store, PlayerRef, Message calls use reflection for stub compatibility
• Ecotale API (static) — Rewards and currency tracking via com.ecotale.api.EcotaleAPI (static API from Ecotale-1.0.7)
• Balance Polling — CoinQuestListener checks balances every 2 seconds — if increased, the difference counts as earnings
• RPG API Auto-detect — Tries get(), getInstance(), getAPI() methods for cross-version compatibility
• JSON Storage — File-based persistence (quests/ for pools, players/<uuid>.json for progress) — no database required
• Immutable Quests — Quest objects are immutable; only PlayerQuestData tracks mutable progress state
• HyUI GUI — Tabbed quest panel with accept/abandon buttons, progress bars, auto-refresh

🔌 EcoTale Ecosystem

EcoTaleQuests is part of the CrystalRealm EcoTale plugin family:

🌍 Localization

Built-in support for 6 languages: English, Russian, Brazilian Portuguese, French, German, Spanish. Language files are auto-generated on first start.

Per-player switching:

/quests lang en
/quests lang ru
/quests lang pt_br
/quests lang fr
/quests lang de
/quests lang es

Shortcut aliases also work: /quests langen, /quests langru, /quests langpt, /quests langfr, /quests langde, /quests langes

All quest names are fully localized. Players see translated quest descriptions (Добыть: Железо ×24, Убить: Любые мобы ×22) in both GUI and chat — never raw internal IDs.

100+ localization keys, including:

• quest.completed / quest.action_progress — progress and completion messages
• quest.desc.* — descriptions for all 6 quest types
• quest.type.* — category names (Мобы, Руда, Дерево, Урожай, Валюта, Опыт)
• target.* — 40+ targets (mobs, ores, trees, crops) including wildcards (Любые мобы, Любая руда…)
• cmd.* — command feedback
• gui.* — GUI panel elements

Custom translations: Edit the generated JSON files in mods/com.crystalrealm_EcoTaleQuests/lang/

⚠️ Issues & Feature Requests

Please report any bugs, issues, or feature suggestions via GitHub Issues.
This helps keep feedback organized and allows faster tracking and fixes.

📄 License

This project is licensed under the MIT License — see the LICENSE file.

Made with ❤️ by CrystalRealm for the Hytale community