# 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.

---

<div dir="rtl" class="ar" markdown="1">

## المسميات — Terms

كل اسم في هذا الدليل يُذكر باللغتين أول مرة يُستعمل فيها، وهذه القائمة:

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

> **الـHunt اسمها «التحدي» لا «الصيد».** كلمة hunt باقية في اسم الموقع فقط، وفي كل ما يقرأه إنسان هي **التحدي**.

## ١ · مِمّ يتكوّن التحدي (Hunt)

**التحدي (Hunt)** يحوي **مراحل (Stages)** مرتّبة. كل مرحلة فيها **أسئلة (Questions)**، و**دليل (Clue)** يقول للاعبين أين يجدونها، وغالباً **صندوق (Box)**.

الفرق تمشي المراحل بالترتيب. المرحلة الأولى تفتح على الساعة، وكل مرحلة بعدها تفتح للفريق (Team) لحظة اجتيازه التي قبلها.

**نموذج السباق في جملة**: أول فريق يحلّ مرحلة يفوز بصندوقها، لكن كل فريق آخر لا يزال عليه حلّ تلك المرحلة بنفسه ليتقدّم. خسارة الصندوق تكلّف الفريق الصندوق، لا تقدّمه.

## ٢ · كيف تبني واحداً

١. **Hunts ← + Create hunt** وسمِّه.
٢. **Stages ←** أضف مرحلة، واكتب **دليلها** — الجملة التي ترسل اللاعبين إلى المكان.
٣. أضف الأسئلة. ثلاثة أنواع: **اختيار من متعدد**، و**السحب على صورة**، و**المطابقة**.
٤. اضغط **👁** بجانب أي سؤال لتلعبه كما سيلعبه الطالب تماماً. إن بدا خطأ هناك فهو خطأ.
٥. تبويب **Boxes**: وجّه صندوقاً لكل مرحلة، أو اطبع الرموز بدلاً من ذلك (الفقرة ٤).
٦. **Go live.**

ويمكن أن يكون أكثر من تحدٍّ حيّاً في وقت واحد — صفٌّ على واحد وأنت تجرّب آخر. وصفحة الدخول تسأل اللاعبين أيّهما.

### ٢.١ · أو استورده جاهزاً

زر **⬆ Import hunt** في تبويب Hunts يستقبل ملف `.zip` فيه `hunt.json` ومجلّد `images`. وزر **⬆ Upload a stage** في تبويب Stages يضيف **مرحلة واحدة** للتحدي المختار أعلى الصفحة.

وهذه طريقة بناء تحدٍّ بالذكاء الاصطناعي: أعطِه مستند **Integration API** من تبويب Docs، وأجب عن أسئلته، فيعطيك الملف المضغوط.

واختيار الملف **لا يستورده**. يأتيك تقرير أولاً — عدد المراحل والأسئلة وأنواعها، وأي المراحل لها دليل، وكل خطأ في الملف — وزر الاستيراد لا يعمل إلا إذا كان الملف سليماً. والتحدي المستورد يصل **كمسودّة** كأي تحدٍّ آخر.

## ٣ · الساعة

| الإعداد | ماذا يفعل |
|---|---|
| **Start** | متى تفتح المرحلة الأولى. قبلها يستطيع اللاعبون التسجيل والانتظار لا اللعب. |
| **Duration** | كم يستمر التحدي كله من لحظة الانطلاق. و٠ تعني حتى توقفه أنت. |
| **Stage timer** | لكل محاولة، لا لكل فريق. |

والذهاب للبثّ المباشر **يعيد ختم وقت البدء**، وهذه أيضاً طريقة إعادة تشغيل تحدٍّ انتهت مدته.

واللوحة تحذّرك قبل البثّ إن كان التحدي سيفتح فوراً، أو كان منتهياً أصلاً.

## ٤ · الصناديق (Boxes)، أو الورق

الصندوق يعرض رمز QR ويفتح القفل. ولست مضطراً لواحد كي تلعب.

- **مع الصناديق**: تبويب Boxes، أو مفتاح 🔒 على بطاقة التحدي ليوجّه كل صندوق فارغ إليه. والصندوق الذي يستخدمه تحدٍّ آخر يُترك مكانه، والمفتاح يخبرك كم واحداً كان محجوزاً.
- **بدون صناديق**: زر **🖨 Print QR sheet** يعطيك ورقة A4 واحدة فيها رمز كل مرحلة، جاهزة للقصّ والإخفاء. والبطاقة المطبوعة والصندوق المشغّل **بديلان تامّان**.

**والرمز على كل بطاقة سرّ.** رابط المرحلة الأولى عامّ بالتصميم — انشره حيث شئت. أما كل مرحلة بعدها فتحمل رمزاً لا يوجد إلا على بطاقتها أو صندوقها، فلا يستطيع لاعب الوصول للمرحلة الثالثة بتعديل رابط.

## ٥ · أثناء التشغيل

**Live monitor** يعرض كل فريق: أين هو، وأي سؤال يحلّ، وأفضل نتيجة كعدد، وكم مضى عليه خاملاً، **وساعة آخر حركة له**.

- **stuck** = ثلاث محاولات فأكثر على نفس الصندوق. اذهب وكلّمهم.
- **pending pop** = فريق اجتاز مرحلة لكن الصندوق لم يؤكّد فتحه. بطارية فارغة، أو لا صندوق على تلك المرحلة.
- **👁 left ×n** = كم مرة خرج من التطبيق، إن كان حارس الشاشة (Focus guard) مشغّلاً. **معلومة لا دليل** — المكالمة وقفل الشاشة يبدوان متطابقين من هنا.
- **⤓ Export** يعطيك الجدول كله كملف جداول.

## ٦ · حارس الشاشة (Focus guard)

مفتاح 👁 على بطاقة التحدي. حين يُشغَّل، اللاعب الذي ينتقل لتطبيق آخر يأخذ تحذيراً واحداً، وفي الثانية تبدأ **مرحلته الحالية** من السؤال الأول.

وهو **مطفأ افتراضياً** لأنه قد يمسح عمل لاعب.

ما يُغلقه هو الطريق السهل: لقطة شاشة، سؤال ذكاء اصطناعي، ثم العودة. **لكنه لا يرى لقطة الشاشة، ولا يرى هاتفاً ثانياً موجّهاً نحو الشاشة.** لا شيء في المتصفح يرى ذلك. فاعتبره كلفةً تُفرض على الطريق الكسول، لا ضماناً.

وثلاثة أشياء تحميه من الأبرياء: الشاشة تبقى مستيقظة، والخروج أقل من ٣ ثوانٍ يُتجاهل، والمرة الأولى تحذير فقط.

## ٧ · حين يحدث خلل

| ما تراه | ماذا يعني |
|---|---|
| الصندوق يقول **PARKED** | لا مرحلة مُسنَدة. تبويب Boxes. |
| الصندوق يقول **WiFi NOT FOUND** | الـESP32 يعمل على ٢.٤ جيجا فقط. حوّل نقطة الاتصال إلى 2.4 GHz. |
| فريق عالق على «امسح الصندوق» | هو عند صندوق مرحلة أخرى، أو الرمز لم يُقرأ. أعطه الرمز المطبوع ليكتبه. |
| صندوق لا يُفتح أبداً | **Live monitor ← pending** ← علّمه مفتوحاً يدوياً. |
| فريق يجب تمريره | **Advance** من اللوحة. |

و**Reset all teams & progress** يمسح كل الفرق ويلغي كل الفائزين، ليُعاد تشغيل التحدي مع مجموعة جديدة. **ولا يمكن التراجع عنه.**

## ٨ · الورق

**📄 Paper exam** يصدّر أسئلة التحدي كمستند Word — اختيار من متعدد، وصح/خطأ، والمطابقة كبنك كلمات بفراغات. و**مفتاح الإجابات آخر صفحة**: احتفظ بها.

وأسئلة الصور والقرص تُعلَّم بأنها تفاعلية بدل أن تُحذف، فترى ما ينقص.

## ٩ · مساحة التخزين

تبويب Docs ← **🗄 Storage**. كل صورة رُفعت تبقى على السيرفر، حتى صور التحديات التي حذفتها.

زر **Check storage** يعدّها ويصنّفها في أربع مجموعات، وزر **Clean up** يحذف اليتيمة فقط — لا يمسّ أبداً صورةً يستعملها سؤال، ولا صورةً رُفعت خلال ٢٤ ساعة، لأن الصورة كثيراً ما تُرفع قبل دقائق من حفظ السؤال الذي يسمّيها.

وإن أبلغك عن صور **مُشار إليها لكنها مفقودة**، فهذا يعني سؤالاً حيّاً بصورة مكسورة. ذاك يُصلَح يدوياً؛ التنظيف لا يسبّبه ولا يُصلحه.

</div>