# V2: Item Database + Derived Stats — Design Spec

## Overview

Add a predefined item database from the Shadowdark core rules, auto-calculated derived stats (AC, attacks), manual override system, missing character fields, a multi-column detail layout, and gear slot visualization. Builds on the existing v1 app.

## 1. Predefined Item Database

### game_items table

| Column     | Type    | Notes                                        |
| ---------- | ------- | -------------------------------------------- |
| id         | INTEGER | Primary key, autoincrement                   |
| name       | TEXT    | Item name                                    |
| type       | TEXT    | weapon / armor / gear                        |
| slot_count | INTEGER | Gear slots used (0 for coins, backpack, etc) |
| effects    | TEXT    | JSON — mechanical effects (see below)        |
| properties | TEXT    | JSON — display metadata (tags, notes)        |

Seeded on first run from a static data file. Not editable by users — it's a reference list.

### Effects JSON examples

**Weapons:**

```json
{ "damage": "1d8", "melee": true, "stat": "STR" }
{ "damage": "1d4", "ranged": true, "stat": "DEX", "range": "near" }
{ "damage": "1d6", "melee": true, "stat": "STR", "finesse": true }
{ "damage": "1d10", "melee": true, "stat": "STR", "two_handed": true }
```

**Armor:**

```json
{ "ac_base": 11, "ac_dex": true }
{ "ac_base": 15, "ac_dex": false }
{ "ac_bonus": 2 }
```

**Gear:** (no mechanical effects)

```json
{}
```

### Properties JSON examples

```json
{ "tags": ["two-handed"], "note": "Disadvantage on stealth" }
{ "tags": ["finesse", "thrown"], "range": "close" }
```

### Seed Data (~35 items)

**Weapons (~15):**
Bastard sword, Club, Crossbow, Dagger, Greataxe, Greatsword, Javelin, Longbow, Longsword, Mace, Shortbow, Shortsword, Spear, Staff, Warhammer

**Armor (~5):**
Leather armor, Chainmail, Plate mail, Shield, Mithral chainmail

**Gear (~15):**
Arrows/bolts (20), Backpack, Caltrops, Climbing gear, Crowbar, Flask/bottle, Flint and steel, Grappling hook, Iron spikes (10), Lantern, Mirror, Oil flask, Rations, Rope (60ft), Thieves' tools, Torch

### UI for Adding Gear

When clicking "+ Add" in the gear section:

1. A searchable dropdown appears with all predefined items grouped by type (Weapons | Armor | Gear)
2. Selecting an item auto-fills name, type, slot_count, and properties/effects
3. A "Custom..." option at the bottom opens the existing manual form
4. For predefined items, user can still edit the name (e.g. "Longsword" → "Longsword +1") and adjust properties before confirming

## 2. Auto-Calculated Derived Stats

### AC Calculation

Priority chain:

1. **Unarmored:** 10 + DEX modifier
2. **Armor equipped:** armor's `ac_base` + DEX modifier (if `ac_dex: true`) or just `ac_base`
3. **Shield equipped:** adds `ac_bonus` on top of armor/unarmored
4. Only one armor item allowed — if a second armor is added, a confirmation dialog asks "Replace {current armor} with {new armor}?" Yes replaces (removes old from gear), No cancels

Calculated client-side from character stats + gear effects. Not stored in DB — derived on render.

### Attack Lines

Auto-generated for each weapon in the character's gear:

- **Melee weapons:** `LONGSWORD: +{STR mod + bonus}, {damage die}`
- **Ranged weapons:** `SHORTBOW: +{DEX mod + bonus}, {damage die}`
- **Finesse weapons:** use higher of STR/DEX modifier
- **Tags:** `(2H)` for two-handed, `(F)` for finesse
- Format matches paper sheet: `SHORTSWORD: +0, 1d6`

Talents with attack-related effects (like Backstab) appear as additional lines below weapon attacks, showing their description.

Calculated client-side. Not stored.

### Future Dice Rolling Accommodation

Each attack line reserves space on the right side for a roll button. Not implemented now — just layout space. The attacks section heading will also have room for a general "roll" area.

## 3. Override System

### character_overrides column

Add a `overrides` TEXT column (JSON) to the `characters` table. Default: `'{}'`.

Structure:

```json
{
  "ac": 18
}
```

When a field has an override:

- The override value is used instead of the auto-calculated value
- A small indicator icon appears next to the field
- Hovering/clicking the indicator shows the auto-calculated value
- Clicking "revert" removes the override and returns to auto-calculated

For v2, only AC is overridable. The system is extensible — more fields can be added later.

## 4. Missing Character Fields

### Schema additions to characters table

| Column         | Type    | Notes                        |
| -------------- | ------- | ---------------------------- |
| background     | TEXT    | Default ''                   |
| deity          | TEXT    | Default ''                   |
| languages      | TEXT    | Comma-separated, default ''  |
| gp             | INTEGER | Gold pieces, default 0       |
| sp             | INTEGER | Silver pieces, default 0     |
| cp             | INTEGER | Copper pieces, default 0     |
| gear_slots_max | INTEGER | Default 10                   |
| overrides      | TEXT    | JSON overrides, default '{}' |

### XP Threshold Display

Shadowdark XP thresholds: 10 XP per level (level 2 = 10, level 3 = 20, etc.). Derived from `level * 10`. Display as "XP: 6 / 10" on the card and detail view. Not a new DB field.

## 5. Multi-Column Detail Layout

Replace the current 700px single-column modal with a wider (max-width: 1100px) multi-column layout.

### Desktop (1100px+) — 3 columns

**Left column — Identity & Vitals:**

- Name, title
- Class, ancestry, level
- Background, deity
- Alignment
- HP bar with +/- (current / max)
- AC display (with override indicator)
- XP (current / threshold)

**Center column — Combat & Stats:**

- Ability scores (3x2 StatBlock grid)
- Attacks section (auto-generated weapon lines + relevant talents)
- (Future: dice roll area)

**Right column — Abilities & Notes:**

- Talents/Spells list
- Languages
- Notes textarea

**Full-width below columns:**

- Gear/Inventory section — table with slot count, type, currency row
- Gear slot counter: "Slots: 7 / 10"
- "+ Add Gear" with predefined item dropdown

### Tablet (768-1100px) — 2 columns

Left: identity + stats + attacks. Right: talents + notes. Gear full-width below.

### Mobile (<768px)

Single column, stacked vertically (similar to current).

### Still a Modal

Overlay modal, but wider. Click outside or X to close. All the same real-time sync behavior.

## 6. Gear Slot Visualization

### Slot Counter

- Header of gear section: "Slots: 7 / 10" with visual indicator
- Color coding: green (normal), yellow (8-9 of max), red (at or over max)
- `gear_slots_max` stored on character, default 10, editable in detail view

### Gear Table

Each gear row shows:

- Item name
- Type badge (weapon/armor/gear/spell)
- Slot count (or "—" for 0-slot items)
- Remove button

Currency displayed as a compact "GP / SP / CP" row with +/- or direct input, separate from gear slots.

## 7. Data Flow

- Predefined items are read-only reference data in `game_items` table
- When a predefined item is added to a character, a copy is made in `character_gear` with the item's data. The copy can be modified (renamed, bonus added, etc.) without affecting the reference.
- `game_item_id` nullable FK on `character_gear` tracks which predefined item it came from (if any). Custom items have null.
- AC and attacks are calculated client-side from character state (stats + gear + talents + overrides). They are not stored in the database.
- The server broadcasts gear/stat changes; other clients recalculate derived values locally.

## 8. Schema Changes Summary

**New table:** `game_items` (id, name, type, slot_count, effects, properties)

**Alter `characters`:** add columns — background, deity, languages, gp, sp, cp, gear_slots_max, overrides

**Alter `character_gear`:** add column — game_item_id (nullable INTEGER, FK to game_items)

## Out of Scope

- Dice rolling (layout accommodates it)
- Spell attacks / spell system
- Visual theme overhaul
- Authentication
- Drag-and-drop inventory management
- Item editing in the game_items reference table