How To

Understand the engine. Then publish your Mastery Quest.

Start with the adaptive rules: what the engine records, when it can remediate, how short modes calibrate, and when a Mastery Report is allowed to make a strong claim. Then use the deployment guide to publish the finished game with GitHub Pages and your LMS.

Adaptive engine Answer-key hardening Prepare the file Create the repository Turn on Pages Add it to your LMS
Want to know what “adaptive” actually means?

The first section spells out the current engine standard by mode, including remediation, limited-run calibration, and evidence rules. The deployment guide begins immediately after it.

Engine transparency

How adaptation, remediation, and evidence work by mode

Mastery Quests does not use one adaptive rule everywhere. Every accepted answer can contribute correctness, response time, concept/tag, learning objective, skill, question type, difficulty exposure, and recent-performance evidence. What the engine does with that evidence depends on the mode.

Full adaptive selection

Standard Campaign, Timed Trial, Exam Drill, Score Attack, and Unlimited Practice can use the full selector. The engine balances coverage and novelty while also responding to demonstrated weakness, recent performance, response time, and readiness for harder material.

observe → adapt → remediate when warranted → confirm → return

Targeted remediation

In remediation-enabled modes, a meaningful miss can move the learner out of the ordinary stream. The engine uses the question’s skill, objective, concept, question type, response time, and prior evidence to choose the recovery path.

  • Repair isolates the underlying concept or skill.
  • Bridge asks the learner to apply that repaired idea in a nearby context.
  • Retest checks whether the learner can return to normal difficulty.

A very fast or apparently careless miss can begin with a bridge-style check instead of assuming a deep conceptual failure.

Cold-start limited runs

Fading Fortune, Risk & Reward, and Trial by Graph do not begin by pretending the engine already knows the learner. Mastery starts as unknown.

unknown → calibration → investigation

Calibration emphasizes breadth and avoids repeating the same skill. After calibration, repeated misses, weak observed accuracy, slow responses, and unsampled areas influence what eligible question comes next.

Sample-aware reporting

Short fixed-length modes never treat a small sample as a full mastery diagnosis.

  • 1–2 observations: Limited Signal
  • 3–4 observations: Emerging Pattern
  • 5+ observations: Meaningful Sample

A sampled area needs at least five observations before the report can treat it as a confirmed weakness. Unsampled content remains unknown.

ModeHow questions are selectedRepair / Bridge detoursHow the report interprets evidence
Standard CampaignFull adaptive selection using coverage, recent performance, weakness signals, response time, repetition control, and difficulty readiness.Yes. Targeted remediation can interrupt the normal path when the evidence supports it.Full-evidence Mastery Report.
Timed TrialThe full adaptive selector continues operating under the countdown.Yes. Remediation can still occur while time pressure remains part of the run.Full-evidence interpretation with timing behavior included.
Exam DrillAdaptive nine-question sections with answered/unanswered navigation, review, and revision. Students deliberately commit at each checkpoint; future sections stay locked until progression, and correctness remains hidden while a section is active.Yes, after committed evidence supports it. Artifact powers remain disabled so the exam experience stays consistent.Full-evidence Mastery Report with checkpoint and section evidence.
Score AttackFull adaptive selection underneath the scoring mechanic. Score changes the stakes, not the learning selector.Yes. Remediation remains available.Full-evidence report plus score behavior.
Unlimited PracticeFull adaptive selection continues until the learner ends the session.Yes. Repair and bridge behavior remains available throughout practice.Full-evidence report; long sessions can accumulate especially deep evidence.
Legendary ModeAdaptive challenge selection favors the hardest available material and pressure-tests stronger performance.No. Legendary does not interrupt the challenge with remediation detours.Full-evidence challenge report. Strong conclusions still depend on sufficient evidence.
QuizBalanced sampling with planned Easy → Medium → Hard coverage. Early misses do not cause weakness-chasing.No. The instructor-selected quiz remains a quiz.Sample-aware report. A short quiz is not treated as a complete mastery diagnosis.
Fading FortuneBroad calibration first, then constrained adaptive investigation inside the eligible Fading Fortune pool.No. The normal question stream itself becomes more targeted.Sample-aware report.
Risk & RewardBroad calibration first, then constrained adaptive investigation inside the eligible Risk & Reward pool.No. Wager play is not interrupted by a repair hallway.Sample-aware report.
Trial by GraphBroad calibration first, then constrained adaptive investigation using only legitimate graphRequired questions.No. The graph-only stream remains intact.Sample-aware report. The mode appears only when the game has enough graph-dependent inventory.

Calibration length in short adaptive runs

  • Up to 5 questions: first 3 are calibration.
  • 6–10 questions: first 4 are calibration.
  • 11–15 questions: first 5 are calibration.
  • 16–20 questions: first 6 are calibration.

After that point, the engine can investigate emerging signals without repeatedly hammering the same skill or leaving the mode’s eligible question pool.

Why Quiz is different

Quiz is intentionally protected from weakness-chasing because an instructor may use it as an actual graded or assigned quiz. The engine still spreads coverage and avoids unnecessary repetition, but student performance does not progressively rewrite the quiz around early mistakes.

Availability varies by game. A mode is shown only when the game and its question bank support it. Trial by Graph, for example, requires enough questions whose graph is genuinely necessary to answer the item.

Portable answer-key hardening

What the published game exposes—and what it does not.

Mastery Quests is designed to stay portable: faculty can publish one generated HTML file without standing up a backend server. That portability does not require publishing a plain answer key. Correct answers in published question records are stored as hashes rather than numeric option indexes.

Hashed published answers

A published question does not need to expose a plain correct-choice field such as a: 2. The game compares the learner's selected answer with a stored hash during verification.

LMS iframe friction

When a Quest is embedded in an LMS, developer tools still exist, but the student first encounters the LMS application, its source tree, and separate frame contexts. Inspecting the active game state requires deliberate navigation into the Quest's runtime rather than simply opening page source.

No backend required

This approach keeps deployment simple. Faculty can host the generated file at a public HTTPS URL and embed it in an LMS without maintaining accounts, APIs, databases, or a server-side answer service.

Know the limit

This is answer-key hardening and inspection friction, not secure-exam infrastructure. Any client-side application can be reverse engineered by a sufficiently determined technical user. Use server-side assessment tools when concealed answer verification is a formal security requirement.

Practical takeaway: for ordinary practice, review, homework, and instructor-directed quiz workflows, the generated file avoids the easiest developer-tools shortcut while preserving the one-file deployment model.

Before GitHub

Start with one finished game file.

Composer-generated games are self-contained HTML activities. Graphs and runtime logic are embedded. Concept Reviews open from the Mastery Quests web library when recommended.

01

Rename the generated game index.html

GitHub Pages will automatically serve index.html when someone opens the repository's published web address. Keep the other Composer files as faculty records; they do not need to be hosted.

If you are updating an existing game, keep the same repository and replace its old index.html. You do not need to create a new repository every time.

Create the host

Create a GitHub repository for the game.

A repository is the folder GitHub will publish as a website. For a simple faculty deployment, one repository per game keeps the URL and updates easy to manage.

02

Create a new repository

  1. Sign in to GitHub.
  2. Use the + menu and choose New repository.
  3. Give the repository a short name such as principles-macro-review.
  4. For the simplest GitHub Pages setup on a free account, make the repository public.
  5. Create the repository.
GitHub plus menu with New repository highlighted.
GitHub's New repository command. Interface screenshot from GitHub Docs.
03

Upload index.html

  1. Open the new repository.
  2. Select Add file → Upload files.
  3. Drag index.html into the upload area.
  4. Commit the upload to the repository.
GitHub repository Add file menu with Upload files highlighted.
Use Add file → Upload files to place the game in the repository. Screenshot from GitHub Docs.
The browser upload is enough for a normal Mastery Quest game. You do not need Git, GitHub Desktop, a command line, or a local development environment for this workflow.

Publish the game

Turn on GitHub Pages.

GitHub Pages converts the repository into a public HTTPS website. For a plain Mastery Quest HTML file, publishing directly from the repository's main branch is the simplest setup.

04

Open the repository settings

Select Settings from the repository navigation.

GitHub repository navigation with Settings highlighted.
Open the repository Settings tab. Screenshot from GitHub Docs.
05

Choose Pages and publish from main

  1. In Settings, open Pages under Code and automation.
  2. Under Build and deployment, choose Deploy from a branch.
  3. Select the main branch.
  4. Select /(root) as the folder.
  5. Click Save.
GitHub Pages publishing source branch selector and Save button.
Select the publishing branch in GitHub Pages settings. Screenshot from GitHub Docs.
06

Open the public game URL

After GitHub finishes publishing, the project-site address normally follows this pattern:

https://YOURUSERNAME.github.io/YOUR-REPOSITORY/

Open that URL in a private/incognito browser window and make sure the game starts before placing it in your LMS. GitHub notes that a Pages deployment can take several minutes to become available after a change.

Run at least one enabled mode, open a graph, complete a short run, and test a Concept Review recommendation before giving students the link.

Course deployment

Put the public URL in your LMS.

The GitHub Pages URL is now the game. Use it as a normal course link or embed it when your LMS permits external iframes.

07

Choose link or embed

Option A — External link: Add the GitHub Pages URL as a module item, assignment link, button, or course resource.

Option B — Embed: If your LMS accepts external iframe content, use the published game URL as the iframe source.

<iframe
  src="https://YOURUSERNAME.github.io/YOUR-REPOSITORY/"
  width="100%"
  height="900"
  style="border:0;"
  loading="lazy"
  allowfullscreen>
</iframe>
LMS security policies vary. If your institution blocks the iframe, use the same public HTTPS URL as an external link instead. Embedding the Quest in an iframe also adds practical inspection friction, but the iframe should not be treated as a formal security boundary.
08

Update the game later without changing the student link

To publish a revised build, return to the same repository, replace index.html, commit the change, and let GitHub Pages republish. The public repository URL stays the same.

Troubleshooting

The usual problems are small.

404 or no site

Confirm Pages is enabled, the selected source is main and /(root), and the game file is named index.html.

Old version still appears

Wait for the Pages deployment to finish, then hard-refresh or test the URL in a private browser window.

The LMS will not embed it

Use the same GitHub Pages address as an external course link. The game does not require an LMS wrapper.

Concept Review will not open

The game itself is self-contained, but Concept Review PDFs come from the Mastery Quests web library and therefore require internet access.

That's the whole deployment path

Build once. Publish one HTML file. Use the URL anywhere.

Build a Quest handles creation. Downloads holds the downloadable files. How To is now the hosting and deployment guide.

Build a Quest Downloads