# Shiny Hunter

A collection journal for tameable pets, for Hunters, inside World of Warcraft.

Track which pet **appearances** you have tamed, which you are missing, where
they come from and how to reach them — without alt-tabbing to a website.

> **Status: 0.19.0 — autonomous hunts with an original hunter-field UI.**
> The collection browser, stable reader, 3D models, sighting log and nameplate
> discovery labels are working over 17 verified appearances. Search and
> filters are implemented and awaiting in-game confirmation. See the
> [roadmap](ROADMAP.md).

## Why appearances and not NPCs

Several creatures can share the same look. You do not collect "NPC 32517", you
collect *a white spirit wolf* — which may be tameable from several NPCs in
several zones. Shiny Hunter is organised the way you actually think about
it:

```
FAMILY  ->  APPEARANCE  ->  CREATURE / SOURCE
```

The game has no concept of a pet appearance, so the addon defines its own and
maps it onto the display ids the client does expose. That decision is written
up in [docs/database-schema.md](docs/database-schema.md).

## Installation

1. Close World of Warcraft.
2. Copy the `ShinyHunter` folder into
   `World of Warcraft/_retail_/Interface/AddOns/`.
3. Start the game and make sure **Shiny Hunter** is enabled in the
   AddOns list on the character select screen.

Requires Retail, client 12.0.7 or later (TOC interface `120007`).

## Commands

| Command | Effect |
|---|---|
| `/shiny` | Open or close the main window |
| `/shiny help` | List the commands |
| `/shiny version` | Addon version and client build |
| `/shiny validate` | Check the database for errors and run the self-tests |
| `/shiny stable` | Report what the client tells us about your stable |
| `/shiny sightings` | List tameable beasts you met that are not in the database |
| `/shiny debug` | Toggle diagnostic output (off by default) |
| `/shiny debug dump` | Print the recent diagnostic lines, including start-up |
| `/shiny reset` | Erase stored data — asks for `/shiny reset confirm` first |

`/shinyhunter` works everywhere `/shiny` does.

## What works today

- Loads cleanly on 12.0.7 with no Lua errors
- Modular architecture with an explicit start-up sequence
- SavedVariables keyed by player GUID: collection per character, favourites and
  settings account-wide, with versioned forward migrations
- A validated database of families, appearances, creatures and locations, with
  indexes built at load and no query that scans
- An extensible requirement system, and coordinates stored the way the game's
  own APIs expect them
- `/shiny validate`: cross-record validation plus 26 self-tests
- A browser: virtualized list grouped by family with per-family counters, and a
  detail panel with traits, requirements, zones and coordinates
- Bestiary catalogue numbers and real creature portraits: collected looks
  appear in full colour, while missing ones remain desaturated
- The 604-name rare ledger counts a beast as recorded when captured or
  defeated, while preserving both outcomes separately in its dossier
- Instant search over pets, families, expansions, tags and locations, with
  filters for state, family, expansion and traits
- Favourite and collected marks that survive `/reload`
- A 3D model for every appearance, with drag to rotate and wheel to zoom
- Stable detection: pets you own are matched by display id and marked
  automatically, additively, without ever clearing a mark you made yourself
- English and Spanish, with English as the fallback for missing strings
- Movable main window that remembers its position and closes with ESC
- Debug channel that records start-up even while it is switched off

## What does not work yet

The complete appearance catalogue and automatic "pets in this zone" view are
still being filled. Active-hunt map areas already work; global collection pins
remain a later phase in the [roadmap](ROADMAP.md).

## What the collection covers

Shiny Hunter is growing toward a **complete catalogue of tameable hunter-pet
appearances**. The collectible is the visual appearance, not every NPC that
uses it: several wolves with the same model belong to one bestiary entry, while
a rare with a unique look remains its own entry.

The shipped database is still small. A 633-entry rare-tameable candidate index
now drives the verification queue, and the wider family taxonomy contains
5,542 NPC pages that must be deduplicated by appearance. How every shipped
value was verified, and
which sources turned out not to carry the data at all, is recorded in
[docs/data-sources.md](docs/data-sources.md).

## Native navigation

Press `Track beast` once and Shiny Hunter builds an automatic patrol
through every search zone for that appearance. It advances after arrival and
stops when the target is sighted. Shiny Hunter places a Blizzard user waypoint
and renders a final-approach beacon only when close. When the target
is on another map, a route card shows the next travel step supplied by WoW —
including portal, boat or map-transition descriptions when the client provides
them. Seeing a rare or exotic hunter beast produces a compact encounter card
with its portrait, localized name, family, sound and a secure target action.
The same alert covers a tracked creature without playing the sound twice.
Selecting the active coordinate again clears the patrol. The feature has no
addon dependency.

The detail view keeps raw coordinates folded away by default. Its field
instrument offers one `Track beast` action, a compact hunting-ground summary
and live route progress; exact points remain available on demand.

Opening the world map during an active hunt shows all verified spawn areas for
that appearance. Alternatives are magenta, the point currently followed is gold,
and every area can be selected directly from the map.

## Design boundaries

The addon informs; it does not play. It will show you where a pet is, what it
requires and whether you have it. It will never move your character, automate
combat or taming, or work around anything Blizzard restricts.

## Documentation

| Document | Contents |
|---|---|
| [docs/architecture.md](docs/architecture.md) | Modules, layers, event flow, start-up |
| [docs/database-schema.md](docs/database-schema.md) | Record contracts and saved variables |
| [docs/wow-api.md](docs/wow-api.md) | Every API used, how it was verified, and what is still unproven |
| [docs/data-sources.md](docs/data-sources.md) | Where every fact in the database came from, and what could not be verified |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Working rules for the project |
| [ROADMAP.md](ROADMAP.md) | Where this is going |
| [CHANGELOG.md](CHANGELOG.md) | What changed when |

## Licence and originality

Shiny Hunter is an original implementation. It contains no code from
Petopia or from any other addon, and it does not scrape or depend on any
external website at runtime.
