# Daily & Weekly Pools

# Daily & Weekly Pools

The pool system controls which quests are offered to players each day and each week. A configurable number of quests are randomly drawn from weighted pools and assigned to every player at the reset time. Players can reroll individual quests they do not want.

## How It Works

1. At the daily reset time, the server selects quests from `daily_pool.json` for each online player.
2. At the weekly reset time (a specific day of the week), quests are drawn from `weekly_pool.json`.
3. Players who were offline during a reset receive their new quests on next login (lazy reset).
4. Old daily/weekly quests that were not completed are abandoned when the reset occurs. Quests that are **ready to claim** stay active until they are claimed.
5. A finished daily or weekly only counts as done within its reset period. When the same quest comes back later, it shows as **New** and can be done again.

With `notifications.announceResets: true`, online players read a chat line when the dailies or weeklies were reset. Admins can force a reset with `/ksquestadmin resetdaily` and `resetweekly`.

## Reset Schedule

The reset schedule is configured in `config.json`:

```json
{
  "dailyResetTime": "04:00",
  "weeklyResetDay": "MONDAY",
  "timezone": "Europe/Berlin",
  "dailyQuestCount": 3,
  "weeklyQuestCount": 5
}
```

| Setting | Default | Description |
|---------|---------|-------------|
| `dailyResetTime` | `"04:00"` | Time of day when daily quests reset (24h format) |
| `weeklyResetDay` | `"MONDAY"` | Day of the week when weekly quests reset |
| `timezone` | `"Europe/Berlin"` | Timezone for all reset calculations |
| `dailyQuestCount` | `3` | Number of daily quests assigned per player |
| `weeklyQuestCount` | `5` | Number of weekly quests assigned per player |

:::tip
All players on the server share the same reset schedule. Resets run at the configured time in the configured time zone; daylight saving time does not move them. The **General** tab of the [admin window](./admin-panel#settings) previews the next resets.
:::

## Pool JSON Structure

Both `daily_pool.json` and `weekly_pool.json` use the same format. Each entry specifies a quest ID and a weight that controls how likely it is to be selected.

```json
{
  "_config_version": "2",
  "pool": [
    { "quest_id": "daily_mine_stone", "weight": 50 },
    { "quest_id": "daily_mine_stone_rare", "weight": 30 },
    { "quest_id": "daily_mine_stone_epic", "weight": 15 },
    { "quest_id": "daily_mine_stone_legendary", "weight": 5 }
  ]
}
```

### Weight System

Each draw picks one quest at random, weighted by its `weight`, and a quest is never drawn twice for the same player in one reset. A quest's chance is its weight divided by the sum of the weights still in the pool. The shipped pools give each tier variant of a quest family these weights:

| Weight | Typical Tier | Share within its family |
|--------|-------------|---------------------------|
| 50 | Common | ~50% |
| 30 | Rare | ~30% |
| 15 | Epic | ~15% |
| 5 | Legendary | ~5% |

- A missing weight counts as **1**.
- **Weight 0** means "never drawn" (since 2.1.0). A pool where every weight is 0 draws nothing and logs one warning.
- Pool weights work the same whether the tier system is on or off. The tier system only sets the reward factor.

The **Pools** tab of the [admin window](./admin-panel#pools) shows the daily and weekly pools side by side, grouped by quest family, with "chance approx. %" per quest, a "Not in pool" list and a rotation preview.

:::info
The pool files are located in `mods/kyuubisoft_questbook/configs/`. They are **base files** that may be updated when the mod is upgraded. Add your custom pool entries in the `custom/` folder instead (the admin window does that for you).
:::

## Custom Pool Entries

To add your own quests to the pool without modifying base files, create `custom_daily_pool.json` or `custom_weekly_pool.json` in the `custom/` folder:

```json
{
  "_info": "Admin-modified daily quest pool. NOT overwritten on mod updates.",
  "disabled_base_ids": [
    "daily_walk",
    "daily_walk_rare"
  ],
  "pool": [
    { "quest_id": "my_custom_daily_quest", "weight": 50 },
    { "quest_id": "my_custom_daily_quest_hard", "weight": 15 }
  ]
}
```

| Field | Description |
|-------|-------------|
| `disabled_base_ids` | Base pool quest IDs to remove from rotation |
| `pool` | Custom quest entries to add to the pool |

Custom entries are merged with the base pool at load time. Disabled base IDs are removed first, then custom entries are appended.

## Reroll System

Players can reroll individual daily and weekly quests they do not want, from the quest's detail panel in the Questbook. The reroll system is configured in `config.json`:

```json
{
  "reroll": {
    "enabled": true,
    "freeRerollsPerDay": 1,
    "freeRerollsPerWeek": 1,
    "paidRerollCost": 10,
    "maxPaidRerollsPerDay": 5,
    "maxPaidRerollsPerWeek": -1,
    "allowRerollStarted": false
  }
}
```

| Setting | Default | Description |
|---------|---------|-------------|
| `enabled` | `true` | Enable or disable the reroll system |
| `freeRerollsPerDay` | `1` | Free daily rerolls per day |
| `freeRerollsPerWeek` | `1` | Free weekly rerolls per week |
| `paidRerollCost` | `10` | Quest token price of the first paid reroll |
| `maxPaidRerollsPerDay` | `5` | Paid daily rerolls per day |
| `maxPaidRerollsPerWeek` | `-1` | Paid weekly rerolls per week; `-1` = same as the daily limit |
| `allowRerollStarted` | `false` | Whether already-started quests can be rerolled |

A quest can opt out with `options.rerollable: false`. In economy mode the price is paid in coins (token price × `tokenExchangeRate`).

### Escalating Costs

Paid rerolls use an escalating cost formula. Each subsequent paid reroll doubles in price:

| Reroll # | Cost (base = 10) |
|----------|-------------------|
| 1st paid | 10 tokens |
| 2nd paid | 20 tokens |
| 3rd paid | 40 tokens |
| 4th paid | 80 tokens |
| 5th paid | 160 tokens |

:::warning
If `allowRerollStarted` is `false` (the default), players cannot reroll a quest they have already begun working on. The reroll button will only appear for quests that have not been started yet.
:::

### Reroll Results

The reroll window shows the price, the free rerolls left and the player's balance before they confirm. The new quest is drawn from the same pool with the pool weights, excluding quests the player already has assigned or running. The player is only charged when another quest was found and the payment succeeded. If no other quest is available, nothing is charged, a free reroll is not used up, and the player gets a notice.

## Default Pool Contents

### Daily Pool

The default daily pool contains quests across 11 categories (Mining, Woodcutting, Digging, Harvesting, Combat, Damage, Crafting, Building, Exploration, Collection, Playtime), each with Common/Rare/Epic/Legendary tier variants.

### Weekly Pool

The default weekly pool features longer quests in 3 categories: Mastery (Miner, Lumberjack, Hunter, Crafter), Challenges (Slayer, Gold Rush, Berserker, Marathon), and Journeys (Adventurer, Survivor, Warrior, Allrounder).