aaron/darkwatch
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
darkwatch/docs/specs/2026-04-08-v2-item-database-derived-stats-design.md

8 KiB
Raw Blame History

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:

{ "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:

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

Gear: (no mechanical effects)

{}

Properties JSON examples

{ "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:

{
  "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