🕵️‍♂️ Create Your Own Hunt

Everything you need to build, host, and run your own custom QR Scavenger Hunt.

🆘 I need help!

If you read through the instructions on this page, you should have everything you need to build your own hunt.

However, if you are absolutely stuck, you can email: qrshunt@gmail.com.

Please note: This is a side project, so I might not be able to respond very quickly.

Visual Learner? Watch this video here

🚫 No login required. 🔒 No passwords to remember.

It’s just free* fun.

*If you have a great event and want to say thanks, you can buy me a coffee, but there is no pressure to do so.

☕ Support This Project

How It Works

This application is completely free to use. It works by loading a "Game Config" (a simple text file in JSON format) that tells the app what questions to ask, what teams are playing, and what the correct answers are.

You don't need to be a programmer! Use our builder tools below to generate the file.

Types of Hunts You Can Build

📍 Station Hunts (The Classic)

You create specific stations (locations). At each station, you place a QR code. The player must physically go to that location to scan the code to "answer" the question.

Advanced Mode: Place multiple QR codes at one location. Only one is the correct answer. (e.g., "Find the red book on the shelf and scan the code inside").

Penalty System: You can configure a "timeout" in the game settings. If a player scans the wrong code, they are locked out for a set amount of time (e.g., 30 seconds) before they can try again, preventing them from just rapidly scanning every code they find.

🏙️ Discovery Hunts (Existing QR Codes)

The QR codes already exist in the real world! Think of a "Town Tour" where players must find the QR code for a restaurant's menu, a museum exhibit, or a local business hours sign.

The question might be: "Find Joe's Pizza. Scan their menu QR code to continue." The app treats that existing QR code as the "Answer."

How to get the Answer text: You will need to go around and scan the existing codes to see what text they produce. You can use a free app to do this:

Download on App Store Get it on Google Play

🤝 Ice Breakers & People Hunts

Great for conferences or first days of school. Every participant wears a "Hello My Name Is" sticker with their name under the QR code.

Players must find specific people to "collect" them. (e.g., "Find someone who speaks 3 languages" or "Find the person whose name starts with Z").

Ideas for Groups

Step-by-Step Guide

  1. Build Your Game File

    Use the JSON Builder to create your questions, define your teams, and set your game rules. You must have at least one team defined. This tool will create a downloadable file for you.

    Open JSON Builder

  2. Host Your Game File

    The app needs to read your file from the internet.

    Upload JSON
    • Capture this link now. The file name/link is only shown ONCE after upload.
    • Files cannot be edited. Once uploaded, the file is locked.
    • Need changes? If you made a mistake or lost the link, you must update your local JSON file and upload it again to generate a new link.
    • Retention: We will keep your JSON file on our server for at least 60 days.
    ✨ Bonus: If you use our upload option, we can automatically generate all your Team Start Codes and Answer QR codes for you!

    Option 2: Host it yourself

    We understand you might not want to upload your information to our server, so we allow you to host your own JSON file. However, the file must be visible via the public internet (in raw JSON form). You cannot load it and run a Hunt from your personal computer or a private network.

    If you decide to host it yourself:

    • JsonHosting.com: Drag and drop your file. (Free files last 24 hours).
    • JsonBin.io: Good for permanent storage.
    • GitHub Gist: Create a public gist, click "Raw", use that URL.
    • Your own website: Just upload the .json file to your server.

  3. Generate Your QR Codes

    There are two types of QR codes you might need to make:

    • Start Codes: These tell the app which game to load and which team the player is on. (See examples below).
    • Answer Codes: These are the codes players scan to answer questions. The text inside these must match the "Answer" field in your JSON exactly.
    Team Start Code Example
    Start Code Example
    Trent QR Example
    Answer: "Trent"
    Piano QR Example
    Answer: "Piano"
    Open QR Generator

  4. Play & Track

    Players use the main site to play. You use the Game Master page to track team points (scroll down for instructions on how to use the game master page).

    Open Game Master

Understanding the Start Code

To start a game, players scan a "Start Code". This code tells the app: "This is the team, and this is where the game file lives."

Example 1: Using this site's uploader

If you used our uploader, your file link will look like json/abc123.json.

Short Version (Built-in Scanner Only):
If players are already on https://www.qrscavengerhunt.com/ and using the built-in "Scan Game Code" button, they only need the relative path:

team=ALPHA&config=json/abc123.json

Full Version (Any Camera):
If you want players to scan a code with their regular phone camera (which opens the site and launches the game), use the full URL:

https://www.qrscavengerhunt.com/?team=ALPHA&config=json/abc123.json

Example 2: Using external hosting

If you are hosting the file yourself (GitHub, etc.), use the full https link:

team=ALPHA&config=https://mysite.com/game.json

Using the Game Master Interface

If you have multiple teams, use this page to track points. When a team finishes the hunt, they show you their "Success Screen". You scan the code on that screen to give their team a point.

Equipment Needed:

Admin & Security Controls

By default, the management buttons are hidden to prevent accidental resets during a game.

  • Reveal Admin Buttons: Click the title "Game Master" at the top of the page 5 times quickly, or press Ctrl + Alt + M on your keyboard.
  • Manage Allowed Teams: Once revealed, click "Manage Allowed Teams" to enter team names (one per line). This prevents cheating by rejecting scans from unknown teams.
  • Reset Counts: Click "Reset Counts" to clear the leaderboard. You will need to enter the PIN. The PIN is 5150.

☕ Support This Project

This tool is completely free to use. I built it because I love seeing people have fun and learn together.

I know teachers often spend their own money on classroom resources, and I want this to be one less thing you have to worry about paying for. Please enjoy it with your students or group absolutely free.

However, if you found this useful, had a great event, and have a little extra to spare, a coffee is always appreciated!


Buy Me a Coffee at ko-fi.com

↑ Return to Top

Why I Built This

It all started because a high school buddy of mine asked if I could make a simple scavenger hunt game and it spiraled out of control. I love solving problems and sometimes I go a little overboard. So it went from just something that I was going to put on my personal website to spending 4 full days coming up with this.

I have had a blast making it (even though sometimes I wanted to pull my hair out). I hope you find it fun and useful!

If you want to share how you have used it you can email me here: qrshunt@gmail.com.

Thanks Adam for the idea and push! :-)