# Hunt Files

Each hunt is stored as a separate YAML file in the `plugins/HeadBlocks/hunts/` directory. On first start, a `default.yml` file is automatically generated from your existing `config.yml` settings.

## File Structure

```
plugins/HeadBlocks/
  hunts/
    default.yml
    christmas.yml
    halloween.yml
    ...
```

Each file defines one hunt. The filename must match the hunt ID (e.g., `christmas.yml` for hunt ID `christmas`).

## Full Example

```yaml
id: christmas
displayName: "Christmas Hunt"
state: ACTIVE
priority: 1
icon: PLAYER_HEAD

behaviors:
  scheduled:
    start:
      date: "12/01/2026"
      time: "00:00"
    end:
      date: "12/31/2026"
      time: "23:59"

config:
  headClick:
    messages:
      - "&aYou found a Christmas head!"
      - "&7Progress: %progress% &e%current%&7/&e%max%"
    title:
      enabled: true
      firstLine: "&c&lChristmas Hunt"
      subTitle: "&aHead found!"
      fadeIn: 10
      stay: 40
      fadeOut: 10
    sound:
      found: block_note_block_bell
      alreadyOwn: block_note_block_didgeridoo
    firework:
      enabled: true
    commands:
      - "give %player% diamond"
    eject:
      enabled: false
      power: 1

  holograms:
    found:
      enabled: true
      lines:
        - "&a&lFound"
    notFound:
      enabled: true
      lines:
        - "&c&lNot found"

  hints:
    distance: 20
    frequency: 15

  spin:
    enabled: true
    speed: 20
    linked: true

  particles:
    found:
      enabled: false
      type: REDSTONE
      amount: 1
    notFound:
      enabled: true
      type: REDSTONE
      amount: 1

  tieredRewards:
    5:
      messages:
        - "%prefix% &aYou found &e5 &aChristmas heads!"
      commands:
        - "give %player% diamond 5"
    10:
      messages:
        - "%prefix% &6%player% &afound all &e10 &aChristmas heads!"
      commands:
        - "give %player% diamond 10"
      broadcast:
        - "%prefix% &6%player% &acompleted the Christmas Hunt!"
```

## Hunt Identity

| Field         | Description                                                      | Required |
| ------------- | ---------------------------------------------------------------- | -------- |
| `id`          | Unique identifier (lowercase, alphanumeric + hyphens)            | Yes      |
| `displayName` | Name shown to players in messages and GUIs                       | Yes      |
| `state`       | Hunt state: `ACTIVE`, `INACTIVE`, or `ARCHIVED`                  | Yes      |
| `priority`    | Integer priority for display conflicts (lower = higher priority) | Yes      |
| `icon`        | Material type for GUIs (default: `PLAYER_HEAD`)                  | No       |

## States

| State        | Description                                                                                |
| ------------ | ------------------------------------------------------------------------------------------ |
| **ACTIVE**   | Players can interact with the hunt's heads. Holograms, particles, and hints are displayed. |
| **INACTIVE** | Players cannot interact with heads. Display elements are suppressed.                       |
| **ARCHIVED** | Preserved but not active. Functionally similar to INACTIVE.                                |

Use `/hb hunt enable <name>` and `/hb hunt disable <name>` to change state at runtime.

## Behaviors

Behaviors control how players can interact with a hunt's heads. They are evaluated as a chain — if any behavior denies a click, the entire chain denies it.

### Free

No constraints. Players can click heads at any time. This is the default behavior.

```yaml
behaviors:
  free:
```

### Ordered

Players must find heads in a specific order. Configure the order via `/hb options order`.

```yaml
behaviors:
  ordered:
```

* Heads with `orderIndex <= 0` are always clickable
* Clicking a head while lower-order heads are unfound shows the `Messages.OrderClickError` message

### Scheduled

The scheduled behavior restricts when a hunt is active. It supports three modes: **range**, **slots**, and \*\*recurring \*\*.

#### Range mode

Active between specific start and end dates. This is the default mode and is backward compatible with existing configurations.

```yaml
behaviors:
  scheduled:
    mode: range          # optional, defaults to "range" if omitted
    start:
      date: "12/01/2026"
      time: "00:00"      # optional, defaults to 00:00
    end:
      date: "12/31/2026"
      time: "23:59"      # optional, defaults to 00:00
```

* **date**: required, format `MM/dd/yyyy`
* **time**: optional, format `HH:mm` — if omitted, defaults to `00:00`
* Both `start` and `end` are optional — omit one to leave that bound open

You can optionally add **time slots** to a range to restrict activity to specific hours on certain days:

```yaml
behaviors:
  scheduled:
    mode: range
    start:
      date: "03/01/2026"
    end:
      date: "03/31/2026"
    slots:
      - days: [ SATURDAY, SUNDAY ]
        from: "14:00"
        to: "18:00"
```

This means the hunt is only active on weekends between 2pm and 6pm during March 2026.

#### Slots mode

Active during recurring weekly time windows. No start/end date by default, but you can optionally bound it with `activeFrom` / `activeUntil`.

```yaml
behaviors:
  scheduled:
    mode: slots
    slots:
      - days: [ MONDAY, WEDNESDAY, FRIDAY ]
        from: "14:00"
        to: "18:00"
      - days: [ SATURDAY, SUNDAY ]
        from: "10:00"
        to: "20:00"
    activeFrom:
      date: "03/01/2026"    # optional
    activeUntil:
      date: "06/30/2026"    # optional
```

* **slots**: list of time windows with `days` (list of day names), `from` and `to` (format `HH:mm`)
* **activeFrom** / **activeUntil**: optional date bounds (format `MM/dd/yyyy`)

#### Recurring mode

The hunt automatically recurs on a yearly, monthly, or weekly cycle.

```yaml
behaviors:
  scheduled:
    mode: recurring
    every: year            # year, month, or week
    startRef: "12/01"      # MM/dd for year, day number for month, day name for week
    duration: "31d"        # supports d (days), w (weeks), h (hours)
```

**Examples:**

| Use case                   | `every` | `startRef` | `duration` |
| -------------------------- | ------- | ---------- | ---------- |
| Christmas event (Dec 1-31) | `year`  | `12/01`    | `31d`      |
| First 3 days of each month | `month` | `1`        | `3d`       |
| Every weekend (Sat-Sun)    | `week`  | `SATURDAY` | `2d`       |

Recurring mode also supports optional `slots` for further restricting activity hours within the active period:

```yaml
behaviors:
  scheduled:
    mode: recurring
    every: year
    startRef: "12/01"
    duration: "31d"
    slots:
      - days: [ SATURDAY, SUNDAY ]
        from: "14:00"
        to: "18:00"
```

{% hint style="info" %}
Duration can span across boundaries (e.g., a yearly recurrence starting December 15 with `30d` duration will extend into January).
{% endhint %}

### Timed

Players race against the clock. A pressure plate starts the timer.

```yaml
behaviors:
  timed:
    startPlate:
      world: default
      x: 100
      y: 64
      z: 200
    repeatable: true
```

* **startPlate**: location of the pressure plate that starts the timed run
* **repeatable**: if `true`, players can replay after completion (progress is reset)
* Players can leave a run with `/hb leave`

{% hint style="info" %}
Behaviors can be combined. For example, `scheduled` + `ordered` means the hunt is date-restricted and heads must be found in order.
{% endhint %}

## Per-Hunt Configuration

Each setting under `config:` overrides the global `config.yml` value for this hunt only. **Any field left out inherits from `config.yml` at runtime.** This means hunt files stay lightweight — only override what you need.

See [Head Click](/headblocks/headblocks3/configuration-config.yml/head-click.md), [Holograms](/headblocks/headblocks3/configuration-config.yml/holograms.md), [Effects](/headblocks/headblocks3/configuration-config.yml/effects.md), and [Rewards](/headblocks/headblocks3/configuration-config.yml/rewards.md) for the available options.

## Default Hunt

The `default` hunt is special:

* Created automatically on first start
* Cannot be deleted
* Newly placed heads go into `default` unless another hunt is selected
* When a hunt is deleted with `--keepHeads`, its heads and progress are reassigned to `default` (or to a specified `--fallback` hunt)
* When a hunt is deleted without `--keepHeads`, its heads are physically removed and player progress is reset

## Backward Compatibility

If only the `default` hunt exists, the plugin behaves identically to previous versions. All commands work as before. No configuration changes needed.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://aerwyn81.gitbook.io/headblocks/headblocks3/other-files/hunts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.