Shadowdark Character Sheet Manager — Design Spec
Overview
A web app for managing Shadowdark RPG character sheets in real-time. Players in a campaign can view and edit characters simultaneously, with changes syncing live across all connected clients. Hosted locally and exposed via ngrok for group access.
Tech Stack
- Frontend: React + Vite (TypeScript)
- Backend: Node.js + Express + Socket.IO
- Database: SQLite (single file, zero config)
- Project location:
/Users/aaron.wood/workspace/shadowdark/
- Structure:
client/ and server/ directories
Data Model
campaigns
| Column |
Type |
Notes |
| id |
INTEGER |
Primary key, autoincrement |
| name |
TEXT |
Campaign name |
| created_by |
TEXT |
For future auth |
| created_at |
TEXT |
ISO timestamp |
characters
| Column |
Type |
Notes |
| id |
INTEGER |
Primary key, autoincrement |
| campaign_id |
INTEGER |
FK to campaigns |
| created_by |
TEXT |
For future auth |
| name |
TEXT |
Character name |
| class |
TEXT |
Fighter / Priest / Thief / Wizard |
| ancestry |
TEXT |
Human / Elf / Dwarf / Halfling / Goblin / Half-Orc |
| level |
INTEGER |
Default 1 |
| xp |
INTEGER |
Default 0 |
| hp_current |
INTEGER |
|
| hp_max |
INTEGER |
|
| ac |
INTEGER |
|
| alignment |
TEXT |
Lawful / Neutral / Chaotic |
| title |
TEXT |
Optional, e.g. "the Brave" |
| notes |
TEXT |
Freeform notes |
character_stats
| Column |
Type |
Notes |
| character_id |
INTEGER |
FK to characters |
| stat_name |
TEXT |
STR / DEX / CON / INT / WIS / CHA |
| value |
INTEGER |
Raw score (3-18 typically) |
One row per stat per character. Ability modifiers are derived, not stored:
| Score |
Modifier |
| 1-3 |
-4 |
| 4-5 |
-3 |
| 6-7 |
-2 |
| 8-9 |
-1 |
| 10-11 |
+0 |
| 12-13 |
+1 |
| 14-15 |
+2 |
| 16-17 |
+3 |
| 18 |
+4 |
character_gear
| Column |
Type |
Notes |
| id |
INTEGER |
Primary key, autoincrement |
| character_id |
INTEGER |
FK to characters |
| name |
TEXT |
Item name |
| type |
TEXT |
weapon / armor / gear / spell |
| slot_count |
INTEGER |
Gear slots used (Shadowdark inventory system) |
| properties |
TEXT |
JSON — e.g. {"damage":"1d6","melee":true,"bonus":1} |
Spells are stored as gear entries with type: "spell" and a tier property in the JSON.
character_talents
| Column |
Type |
Notes |
| id |
INTEGER |
Primary key, autoincrement |
| character_id |
INTEGER |
FK to characters |
| name |
TEXT |
Talent name |
| description |
TEXT |
Flavor/rules text |
| effect |
TEXT |
JSON — mechanical bonuses for dice roller |
UI Layout
Campaign List (home page)
- Grid/list of existing campaigns
- "+ New Campaign" button
- Click a campaign to enter it
Campaign View (main screen)
- Campaign name header
- Responsive character card grid:
- Desktop: 4 cards across
- Tablet: 2 cards across
- Mobile: 1 card, stacked
- Cards flow naturally — 6 characters = 4 + 2 rows on desktop, just scroll
- "+ Add Character" button
- Future: dice log panel (right side on desktop, bottom drawer on mobile)
Character Card (in the grid)
- Name, class, ancestry, level header
- HP bar with +/- buttons (current / max)
- AC display
- Six stats in compact 3x2 layout: score, modifier, +/- buttons
- Gear summary (slots used / total)
- Click to expand into full detail view
Character Detail (expanded / modal)
- Full stat editing with +/- buttons
- Gear/inventory management: add/remove items with type and properties
- Talents list: add/remove with name, description, effect
- Spell list (for Priests/Wizards — gear items with type "spell")
- Notes freeform text field
- Future: dice roll buttons next to weapons/spells
Real-time Sync
- Client joins a Socket.IO room per campaign (room ID = campaign ID)
- Mutation flow: client -> server API -> save to SQLite -> broadcast to room
- Other clients receive update and patch local state (no full reload)
- Optimistic UI: editing client updates immediately, server confirms
- On reconnect, client fetches latest full state from server
Auth (v1: none, future-ready)
- v1 is open free-for-all: anyone with the link can create/edit anything
created_by fields exist in the schema for future use- Migration path to light auth (name/pin per character) or GM controls requires adding middleware, not restructuring
Future: Dice Rolling (not in v1)
Design accommodations for future dice rolling:
- Shared dice log panel — layout reserves space for it
- Inline roll buttons — next to weapons/spells and stats
- Server-side rolls — server calculates d20 + ability modifier + gear/talent bonuses, broadcasts result
- Log entries — show who rolled, what for, full breakdown (e.g. "Kira attacks with Longsword +1: d20(14) + STR(+2) + weapon(+1) = 17"), and timestamp
- Data model supports it —
character_gear.properties and character_talents.effect JSON fields carry the mechanical data the roller needs
Deployment
- Run
server/ on localhost with a configured port
client/ built and served by Express (or Vite dev server during development)- Expose via ngrok for friends to access
- SQLite file lives in
server/data/shadowdark.db
Out of Scope for v1
- Authentication / permissions
- Dice rolling
- Character import/export
- Multiple themes / dark mode
- Mobile native app
