Quest Template Example

This page provides a minimal quest JSON structure that you can use as a starting point for your own quests. For field details see the Quest Schema Requirements, and when you're ready to publish, follow the Quest Submission Guide. Feel free to copy this snippet into your editor to speed up the process.

Ready-to-use JSON templates live in frontend/src/pages/quests/templates. Copy basic.json for a linear quest or branching.json to experiment with multiple paths. You can also run npm run generate-quest --template basic (or branching) to copy one automatically.

{
    "id": "astronomy/constellations",
    "title": "Map the Constellations",
    "description": "Identify key star patterns to aid celestial navigation.",
    "hardening": {
        "passes": 0,
        "score": 0,
        "emoji": "🛠️",
        "history": []
    },
    "image": "/assets/quests/solar.jpg",
    "npc": "/assets/npc/nova.jpg",
    "start": "start",
    "dialogue": [
        {
            "id": "start",
            "text": "Great progress so far! Next let's learn the constellations visible this season.",
            "options": [{ "type": "goto", "goto": "study", "text": "I'm excited to learn!" }]
        },
        {
            "id": "study",
            "text": "Using your telescope, locate Orion, Ursa Major, and Cassiopeia. Sketch their brightest stars and note their orientation each night.",
            "options": [
                {
                    "type": "process",
                    "process": "identify-constellations",
                    "text": "Charting patterns..."
                },
                {
                    "type": "goto",
                    "goto": "finish",
                    "text": "I can spot them easily now!",
                    "requiresItems": [{ "id": "item-id", "count": 1 }]
                }
            ]
        },
        {
            "id": "finish",
            "text": "Excellent! Recognizing these patterns will help you orient spacecraft sightings and plan future observations.",
            "options": [{ "type": "finish", "text": "Thanks, Nova!", "requiresGitHub": false }]
        }
    ],
    "rewards": [],
    "requiresQuests": ["astronomy/jupiter-moons"]
}

Use this template as a baseline and expand it with additional dialogue nodes, processes, item requirements, and rewards. For more in-depth guidance, see the Quest Development Guidelines. The optional hardening block tracks how many upgrade passes a quest has survived and stores a history of Codex tasks. This metadata is meant for maintainers and QA reporting; it no longer surfaces in the player-facing UI but is still used by tests and dashboards. Increment passes, update score, switch the status emoji (🛠️ → 🌀 → ✅ → 💯) and append an entry to history with the task ID, date and score each time you run the quest hardening loop described in the quest prompt guide. An automated Playwright example (constellations-quest.spec.ts) walks through creating this quest step by step if you prefer a hands-on reference.