⚔️ Story Quest

Turn lessons into legends. Story Quest is a web app for educators that transforms lesson plans, slide-deck text, and standards documents into interactive, LITRPG-style story adventures students play to learn.

Everything runs in the browser — no server, no accounts, no installs, and no student data ever leaves the educator's computer.

Quick start

Open index.html in any modern browser (double-clicking the file works). No build step, no dependencies.

100% offline: the welcome page has a 💾 Take Story Quest offline section. When the app is hosted on the web, its download button bundles the entire app — HTML, CSS, and JS — into one story-quest-offline.html file that educators can keep on a laptop, USB drive, or school shared drive and open in any browser with no internet, no account, and nothing to install. When you're already running from a local file, the section shows copy/share instructions instead.

Want to try it immediately? Paste examples/sample-lesson-plan.txt into step 1, and see the finished quests in examples/:

• sample-quest-woodland.html — Grade 4 equivalent fractions in the Elderwood
• the-great-program-of-maplewood-falls.html — middle-grades CS standard 68-AP-06 (design, implementation, and review of programs)
• made-in-maplewood.html — Grade 9 Technology, Engineering & Design: the role of manufacturing in technology, manufacturing types, local careers, and the multiplier effect

Each quest ships with a matching .storyquest.json you can import into the builder to edit.

How it works

Story Quest walks the educator through six guided steps:

1. Lesson Material — Upload or paste a lesson plan, slide-deck text, or standards document (.txt/.md upload; paste for PDFs/Word/slides). It stays available in a side panel while building.
2. Quest Basics — Title, subject, grade level, and educator name (shown on the title screen and certificate).
3. Choose a World — Pick one of four templates (more coming later):
   • 🌲 The Elderwood — fantasy woodland; students are Apprentice Rangers rekindling the fading Heartwood, guided by Sage the Owl.
   • 🌊 Depths of Coralia — underwater adventure; students are Pearl Divers recovering the Pearls of Wisdom, guided by Nautica the Sea Turtle.
   • 🏙️ Maplewood Falls — small-town city simulation; students are Junior Town Councilors solving problems for neighbors, guided by Mayor Rosa Delgado.
   • 🚀 The Nova Frontier — deep space exploration; students are Star Cadets aboard the survey ship Meridian recovering scrambled Star Cores, guided by AURA, the Ship's AI.
4. Objectives — List learning objectives by hand, or let Story Quest scan the lesson material and suggest them.
5. Quest Stages — The heart of the builder. Each stage is one scene: auto-drafted, fully editable story narration plus one challenge (multiple choice, true/false, or typed short answer) with hint, explanation, and XP reward. Attach an optional challenge image (a diagram, model, or photo — auto-resized and embedded straight into the quest file, so it still works offline). One-click "create a stage per objective," re-draft narration in a different voice, reorder, and link stages to objectives.
6. Preview & Publish — Tune game rules (hearts/attempts, rank names, hero-name prompt, answer shuffling), polish the opening/closing narration, preview the quest exactly as a student sees it, then download it. A one-click Answer Key / Teacher Guide opens a printable document with every question, marked correct answers, hints, explanations, and linked objectives — handy for sub plans and review.

The published quest is one standalone HTML file with all CSS and JS embedded — share it through an LMS, email, shared drive, or USB stick. It works offline.

The student experience

• Themed title screen; students enter a hero name that appears throughout the story and on their certificate.
• Story narration carries them from location to location; each scene ends in a challenge.
• The world's guide character (Sage the Owl, Nautica the Sea Turtle, Mayor Rosa Delgado, or AURA the Ship's AI) appears as a drawn portrait beside the story and reacts to answers — celebrating wins, encouraging retries.
• A quest map trail tracks the journey: one node per stage on a winding path (a dashed woodland trail, a bubble line in Coralia, a marked road in Maplewood Falls, an orbit line in the Nova Frontier) — completed nodes turn gold with a check, the current node pulses under its location name, and a star marks the goal.
• Stars and collectibles: each stage awards 1–3 stars (3 for a first-try win) shown under its trail node, and every solved challenge drops a themed treasure — Heartwood Embers, Golden Seashells, Maplewood Seals, or Star Cores — into a satchel bar. Results tally stars and treasures, with Treasure Hunter and Perfect Run badges for full collections.
• Hearts limit attempts per challenge: full XP on the first try, half on the second, a quarter after that. When hearts run out, the answer and the educator's explanation are revealed — learning never dead-ends.
• XP and ranks: earning XP fills a progress bar and levels students up through five themed ranks (e.g., Wanderer → Elderwood Sage).
• Hints appear after the first wrong answer; explanations appear once each challenge resolves.
• A results screen shows XP, rank, badges, and per-stage outcomes, plus a printable completion certificate.
• A mission report closes the assessment loop: a printable per-stage summary (question, result, tries, stars, points earned, signature lines) and a downloadable .txt version students can submit through an LMS.
• Multiple-choice answers shuffle into a random order for each student (educators can turn this off in the publish step for order-dependent choices like "All of the above").
• Progress saves automatically at every stage: if the bell rings mid-quest, reopening the file offers "Welcome back — continue from Stage 4?" with XP, stars, and treasures intact. Finishing (or choosing Start Over) clears the save.

For educators: your control

Every drafted sentence is editable. You choose the order of stages, the difficulty curve, the XP economy, the number of attempts, the rank names, and every question, hint, and explanation. Story Quest drafts the fiction; you own the pedagogy.

Projects autosave in the browser, and you can export/import a project as .json to back it up, move computers, or share with a colleague.

Project layout

index.html          — educator app shell
css/styles.css      — educator app styles
js/templates.js     — the three world templates (add new worlds here)
js/generator.js     — builds the standalone student HTML file
js/app.js           — wizard, state, autosave, stage builder
examples/           — sample lesson plan and a generated sample quest

Adding a new world template

Add an entry to TEMPLATES in js/templates.js (copy an existing one — it's all data: names, locations, colors, and narration patterns) and add its id to TEMPLATE_ORDER. The builder and generator pick it up automatically.