# World of Warcraft API

[![pipeline status](https://git.drupalcode.org/project/wow/badges/2.x/pipeline.svg)](https://git.drupalcode.org/project/wow/-/pipelines)
[![coverage report](https://git.drupalcode.org/project/wow/badges/2.x/coverage.svg)](https://git.drupalcode.org/project/wow/-/pipelines)

Bring World of Warcraft data into your Drupal site. Sync game data from the Blizzard API, let players log in with Battle.net, and build WoW-powered features with standard Drupal tools.

## Features

- **Battle.net login** — players authenticate with their existing Battle.net accounts.
- **Character profiles** — import by realm and name, with class, race, level, gear, avatar, and active title (prefix/suffix rendering via `display_string`). Shallow imports on first encounter with lazy full sync on page visit.
- **Guild profiles** — canonical guild pages with crest, roster, class distribution chart, and recent achievements sidebar. Auto-imported during character sync.
- **Achievement catalog** — thousands of achievements with categories, points, icons, and per-character and per-guild progress.
- **Collection tracking** — mounts, battle pets, toys, and titles tracked per character with dedicated browsing pages and summary cards on the character profile.
- **Reputation standings** — per-character faction reputation with tier and point values.
- **Equipment display** — character sheet layout with item quality colors and empty slot placeholders.
- **Reference data** — realms, classes, races, specializations, and power types kept up to date.
- **Admin dashboard** — at-a-glance sync status with one-click actions.
- **WoW class colors** — CSS utility classes for all 13 classes (text, background, and row hover variants).

Enable only what you need. Every submodule is optional.

### Character pages (`wow_character`)

Characters are the primary entity. The canonical page lives at `/wow/character/{region}/{realm}/{name}`.

- **Shallow imports** — roster-discovered characters are created as lightweight stubs (no extra API calls). The first page visit triggers a full sync with all CharacterDataProvider plugins.
- **Loading page** — shallow characters render a spinner with JS polling against a JSON status endpoint (`/wow/character/{region}/{realm}/{name}/status`). The page auto-refreshes when the sync completes.
- **Local-first gating** — `CharacterSync::lookup()` checks `last_fetched` against a 30-day TTL before calling the API. Shallow-to-full upgrades always fetch.
- **Refresh cooldown** — manual refresh is rate-limited per character (configurable via `wow_character.settings`). Admins (`administer wow` or site admin) bypass the cooldown.
- **Achievements tab** — full character achievements page powered by Views.
- **Collection pages** — mounts, pets, toys, and titles each have a dedicated page (Views + controller + local task). Summary cards on the character page link to their respective collection pages.
- **Canonical link** — `Character::toUrl()` is overridden to build clean `/wow/character/{region}/{realm}/{name}` URLs from entity fields.

### Guild pages (`wow_guild`)

Guilds have canonical pages at `/wow/guild/{region}/{realm_slug}/{name_slug}`.

- **Guild page** — displays the guild crest (emblem + border + colors), faction, achievement points, member count, and creation date. The roster is rendered via a Views block, with a class distribution bar chart and a recent achievements sidebar.
- **Roster sync** — the `RosterData` GuildDataProvider plugin fetches the guild roster and creates character entities at a configurable depth via `RosterMode`: Basic (stub from roster data, 0 API calls), Profile (shallow character import, 1 call each), or Full (complete import with all plugins).
- **Auto guild import** — the `GuildData` CharacterDataProvider plugin triggers `GuildSync::lookup()` during character sync, ensuring the guild entity exists. The lookup is local-first.
- **Guild achievements** — the `GuildAchievementData` GuildDataProvider plugin syncs guild achievement progress into `wow_achievement_progress` entities.
- **Custom rank names** — guild masters can edit rank display names (0-9) via the rank names form. Access is controlled by `GuildMasterAccessCheck`, which verifies the current user owns a rank 0 character in the guild.
- **Local tasks** — Guild and Achievements tabs on the guild page.
- **Search integration** — `GuildSearch` SearchableDataProvider makes guilds discoverable.
- **Connected realms** — the `guild_realm_slug` field on characters matches against the guild's actual realm, so characters on connected realms appear in the correct roster.

### Theming and infrastructure

- **WoW class colors** — `guild-page.css` ships CSS classes for all 13 WoW classes in three variants: `.wow-class-color--{slug}` (text), `.wow-class-bg--{slug}` (background), and `tr.wow-class--{slug}:hover` (row highlight). Used by roster tables and class distribution charts.
- **`wow_icon` field formatter** — `WoWIconFormatter` renders icon fields as `<img>` tags with configurable dimensions. Includes a config schema for Views and field display settings.
- **View render elements** — controllers use `#type => view` render elements instead of `views_embed_view()` for proper render caching and lazy building.

## Quick start

```
composer require drupal/wow
drush en wow wow_realm wow_playable_class -y
```

Then configure your Battle.net API credentials at **Administration > Configuration > Web services > World of Warcraft**.

## Requirements

- Drupal 11.3+
- A [Battle.net Developer](https://develop.battle.net/) account

## Documentation

Full documentation is available at [project.pages.drupalcode.org/wow](https://project.pages.drupalcode.org/wow/).

## Maintainers

- [hexblot](https://www.drupal.org/u/hexblot)
