Raid Finder

Raid Finder

The Raid Finder is hailsDotGO's real-time raid coordination system, available at /raidfinder. Instead of a bulletin board, it runs per-boss matchmaking queues that feed host lobbies with server-enforced timers: you pick a boss, wait in line, get matched, confirm, swap friend codes, raid, and leave feedback. Behavior in the system feeds the Trust and Awards engine and a raid XP rank ladder.

What you need

• A logged-in account (see Accounts and Roles).
• A trainer name and 12-digit trainer code set in Settings. The whole point is exchanging friend codes, so both are required before you can host or queue.
• Not being raid-banned. A ban blocks hosting and joining and immediately pulls you out of any live queue or lobby.
• Keep the page open while queued: your poll doubles as a heartbeat, and a queue entry that has not been seen for 45 seconds is silently dropped.

A raid, step by step

1. Hosts create a lobby for a current raid boss, choosing the party size (1 to 20), an optional note (up to 160 characters), and whether the boss is weather boosted. A lobby lives for at most 10 minutes.
2. Players join the queue for a boss from the open lobbies list. The matcher fills the oldest open lobby first: priority pass holders jump ahead, and within the same class it is first come, first served.
3. Matched players get a 2-minute confirm window to send the host a friend request in game and press confirm. The lobby view shows the host's trainer name and code to every matched member; the host sees a member's details only after that member confirms.
4. When every slot is confirmed the lobby goes full and the host gets a 4-minute invite window to send the in-game raid invites and press "invited", which moves the lobby to raiding.
5. After the raid the host files an attendance report: who actually showed up and whether anyone left early. This closes the lobby (reported) and pays out XP.
6. Attended members owe feedback within 24 hours: was the raid successful, and a commend or dislike for the host. Feedback is once per lobby and feeds the trust engine.

Lobby lifecycle and timers

Lobby states: open, full, raiding, reported, cancelled, expired. Member states: matched, confirmed, timed_out, left, removed, requeued.

Timer	Value	On expiry
Lobby TTL	10 minutes	Lobby expires; non-host members are dropped without penalty. The host logs a host_unfulfilled event: free up to 6 per rolling 4 hours, a minor trust penalty past that (see Trust and Awards)
Confirm window	2 minutes	The member is removed (not requeued) and a confirm timeout is logged; the first two timeouts in any rolling 24 hours are free, after that they cost trust
Invite window	4 minutes	The lobby expires, confirmed members go back to the front of the queue with no penalty, and the host takes a small trust reduction
Queue heartbeat	45 seconds	Closing the tab quietly removes you from the queue
Sweeper	every 15 seconds	A background goroutine enforces all of the above even when nobody is polling; state reads also lazily expire anything relevant to the caller so countdowns are exact

Other mechanics:

• Requeue keeps your seniority. When a lobby is cancelled or its invite window lapses, members re-enter the queue with their original matched time as their enqueue time, placing them ahead of everyone who queued after they were first matched.
• Hosts can kick members. From an open or full lobby, a host can kick any matched or confirmed member. Staff can also kick any member from any lobby. A kicked member's slot opens back up immediately and matching resumes.
• Slots reopen. If a confirmed member leaves or is kicked from a full lobby, the lobby reverts to open, the invite timer clears, and matching resumes.
• Hosts are accountable for unstarted lobbies. Cancelling your own lobby before the raid starts counts toward the same host_unfulfilled tally as a TTL expiry. Staff cancellations and cancels of an already-raiding lobby do not count.
• Leave churn cooldown: 4 or more lobby leaves within an hour triggers a 10-minute cooldown on joining queues.
• Hosting supersedes queueing (creating a lobby removes your queue slot), and you can only be in one queue or lobby at a time.

Queue rules and perks

• You can normally only queue for a current raid boss that already has an open lobby. The open lobbies list is where queueing starts.
• Pre-queueing (waiting on a boss with no open lobby yet) is reserved for staff. The code also supports a Super Donator store benefit for this perk, but no Super Donator item is currently seeded in the catalog (see Store).
• Queue priority: active Priority Pass holders are matched before regular queuers.
• Custom lobbies can name any boss, not just the current rotation, and appear in their own list on the overview. Creating one requires staff, an admin-granted special rank (Trusted or Content Creator), or effective trust at or above the configurable threshold (default 50). Anyone can queue for a custom boss while an open custom lobby for it exists.

Raid XP and ranks

Completed raids pay XP: 15 per completed raid as a member, 20 as the host (paid when at least one member attended), and 5 to the host per commend received. XP drives a 30-step rank ladder displayed beside your name, from Youngster I at 0 XP through Trainer, Gym Leader, Elite Four, and Champion up to League Master V at 200,000 XP. Staff display fixed titles instead: PKMN Scientist (testers), PKMN Researcher (moderators), and PKMN PROF (admins and the superadmin). Admins can set a user's XP directly (see Admin Guide).

Frontend polling

The page (ts/raidfinder.ts) polls GET /api/raid/state every 4 seconds while you are queued or in a lobby (this is also the heartbeat), and the public GET /api/raid/overview every 30 seconds when you are just browsing. Countdown displays tick locally between polls. Endpoint details are in the API Reference.

For developers

Set RAID_FAST_TIMERS=1 to shrink the timers for local testing: the confirm window drops to 15 seconds, the invite window to 30 seconds, and the sweeper to every 3 seconds. See Building and Development for the rest of the dev setup, and the Admin Guide for lobby moderation tools.