Skip to content

Headless Host

Mario Carbajal edited this page Nov 23, 2018 · 28 revisions

HaxBall Headless Host

The headless room host is useful if you want to run an unmanned haxball host on a vps. It doesn't draw or play any sounds which makes it a lot more lightweight. It is only controllable through a javascript API.

You can load the headless host here

API

When haxball headless host is done loading it will set window.HBInit and call the function window.onHBLoaded

Note: All of the API functions that modify the game's state will execute asynchronously. This means that if you move a player using the roomObject.setPlayerTeam method and immediately after you call roomObject.getPlayerList, the player list obtained will show the player's original team and not the modified one.

HBInit(roomConfig : RoomConfigObject) : RoomObject

Use this function to initialize the room, it returns the room object used to control the room.

After calling this function a recaptcha challenge will appear, after passing the recaptcha the room link will appear on the page.

Example:

var room = HBInit({ roomName: "My room", maxPlayers: 16 });
room.setDefaultStadium("Big");
room.setScoreLimit(5);
room.setTimeLimit(0);

// If there are no admins left in the room give admin to one of the remaining players.
function updateAdmins() { 
  // Get all players except the host (id = 0 is always the host)
  var players = room.getPlayerList().filter((player) => player.id != 0 );
  if ( players.length == 0 ) return; // No players left, do nothing.
  if ( players.find((player) => player.admin) != null ) return; // There's an admin left so do nothing.
  room.setPlayerAdmin(players[0].id, true); // Give admin to the first non admin player in the list
}

room.onPlayerJoin = function(player) {
  updateAdmins();
}

room.onPlayerLeave = function(player) {
  updateAdmins();
}

RoomConfigObject

RoomConfig is passed to HBInit to configure the room, all values are optional.

roomName : string

The name for the room.

playerName : string

The name for the host player.

password : string

The password for the room (no password if ommited).

maxPlayers : int

Max number of players the room accepts.

public : bool

If true the room will appear in the room list.

geo : {"code": string, "lat" : float, "lon" : float}

GeoLocation override for the room.

token : String

Can be used to skip the recaptcha by setting it to a token that can be obtained here

These tokens will expire after a few minutes.

RoomObject

RoomObject is the main interface which lets you control the room and listen to it's events

sendChat(message : string, targetId? : Int) : void

Sends a chat message using the host player

If targetId is null or undefined the message is sent to all players. If targetId is defined the message is sent only to the player with a matching id.

setPlayerAdmin(playerID : int, admin : bool) : void

Changes the admin status of the specified player

setPlayerTeam(playerID : int, team : int) : void

Moves the specified player to a team

kickPlayer(playerID : int, reason : string, ban : bool) : void

Kicks the specified player from the room

clearBan(playerId : int) : void

Clears the ban for a playerId that belonged to a player that was previously banned.

clearBans() : void

Clears the list of banned players.

setScoreLimit(limit : int) : void

Sets the score limit of the room

If a game is in progress this method does nothing.

setTimeLimit(limitInMinutes : int) : void

Sets the time limit of the room. The limit must be specified in number of minutes.

If a game is in progress this method does nothing.

setCustomStadium(stadiumFileContents : string) : void

Parses the stadiumFileContents as a .hbs stadium file and sets it as the selected stadium.

There must not be a game in progress, If a game is in progress this method does nothing

See example here.

setDefaultStadium(stadiumName : string) : void

Sets the selected stadium to one of the default stadiums. The name must match exactly (case sensitive)

There must not be a game in progress, If a game is in progress this method does nothing

setTeamsLock(locked : bool) : void

Sets the teams lock. When teams are locked players are not able to change team unless they are moved by an admin.

setTeamColors(team : TeamID, angle : float, textColor : int, colors : []int) : void

Sets the colors of a team.

Colors are represented as an integer, for example a pure red color is 0xFF0000.

startGame() : void

Starts the game, if a game is already in progress this method does nothing

stopGame() : void

Stops the game, if no game is in progress this method does nothing

pauseGame(pauseState : bool)

Sets the pause state of the game. true = paused and false = unpaused

getPlayer(playerId : Int) : PlayerObject

Returns the player with the specified id. Returns null if the player doesn't exist.

getPlayerList() : PlayerObject[]

Returns the current list of players

getScores() : ScoresObject

If a game is in progress it returns the current score information. Otherwise it returns null

getBallPosition() : {"x": float, "y": float}

Returns the ball's position in the field or null if no game is in progress.

startRecording() : void

Starts recording of a haxball replay.

Don't forget to call stop recording or it will cause a memory leak.

stopRecording() : Uint8Array

Stops the recording previously started with startRecording and returns the replay file contents as a Uint8Array.

Returns null if recording was not started or had already been stopped.

setPassword(pass : string) : void

Changes the password of the room, if pass is null the password will be cleared.

onPlayerJoin(player : PlayerObject) : void

Event called when a new player joins the room.

onPlayerLeave(player : PlayerObject) : void

Event called when a player leaves the room.

onTeamVictory(scores : ScoresObject) : void

Event called when a team wins.

onPlayerChat(player : PlayerObject, message : String) : bool

Event called when a player sends a chat message.

The event function can return false in order to filter the chat message. This prevents the chat message from reaching other players in the room.

onPlayerBallKick(player : PlayerObject) : void

Event called when a player kicks the ball.

onTeamGoal(team : TeamID) : void

Event called when a team scores a goal.

onGameStart(byPlayer : PlayerObject) : void

Event called when a game starts.

byPlayer is the player which caused the event (can be null if the event wasn't caused by a player).

onGameStop(byPlayer : PlayerObject) : void

Event called when a game stops.

byPlayer is the player which caused the event (can be null if the event wasn't caused by a player).

onPlayerAdminChange(changedPlayer : PlayerObject, byPlayer : PlayerObject) : void

Event called when a player's admin rights are changed.

byPlayer is the player which caused the event (can be null if the event wasn't caused by a player).

onPlayerTeamChange(changedPlayer : PlayerObject, byPlayer : PlayerObject) : void

Event called when a player team is changed.

byPlayer is the player which caused the event (can be null if the event wasn't caused by a player).

onPlayerKicked(kickedPlayer : PlayerObject, reason : string, ban : bool, byPlayer : PlayerObject) : void

Event called when a player has been kicked from the room. This is always called after the onPlayerLeave event.

byPlayer is the player which caused the event (can be null if the event wasn't caused by a player).

onGameTick() : void

Event called once for every game tick (happens 60 times per second). This is useful if you want to monitor the player and ball positions without missing any ticks.

This event is not called if the game is paused or stopped.

onGamePause(byPlayer : PlayerObject) : void

Event called when the game is paused.

onGameUnpause(byPlayer : PlayerObject) : void

Event called when the game is unpaused.

After this event there's a timer before the game is fully unpaused, to detect when the game has really resumed you can listen for the first onGameTick event after this event is called.

onPositionsReset() : void

Event called when the players and ball positions are reset after a goal happens.

onPlayerActivity(player : PlayerObject) : void

Event called when a player gives signs of activity, such as pressing a key. This is useful for detecting inactive players.

onStadiumChange(newStadiumName : string, byPlayer : PlayerObject ) : void

Event called when the stadium is changed.

onRoomLink(url : string) : void

Event called when the room link is obtained.

PlayerObject

PlayerObject holds information about a player

id : int

The id of the player, each player that joins the room gets a unique id that will never change.

name : string

The name of the player.

team : TeamID

The team of the player.

admin : bool

Whether the player has admin rights.

position : {"x": float, "y": float}

The player's position in the field, if the player is not in the field the value will be null.

auth : String

The player's public ID.

Can be null if the ID validation fails.

This property is only set in the RoomObject.onPlayerJoin event.

conn : String

A string that uniquely identifies the player's connection, if two players join using the same network this string will be equal.

This property is only set in the RoomObject.onPlayerJoin event.

ScoresObject

ScoresObject holds information relevant to the current game scores

red : int

The number of goals scored by the red team

blue : int

The number of goals scored by the blue team

time : float

The number of seconds elapsed (seconds don't advance while the game is paused)

scoreLimit : int

The score limit for the game.

timeLimit : float

The time limit for the game.

TeamID

TeamID are int values:

Spectators: 0
Red Team: 1
Blue Team: 2
You can’t perform that action at this time.