The Haxball headless host

Most Haxball rooms you have played in were opened by the headless host: an official page Haxball provides that runs a room with no graphics, no sound and — normally — no player. It is the foundation of essentially every serious Haxball setup, from league rooms to the bot that benches AFK players in your local pub.

This guide covers what it gives you. If you are earlier in the process and just want a room that stays up, start with how to host a Haxball room.

Why "headless" matters

A normal Haxball client spends most of its effort drawing: the pitch, the discs, the score, the chat. A host does not need any of that. It needs to simulate physics and relay state.

Stripping the rendering out has three effects that all point the same direction:

• It is far lighter. A machine can host rooms it could never play in, which is what makes running rooms around the clock economical.
• It needs no human. Nobody has to keep a tab open and stay awake.
• It is programmable. Because the room is exposed as a JavaScript object, you can write logic against it — and that is where Haxball's whole bot ecosystem came from.

HBInit and the room configuration

A headless room starts with a single call. You hand it a configuration object and it hands you back a room object:

var room = HBInit({
  roomName: "My League — Match Room",
  maxPlayers: 16,
  public: true,
  noPlayer: true,
  token: "thr1.AAAAA…"
});

The fields that actually change behaviour:

What the room object gives you

The room object is the whole API surface. Broadly it does four things.

It tells you what happened

You attach handlers for the events you care about — players joining and leaving, chat messages, goals, kick-offs, team and admin changes, the game starting, stopping or pausing, the stadium changing, and the room link being issued. A bot is, mechanically, a pile of these handlers:

room.onPlayerJoin = function (player) {
  room.sendAnnouncement("Welcome, " + player.name, player.id);
};

room.onTeamGoal = function (team) {
  var s = room.getScores();
  room.sendChat("GOAL — " + s.red + " : " + s.blue);
};

It lets you moderate

Send chat and targeted announcements, grant or revoke admin, move players between teams, kick and ban, clear bans, set a password, and rate-limit kicks. Everything a human admin can do from inside the room, a script can do from outside it.

It lets you run the match

Start, stop and pause the game, set score and time limits, lock teams, load a default or a fully custom stadium, and set team colours. This is how league rooms enforce their own format rather than relying on whoever has admin.

It lets you read the world

The player list, scores, the ball position, and disc properties for the ball and for each player. Reading disc positions on a tick is how possession stats, heatmaps and touch counts get built. It is also the expensive one — see room scripts and bots for what to do and what not to do inside a per-tick handler.

Tokens, and why rooms quietly die

A headless room cannot open without a token, which you get by solving a captcha on Haxball's headless token page. The token authorises the open.

The crucial detail: a token is not a permanent key. It has a life, and when a room needs to reopen — after a crash, a restart, a network blip — it needs a valid token at that moment. A captcha is a human, and humans are asleep at 3 am. That is the mechanical reason most self-managed "24/7" rooms are actually "24/7 until something restarts".

The flag in the room list is a label, not a location

Public rooms show a country next to them. It is natural to read that as "the server is in this country". It is not.

That flag comes from the geo values in the room configuration, and the host sets those itself. There is no verification step. A room can advertise one country while running on hardware on another continent — sometimes carelessly, sometimes deliberately, because a familiar flag attracts joins.

We will say the uncomfortable part out loud: we set that flag on our own rooms too. Everyone who hosts does. It is a display field, and no host — us included — should be trusted on it.

What the headless host will not do for you

It runs a room. It does not run your service. Specifically, it does not:

• Keep itself alive. If the process dies, the room is gone. Something outside it has to notice and restart it.
• Keep your room link stable. A fresh room means a fresh join link. If your community relies on a permanent URL, that has to be solved a layer above the room.
• Persist anything. Bans, stats, warnings and match history live only in your script's memory unless you write them somewhere durable. A restart is amnesia.
• Choose a good location. It hosts wherever it is run. Latency is your decision, not the engine's.

Those four gaps are, more or less, the entire job of a Haxball hosting service — including ours.

Where to go next

• Room scripts and bots — building on the room object without wrecking your tick budget.
• Why Haxball lags — what latency does to the physics you are hosting.
• Public vs private rooms — the public flag, and the slot cap behind it.