EcoTale Quests

📜 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

Feature	Description
📋 Daily Quests	Up to 10 fresh quests every day from a generated pool (4 active at once)
📅 Weekly Quests	Up to 5 weekly quests with bigger rewards (2 active at once)
⚔️ Kill Mobs	11 mob types — zombie, skeleton, spider, trork, kweebec, scarrak, feran, outlander, raptor, magma golem + any mob wildcard
⛏️ Mine Ores	8 ore types — copper, iron, silver, gold, cobalt, emerald, mythril + any ore wildcard
🪓 Chop Wood	7 tree types — oak, birch, pine, willow, redwood, jungle + any wood wildcard
🌾 Harvest Crops	10 crop types — wheat, potato, carrot, berry, tomato, onion, pumpkin, corn, melon + any crop wildcard
💰 Earn Currency	Meta-quests — earn a total amount of currency from any source
✨ Gain XP	Meta-quests — gain RPG experience from any source
🎯 Wildcard Targets	any_mob, any_ore, any_wood, any_crop — match any action of that type
🖥️ GUI Panel	Native quest panel with Daily/Weekly tabs, accept/abandon/info buttons
🛠️ Admin Panel	Admin settings GUI — toggle modules, reload config, save settings
📊 Localized Progress	Fully translated quest names in chat (e.g. [Q] Добыть: Железо: 3/22)
🎲 Auto-Generation	46+ quest candidates, pools generated automatically each day/week
📈 Level Scaling	Quest difficulty and rewards scale with player RPG level
🏅 Milestone Alerts	Additional notifications at 25%, 50%, 75% progress
🛡️ Abuse Protection	Accept cooldowns, world filtering, duplicate prevention, expiry enforcement
💾 JSON Storage	Per-player quest data saved as JSON files
🌍 Localization	RU / EN / PT-BR / FR / DE / ES — all quest names, targets, and UI elements fully translated
🔧 Hot Reload	/quests reload — no restart needed
🏅 Adventurer Ranks	E→S rank progression, rank badges on quests, rank-locked quests
⏰ Quest Timers	Configurable time limits for quests with countdown display
📌 Quest Board	Physical wall-mounted quest board block — interact with [F] to open quests

📦 Requirements

Dependency	Required	Description
Ecotale ≥ 1.0.0	✅	Economy & currency system
RPG Leveling ≥ 0.2.0	✅	Level-scaling for mob rewards
EconomyAPI ≥ 1.4.5	✅	Economy & currency system
MMO Skill Tree ≥ 0.11.2	✅	Level-scaling for mob rewards
Endless Leveling ≥ 5.13	✅	Level-scaling for mob rewards

🚀 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

Command	Description	Permission
/quests tracker	for on/off HUD for player
/quests	Show active quests with progress	ecotalequests.command.quests
/quests available	Browse available quests to accept	ecotalequests.command.quests
/quests accept	Accept a quest from the pool	ecotalequests.command.quests
/quests abandon	Abandon an active quest	ecotalequests.command.quests
/quests info	Detailed quest information	ecotalequests.command.quests
/quests gui	Open the quest GUI panel	ecotalequests.use
/quests admin	Open the admin settings panel	ecotalequests.admin.settings
/quests stats	Your quest completion statistics	ecotalequests.use
/quests rank	Your adventurer rank and progress	ecotalequests.use
/quests reload	Reload config & lang files	ecotalequests.admin.reload
/quests lang	Switch language (en/ru/pt_br/fr/de/es)	—
/quests help	Command reference	—

[!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"
  }
}

Key	Default	Description
MaxDailyActive	4	Max daily quests a player can have active at once
MaxWeeklyActive	2	Max weekly quests active at once
DailyPoolSize	10	How many daily quests are generated each day
WeeklyPoolSize	5	How many weekly quests are generated each week
MaxAbandonPerDay	3	Max quest abandonments per day
DailyResetTime	00:00	Time when daily pool refreshes
WeeklyResetDay	MONDAY	Day of week for weekly pool refresh

🎲 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
  }
}

Key	Default	Description
dailyBaseCoins	15.0	Base currency reward for daily quests
weeklyBaseCoins	75.0	Base currency reward for weekly quests
bonusXpPerQuest	50	Bonus RPG XP per completed quest
levelScalingFactor	0.08	Reward multiplier per player level (level × factor)

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

🛡️ Protection

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

Key	Default	Description
acceptCooldownSeconds	30	Cooldown between accepting quests
allowedWorlds	[] (all)	Restrict quest progress to specific worlds
blockAbuseInCreative	true	Prevent quest progress in creative mode

📝 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:

Plugin	Description
EcoTaleIncome	Earn currency through mob kills, mining, woodcutting, farming
EcoTaleBanking	Banking system — deposits, loans, credit score, interest
EcoTaleQuests	Daily & weekly quest system ← you are here

🌍 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