235 lines
8 KiB
Markdown
235 lines
8 KiB
Markdown
# 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
|