📜 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     │
                            └──────────────┘

Pool Generation — Server generates daily/weekly quest pools from config templates
Browse & Accept — Players view available quests (GUI or chat) and accept
Progress Tracking — Actions automatically tracked via ECS events and balance polling
Notifications — Players receive chat messages on every action + milestones at 25/50/75%
Completion & Reward — At 100%, currency is deposited via Ecotale API + bonus XP granted
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