For AI agents or engineers taking over this project. Last updated: 2026-05-21
Ribbitz is a D&D character operations system built from:
| Component | Purpose | Location |
|---|---|---|
| Source Content | Canonical Markdown character docs | Repo root (*.md) |
| Interactive UI | React/Vite dashboard for in-session use | ui/ |
| Live Sync Proxy | Express server that proxies Google Apps Script | ui/server/ |
| OBS Stat Output | PowerShell scripts generating .txt files for OBS overlays |
OBS Auto Sync/ |
| Sophie’s Dice Bridge | Sends Ribbitz skill rolls to Sophie’s Dice on Stealth | C:\Users\Drachen\Documents\SophiesDice\RibbitzBridge |
The system is designed for in-session use: quick stat checks, tracker toggles, consumable updates, inventory editing, and fast navigation to rules/details via internal hash links.
| File | Description |
|---|---|
README.md |
GitHub-facing index/navigation |
Basic Stats.md |
Core stats, ability scores, skills, DCs |
Actions.md |
Combat reference, weapon stats, damage formulas |
Inventory.md |
Item list |
Class Features.md |
Ranger/Druid class features, feats |
Racial Traits.md |
Grung racial traits |
Spells and Magic Abilities.md |
Full spell list, trackers |
Backstory.md |
Character backstory |
Misc.md |
Conditions, misc rules |
Images.md |
Image gallery |
| Path | Purpose |
|---|---|
ui/src/main.jsx |
React entry point with BrowserRouter |
ui/src/App.jsx |
Main dashboard: routes, trackers, combat kit, spell parsing |
ui/src/App.css |
Dashboard layout/styling |
ui/src/index.css |
Global styles |
ui/src/components/MarkdownPage.jsx |
Markdown renderer with anchor/scroll behavior |
ui/src/components/TrackerGroup.jsx |
Reusable tracker chip component |
ui/src/pages/InventoryPage.jsx |
Inventory CRUD UI |
ui/src/utils/slugifyHeading.js |
Slug utility for anchor links |
ui/public/content/*.md |
Content consumed by UI markdown routes |
ui/public/content-images/* |
Images for the UI image page |
ui/vite.config.js |
Vite config with /api proxy to port 5175 |
| Path | Purpose |
|---|---|
ui/server/server.js |
Express API proxy, snapshot logic, cron |
ui/server/.env |
Runtime config (NOT committed) |
ui/server/.env.example |
Template for .env |
ui/server/snapshot.json |
Offline fallback snapshot |
| Path | Purpose |
|---|---|
OBS Auto Sync/Engine/* |
PowerShell scripts for stat sync |
OBS Auto Sync/Stats/* |
Generated .txt files for OBS text sources |
OBS Auto Sync/Config/* |
Mapping/config JSON and CSV files |
| File | Platform | Notes |
|---|---|---|
Launch Ribbitz Program.bat |
Windows | Starts server + UI + OBS script |
launch.sh |
Linux/macOS | Starts server + UI (OBS script won't run) |
User opens UI in browser (127.0.0.1:5174)
→ UI calls /api/* routes
→ Vite proxy forwards /api/* to Express server (localhost:5175)
→ Express server calls Google Apps Script Web App
→ Data returns to UI
- If Apps Script read fails, server serves
snapshot.jsonwhen present. - UI indicates offline state and warns when changes won't sync.
- Inventory falls back to
ui/public/content/seed-inventory.csv.
| Operation | Endpoint | Notes |
|---|---|---|
| Read stats | GET /api/stats |
Returns parsed stat rows or snapshot |
| Write stat | POST /api/stats |
Single { key, value } or batch { updates: [...] } |
| Read inventory | GET /api/inventory |
Returns items array |
| Write inventory | POST /api/inventory |
{ items: [...] } |
| Health check | GET /api/health |
Returns { status: 'ok' } |
| Sophie roll list | GET /api/sophie/rolls |
Legacy/reference roll metadata; no hotkeys |
| Sophie roll trigger | POST /api/sophie/roll |
Legacy endpoint; dashboard UI does not call it |
As of 2026-06-13, the Ribbitz dashboard no longer shows Sophie Roll buttons and no longer stores Sophie hotkey fields in the server roll metadata. The hotkey workflow caused issues during live play, so future instances should not reintroduce dashboard roll buttons, Sophie hotkey fields, or automatic Sophie keypress behavior without an explicit user request.
The legacy server endpoints may remain for compatibility/reference while the UI is disconnected from them.
Important paths:
| Item | Path / Value |
|---|---|
| Stealth host | 10.0.0.42 |
| Bridge URL | http://10.0.0.42:5195 |
| Runtime env override | SOPHIES_DICE_BRIDGE_URL |
| Bridge folder | C:\Users\Drachen\Documents\SophiesDice\RibbitzBridge |
| Bridge script | ribbitz_sophie_bridge.py |
| Bridge scheduled task | Ribbitz Sophie Dice Bridge |
| Sophie’s Dice install | C:\Program Files (x86)\Steam\steamapps\common\Sophies Dice |
| Sophie Ribbitz rolls | C:\Users\Drachen\Documents\SophiesDice\CustomDice\Ribbitz |
| Sophie local handoff | C:\Users\Drachen\Documents\SophiesDice\HANDOFF.md |
| Sophie roll inventory | C:\Users\Drachen\Documents\SophiesDice\ROLL_INVENTORY.md |
| XML backup made before hotkey edits | C:\Users\Drachen\Documents\SophiesDice\Archive\RibbitzSkillHotkeyBackup-20260521-234157 |
| Hotkey repair backup | C:\Users\Drachen\Documents\SophiesDice\Archive\RibbitzHotkeyRepair-20260522-001740 |
Safe checks:
curl -fsS http://10.0.0.42:5195/health
docker exec diceknights-ribbitz wget -qO- http://127.0.0.1:5175/api/sophie/rolls- Node.js 18+
- npm
-
Clone the repo
git clone <repo-url> cd Ribbitz
-
Install dependencies
cd ui && npm install cd ../ui/server && npm install cd ../..
-
Configure environment
cp ui/server/.env.example ui/server/.env # Edit .env and set: # APPS_SCRIPT_WEBAPP_URL=<your deployed Google Apps Script Web App URL> # OFFLINE_SNAPSHOT_PATH=./snapshot.json # PORT=5175
-
Make launcher executable
chmod +x launch.sh
-
Start the application
./launch.sh
-
Verify
- UI: http://127.0.0.1:5174
- API Health: http://127.0.0.1:5175/api/health
The OBS Auto Sync/ tooling is Windows-only (PowerShell scripts). On Linux:
- The UI and API will work fine
- OBS overlays won't auto-update
- If you need OBS overlays on Linux, you'll need to reimplement the stat-watcher logic in Python or shell
| Route | Loads File | Notes |
|---|---|---|
/ |
Dashboard (App.jsx) | Main interactive dashboard |
/stats |
ui/public/content/Basic Stats.md |
Core stats page |
/actions |
ui/public/content/Actions.md |
Combat reference |
/inventory |
InventoryPage.jsx | Inventory UI (API-driven) |
/spells |
ui/public/content/Spells and Magic Abilities.md |
Spell list + trackers |
/features |
ui/public/content/Class Features.md |
Class features |
/racial-traits |
ui/public/content/Racial Traits.md |
Racial traits |
/backstory |
ui/public/content/Backstory.md |
Character backstory |
/misc |
ui/public/content/Misc.md |
Conditions, misc rules |
/images |
Built-in image gallery |
The UI reads/writes these keys from the Google Sheet. This is critical for debugging and integration.
| Key | Description |
|---|---|
hp-current |
Current HP |
hp-max |
Max HP (112) |
temp-hp |
Temporary HP (spore shield) |
ac |
Armor Class (19) |
initiative |
Initiative bonus (+5) |
speed |
Speed (25 ft) |
proficiency |
Proficiency bonus (+5) |
darkvision |
Darkvision range (90 ft) |
passive-perception |
Passive Perception (19) |
spell-dc |
Spell Save DC (17) |
spell-attack |
Spell Attack bonus (+9) |
size |
Size (Small) |
| Key | Score Key | Mod Key | Save Key |
|---|---|---|---|
| STR | str |
str-mod |
save-str |
| DEX | dex |
dex-mod |
save-dex |
| CON | con |
con-mod |
save-con |
Note: On Windows, the file
con.txtcannot be tracked by Git becauseCONis a reserved device name. The OBS stats file was renamed tocon-ability.txtas a workaround. | INT |int|int-mod|save-int| | WIS |wis|wis-mod|save-wis| | CHA |cha|cha-mod|save-cha|
| Key | Description |
|---|---|
skill-acrobatics |
Acrobatics |
skill-animal-handling |
Animal Handling |
skill-arcana |
Arcana |
skill-athletics |
Athletics |
skill-athletics-gloves |
Athletics (with Gloves of Swimming & Climbing) |
skill-deception |
Deception |
skill-history |
History |
skill-insight |
Insight |
skill-intimidation |
Intimidation |
skill-investigation |
Investigation |
skill-medicine |
Medicine |
skill-medicine-terrain |
Medicine (Preferred Terrain) |
skill-nature |
Nature |
skill-nature-terrain |
Nature (Preferred Terrain) |
skill-perception |
Perception |
skill-perception-terrain |
Perception (Preferred Terrain) |
skill-performance |
Performance |
skill-persuasion |
Persuasion |
skill-religion |
Religion |
skill-sleight |
Sleight of Hand |
skill-stealth |
Stealth |
skill-survival |
Survival |
skill-survival-terrain |
Survival (Preferred Terrain) |
| Key | Max |
|---|---|
slots-1st |
4 |
slots-2nd |
3 |
slots-3rd |
3 |
slots-4th |
3 |
slots-5th |
2 |
| Key | Max | Notes |
|---|---|---|
wild-shape |
2 | Druid Wild Shape uses |
active-camo |
5 | Grung Active Camouflage (PB) |
fungal-infestation |
4 | Circle of Spores (WIS mod) |
song-grung |
1 | Song of the Grung (1/day) |
fey-misty-step |
1 | Fey Touched Misty Step |
fey-hunters-mark |
1 | Fey Touched Hunter's Mark |
poison-weapon |
5 | Grung Poison Weapon (PB) |
tongue-grapple |
5 | Grung Tongue Grapple (PB) |
| Key | Description |
|---|---|
dart-sleep |
Sleep dart (1/day) |
dart-paralyze |
Paralyze dart (1/day) |
dart-purple |
Purple Grung dart (5/day) |
| Key | Description |
|---|---|
arrow-standard |
Standard arrows |
arrow-fire |
Fire arrows |
arrow-water |
Water arrows |
arrow-lava |
Lava arrows |
| Key | Description |
|---|---|
blowgun-hit |
Blowgun standard attack (+13) |
blowgun-hit-ss |
Blowgun Sharpshooter attack (+8) |
blowgun-dmg |
Blowgun standard damage (1d8) |
blowgun-dmg-ss |
Blowgun Sharpshooter damage (1d8+10) |
blowgun-elem-dmg |
Blowgun elemental damage (1d6) |
blowgun-gloom-dmg |
Blowgun Gloom Stalker damage (1d8) |
longbow-hit |
Longbow attack (+14) |
longbow-hit-ss |
Longbow Sharpshooter attack (+9) |
longbow-dmg |
Longbow standard damage (1d10+7) |
longbow-dmg-ss |
Longbow Sharpshooter damage (1d10+17) |
longbow-elem-dmg |
Longbow elemental damage (1d6) |
longbow-gloom-dmg |
Longbow Gloom Stalker damage (1d8) |
dagger-hit |
Dagger attack (+11) |
dagger-dmg |
Dagger damage (1d4+6) |
dagger-gloom-dmg |
Dagger Gloom damage (1d4+6+1d8) |
poison-dagger-hit |
Poison dagger attack (+10) |
poison-dagger-dmg |
Poison dagger damage (1d4+5) |
| Key | Value |
|---|---|
poison-skin-dc |
17 (12 + PB) |
poison-weapon-dc |
17 (9 + PB + CON) |
song-grung-dc |
17 (uses Spell Save DC) |
| Key | Description |
|---|---|
symbiotic-active |
Is Symbiotic Entity active? |
symbiotic-temp-hp |
Symbiotic temp HP (40) |
halo-damage |
Halo of Spores damage (1d8) |
halo-damage-symbiotic |
Halo damage while Symbiotic (2d8) |
spreading-spores |
Spreading Spores uses Halo damage in a 10-foot cube while Symbiotic Entity is active |
The UI persists certain state locally (not synced to sheet):
| Key | Type | Description |
|---|---|---|
ribbitz.deathSaves |
JSON array[6] | Death saves (3 success, 3 failure) |
ribbitz.exhaustionLevel |
number | Exhaustion level (0-6) |
ribbitz.conditions |
JSON object | Active conditions (slug → bool) |
ribbitz.drugsHerbs |
JSON object | Active drug/herb toggles (slug → bool) |
This is the live character state as of the last session:
| Stat | Value |
|---|---|
| Name | Ribbitz |
| Race | Grung (Homebrew v4) |
| Class | Ranger 6 / Druid 10 (Level 16) |
| Background | Vanguard of the Great Golden Risabere |
| Alignment | Neutral Good |
| Age | 3.5 years |
| Size | Small (4' 0", 55 lbs) |
| HP Max | 112 |
| AC | 19 |
| Initiative | +5 (+8 with Dread Ambusher) |
| Speed | 25 ft (hop/climb/swim) |
| Darkvision | 90 ft |
| Proficiency Bonus | +5 |
| Ability | Score | Modifier |
|---|---|---|
| STR | 14 | +2 |
| DEX | 20 | +5 |
| CON | 16 | +3 |
| INT | 9 | -1 |
| WIS | 18 | +4 |
| CHA | 8 | -1 |
- DEX (+10)
- WIS (+9)
Acrobatics, Arcana, Medicine, Nature, Perception, Stealth, Survival
The backend expects a Google Apps Script Web App that exposes:
Returns { rows: [{ A: label, B: value, C: type, D: key, E: outputFile }, ...] }
Returns inventory rows: { rows: [{ A: name, B: quantity, C: category, D: weight, E: notes, F: imageUrl }, ...] }
Body: { key, value, label, type, outputFile, extra } or array of updates.
Body: { key, value, label, type, weight, outputFile, extra } for inventory items.
- Use launch script (
launch.shon Linux,.baton Windows) — don't manually start servers - UI runs on port 5174, API on 5175 — the proxy in
vite.config.jsforwards/apito 5175 - Don't break slug behavior —
MarkdownPage.jsxrelies on stable anchor IDs - snapshot.json is runtime — don't commit changes to it
- Content in
ui/public/content/must match route expectations
Create ui/server/.env:
APPS_SCRIPT_WEBAPP_URL=https://script.google.com/.../exec
OFFLINE_SNAPSHOT_PATH=./snapshot.json
PORT=5175There is a completely separate tool called "Sophie's Dice" that lives in:
C:\Users\Drachen\Documents\SophiesDice\
It is a Windows desktop dice-rolling app with custom dice for Ribbitz. The web app still uses Google Sheets for character state, but the Skills card can now trigger Sophie’s Dice rolls through the Stealth bridge. If working on this integration, read C:\Users\Drachen\Documents\SophiesDice\HANDOFF.md and C:\Users\Drachen\Documents\SophiesDice\ROLL_INVENTORY.md.
- UI won't load: Check
npm installran in bothui/andui/server/ - Stats not loading: Check
.envhas validAPPS_SCRIPT_WEBAPP_URL - API errors: Check port 5175 is running, try
http://127.0.0.1:5175/api/health - Hash links broken: Check
slugifyHeading.jshasn't changed
When making changes, prioritize committing:
ui/src/**— UI logicui/server/server.js— Backend behaviorui/public/content/**— Markdown contentlaunch.sh— Linux launcherHANDOFF.md,README.md— Documentation
Avoid committing:
ui/server/snapshot.json— Runtime dataui/server/.env— SecretsOBS Auto Sync/Stats/*.txt— Generated OBS files
# Start (Linux)
./launch.sh
# Start (Windows
.\Launch Ribbitz Program.bat
# URLs
UI: http://127.0.0.1:5174
API: http://127.0.0.1:5175
Health: http://127.0.0.1:5175/api/health
# OBS on Linux?
NOT SUPPORTED - PowerShell only