Gamemaster manual — دليل القيم ماستر

Running a Hunt (التحدي): building it, putting the boxes out, watching it, and the things that go wrong. Arabic follows the English.

Terms — المسميات

Every name in this manual appears in both languages the first time it is used. This is the list:

English	بالعربية
Hunt	التحدي
Stage	المرحلة
Clue	الدليل
Box	الصندوق
Team	الفريق
Gamemaster	القيم ماستر
Question	السؤال
Focus guard	حارس الشاشة

A Hunt is a تحدي, not a صيد. The word "hunt" survives in the website's name only. Everywhere a person reads, it is التحدي.

---

1. What a Hunt (التحدي) is made of

A Hunt holds ordered Stages (المراحل). Each Stage has Questions (الأسئلة), a Clue (الدليل) telling players where to find it, and usually a Box (الصندوق).

Teams walk the Stages in order. Stage 1 opens on the clock; every later Stage opens for a Team (الفريق) the moment they clear the one before it.

The race model, in one sentence: the first Team to solve a Stage wins its Box, but every other Team still has to solve that Stage themselves to move on. Losing a Box costs a Team the Box, not their progress.

2. Building one

1. Hunts → + Create hunt. Give it a name.
2. Stages → add a Stage, write its Clue — the sentence that sends players to the place.
3. Add Questions. Three kinds: Multiple choice, Drag onto a picture, Match to labels.
4. Click the 👁 beside any Question to play it exactly as a student will. If it looks wrong there, it is wrong.
5. Boxes tab: point a Box at each Stage, or print the codes instead (§4).
6. Go live.

More than one Hunt can be live at once — a class on one while you test another is fine. The landing page asks players which.

2.1 Or import one

⬆ Import hunt (Hunts tab) takes a .zip holding a hunt.json and an images folder. ⬆ Upload a stage (Stages tab) adds a single stage to the hunt you have selected.

This is how you build a Hunt with an AI: give it the Integration API document from the Docs tab, answer its questions, and it hands you the ZIP.

Choosing a file does not import it. You get a report first — stages, Questions, types, which Stages have a Clue, and anything wrong with it — and the Import button only wakes up if the bundle is sound. An imported Hunt arrives as a draft, like any other.

3. The clock

Setting	What it does
Start	When Stage 1 opens. Before it, players can join and wait but not play.
Duration	How long the whole Hunt runs from the gun. 0 = until you stop it.
Stage timer	Per attempt, not per Team.

Going live re-stamps the start, which is also how you re-run a Hunt that has already expired.

The dashboard warns you before going live if the Hunt would open immediately, or would already be over.

4. Boxes (الصناديق), or paper

A Box shows a QR and pops its latch. You do not need one to play.

• With Boxes: Boxes tab, or the 🔒 switch on a Hunt card to point every free Box at it. A Box another Hunt is using is left alone — the switch will tell you how many were unavailable.
• Without Boxes: 🖨 Print QR sheet on the Hunt card gives you one A4 page with every Stage's code, ready to cut and hide. A printed card and a powered Box are interchangeable.

The code on each card is a secret. Stage 1's link is public by design — share it anywhere. Every later Stage carries a token that exists only on its own card or Box, so a player cannot reach Stage 3 by editing a URL.

5. While it runs

Live monitor shows every Team: where they are, which Question they are on, their best score as a count, how long they have been idle, and the clock time of their last move.

• stuck = three or more attempts at the same Box. Go and talk to them.
• pending pop = a Team cleared a Stage but the Box never confirmed it opened. Flat battery, or no Box on that Stage.
• 👁 left ×n = how many times they left the app, if the Focus guard (حارس الشاشة) is on. Information, not proof — a phone call and a lock screen look identical from here.
• ⤓ Export gives you the whole table as a spreadsheet.

6. The Focus guard (حارس الشاشة)

The 👁 switch on a Hunt card. With it on, a player who switches to another app gets one warning; the second time, their current Stage restarts at Question 1.

It is off by default because it can clear a player's work.

What it closes is the cheap route — screenshot, ask an AI, come back. It cannot see a screenshot, and it cannot see a second phone pointed at the screen. Nothing in a browser can. Treat it as a cost imposed on the lazy route, not a guarantee.

Three things keep it off honest players: the screen is held awake, trips under 3 seconds are ignored, and the first one only warns.

7. When something goes wrong

What you see	What it means
Box screen says PARKED	No Stage assigned. Boxes tab.
Box says WiFi NOT FOUND	The ESP32 is 2.4 GHz only. Set the hotspot band to 2.4 GHz.
A Team is stuck on "scan the box"	They are at the wrong Stage's Box, or the code did not read. Give them the printed code to type.
A Box never pops	Live monitor → pending → mark it opened by hand.
A Team must be moved on	Advance them from the monitor.

Reset all teams & progress wipes every Team and clears every winner, so the same Hunt can be run with a fresh group. It cannot be undone.

8. Paper

📄 Paper exam exports a Hunt's Questions as a Word document — multiple choice, true/false, and match-to-labels as a word bank with blanks. The answer key is the last page: keep that page.

Picture and dial Questions are marked as interactive rather than dropped, so you can see what is missing.

9. Storage

Docs tab → 🗄 Storage. Every picture ever uploaded stays on the server, including ones belonging to Hunts you deleted.

Check storage counts them and sorts them into four groups. Clean up removes only the orphaned ones — never a picture a Question still uses, and never one uploaded in the last 24 hours, because a picture is often uploaded minutes before the Question that names it is saved.

If it reports pictures that are *referenced but missing*, a live Question has a broken image. That one needs fixing by hand; clean-up will not cause it and cannot repair it.

---