Skip to content
PeekSeekPeekSeek Docs

PeekSeek

PeekSeek is an open-source matchmaking and esports platform. It runs peekseek.net for Unturned, and everything that makes it work is in one repository.

These docs are for three kinds of people:

  • You want to run your own instance. Start at Getting Started.
  • You want to understand how it works before trusting it. Start at Architecture.
  • You want it for a different game. Start at Forking. The part of the system that talks to game servers was built to not care what game it is.

What it does

Section titled “What it does”
Matchmaking Players queue, servers pull. Teams are balanced on Elo with a configurable gap, and a rematch cooldown stops the same two people meeting twice in a row.
Match hosting A pool of game servers claims matches, runs them, and reports results back. Servers that go quiet are noticed.
Lobbies A persistent arena players wait in, which queues them without leaving the game.
Ranking Elo per player, adjusted from reported match results.
Parties Queue together, stay together.
Events Tournament pairings and signups on top of the same match machinery.
Discord A live player counter, queue logging, and a ping when a dead arena wakes up.

The pieces

Section titled “The pieces”

One repository, because the site and the plugins are two halves of one contract and a change to both belongs in one commit.

The repository README lists every component, what it is, and whether it is maintained. That table lives there and only there, this page used to carry a copy of it, which said “four deployables”, listed five, and had never heard of two of the gamemodes.

What is worth knowing from here is the shape rather than the inventory:

  • The website is the backend. It holds the queue, the matches, the ratings and the moderation state, and it is the only thing with a database.
  • The plugins are clients of it. Each one polls /server/v1/* and does what it is told; none of them talks to another, and none of them has state worth keeping.
  • Gamemodes plug into one plugin. ARENA and RAID are gamemodes for PeekSeek Match, loaded beside it, not servers of their own.
  • The Discord bot imports the site’s own code rather than calling it over HTTP, so a ban issued in Discord and a ban issued on the dashboard are the same function.

The RocketMod plugins are the only Unturned-specific code in the system. The website never imports anything that knows what Unturned is, which is the thing that makes forking it for another game possible at all.

The one idea worth reading first

Section titled “The one idea worth reading first”

A match cannot exist without a game server holding it.

Matchmaking does not run when a player queues. Queueing only puts you in the queue. When a server reports itself free, that server’s own poll scans the queue, forms the best match it can, and takes it, all before answering the request.

So a matchmade match is created already assigned to the server that will host it. There is no scheduler, no broker, and no window where a match exists with nowhere to play it. The match lifecycle walks through what that means in practice.

Licence

Section titled “Licence”

MIT, per LICENSE. Fork it, run it, sell it. Attribution is welcome and not required. No exceptions, no directory under other terms.

NOTICE lists the third-party fonts and the build-time assemblies, which keep their own licences as third-party material always does.

Section titled “Quick links”