Quest Development Guidelines
- Be grounded in reality - Focus on projects people can actually build at home
- Follow logical progression - Start with beginner-friendly content before advanced concepts
- Provide educational value - Teach useful skills that connect to space exploration themes
- Emphasize sustainability - Showcase environmentally responsible approaches
- Be scientifically accurate - Present correct information with proper terminology
- 3D Printing
- Aquaria
- Astronomy
- Chemistry
- Completionist
- Composting
- DevOps
- Electronics
- Energy
- First Aid
- Geothermal
- Hydroponics
- Programming
- Robotics
- Rocketry
- Sysadmin
- UBI
- Welcome
- Woodworking
- Quest order and
requiresQuestsrelationships - Dialogue-level
requiresItemsgates that affect progression - Quest-level
grantsItems(or an explicit "None" when absent) - Quest
rewards - Linked process references with accurate Requires / Consumes / Creates summaries
- If a tree directory is added/removed/renamed under
frontend/src/pages/quests/json/<tree>/:- Ensure
/docs/<tree>is present in the/docsSkills section via merged auto-discovery. - Ensure
frontend/src/pages/docs/md/<tree>.mdexists and documents the full tree.
- Ensure
- If any quest JSON changes:
- Update
frontend/src/pages/docs/md/<tree>.mdin the same PR (gates, grants, rewards, process IO, QA notes). - Run
npm run lint,npm run link-check, and the bulk quest validator.
- Update
- Don't invent grants: docs may only list
grantsItemsthat exist in quest JSON (quest or option level). Processcreatesare process outputs and must not be labeled as quest grants unless explicitly granted by quest JSON. - Branched trees: when
requiresQuestsbranches, document Main path + Branches (or a clear edge list). Do not force false linear ordering. - After docs, tweak quests: update docs first, then apply minimal quest JSON fixes justified by the docs review.
- Anti-pattern scan (process option gated by its own output, or equivalent redundant gates):
rg -n "\"requiresItems\"|\"process\"\s*:\s*\"" frontend/src/pages/quests/json/<tree> -S - Repeated-log minimum counts: when later quests require repeated measurements/logging, gate
continue/skip options on count
>= Ninstead of forcing process reruns for players who already have enough. - Rewards sanity: only tune rewards when docs expose a clear progression blocker.
frontend/__tests__/questCanonical.test.jsfrontend/__tests__/questQuality.test.jsfrontend/__tests__/questSimulation.test.jsfrontend/__tests__/questDependencies.test.jstests/questDialogueValidation.test.tstests/questSchemaValidation.test.tsandtests/builtinQuestSchema.test.tstests/questRewardsValidation.test.tsandtests/questCompletableItems.test.tstests/questProcessCoverage.test.tsandtests/questProcessNecessitySimulation.test.tstests/questReliabilityCoverage.test.tstests/questProcessRecoveryPaths.test.tsandtests/questRewardGrantSeparation.test.tstests/questStaticTestRegression.test.ts(regression guard for static-test proof gating and process-option traversal semantics)tests/questDependencyReferences.test.ts,tests/questGraphValidation.test.ts,tests/questGraph.test.ts, andtests/questPrerequisites.test.tstests/progressionBalance.test.tstests/sysadminQuestQuality.test.ts- Entry Level - Minimal equipment, very accessible, quick results
- Beginner - Common household items or inexpensive purchases
- Intermediate - More specialized equipment, longer timeframes
- Advanced - Specialized equipment, technical knowledge, significant commitment
- Make dependencies clear and logical
- Only
welcome/howtodoquestsshould have an emptyrequiresQuestslist. All other quests must depend on it directly or on a downstream quest so new players always learn the mechanics first. This rule is enforced by automated repository tests to prevent regressions. - Each category should have a clear entry point that chains back to
welcome/howtodoquests. - Dependencies should mirror the real learning path so prerequisites teach the skills needed for later quests.
- Advanced quests should require completion of relevant prerequisites
- Authentic Voice: Each NPC should have a consistent personality
- Educational Tone: Instructive without being condescending
- Technical Accuracy: Use proper terminology and scientifically accurate information
- Clear Instructions: Step-by-step guidance that's easy to follow
- Branching Options: Provide meaningful choices where appropriate
- Always include appropriate safety warnings
- Recommend proper protective equipment when needed
- Never encourage dangerous activities or improper handling of materials
- Processes introduce time-based play and should reflect real-world timing. Quick setup actions (plugging in a smart plug, scanning a barcode, initiating a download) should resolve in seconds, while longer projects scale sensibly (filling a bucket in under a minute, printing a Benchy in a couple of hours, growing a plant over weeks).
- When quests reference processes, double-check durations against the real task to keep the experience grounded and avoid multi-hour waits for introductory tutorials.
- Position the Tank (Entry) - Choose a safe, stable location
- Sponge Filter (Beginner) - Add mechanical filtration
- Walstad Method (Intermediate) - Set up a planted, low-tech tank
- Shrimp Care (Intermediate) - Introduce shrimp and floating plants
- Goldfish Care (Advanced) - Meet higher filtration and water quality needs
- Basil Growing (Entry) - Simple setup with minimal equipment
- Bucket System (Beginner) - Move to a basic bucket configuration
- Lettuce Production (Intermediate) - Add leafy greens with routine checks
- Nutrient Refresh (Intermediate) - Refresh reservoir nutrients and pH
- Stevia Regrowth (Advanced) - Maintain and regrow a more sensitive crop
- Basic Circuit (Entry) - Simple LED circuit with battery
- Arduino Blink (Beginner) - Programmed interactions
- Light Sensor (Intermediate) - Read sensor data reliably
- Temperature Logging (Intermediate) - Capture and chart readings
- Potentiometer Dimmer (Advanced) - Build a variable control circuit
id: Unique identifier following the patterncategory/nametitle: Display title of the questdescription: Brief description explaining the quest purposeimage: Path to quest imagenpc: Path to NPC avatar image (choose from the NPC list in /docs/npcs)start: ID of the starting dialogue nodedialogue: Array of dialogue nodes, each containing:id: Node identifiertext: NPC's dialogue textoptions: Array of player response options, including:type: Action type (goto, finish, process, grantsItems)text: Player's response textgoto: For type:goto, target node IDprocess: For type:process, process IDrequiresItems: Optional items needed to select optiongrantsItems: Optional items given when selecting optionrequiresGitHub: Optional schema field used by the quest runtime to gate an option
rewards: Items given upon quest completionrequiresQuests: Array of quest IDs that must be completed first (select these in the quest form under Quest Requirements). Automated tests ensure these dependencies reference existing quests and avoid cycles.- Item requirement and reward configuration for dialogue options
- Process action selection
- Preview functionality to test dialogue flow
- Open
/quests/create. - Fill out the quest metadata (title, description, image, NPC).
- Add dialogue nodes and options (goto, finish, process, or grantsItems) and choose the start node.
- Save the quest to store it locally and receive a link to view it.
- Open
/quests/manage. - Click Edit on a custom quest (built-in quests are read-only); this routes to
/quests/[id]/edit. - Update the fields and save to update the local IndexedDB record.
- Titles must be unique and at least 3 characters; descriptions must be at least 10 characters.
- NPC selection defaults to Mission Control if left blank.
- Dialogue node IDs must be unique, nodes require text, and each node needs at least one option.
- Goto options must target existing node IDs; process options require a process ID.
- Required and granted item rows must include an item ID and positive count (the same applies to quest reward items).
- Image uploads are downsampled into square JPEG data URLs (target ~50KB). If you leave the image
blank on a new quest, the editor uses
/assets/quests/howtodoquests.jpgas the default. - The simulation summary warns if dialogue paths cannot reach a finish option, but it does not block saving.
- All dialogue paths lead to completion
- Item grants and requirements function correctly
- Process integrations work as expected
- Educational content is accurate and clear
- Safety warnings are included where appropriate
- Use the in-game editor at
/quests/createor/quests/[id]/edit. - Test using the preview and simulation summary to confirm dialogue flow and rewards.
- Export your custom content from
/contentbackup. - Submit the quest JSON at
/quests/submit(or bundle JSON at/bundles/submit) with a GitHub token. - Track review feedback in the linked GitHub pull request and iterate as needed.
- Develop your quest locally following these guidelines. Start with
npm run generate-quest --template basicfor a ready-made template. - Validate the quest JSON with
node scripts/validate-quest.js path/to/quest.json. - Update the matching Skills-category quest-tree doc (for example,
/docs/composting) so it reflects any new quests or changed gates/rewards. - Submit a pull request with your quest JSON file.
- Respond to feedback during code review.
- Sustainable energy systems
- Small-scale biology experiments
- Chemistry demonstrations relevant to space exploration
- Sensor systems and data collection
- Resource recycling and waste management
- Low-cost astronomy projects
- Materials testing experiments
Quest Development Guidelines
This guide provides structured instructions for creating engaging, educational quests that align with DSPACE's mission to democratize space exploration through practical, hands-on learning experiences. Start with the Quest Template Example and consult the Quest Schema Requirements for field definitions. When your quest is ready, follow the Quest Contribution Guidelines and the Quest Submission Guide to share it with the community. For an overview of existing quest categories, see Quest Trees.
Quest Philosophy
DSPACE quests should:
Quest Categories
Quest trees map to the folders in frontend/src/pages/quests/json. The current in-game trees are
listed in Quest Trees. When writing new content, align the quest's id with an
existing tree unless you're intentionally adding a new category.
Current trees include:
Quest Tree Documentation Requirement
When you add a quest to an existing tree (or create a new tree), update a matching doc in the
Skills category under frontend/src/pages/docs/md/ so reviewers can audit progression without
reverse-engineering JSON. Use Composting as the reference format.
Each tree doc should include:
If you change quest gating or inventory flow, update the corresponding Skills doc in the same pull request.
Quest ↔ Docs 1:1 Contract (Required)
Every quest tree directory under frontend/src/pages/quests/json/<tree>/ must have a matching
/docs/<tree> page and a Skills chip on /docs. Treat quest JSON and tree docs as a single
change unit in the same pull request.
Required workflow checklist (copy/paste)
Deterministic QA audit checklist
Required verification commands for PR descriptions
npm run lint
npm run link-check
for f in frontend/src/pages/quests/json/*/*.json; do node scripts/validate-quest.js "$f" || exit 1; done
Quest quality and reliability test suites
Beyond JSON validation, quest quality relies on these automated suites:
Run them with a command that accepts explicit test file paths, for example npm run test:root -- frontend/__tests__/questCanonical.test.js frontend/__tests__/questQuality.test.js frontend/__tests__/questSimulation.test.js frontend/__tests__/questDependencies.test.js tests/questDialogueValidation.test.ts tests/questSchemaValidation.test.ts tests/builtinQuestSchema.test.ts tests/questRewardsValidation.test.ts tests/questCompletableItems.test.ts tests/questProcessCoverage.test.ts tests/questProcessNecessitySimulation.test.ts tests/questReliabilityCoverage.test.ts tests/questProcessRecoveryPaths.test.ts tests/questRewardGrantSeparation.test.ts tests/questStaticTestRegression.test.ts tests/questDependencyReferences.test.ts tests/questGraphValidation.test.ts tests/questGraph.test.ts tests/questPrerequisites.test.ts tests/progressionBalance.test.ts tests/sysadminQuestQuality.test.ts.
Quest Structure Guidelines
Progressive Difficulty
Organize quests in a clear progression from beginner to advanced:
Quest Dependencies
Content Guidelines
Dialogue Best Practices
Safety First
Process Duration Realism
Examples of Well-Structured Quest Sequences
Aquaria Sequence (Example)
Hydroponics Sequence (Example)
Electronics Sequence (Example)
Quest Technical Requirements
Required Fields
Every quest JSON file must include:
Quest data is validated against a JSON schema. In the in-game editor, titles and descriptions
reject < and > characters, and image must be a data URL, an absolute HTTP(S) link, or a
root-relative path. Quest titles must be unique across all existing quests.
Current Implementation State
Note: The quest editor lets you build branching dialogue directly in the browser. The current implementation in
QuestForm.sveltesupports quest metadata (title, description, image), selecting required quests, choosing an NPC, creating dialogue nodes withgoto,finish,process, orgrantsItemsoptions, and adding item requirements or rewards on each option. You can choose the start node and manage options without writing JSON, and the preview updates live for uploaded images. The form remains mobile‑responsive and stacks action buttons on small screens. Advanced option flags likerequiresGitHubare part of the JSON schema/runtime but are not exposed in the editor UI.
The editor focuses on the fundamentals today and exposes controls to gate dialogue options on
specific items or grant rewards inline. You can run npm run generate-quest --template basic
(or branching) to scaffold a template JSON file with placeholder dialogue.
In-game editor flow (create + edit)
Use the in-game quest editor to create and update custom quests that are stored locally in your browser's IndexedDB custom content database (with an in-memory fallback if IndexedDB is not available, so changes will not persist after refresh). The editor only saves locally; to submit content, export JSON and use the submission forms described in the Quest Submission Guide.
Create a quest
Edit a quest
Validation and image handling
Testing Your Quest
Before submitting a quest, verify:
Contribution Workflow
Preferred: In-game editor + submission forms
Manual JSON contribution
Areas Needing More Content
We're particularly interested in new quests that cover:
By following these guidelines, you'll create quests that engage players while advancing DSPACE's mission of democratizing space exploration through practical, hands-on education.
