# Configuration

# Tracking System

The tracking system is the shared backbone that feeds player activity data into both quest objectives and achievement triggers. It runs through a central `TrackingService` in the Core mod, which dispatches events to all registered listeners (Quest mod, Achievement mod, and any future modules).

## Architecture

```
ECS Systems (Block Break, Kill, Damage, ...)
    |
    v
TrackingService  (Core mod, central dispatcher)
    |
    +---> QuestTrackingListener    (Quest mod)
    +---> AchievementTrackingListener (Achievement mod)
    +---> Season Pass listener     (Season Pass mod)
```

All tracking events flow through the `TrackingService`. This ensures that a single block break or kill is counted for quests, achievements and season challenges without duplication.

## Tracked Event Types

| Event | Trigger Type | Description |
|-------|-------------|-------------|
| Block broken (mined) | `blocks_mined` | Stone, ores, and hard blocks |
| Block broken (chopped) | `blocks_chopped` | Wood and tree blocks |
| Block broken (dug) | `blocks_dug` | Dirt, sand, gravel, and soft blocks |
| Block placed | `blocks_placed` | Any block placed by a player |
| Block harvested | `blocks_harvested` | Plants picked with the interact key (F) |
| Flower picked | `flowers_picked` | Flower blocks specifically (subset of harvest) |
| Mob killed | `kills` | Any mob or entity killed |
| Player killed | `player_kills` | PvP kills |
| Damage dealt | `damage_dealt` | Damage done to mobs or players |
| Damage taken | `damage_taken` | Damage received from any source |
| Distance traveled | `distance_walked` | Horizontal movement in blocks, measured for every online player |
| Playtime | `playtime_minutes` | Minutes spent online |
| Zone discovered | `zones_discovered` | New map zones entered |
| Item crafted | `items_crafted` | Items crafted at a workbench |
| Item collected | `items_collected` | Items picked up or received |
| Chat messages | `chat_messages` | Messages sent in chat |
| Equipment | `full_armor_set`, `equip_item` | Armor sets and specific items equipped |

## Block Category Mapping

When a block is broken, the system categorizes it based on the block's group property. This determines which trigger type is fired.

### Chopped (Wood)

Blocks in the `Wood` group are counted as chopped. This includes all tree trunks and wooden logs.

### Dug (Soft Blocks)

Blocks in these groups are counted as dug:

| Group |
|-------|
| `Dirt` |
| `Sand` |
| `Gravel` |
| `Mud` |
| `Soil` |
| `Snow` |
| `Grass` |
| `Moss` |
| `Cover` |

### Mined (Hard Blocks)

Blocks in the `Stone` group or any group starting with `Ore` are counted as mined. Unknown solid blocks also fall into this category.

### Excluded

The following groups are **not** tracked for break events:

| Group | Reason |
|-------|--------|
| `Plant` | Tracked separately via harvest |
| `Leaves` | Tracked separately via harvest |
| `Fluid_Water` | Not player-breakable |
| `Lava` | Not player-breakable |
| `Props` | Decorative objects |
| `Air` | Not a real block |

:::tip
You can target specific blocks in quest objectives and achievement triggers by using the exact block ID (e.g. `Ore_Gold`) or by using the `group:` prefix (e.g. `group:Wood` to match all wood types).
:::

## Anti-Exploit: PlacedBlockTracker

The system includes built-in exploit prevention. When a player places a block and then breaks it, the break does **not** count toward quest or achievement progress.

| Setting | Default | Description |
|---------|---------|-------------|
| Enabled | `true` | Whether placed-block tracking is active. |
| Expiry | `30 minutes` | How long a placed block is remembered. After this time, breaking it counts normally. |

This prevents players from repeatedly placing and breaking blocks to farm progress. The tracker is shared between the Quest and Achievement mods.

:::info
The expiry timer means that blocks placed more than 30 minutes ago are treated as natural blocks again. This allows legitimate rebuilding to count after a reasonable delay.
:::

## Combat Tracking

### Kills

Kill events include the victim type, which can be used for targeted triggers:

- `any_mob` -- matches any non-player kill
- `any_player` -- matches any PvP kill
- Specific mob type (e.g. `Spider`, `Snake_*`) -- matches that mob type

### Damage

Damage events track both dealt and received damage:

- `damage_dealt` with target `any`, `any_mob`, `any_player`, or a specific mob type
- `damage_taken` with cause `fall`, `attack`, `fire`, or `any`

## Exploration Tracking

Zone discovery comes from two sources:

1. **First discovery (Core)** -- When the game reports that a player discovered a zone for the first time, Core dispatches a zone event. This also counts when the on-screen zone title is hidden.
2. **Zone polling (Quests mod)** -- Every 2 seconds the Quests mod checks each player's current zone and reports zone changes, so quests accepted after a first visit can still progress on a later visit. Entering an instance world (e.g. a dungeon) is reported with the zone name taken from the world name.

When both sources report the same zone for the same player within a few seconds, it is passed on only once. Each listener keeps its own per-player record (Achievements count each zone once, Season Pass awards zone XP once per zone, quests count unique zones per objective).

:::note
Distance and zone tracking were repaired in Core 2.7.4: before, distance was only measured for one player per group, and first-time zone discoveries did not reach Achievements and the Season Pass.
:::

## Playtime and Social Tracking

| Tracker | How It Works |
|---------|-------------|
| Playtime | Session start time is recorded on connect. Minutes are calculated on disconnect and saved. Hourly checkpoints prevent data loss on crashes. |
| Chat messages | Each chat message increments the counter. Total count is used for achievement triggers. |

## Using Triggers in Achievements and Quests

Both achievements and quest objectives reference the same trigger types. Achievement triggers use `count` while quest objectives use `amount`:

```json title="Achievement trigger"
{ "type": "blocks_mined", "target": "any", "count": 1000 }
{ "type": "kills", "target": "Spider", "count": 50 }
{ "type": "distance_walked", "target": "any", "count": 5000 }
{ "type": "flowers_picked", "target": "any", "count": 25 }
```

```json title="Quest objective"
{ "type": "blocks_mined", "target": "Ore_Gold", "amount": 10 }
{ "type": "blocks_chopped", "target": "group:Wood", "amount": 50 }
{ "type": "kills", "target": "Bear_Grizzly", "amount": 3 }
{ "type": "items_crafted", "target": "Weapon_Sword_Iron", "amount": 1 }
```

:::info
The `group:` prefix in quest objectives allows matching all blocks in a group. For example, `group:Wood` matches `Wood_Oak_Log`, `Wood_Birch_Log`, and every other wood type.
:::