diff --git a/README.md b/README.md index 034d002..5b5b771 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,11 @@ > Turn household chores into a pixel art RPG adventure for the whole family. -Each family member gets a hero and a daily monster to fight. Complete chores to deal damage — defeat the monster before midnight to earn gold, or it strikes back. Spend gold on rewards you've agreed on as a family. +Each family member gets a hero and a daily monster to fight. Complete chores to deal damage - defeat the monster before midnight to earn gold, or it strikes back. Spend gold on rewards you've agreed on as a family. Built to run on a kitchen tablet, locked to a browser, always-on. -![Questboard main screen](screenshot.png) +![Questboard main screen](screenshots_combined.png) [![Release](https://img.shields.io/github/v/release/thillygooth/questboard)](https://github.com/thillygooth/questboard/releases) [![License](https://img.shields.io/github/license/thillygooth/questboard)](LICENSE) @@ -16,14 +16,14 @@ Built to run on a kitchen tablet, locked to a browser, always-on. ## What it looks like -The interface runs fullscreen in the browser. Each player gets a card with their hero, live HP bar, and current monster. Completing chores hits the monster — chain them fast for combo damage, score a crit, or find loot drops. +The interface runs fullscreen in the browser. Each player gets a card with their hero, live HP bar, and current monster. Completing chores hits the monster - chain them fast for combo damage, score a crit, or find loot drops. -**Player card** — hero class, gold, XP bar, crit %, streak -**Monster section** — animated pixel art enemy, segmented HP bar, kill = gold reward -**Chore grid** — daily / weekly / monthly quests shown with damage values -**Dungeon map** — per-player fog-of-war grid; chores earn moves, rooms hide gold, traps, and mini-bosses -**Reward shop** — spend gold on family rewards you configure in setup -**History** — full log of kills, loot drops, rewards redeemed, badges earned +**Player card** - hero class, gold, XP bar, crit %, streak +**Monster section** - animated pixel art enemy, segmented HP bar, kill = gold reward +**Chore grid** - daily / weekly / monthly quests shown with damage values +**Dungeon map** - per-player fog-of-war grid; chores earn moves, rooms hide gold, traps, and mini-bosses +**Reward shop** - spend gold on family rewards you configure in setup +**History** - full log of kills, loot drops, rewards redeemed, badges earned --- @@ -41,21 +41,43 @@ The interface runs fullscreen in the browser. Each player gets a card with their | 🛡 Shield Aura | Active power-up blocks the midnight gold penalty | | 🏅 Badges & titles | Unlock achievements and choose your hero title | | ⭐ Prestige | Reset XP at level 10 for a permanent gold % bonus | -| 🗺 Dungeon map | Explore a per-player fog-of-war dungeon — chores = moves | +| 🗺 Dungeon map | Explore a per-player fog-of-war dungeon - chores = moves | | 🏆 Weekly leaderboard | See who earned the most gold this week | | ⚡ Auto-resets | Daily/weekly/monthly chores reset at exactly the right time | | 🌙 Overnight penalty | Fail to kill your monster and lose gold at midnight | | 👥 Up to 6 players | Each with their own hero, monster, gold, XP, and dungeon | | 👤 Solo chores | Personal tasks (brushing teeth, homework) tracked per player | -| 📱 Kids & adults modes | Separate difficulty scaling — kids get easier monsters | +| 📱 Kids & adults modes | Separate difficulty scaling - kids get easier monsters | | 🎮 CRT overlay | Optional scanline filter for maximum retro vibes | | 🔍 UI Scale | Mini / Heroic / Epic zoom modes for any screen size | +📖 **[Full game guide →](questboard/DOCS.md)** - hero classes, dungeon mechanics, combat details, badges, power-ups, and more. + +--- + +## Quick Reference + +### Hero Classes + +Classes are cosmetic - they change your hero's sprite but don't affect stats. Available: Warrior, Mage, Witch, Rogue, Paladin, Ranger, Frost Knight. + +### Midnight Monster Penalty + +If you don't defeat your daily monster before midnight, it **attacks** - you lose gold equal to its attack power. Tougher monsters hit harder. Shield Aura power-up blocks the penalty. + +### Dungeon + +A per-player fog-of-war dungeon you explore by earning moves from chores. Use the on-screen d-pad to navigate. Find gold, treasure chests, keys, and fight dungeon monsters - but watch out for traps. Deeper floors have better rewards. + +### Reset Week + +Manual full reset: clears all gold, chore progress, streaks, and power-ups for every player. History, XP, levels, and badges are kept. Triggers immediately (not aligned to a specific day). + --- ## Install on Home Assistant -**Step 1 — Run the container** +**Step 1 - Run the container** In the HA Terminal add-on: @@ -66,7 +88,7 @@ docker run -d --restart unless-stopped -p 8099:8099 \ ghcr.io/thillygooth/questboard:latest ``` -**Step 2 — Add to the HA sidebar** +**Step 2 - Add to the HA sidebar** In `configuration.yaml` (use the File Editor add-on): @@ -102,7 +124,7 @@ Open `http://localhost:8099`. ## Running on a Separate Host -Questboard is a standalone web app — no connection to Home Assistant required. Run it on any machine on your network. +Questboard is a standalone web app - no connection to Home Assistant required. Run it on any machine on your network. ```yaml panel_iframe: @@ -123,11 +145,11 @@ A setup wizard runs the first time you open the app: 1. Set the number of players (1–6) 2. For each player: name, difficulty (kids / adults), avatar class -3. Choose which chores to track — toggle on/off, set solo vs. shared, adjust values -4. Configure the reward shop — enable/disable rewards, set custom costs +3. Choose which chores to track - toggle on/off, set solo vs. shared, adjust values +4. Configure the reward shop - enable/disable rewards, set custom costs 5. Configure power-ups and display options (CRT overlay, UI scale) -After launch, tap **Settings** for a tabbed editor: Party, Quests, Rewards, Power-Ups, and Display — no need to re-run the wizard. +After launch, tap **Settings** for a tabbed editor: Party, Quests, Rewards, Power-Ups, and Display - no need to re-run the wizard. --- @@ -148,7 +170,7 @@ The dev server proxies `/api/*` to the backend automatically. ## License -[CC BY-NC 4.0](LICENSE) — free to share and adapt for non-commercial purposes with attribution. Commercial use is prohibited. +[CC BY-NC 4.0](LICENSE) - free to share and adapt for non-commercial purposes with attribution. Commercial use is prohibited. Sprite assets from [OpenGameArt.org](https://opengameart.org) under CC-BY / CC0 licenses. Font: [Pixelated Elegance](https://www.fontspace.com/pixelated-elegance-font-f126145) by GGBotNet (CC0). @@ -156,4 +178,4 @@ Sprite assets from [OpenGameArt.org](https://opengameart.org) under CC-BY / CC0 ## Credits -Overkill system, power-ups, solo chore mode, tabbed settings, new hero classes, and gold economy rebalancing contributed by **[TreasuryMatt](https://github.com/TreasuryMatt)** — thanks for the excellent fork! +Overkill system, power-ups, solo chore mode, tabbed settings, new hero classes, and gold economy rebalancing contributed by **[TreasuryMatt](https://github.com/TreasuryMatt)** - thanks for the excellent fork! diff --git a/frontend/src/App.jsx b/frontend/src/App.jsx index 230093f..869daf1 100644 --- a/frontend/src/App.jsx +++ b/frontend/src/App.jsx @@ -206,7 +206,7 @@ export default function App() { const base = ALL_CHORES .filter(c => enabled.has(c.id)) .map(c => overrides[c.id] ? { ...c, ...overrides[c.id] } : c); - return [...base, ...(config.customChores ?? [])]; + return [...base, ...(config.customChores ?? []).map(c => overrides[c.id] ? { ...c, ...overrides[c.id] } : c)]; }, [config]); const bonusChoreId = useMemo(() => { diff --git a/frontend/src/components/HistoryTab.jsx b/frontend/src/components/HistoryTab.jsx index 9012c24..f2f7754 100644 --- a/frontend/src/components/HistoryTab.jsx +++ b/frontend/src/components/HistoryTab.jsx @@ -23,6 +23,8 @@ const TYPE_TILE = { gold: 55, penalty: 123, reward: 41, + badge: 29, + loot: 72, }; export default function HistoryTab({ history, players, weeklyGold = {} }) { @@ -60,8 +62,14 @@ export default function HistoryTab({ history, players, weeklyGold = {} }) {
{hist.map((h, i) => { const tile = TYPE_TILE[h.type] ?? 118; - const action = h.type === 'chore' ? 'completed' : h.type === 'penalty' ? 'attacked by' : 'slew'; - const pts = h.type === 'chore' ? `(+${h.pts} dmg${h.crit ? ' CRIT' : ''})` : h.type === 'penalty' ? `(-${h.pts} gold)` : `(+${h.pts} gold${h.lucky ? ' LUCKY' : ''})`; + let action, pts; + switch (h.type) { + case 'chore': action = 'completed'; pts = `(+${h.pts} dmg${h.crit ? ' CRIT' : ''})`; break; + case 'penalty': action = 'attacked by'; pts = `(-${h.pts} gold)`; break; + case 'badge': action = 'earned'; pts = h.icon || '🏅'; break; + case 'loot': action = 'found'; pts = h.pts ? `(+${h.pts} gold)` : (h.xp ? `(+${h.xp} XP)` : ''); break; + default: action = 'slew'; pts = h.pts != null ? `(+${h.pts} gold${h.lucky ? ' LUCKY' : ''})` : ''; break; + } return (
diff --git a/frontend/src/components/SetupWizard.jsx b/frontend/src/components/SetupWizard.jsx index 29843a6..c34e083 100644 --- a/frontend/src/components/SetupWizard.jsx +++ b/frontend/src/components/SetupWizard.jsx @@ -303,7 +303,7 @@ function CustomForm({ form, setForm, onSubmit, onCancel, extraFields }) { // ── Shared: chore list (wizard step + Quests tab) ───────────────────────────── function ChoreSection({ players, enabledChores, onToggle, choreOverrides, onOverride, customChores, onAddCustom, onRemoveCustom }) { const [addingCustom, setAddingCustom] = useState(false); - const [form, setForm] = useState({ name: '', icon: '⭐', pts: 2, who: 'all', freq: 'daily' }); + const [form, setForm] = useState({ name: '', icon: '⭐', pts: 2, who: 'all', freq: 'daily', mode: 'party' }); const modes = new Set(players.map(p => p.mode)); const daily = ALL_CHORES.filter(c => c.freq === 'daily'); @@ -317,7 +317,7 @@ function ChoreSection({ players, enabledChores, onToggle, choreOverrides, onOver function submitCustom() { if (!form.name.trim()) return; onAddCustom({ ...form, id: `custom_${Date.now()}`, name: form.name.trim() }); - setForm({ name: '', icon: '⭐', pts: 2, who: 'all', freq: 'daily' }); + setForm({ name: '', icon: '⭐', pts: 2, who: 'all', freq: 'daily', mode: 'party' }); setAddingCustom(false); } @@ -399,6 +399,10 @@ function ChoreSection({ players, enabledChores, onToggle, choreOverrides, onOver + } /> diff --git a/frontend/src/index.css b/frontend/src/index.css index 900a7a7..482b069 100644 --- a/frontend/src/index.css +++ b/frontend/src/index.css @@ -98,6 +98,11 @@ body.crt::after { .torch-wrap.torch-left { left: 14px; } .torch-wrap.torch-right { right: 14px; } +/* Hide torches on screens where they overlap player cards (tablets, small laptops) */ +@media (max-width: 1400px) { + .torch-wrap { display: none; } +} + .torch-sprite { width: 48px; height: 96px; diff --git a/questboard/DOCS.md b/questboard/DOCS.md index 16f6a6e..202be91 100644 --- a/questboard/DOCS.md +++ b/questboard/DOCS.md @@ -1,41 +1,263 @@ -# Questboard +# Questboard - Full Guide A pixel art RPG-themed chore tracker for the whole family. Complete household chores to battle monsters, earn gold, and unlock rewards. +--- + ## First-Run Setup -When you open Questboard for the first time, a setup wizard will guide you through: +When you open Questboard for the first time, a setup wizard guides you through: + +1. **Add players** (1–6) - enter names and choose difficulty mode + - **Kids mode** - kid-appropriate chores, lower monster HP, easier battles + - **Adults mode** - full chore list, tougher monsters, higher stakes +2. **Pick an avatar and class** - see [Hero Classes](#hero-classes) below +3. **Choose chores** - toggle individual chores on/off, add custom ones +4. **Choose rewards** - pick what you can spend gold on +5. **Start your adventure!** -1. **Add players** (1–6) — enter names and choose difficulty - - **Easy mode** — kid-appropriate chores, lower monster HP - - **Hard mode** — full adult chore list, tougher monsters -2. **Pick an avatar and class** — Knight, Sorceress, Ranger, and more -3. **Choose chores** — toggle individual chores on/off, add custom ones -4. **Start your adventure!** +You can return to Settings any time to add/remove players, change chores, adjust rewards, or tweak difficulty. -You can return to settings any time to add players, change chores, or adjust difficulty. +--- ## How to Play -- Tap a **player card** to select your hero -- Tap any **chore** to complete it — this deals damage to your monster -- Fill the monster's HP bar to zero before midnight to **earn gold** -- If you don't defeat it, the monster **attacks** and you lose gold -- Spend gold in the **Reward Shop** on treats your family has agreed on +1. Tap a **player card** to select your hero +2. Tap any **chore** to complete it - this deals damage to your daily monster +3. Fill the monster's HP bar to zero before midnight to **earn gold** +4. Spend gold in the **Reward Shop** on family rewards + +### The Daily Cycle + +Every day at midnight: +- Each player gets a new monster (seeded by date, so everyone sees the same monsters) +- All daily chores reset +- Weekly chores reset on Sundays, monthly chores on the 1st + +### What Happens If You Don't Defeat Your Monster + +If midnight hits and your monster still has HP left, **the monster attacks you**. You lose gold equal to the monster's attack power. The exact amount depends on the monster - tougher monsters hit harder. + +You'll see a warning toast like: `⚠ Amy: The goblin swings wildly at your coins! -3 gold` + +Your gold can't go below zero, but a penalty resets your "penalty-free days" streak (which matters for the Untouchable badge). + +**Shield Aura** power-up blocks the midnight penalty if active. + +--- + +## Hero Classes + +Classes are cosmetic - they change your hero's sprite but don't affect gameplay stats. Pick whatever looks cool! + +| Class | Description | +|-------|-------------| +| Warrior | Classic sword-and-shield fighter | +| Mage | Arcane spellcaster | +| Witch | Dark magic wielder | +| Rogue | Sneaky dual-wielder | +| Paladin | Holy knight | +| Ranger | Bow-wielding forest guardian | +| Frost Knight | Ice-armored warrior | + +All players earn XP, gold, and level up at the same rate regardless of class. + +--- + +## Chores - Party vs Solo + +Every chore has a mode: + +- **ALL (party)** - shared by the whole group. When one person completes it, it's done for everyone. Great for household tasks like "Cook dinner" or "Vacuum." +- **1P (solo)** - tracked per player. Each person must complete it themselves. Perfect for personal tasks like "Brush teeth" or "Pack backpack." + +You can toggle any chore between ALL and 1P in Settings using the green ALL / pink 1P button. + +### Custom Chores + +Add your own chores in Settings → Chores → "+ Add custom chore". Set the name, icon, points, frequency (daily/weekly/monthly), and mode (ALL shared or 1P per player). + +### Bonus Chore + +One random chore each day is marked as the **bonus chore** (shown with a ⭐). Completing it gives extra rewards. + +--- + +## Combat Mechanics + +### Crit Hits +Each chore completion has a chance to deal **double damage**. Base crit chance is 5%, increasing by 1% per level. Crits show a ⚡ flash and play a special sound. + +### Combo Attacks +Complete multiple chores within 8 seconds to chain a combo. Combos multiply damage up to 2.5×. + +### Kill Streaks +Defeat your monster every day to build a streak: +- 3+ days: 1.2× gold multiplier +- 7+ days: 1.5× gold multiplier +- 14+ days: 2.0× gold multiplier + +Missing a day (monster survives) resets your streak to zero. + +### Loot Drops +Every chore has a 10% chance to drop bonus loot - extra gold or XP. Your luck stat (increases with level) improves drop quality. + +### Overkill System +After killing your monster, any additional chores charge an **overkill bar**. Fill it up to bank Power Tokens that can be spent on power-ups. + +--- + +## Dungeon + +The Dungeon is a fog-of-war exploration mode - a procedurally generated dungeon that each player explores independently. + +### How It Works + +1. **Earn moves** by completing chores. Each chore grants dungeon moves. +2. **Explore** the dungeon using the on-screen d-pad (← ↑ ↓ →) or swipe gestures. +3. **Discover rooms** as you move - the fog lifts to reveal what's inside. +4. **Collect loot** and avoid traps as you go deeper. + +### What You'll Find + +| Tile | What It Does | +|------|-------------| +| 🟡 Small gold | 1–2 gold (scaled by depth and floor) | +| 💰 Large gold | 2–5 gold | +| 📦 Chest | 5–9 gold jackpot | +| ⚠️ Trap | Lose gold (reduced by luck stat) | +| 👹 Monster | Dungeon combat - defeat it with chore completions | +| 🗝️ Key | Picks up the floor key | +| 🔒 Locked chest | 10–17 gold - requires the floor key | +| ⬇️ Stairs down | Descend to the next floor (harder but more loot) | +| ⬆️ Stairs up | Return to the previous floor | + +### Dungeon Strategy + +- **Go deep** - deeper floors and rooms farther from the start give better rewards (depth multiplier + floor multiplier) +- **Find the key first** - each floor has one key and one locked chest. The locked chest is the biggest payout. +- **Watch for traps** - higher luck (from leveling up) reduces trap damage +- **Dungeon monsters** require multiple chore completions to defeat, but drop gold when killed + +### Controls + +- **D-pad overlay** - tap the directional arrows on screen +- Each move costs 1 pending move from your pool +- You earn moves from completing chores during normal play + +### Daily Starter Moves + +Every day you get free dungeon moves based on your level: +- Level 1: 2 moves +- +1 move per 3 levels + +--- + +## Power-Ups + +Power-ups activate when you meet certain conditions (configurable in Settings): + +| Power-Up | Effect | Duration | +|----------|--------|----------| +| Gold Rush | Bonus gold on all chore completions | Timed | +| Double Damage | All chores deal 2× damage | Timed | +| Shield Aura | Blocks midnight gold penalty | Timed | +| Treasure Magnet | Increased loot drop chance | Timed | +| Forge Reward | Grants Power Tokens directly | Instant | + +Power-up triggers can be set to: daily chores completed, weekly chores completed, monthly chores completed, kill streak length, or all dailies done. + +--- + +## Badges & Titles + +Earn badges by reaching milestones. Each badge also unlocks a hero title. + +| Badge | Requirement | Title Unlocked | +|-------|------------|----------------| +| 🩸 First Blood | Defeat your first monster | Monster Hunter | +| 🔥 On a Roll | 3-day kill streak | On a Roll | +| ⚡ Streak Lord | 7-day kill streak | The Relentless | +| 👑 Unstoppable | 14-day kill streak | The Unstoppable | +| 💸 Big Spender | Redeem 5 rewards | The Wealthy | +| 💰 Gold Hoarder | Hold 100+ gold at once | Gold Hoarder | +| ⚔️ Monster Slayer | Defeat 10 monsters total | Monster Slayer | +| 🍀 Lucky Charm | Get 3 lucky loot drops | Lucky Charm | +| 🛡️ Untouchable | No midnight penalties for 7 days | Untouchable | +| 🌟 Prestige | Reach level 10 and prestige | The Prestigious | + +### Prestige + +At level 10, you can **prestige** - reset your XP and level back to 1 in exchange for a permanent gold bonus. Your badges, gold, and history are kept. + +--- + +## Leveling & XP + +| Level | XP Required | +|-------|-------------| +| 1 → 2 | 10 XP | +| 2 → 3 | 15 XP | +| 3 → 4 | 25 XP | +| n → n+1 | 10 + 5 × (n−1)² XP | + +Each level increases: +- Crit chance (+1% per level) +- Luck stat (+2% per level, caps at 50%) +- Daily dungeon starter moves (+1 per 3 levels) + +XP and levels never reset (except prestige). + +--- + +## Reset Week Button + +The **Reset Week** button in the top-right is a manual full reset. It: +- Resets all gold to 0 for every player +- Clears all chore completion states (daily, weekly, monthly) +- Resets all monster damage and kill streaks to 0 +- Clears overkill charge and power tokens +- Removes active power-ups + +It does **NOT** reset: history log, XP/levels, badges, or settings. + +This is a hard reset - use it when you want a fresh start for the family. It triggers immediately from the current moment, not aligned to any specific day of the week. + +A confirmation dialog appears before it runs. + +--- + +## Automatic Resets + +| What | When | +|------|------| +| Daily chores | Every midnight | +| Weekly chores | Every Sunday at midnight | +| Monthly chores | 1st of each month at midnight | +| Monster assignment | Every midnight (new monster) | +| Kill streak | Resets to 0 if monster survived | +| Dungeon starter moves | Granted daily | + +XP, levels, gold, badges, and history persist forever. + +--- + +## Weekly Leaderboard -## Crit Hits +The History tab shows a weekly gold leaderboard - who earned the most gold this week. Resets when the week rolls over (Sunday). -Each chore has a chance to deal **double damage** (crit). Your base crit chance is 5% and increases by 1% each time you level up. Crits are shown with a ⚡ and a special sound. +--- -## Resets +## Tips -| Chore type | Resets | -|------------|--------| -| Daily | Every midnight | -| Weekly | Every Sunday | -| Monthly | 1st of each month | +- Chain chores quickly for combo damage (within 8 seconds) +- The bonus chore (⭐) changes daily - prioritize it +- Kill streaks compound - a 14-day streak doubles your gold +- Explore the dungeon for extra gold that doesn't depend on monsters +- Shield Aura is your insurance policy against midnight penalties +- Personal chores (1P) are great for kids' routines that each child needs to do independently -XP and levels never reset — they carry over forever. +--- ## Support