Quests Core Skeleton

Reference template for building new STEAM Quests. This repo is a stripped-down copy of the production quests-core-app codebase: the same shared components, build pipeline, and tooling, but trimmed down to a single reference quest (calculated-rescue) so new developers can read every file that matters without wading through 30+ quests' worth of content.

Use this repo to:

• Understand the app architecture before contributing to the real quest repo.
• See a working, end-to-end example of every scene type, the interactives framework (including a custom canvas-based interactive), localization, and audio.
• Bootstrap a brand-new quest by copying src/GAME_DATA/calculated-rescue as a starting point.

Read these in order:

1. docs/ARCHITECTURE.md — how the app is put together: rendering pipeline, quest loading, scene types, shared vs. quest-specific code.
2. docs/DATA_MODEL.md — the shape of sceneData.ts, dialogs, interactives, locales, and how audio files are wired up.
3. docs/BEST_PRACTICES.md — what to put where, naming conventions, and pitfalls to avoid.
4. HowToAddNewGame.md — step-by-step for adding a new quest.

Quick start

npm install
npm run start:calculated-rescue       # dev server for the reference quest
npm run start:launcher                # dev server for the quest-picker hub
npm run build                          # builds VITE_GAME_ID=calculated-rescue by default
VITE_GAME_ID=calculated-rescue npm run build:scorm   # package as SCORM zip

The dev server runs at http://localhost:5173.

What's in here

src/
  components/        Shared UI: Scene, OneAtATime, TurnBasedChat,
                      SplitScreenChat, EndScreen, Dialog/*, Avatar, etc.
  hooks/              useSceneData, useGameContext, useAudio, ...
  contexts/           GameProvider, ScormContextProvider, ...
  services/           EventBus, GlossaryService, ScormService, ...
  utils/              assetPath, dialogContentUtils, ...
  types/interfaces.ts Shared TypeScript types (SceneData, DialogData, ...)
  constants/          SceneType enum, GAME_TITLES registry, etc.
  GAME_DATA/
    calculated-rescue/  The one reference quest (see docs/DATA_MODEL.md)
    launcher/            Quest-picker hub, lists quests from quests.json
scripts/              Build tooling: audio generation (TTS), glossary CSV
                      conversion, SCORM packaging, deploy menu

Everything under src/ outside GAME_DATA/ is shared and quest-agnostic. Everything a new quest needs lives inside its own src/GAME_DATA/<quest-id>/ folder — quests never import from one another.