Default Event Callbacks

There are 6 types of event callbacks in this API.

1. Host-Only Events

These events can only be received by a host room.

1.1. RoomLink(link: string)

The room link was received from Haxball's backend server. Called some time after a room is created successfully. Also called when your room stops sending signal to Haxball's backend server, and starts it again after some time. This can happen if your connection gets interrupted or the room somehow becomes unstable due to bugs.

Parameters:

• link: string

  The room link that was just received.

1.2. BansClear()

All bans have been cleared.

1.3. RoomRecaptchaModeChange(on: boolean)

The room's recaptcha mode was changed.

Parameters:

• on: boolean

  The new value; whether to request recaptcha or not while joining the room.

2. Host-Triggered Events

These events can only be triggered by the room's host.

2.1. Announcement(msg: string, color: int, style: int, sound: int)

An announcement was just made by the room host.

Parameters:

• msg: string

  The announcement message.

• color: int

  The color of the announcement message. Range: -1 <= color < 16777216.

  • The color value can be converted into a rgba string via API's Utils.numberToColor function.
  • The special value -1 means transparent color.

• style: int

  The style of the announcement message. Must be one of the following:

  • 0: use document's default font style.
  • 1: fontWeight = "bold".
  • 2: fontStyle = "italic".
  • 3: fontSize = "12px".
  • 4: fontWeight = "bold", fontSize = "12px".
  • 5: fontWeight = "italic", fontSize = "12px".

• sound: int

  The sound of the announcement message. Must be one of the following:

  • 0: no sound.
  • 1: chat sound.
  • 2: highlight sound.

2.2. PlayerHeadlessAvatarChange(id: int, value: string)

A player has just changed his/her headless avatar.

Parameters:

• id: int

  Id of the player who triggered this event.

• value: string

  The new headless avatar value.

2.3. PlayersOrderChange(idList: Array<int>, moveToTop: boolean)

The order of players have just been changed.

Parameters:

• idList: Array<int>

The ids of players that were removed from the room's players list, reordered to match the order in idList and added back to the room's players list.

• moveToTop: boolean

Whether to add the players to the top or bottom of the room's players list.

2.4. SetDiscProperties(id: int, type: int, data1: Array<number>, data2: Array<int>)

A disc's properties have just been modified.

Parameters:

• id: int

  The id of player or disc whose disc properties have changed.

• type: int

  The type of object. Must be one of the following:

  • 0: disc.
  • 1: player.

• data1: Array<number> Must consist of the following properties of the disc in the same order: [x, y, xspeed, yspeed, xgravity, ygravity, radius, bCoeff, invMass, damping].

• data2: Array<int> Must consist of the following properties of the disc in the same order: [color, cMask, cGroup].

2.5. PingData(array: Array<int>)

Ping values for all players have just been updated.

Parameters:

• array: Array<int>

  The updated list of ping values for each player in the same order as the player list in the current room's RoomState object.

2.6. RoomPropertiesChange(props: object)

The room's properties have just been changed.

Parameters:

• props: object

  The properties that were changed. The current structure of this object is as follows:

  props = {
    name: string | null,
    password: string | null,
    fakePassword: boolean | null,
    geo: GeoLocation | null,
    playerCount: int | null,
    maxPlayerCount: int | null
  }

  Note that only the changed keys will show up in props.

3. Individually-Triggered Events

3.1. Game Events

3.1.1. PlayerBallKick(playerId: int)

The ball has just been kicked.

Parameters:

• playerId: int

  Id of the player who kicked the ball.

3.1.2. TeamGoal(teamId: int)

A goal has just been scored.

Parameters:

• teamId: int

  Id of the team who scored the goal.

3.1.3. GameEnd(winningTeamId: int)

The game has just ended.

Parameters:

• winningTeamId: int

  Id of the team who won the game.

3.1.4. GameTick()

A game tick has just occurred.

Note:

This will run a lot of times per second. Be careful not to make too many calculations here, otherwise the game might slow down.

3.1.5. KickOff()

The game has just kicked-off.

3.1.6. TimeIsUp()

The game has just ended by timeout.

3.1.7. PositionsReset()

The positions have just been reset. This event happens just after a new game has been started or a goal has been scored. The player positions are reset to their corresponding spawn points defined in the current room's Stadium object.

3.1.8. LocalFrame(localFrameNo: int)

A new game frame number has just occurred. This is just like a game tick, but with a reference frame no value. In the future, this event might be merged with the GameTick event.

Parameters:

• localFrameNo: int

  An independent and always increasing frame number value.

3.1.9. CollisionDiscVsDisc(discId1: int, discPlayerId1: int, discId2: int, discPlayerId2: int)

A collision has just happened between two discs.

Parameters:

• discId1: int

  Id of the first collided disc.

• playerId1: int

  The player's id that the first disc belongs to. If the disc is not a player's disc, this value will be null.

• discId2: int

  Id of the second collided disc.

• playerId2: int

  The player's id that the second disc belongs to. If the disc is not a player's disc, this value will be null.

3.1.10. CollisionDiscVsSegment(discId: int, discPlayerId: int, segmentId: int)

A collision has just happened between a disc and a segment.

Parameters:

• discId: int

  Id of the collided disc.

• discPlayerId: int

  The player's id that the disc belongs to. If the disc is not a player's disc, this value will be null.

• segmentId: int

  Id of the collided segment.

3.1.11. CollisionDiscVsPlane(discId: int, discPlayerId: int, planeId: int)

A collision has just happened between a disc and a plane.

Parameters:

• discId: int

  Id of the collided disc.

• discPlayerId: int

  The player's id that the disc belongs to. If the disc is not a player's disc, this value will be null.

• planeId: int

  Id of the collided plane.

3.2. Local Events

3.2.1. ExtrapolationChange(value: int)

The local extrapolation value has just been changed.

Parameters:

• value: int

  The new extrapolation value in milliseconds. Range: -200 <= value <= 200.

3.2.2. HandicapChange(value: int)

The local ping handicap value has just been changed.

Parameters:

• value: int

  The new ping handicap value in milliseconds. Range: 0 <= value <= 300.

3.2.3. RoomRecordingChange(value: true | ArrayBuffer)

Room recording has just been started or stopped.

Parameters:

• value: true | ArrayBuffer

  • If value is true, recording has just been started,
  • Else, the recording has just stopped and the recorded data is returned in value as an ArrayBuffer. You might want to write the contents to a version-3 replay file.

3.3. API Events

3.3.1. PluginActiveChange(plugin: Plugin)

A plugin has just been activated or deactivated.

Parameters:

• plugin: Plugin

  The plugin which was activated or deactivated. This property stores the current activation status of the plugin: plugin.active.

3.3.2. ConfigUpdate(oldRoomConfigObj: RoomConfig, newRoomConfigObj: RoomConfig)

The room's config object has just been replaced by a new one.

Parameters:

• oldRoomConfigObj: RoomConfig

  The old RoomConfig object.

• newRoomConfigObj: RoomConfig

  The new RoomConfig object.

3.3.3. RendererUpdate(oldRendererObj: Renderer, newRendererObj: Renderer)

The room's renderer object has just been replaced by a new one.

Parameters:

• oldRendererObj: Renderer

  The old Renderer object.

• newRendererObj: Renderer

  The new Renderer object.

3.3.4. PluginUpdate(oldPluginObj: Plugin, newPluginObj: Plugin)

An old plugin object has just been replaced by a new one.

Parameters:

• oldPluginObj: Plugin

  The old Plugin object.

• newPluginObj: Plugin

  The new Plugin object.

3.3.5. LanguageChange(abbr: string)

API's language has just been changed.

Parameters:

• abbr: string

  The new language's abbreviation value.

4. Common Events

4.1. PlayerSyncChange(playerId: int, value: boolean)

A player's synchronization status has just changed.

Parameters:

• playerId: int

  Id of the player whose synchronization status has changed.

• value: boolean

  The new synchronization status.

4.2. AutoTeams(playerId1: int, teamId1: int, playerId2: int | null, teamId2: int | null, byId: int)

An "auto" event has just been triggered to automatically move at least one, at most two players from spectators to teams.

Parameters:

• playerId1: int

  Id of the first player affected by this event.

• teamId1: int

  Id of the team which the first player was moved into.

• playerId2: int | null

  Id of the second player affected by this event, or null if there was only one spectator when this event was triggered.

• teamId2: int | null

  Id of the team which the second player was moved into, or null if there was only one spectator when this event was triggered.

• byId: int

  Id of the player who has triggered the event.

4.3. ScoreLimitChange(value: int, byId: int)

The score limit has just been changed.

Parameters:

• value: int

  The new score limit value.

• byId: int

  Id of the player who has triggered this event.

4.4. TimeLimitChange(value: int, byId: int)

The time limit has just been changed.

Parameters:

• value: int

  The new time limit value.

• byId: int

  Id of the player who has triggered this event.

4.5. PlayerAdminChange(id: int, isAdmin: boolean, byId: int)

A player's admin rights have just been given/taken.

Parameters:

• id: int

  Id of the player whose admin rights have been given/taken.

• isAdmin: boolean

  The new admin rights status of the player whose id is id.

• byId: int

  Id of the player who has triggered this event.

4.6. PlayerAvatarChange(id: int, value: string)

A player has just changed his/her avatar.

Parameters:

• id: int

  Id of the player who has changed his/her avatar.

• value: string

  The new avatar value.

4.7. PlayerTeamChange(id: int, teamId: int, byId: int)

A player has been moved to a different team.

Parameters:

• id: int

  Id of the player who has been moved to a different team.

• teamId: int

  Id of the player's new team.

• byId: int

  Id of the player who has triggered this event.

4.8. StadiumChange(stadium: Stadium, byId: int)

The room's current stadium has just been changed.

Parameters:

• stadium: Stadium

  The room's new Stadium object.

• byId: int

  Id of the player who has triggered this event.

4.9. TeamsLockChange(value: boolean, byId: int)

The current room's teams have just been locked/unlocked.

Parameters:

• value: boolean

  The room's new teams lock value.

• byId: int

  Id of the player who has triggered this event.

4.10. PlayerObjectCreated(playerObj: Player)

A player object has just been created. This callback can be used to define custom

Parameters:

• playerObj: Player

  The new Player object that has just been created.

4.11. PlayerJoin(playerObj: Player)

A player has just joined the room.

Parameters:

• playerObj: Player

  The Player object that has just been created.

4.12. GamePauseChange(isPaused: boolean, byId: int)

The game has just been paused or resumed.

Parameters:

• isPaused: boolean

  Whether the game has been paused or not.

• byId: int

  Id of the player who has triggered this event.

4.13. PlayerChat(id: int, message: string)

A chat message has been received.

Parameters:

• id: int

  Id of the player who has sent the chat message.

• message: string

  The chat message.

4.14. PlayerInputChange(id: int, value: int)

A player's input has just been changed.

Parameters:

• id: int

  Id of the player whose input has been changed.

• value: int

  The new input value of the player.

4.15. PlayerChatIndicatorChange(id: int, value: boolean)

A player has just activated or deactivated his/her chat indicator.

Parameters:

• id: int

  Id of the player whose chat indicator has been activated/deactivated.

• value: boolean

  Whether the chat indicator has been activated or not.

4.16. PlayerLeave(playerObj: Player, reason: string | null, isBanned: boolean, byId: int)

A player has just left the room.

Parameters:

• playerObj: Player

  The player who has left the room.

• reason: string | null

  The reason of leaving the room. If null, the player has left by himself/herself.

• isBanned: boolean

  Whether the player has been banned or not. If reason is null, this value is ignored.

• byId: int

  Id of the player who has kicked/banned the player. If reason is null, this value is ignored.

4.17. TeamColorsChange(teamId: int, value: TeamColors, byId: int)

A player has just left the room.

Parameters:

• teamId: int

  The team whose colors have been changed.

• value: TeamColors

  The new team colors value.

• byId: int

  Id of the player who has changed the team colors.

4.18. KickRateLimitChange(min: int, rate: int, burst: int, byId: int)

The room's kick rate limit has just been changed.

Parameters:

• min: int

  The new min part of kick rate limit.

• rate: int

  The new rate part of kick rate limit.

• burst: int

  The new burst part of kick rate limit.

• byId: int

  Id of the player who has changed the kick rate limit.

4.19. GameStart(byId: int)

The game has just been started.

Parameters:

• byId: int

  Id of the player who has started the game.

4.20. GameStop(byId: int)

The game has just been stopped.

Parameters:

• byId: int

  Id of the player who has stopped the game.

5. Modifier Callbacks

Beware that these callbacks do not exist in Renderer objects, but they do in all RoomConfig and Plugin objects.

5.1. [modifiedName, modifiedFlag, modifiedAvatar] = modifyPlayerData(playerId: int, name: string, flag: string, avatar: string, conn: string, auth: string)

If defined, modifies the player's properties just before the player has joined the room.

Parameters:

• playerId: int

  Id of the new player who is about to join the room.

• name: int

  Name of the new player who is about to join the room.

• flag: string

  Country code of the new player who is about to join the room.

• avatar: string

  Avatar of the new player who is about to join the room.

• conn: string

  Connection string of the new player who is about to join the room.

• auth: string

  Auth string of the new player who is about to join the room.

Expected return values:

• return null:

  Blocks the player from joining the room.

• return [modifiedName: string, modifiedFlag: string, modifiedAvatar: string]:

  Modifies the name, flag and avatar values.

Example usage:

this.modifyPlayerData = function(playerId, name, flag, avatar, conn, auth){
  if (name=="abc")
    return null;  // block anyone trying to join the room with name "abc", before he can join the room.
  return [
    "[" + playerId + "] " + name, // prefix everyone's name with [playerId]
    "tr", // set everyone's flag to tr
    avatar // do not change avatars
  ];
};

5.2. newPing = modifyPlayerPing(playerId: int, ping: int)

If defined, runs for all players except host in a host room. Modifies the ping value of the player whose id is playerId.

NOTE:

Host player's ping will not change using this callback. In order to change host player's ping, you need to modify room.hostPing value directly.

Parameters:

• playerId: int

  Id of the current player.

• ping: int

  Current ping value of the current player.

Expected return values:

• return newPing: int:

  Sets the ping of the current player to newPing.

Example usage:

this.modifyPlayerPing = function(playerId, ping){
  return 100000 + ping*ping*ping; // set everybody(except host)'s ping to 100000 + its original value cubed.
};

5.3. newPing = modifyClientPing(ping: int)

If defined, runs only for the current player in a client room and modifies its ping value.

Parameters:

• ping: int

  Current ping value of the current player.

Expected return values:

• return newPing: int:

  Sets the ping of the current player to newPing.

Example usage:

this.modifyClientPing = function(ping){
  return 100000 + ping*ping*ping; // set your ping to 100000 + its original value cubed;
};

5.4. newFrameNo = modifyFrameNo(frameNo: int)

If defined, expects us to return the physics engine's new current frameNo value, which tells the physics engine that it is currently on a different frame than expected, which causes your player to look laggy to your opponents, especially on extrapolated clients.

Parameters:

• frameNo: int

  Current frameNo value of the physics engine.

Expected return values:

• return newFrameNo: int:

  Sets the frameNo of the physics engine to newFrameNo.

Example usage: (This is also known as the "opMode" cheat)

this.modifyFrameNo = function(frameNo){
  return frameNo - 3; // This tells the physics engine that it is 3 frames behind the actual reference frame.
};

5.5. acceptEvent = onOperationReceived(type: int, msg: object, globalFrameNo: int, clientFrameNo: int)

If defined, runs for each message received from all clients in a host room.

Parameters:

• type: int

  Type of the received message. We have to look it up in the global OperationType object to understand what type of message it actually is.

• msg: object

  The original message object. We can directly modify all contents of this object here as we wish.

• globalFrameNo: int

  The global frame no that host's physics engine is at, at the time that the message is received.

• clientFrameNo: int

  The frame no that this client's physics engine is at, at the time that the message is received.

Expected return values:

• true: accept event.

• false: block message from being processed.

• throw exception: break the connection of the sender of this message.

Example usage:

this.onOperationReceived = function(type, msg, globalFrameNo, clientFrameNo, customData){
  switch (type){
    case OperationType.KickBanPlayer: { // if someone is leaving or being kicked/banned by someone else
      var reason = msg.reason; // get the reason. this is null if the player is leaving by himself/herself.
      if (reason!=null && playerId!=0) // if any player sends a kick/ban event message other than room host
        return false; // block the event message
      break;
    }
  }
  return true;
};

6. Custom Events

These events will only work on host or client rooms that are using this API. The other players will still be able to play the game normally unless these events trigger an important physical change. Synchronization issues might arise in such cases, and the solution to these issues is to create your own Haxball website with this API and invite people there.

6.1. CustomEvent(type: int, data: object, byId: int)

A custom event has just been triggered.

Parameters:

• type: int

  Any integer value to hold the type of the custom event.

• data: object

  Any JSON object to store the properties of the custom event. This object is converted to a string and sent/received by Haxball's original event mechanism.

• byId: int

  Id of the player who has triggered this custom event.