Joining a Hunt
How players join a team with a name and team code, what the validation errors mean, and how rejoining and session expiry work.
Players join without creating an account. All they need is a name and their team's 6-character code.
The join screen
When the app opens without an existing session, players land on the join screen: "Welcome to the Adventure!" with the subtext "Enter your details below to join your team and start the hunt".
Enter your name
The "Your Name" field (placeholder "Enter your name") is the player's display name for the event. It's shown in team chat and the team members list. There is no avatar picker — the team's icon or photo is the visual identity, and it can be changed later in Settings → Team Members.
Enter the team code
The "Team Code" field (placeholder "Enter 6-digit code", hint "Ask your team leader for the code") takes the team's 6-character join code. Despite the placeholder wording, codes contain letters and numbers — they're generated from an alphabet that excludes easily-confused characters (I, O, 0, 1). Case doesn't matter; the field displays whatever is typed in lowercase.
Or scan the QR code
Instead of typing, players can tap "Scan team QR code", which opens a scanner titled "Scan Team Code" with the hint "Point your camera at the team QR code on your event packet." The QR simply encodes the join code.
Join
Tap "Join the Hunt". A spinner shows while the join is in flight. The footer links to the Terms of Service and Privacy Policy.
TODO: screenshot
The join screen showing the "Welcome to the Adventure!" header, the Your Name and Team Code fields, the "Scan team QR code" button, and the "Join the Hunt" button.
Validation and errors
Errors appear inline in a red box above the button:
| Situation | Message |
|---|---|
| Name left empty | "Please enter your name" |
| Code left empty | "Please enter your team code" |
| Code doesn't match any team | "Invalid team code" |
| Event isn't joinable yet | e.g. "Event has not started" |
| Technical/server failure | "Something went wrong on our end — give it another try in a moment. If it keeps happening, ask your event host." |
Joining is only possible while the event is scheduled or active, and before the event's end time. The first player to join a team becomes the team captain (leader).
Rejoining — same device, same player
The join is tied to the device. If a player rejoins with the same team code from the same device, they re-attach to their existing team member — no duplicate member is created, and their progress is untouched. If they typed a different name, the display name is updated.
Session persistence and expiry
- Persistence: after a successful join, the session is saved on the device. On the next app launch a brief "Loading session..." screen appears and the player lands directly in the app — no re-entering the code.
- Expiry: the session token stays valid until the event's end time plus 24 hours (with a minimum lifetime of 1 hour), so teams can still view results after the hunt ends. If the event has no end time set when the player joins, the session defaults to 24 hours from join.
- When it expires: the next time the app talks to the server, the expired session is cleared and the player is returned to the join screen. Rejoining with the same team code on the same device restores their spot.
Leaving vs. rejoining
Leave Hunt (in Settings) removes the session from the device only. Team progress, points, and completions live on the server, so leaving loses nothing — rejoining with the same team code brings the player right back. The confirmation says exactly that: "Your progress will be saved, but you'll need to rejoin with your team code."