# Character Stats Window - Design Document

## Overview

Add a live character stats window to the Dereth Tracker map interface, styled as an Asheron's Call game UI replica. Accessible via a "Char" button on each player in the list, alongside the existing Chat, Stats, and Inventory buttons.

**Scope:** MosswartOverlord only (database, backend, frontend). The plugin implementation is a separate follow-up with a handoff spec.

---

## Architecture: Single Event + JSONB Table with Indexed Columns

One new `character_stats` event type from the plugin. Backend stores in a single `character_stats` table with key columns extracted for efficient SQL queries (level, XP, luminance) plus a `stats_data` JSONB column for the full payload. In-memory cache for live display, DB for persistence.

---

## Database Schema

New table `character_stats`:

```sql
CREATE TABLE character_stats (
    character_name   VARCHAR(255) NOT NULL,
    timestamp        TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
    level            INTEGER,
    total_xp         BIGINT,
    unassigned_xp    BIGINT,
    luminance_earned BIGINT,
    luminance_total  BIGINT,
    deaths           INTEGER,
    stats_data       JSONB NOT NULL,
    PRIMARY KEY (character_name)
);
```

Single row per character, upserted on each 10-minute update.

### JSONB `stats_data` Structure

```json
{
  "attributes": {
    "strength": {"base": 290, "creation": 100},
    "endurance": {"base": 200, "creation": 100},
    "coordination": {"base": 240, "creation": 100},
    "quickness": {"base": 220, "creation": 10},
    "focus": {"base": 250, "creation": 100},
    "self": {"base": 200, "creation": 100}
  },
  "vitals": {
    "health": {"base": 341},
    "stamina": {"base": 400},
    "mana": {"base": 300}
  },
  "skills": {
    "war_magic": {"base": 533, "training": "Specialized"},
    "melee_defense": {"base": 488, "training": "Specialized"},
    "life_magic": {"base": 440, "training": "Trained"},
    "arcane_lore": {"base": 10, "training": "Untrained"}
  },
  "allegiance": {
    "name": "Knights of Dereth",
    "monarch": {"name": "KingName", "race": 1, "rank": 0, "gender": 0},
    "patron": {"name": "PatronName", "race": 2, "rank": 5, "gender": 1},
    "rank": 10,
    "followers": 5
  },
  "race": "Aluvian",
  "gender": "Male",
  "birth": "2018-03-15 14:22:33",
  "current_title": 42,
  "skill_credits": 0
}
```

---

## Backend

### WebSocket Handler (`main.py`)

New `character_stats` event type in the `/ws/position` handler. Same pattern as vitals:

1. **Validate** with `CharacterStatsMessage` Pydantic model
2. **Cache** in `live_character_stats: Dict[str, dict]` for instant access
3. **Persist** to `character_stats` table via upsert (`INSERT ... ON CONFLICT (character_name) DO UPDATE`)
4. **Broadcast** to browser clients via `_broadcast_to_browser_clients()`

### Pydantic Model

```python
class CharacterStatsMessage(BaseModel):
    character_name: str
    timestamp: datetime
    level: Optional[int]
    total_xp: Optional[int]
    unassigned_xp: Optional[int]
    luminance_earned: Optional[int]
    luminance_total: Optional[int]
    deaths: Optional[int]
    race: Optional[str]
    gender: Optional[str]
    birth: Optional[str]
    current_title: Optional[int]
    skill_credits: Optional[int]
    attributes: Optional[dict]
    vitals: Optional[dict]
    skills: Optional[dict]
    allegiance: Optional[dict]
```

### HTTP Endpoint

```
GET /api/character-stats/{name}
```

Returns latest stats for a character. Checks in-memory cache first, falls back to DB. Used when a browser opens a character window after the initial broadcast.

### Test Endpoint (temporary, for development)

```
POST /api/character-stats/test
```

Accepts a mock `character_stats` payload, processes it through the same pipeline (cache + DB + broadcast). Allows full end-to-end testing without the plugin running.

---

## Frontend

### Character Button

New "Char" button in the player list, same pattern as Chat/Stats/Inventory:

```javascript
const charBtn = document.createElement('button');
charBtn.className = 'char-btn';
charBtn.textContent = 'Char';
// click -> showCharacterWindow(playerData.character_name)
```

### `showCharacterWindow(name)`

Uses existing `createWindow` helper. Window size: 450x650px (tall and narrow like the game panel).

**Data loading:**
1. On open, fetch `GET /api/character-stats/{name}`
2. Listen for `character_stats` WebSocket broadcasts to update live
3. Vitals bars update from existing `vitals` WebSocket messages (5-second stream)
4. If no data exists, show "Awaiting character data..." placeholder

### Window Layout

Stacked vertically, mimicking the AC character panel:

1. **Header** - Character name, level, race/gender, title. Gold text on dark background.

2. **Attributes panel** - 3x2 grid:
   ```
   Strength  290    Quickness    220
   Endurance 200    Focus        250
   Coordination 240 Self         200
   ```
   Base values shown, creation values in smaller text.

3. **Vitals bars** - Red (HP), yellow (Stamina), blue (Mana) bars with current/max numbers. Live-updating from existing vitals stream.

4. **Skills section** - Scrollable, grouped by training level:
   - **Specialized** (gold text)
   - **Trained** (white text)
   - **Untrained** (grey text)
   Each shows skill name + level.

5. **Allegiance section** - Monarch, patron, rank, followers count.

6. **Footer** - XP, unassigned XP, luminance, deaths, birth date.

---

## Styling: AC Game UI Replica

Color palette drawn from the Asheron's Call interface:

```css
--ac-bg: #1a1410;           /* Dark brown/black background */
--ac-panel: #2a2218;        /* Panel background */
--ac-border: #8b7355;       /* Gold/brown borders */
--ac-header: #d4a843;       /* Gold header text */
--ac-text: #c8b89a;         /* Parchment-colored body text */
--ac-text-dim: #7a6e5e;     /* Dimmed/secondary text */
--ac-specialized: #d4a843;  /* Gold for specialized skills */
--ac-trained: #c8b89a;      /* Light for trained */
--ac-untrained: #5a5248;    /* Grey for untrained */
```

Vitals bar colors:
- Health: `#8b1a1a` bg, `#cc3333` fill (red)
- Stamina: `#8b7a1a` bg, `#ccaa33` fill (yellow)
- Mana: `#1a3a8b` bg, `#3366cc` fill (blue)

Panel styling:
- Subtle inner border with gold/brown
- CSS gradient background to simulate parchment grain (no image files)
- Section dividers as thin gold lines
- Skill rows with subtle hover highlight
- Compact padding (information-dense like the game UI)

---

## Plugin Event Contract

The plugin will send a `character_stats` message via the existing WebSocket connection:

- **Frequency:** On login + every 10 minutes
- **Channel:** Existing `/ws/position` WebSocket

```json
{
  "type": "character_stats",
  "timestamp": "2026-02-26T12:34:56Z",
  "character_name": "Barris",
  "level": 275,
  "race": "Aluvian",
  "gender": "Male",
  "birth": "2018-03-15 14:22:33",
  "total_xp": 191226310247,
  "unassigned_xp": 0,
  "skill_credits": 0,
  "luminance_earned": 500000,
  "luminance_total": 1500000,
  "deaths": 3175,
  "current_title": 42,
  "attributes": {
    "strength": {"base": 290, "creation": 100},
    "endurance": {"base": 200, "creation": 100},
    "coordination": {"base": 240, "creation": 100},
    "quickness": {"base": 220, "creation": 10},
    "focus": {"base": 250, "creation": 100},
    "self": {"base": 200, "creation": 100}
  },
  "vitals": {
    "health": {"base": 341},
    "stamina": {"base": 400},
    "mana": {"base": 300}
  },
  "skills": {
    "war_magic": {"base": 533, "training": "Specialized"},
    "melee_defense": {"base": 488, "training": "Specialized"},
    "life_magic": {"base": 440, "training": "Trained"},
    "arcane_lore": {"base": 10, "training": "Untrained"}
  },
  "allegiance": {
    "name": "Knights of Dereth",
    "monarch": {"name": "KingName", "race": 1, "rank": 0, "gender": 0},
    "patron": {"name": "PatronName", "race": 2, "rank": 5, "gender": 1},
    "rank": 10,
    "followers": 5
  }
}
```

---

## Data Flow

```
Plugin (every 10 min + on login)
    │ character_stats JSON via /ws/position
    ▼
Backend handler
    │ Pydantic validation
    ├──▶ live_character_stats cache (in-memory)
    ├──▶ character_stats table (upsert)
    └──▶ _broadcast_to_browser_clients()
            │
            ▼
/ws/live → Browser
    │ message.type === 'character_stats'
    ▼
Character window updates live

Browser can also fetch on demand:
GET /api/character-stats/{name} → cache → DB fallback
```

Vitals (HP/Stam/Mana) update separately via existing 5-second vitals stream.

---

## Files Modified

| File | Changes |
|------|---------|
| `main.py` | New `character_stats` handler, Pydantic model, in-memory cache, HTTP endpoint, test endpoint |
| `db_async.py` | New `character_stats` table definition |
| `static/script.js` | New "Char" button, `showCharacterWindow()`, WebSocket listener for `character_stats` |
| `static/style.css` | AC-themed character window styles |

---

## What's NOT in Scope

- Plugin implementation (separate follow-up with handoff spec)
- Historical stat tracking over time (table supports it but no UI yet)
- Skill icons from the game (text-only for v1)
- Title name resolution (show title ID, not name)
- Vassal list display (just monarch/patron/rank/followers)