# Recipe: achievement planner

Browsable achievement catalog with per-character completion status, filters by category and point value, and a "what's left" view.

## What you get

- Views-friendly achievement and category entities.
- Per-character progress entities that can be filtered, grouped, counted.
- A category taxonomy tree you can expose as a facet.

## Minimum modules

```
wow
wow_realm
wow_playable_class
wow_playable_race
wow_playable_specialization
wow_power_type
wow_character
wow_achievement
```

### Optional enrichment

Add the collection modules whose achievements you want to surface (mounts for mount-collection achievements, pets for pet-battle achievements, etc.):

```
wow_mount
wow_pet
wow_title
wow_toy
wow_reputation
```

Each enables its own `CharacterDataProvider`, and the matching per-character rows start landing on the next character refresh.

## Setup

1. Install, configure, sync reference data (see [character tracking](character-tracking.md)).
2. Sync the achievement catalog:
   ```
   drush wow:sync-achi-categories --force
   drush wow:sync-achievements
   ```
3. Import the characters a player cares about:
   ```
   drush wow:character-lookup stormrage khadgar
   ```
4. The per-character progress data lands automatically on character sync.

## Building the planner UI

The suite provides the entities and relationships; you build the views.

### "All achievements by category" view

- Source: `wow_achievement` entities
- Exposed filter: `category` taxonomy reference
- Exposed sort: `points` descending, `display_order`
- Contextual filter (optional): pass a character ID → inner-join `wow_achievement_progress` on `achievement = this.id AND character = :cid`, expose `completed_timestamp` as a column.

### "Not yet completed" view

- Source: `wow_achievement`
- Relationship: `wow_achievement_progress` → filter `character = :cid AND completed_timestamp IS NULL`
- Sort: points descending (the "high-value unfinished" list)

### "Recent completions" block

- Source: `wow_achievement_progress`
- Filter: `character = :cid AND completed_timestamp IS NOT NULL`
- Sort: `completed_timestamp` descending
- Range: 10

## What's not provided

- No scoring heuristic (what's "easy" vs "hard"). The criteria structure is in `criteria_data`, ready for your own classifier.
- No soloable / group-required split. Not in the Blizzard data.
- No ETA estimates.

Add those as your own module that reads the data.

## Per-expansion filtering

Achievement categories form a tree — expansion-level categories have children. Build a facet that walks the `category` taxonomy's parent chain. A View with a taxonomy-reference filter configured for the `wow_char_achi_category` vocabulary works.
