# Challenges

**Version:** 2.0.7

Every player gets their own set of daily and weekly challenges, picked from the pools of the running season. A finished challenge pays XP and tokens once.

![Challenges tab with daily, weekly and premium challenges](../../../../assets/season-pass/season-pass-challenges.png)
*The Challenges tab: daily and weekly columns with progress bars and reset countdowns, premium challenges below.*

## Challenge definition

Challenges are listed in `dailyChallenges` and `weeklyChallenges` of the season file. Premium challenges sit in the same two lists with `"premiumOnly": true`.

| Field | Default | Description |
|-------|---------|-------------|
| `id` | none | Unique ID across both pools, e.g. `daily_mine_50` |
| `name` | the ID | Shown on the card, in the chat message and the HUD toast |
| `description` | `""` | Line under the name |
| `descriptionKey` | none | Optional localization key used instead of `description`; `{0}` is replaced by `count`, `{1}` by `target` |
| `type` | none | See [Types](#types) |
| `target` | `"any"` | What has to be hit, see [Targets](#targets) |
| `count` | `1` | Amount needed |
| `xpReward` | `100` | XP on completion |
| `tokenReward` | `10` | Tokens on completion (in the season currency) |
| `weight` | `10` | Chance in the random pick; higher = more often |
| `iconItem` | none | Card icon; without a valid item a default icon for the type is used |
| `premiumOnly` | `false` | `true`: only rolled into the premium slots |

```json
{
  "id": "daily_kill_10",
  "name": "Monster Slayer",
  "description": "Kill 10 mobs",
  "type": "mob_kill",
  "target": "any",
  "count": 10,
  "xpReward": 150,
  "tokenReward": 8,
  "weight": 15,
  "iconItem": "Weapon_Longsword_Iron"
}
```

---

## Types

| Type | Counts | Needs KyuubiSoft Core tracking |
|------|--------|-------------------------------|
| `break_block` | blocks mined | yes |
| `place_block` | blocks placed | yes |
| `mob_kill` | NPCs killed | yes |
| `player_kill` | players killed | yes |
| `flower_pick` | flowers picked | yes |
| `zone_discover` | zones entered for the first time that day | yes |
| `harvest` | plants harvested | no |
| `distance_traveled` | blocks walked (`count` = blocks) | no |
| `playtime` | minutes online (`count` = minutes) | no |
| `daily_login` | the first join of the day (use `count` 1) | no |
| `login_streak` | the current login streak in days (the progress is set to the streak, not added) | no |

Only these types are ever rolled. Any other type, for example `items_collected` or the old name `travel`, is never picked, because nothing would count it. The admin panel marks such challenges "Never counted". When KyuubiSoft Core's tracking is not running, only the types without "yes" are rolled.

## Targets

| Target | Matches |
|--------|---------|
| `any` | everything of that type |
| `Wood_Oak_Trunk` | exactly this ID (case-sensitive) |
| `Skeleton_*` | IDs that start with `Skeleton_` |
| `*_Ore` | IDs that end with `_Ore` |
| `*Iron*` | IDs that contain `Iron` |

The ID is the block ID for block, harvest and flower challenges, the NPC type for kills and the zone name for zones. `distance_traveled`, `playtime`, `daily_login` and `login_streak` only work with `any`.

---

## Rotation

| Setting | Default | Description |
|---------|---------|-------------|
| `dailyChallengeSlots` | `3` | Daily challenges per player |
| `weeklyChallengeSlots` | `3` | Weekly challenges per player |
| `premiumDailyChallengeSlots` | `2` | Daily premium challenges |
| `premiumWeeklyChallengeSlots` | `1` | Weekly premium challenges |

- **When:** daily challenges change at the first check of a new day, weekly ones at the first check from Monday on, both in the `timezone` of `config.json` (by default the server clock). The check runs when a player joins, every 60 seconds for everyone online, when a season starts and when it is resumed. Nothing rotates while the season is paused.
- **How:** weighted random pick without repeats. Within one list (daily, weekly, premium daily, premium weekly) there is at most **one challenge per type**; free and premium lists are picked separately and may share a type.
- **Per player:** the pick depends on the player and the day, so players see different challenges, and a player sees the same ones all day (or week).
- A new pick drops the progress of the challenges it replaces.
- With fewer usable challenges than slots, the player simply gets fewer.

:::caution[Forced re-roll]
**New daily challenges** / **New weekly challenges** in the admin panel's **Events** section re-roll the lists of all online players within a minute. Because the pick depends on player and day, players usually get the **same** challenges again, with progress back at 0, and can complete them a second time.
:::

---

## Premium challenges

- The premium lists are filled from the `premiumOnly` challenges of the same pools, for every player.
- Progress only counts while the player owns the premium pass. Buying the pass during the day starts counting from then on.
- Players without the pass see the premium section locked, with what their current premium picks are worth, for example "3 bonus challenges worth +1,300 XP and +65 Tokens", and a **View Premium** button that opens the premium window.
- With `premiumEnabled: false` the premium section is hidden.

---

## Completion

When the progress reaches `count`:

1. The challenge is marked **Done** until the next rotation.
2. `xpReward` is granted like any other XP (multipliers and daily caps apply) and `tokenReward` in the season currency.
3. With the player's **Challenge done** setting on (default): the chat line "Challenge complete! +X XP, +Y Tokens" and a HUD toast with the name, XP, tokens and how many daily challenges are left.

Nothing is counted while the season is paused.

---

## Default pools

`season_1.json` ships 16 daily and 12 weekly challenges:

| Pool | Normal | Premium only |
|------|--------|--------------|
| Daily | Miner (50 blocks), Deep Miner (100 blocks), Monster Slayer (10 kills), Monster Hunter (25 kills), Builder (100 placed), Harvester (20), Flower Picker (10), Dedicated (30 min), Scout (1 zone), Wanderer (500 blocks walked), Daily Check-In (login) | Premium Miner (200), Premium Slayer (50), Premium Harvester (50), Premium Botanist (25 flowers), Premium Pathfinder (1,500 blocks walked) |
| Weekly | Mining Expert (500), Monster Destroyer (100 kills), Zone Explorer (5 zones), Master Builder (500 placed), Farmer (100), Veteran (120 min), Marathon Runner (5,000 blocks), Botanist (50 flowers), Loyal Player (5-day streak) | Premium Mining Expert (1,000), Premium Destroyer (200 kills), Premium Explorer (10,000 blocks) |

All of them use target `any`. "Forager" (`items_collected`) was removed in 2.0.0 because nothing counted it.

---

## In the book

The **Challenges** tab shows:

- **Daily** and **Weekly** columns with "new in 5h 12m" and "new on Monday · in 3 days".
- One card per challenge: icon, name, description, a progress bar with "12 / 50", "+150 XP" and "+8 Tokens". Finished cards are dimmed and marked **Done**.
- **Premium challenges** below, with "2 daily · 1 weekly" for premium players or the lock box for everyone else.
- The tab label shows how many of your active challenges are done (e.g. "2 / 6").