uncategorized commonEventCallbacks

Default Event Callbacks

There are currently 6 types of event callbacks in this API.

1. Host-Only Events

These events can only be received by a host room.

RoomLink(link: string): void

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.
Return value: void.

BansClear(): void

Called just after all bans have been cleared using room.clearBans().

Parameters: None. Return value: void.

BanClear(id: int): void

Called just after the ban of a player has been cleared using room.clearBan(id).

Parameters:
- id: int: Id of the player whose ban has just been cleared.
Return value: void.

RoomRecaptchaModeChange(on: boolean): void

Called just after the room's recaptcha mode was changed using room.requireRecaptcha = on.

Parameters:
- on: boolean: The new value; whether to request recaptcha or not while joining the room.
Return value: void.

RoomTokenChange(token: string): void

Called just a little after the room's token was changed using room.token = value.

Parameters:
- token: string: The new token of the room.
Return value: void.

2. Host-Triggered Events

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

Announcement(msg: string, color: int, style: int, sound: int): void

Called just after an announcement was 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.
Return value: void.

PlayerHeadlessAvatarChange(id: int, value: string): void

Called just after a player has changed his/her headless avatar.

Parameters:
- id: int: Id of the player who triggered this event.
- value: string: The new headless avatar value.
Return value: void.

PlayersOrderChange(idList: int[], moveToTop: boolean): void

Called just after the order of players have been changed.

Parameters:
- idList: 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.
Return value: void.

SetDiscProperties(id: int, type: int, data1: number[], data2: int[]): void

Called just after a disc's properties have 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: 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: int[]: Must consist of the following properties of the disc in the same order: [color, cMask, cGroup].
Return value: void.

PingData(array: int[]): void

Called just after the ping values for all players have been updated.

Parameters:
- 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.
Return value: void.

RoomPropertiesChange(props: object): void

Called just after the room's properties have 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.
Return value: void.

3. Client-Triggered Events

These events can only be triggered by a room client.

PingChange(instantPing: number, averagePing: number, maxPing: number): void

Called just after the ping value of the current player has been calculated.

Parameters:
- instantPing: number: The instant ping value at that moment.
- averagePing: number: The calculated average ping value in a period of time.
- maxPing: number: The calculated maximum ping value in a period of time.
Return value: void.

4. Individually-Triggered Events

4.1. Game Events

PlayerBallKick(playerId: int): void

Called just after the ball has been kicked.

Parameters:
- playerId: int: Id of the player who kicked the ball.
Return value: void.

TeamGoal(teamId: int): void

Called just after a goal has been scored.

Parameters:
- teamId: int: Id of the team who scored the goal.
Return value: void.

GameEnd(winningTeamId: int): void

Called just after the game has ended.

Parameters:
- winningTeamId: int: Id of the team who won the game.
Return value: void.

GameTick(): void

Called just after a game tick has 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.

Return value: void.

KickOff(): void

Called just after a kick off event has occurred.

Parameters: None.

Return value: void.

TimeIsUp(): void

Called just after the game has ended by timeout.

Parameters: None.

Return value: void.

PositionsReset(): void

Called just after the player positions have 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.

Parameters: None.

Return value: void.

CollisionDiscVsDisc(discId1: int, discPlayerId1: int, discId2: int, discPlayerId2: int): void

Called just after a collision has 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.
Return value: void.

CollisionDiscVsSegment(discId: int, discPlayerId: int, segmentId: int): void

Called just after a collision has 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.
Return value: void.

CollisionDiscVsPlane(discId: int, discPlayerId: int, planeId: int): void

Called just after a collision has 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.
Return value: void.

4.2. Local Events

HandicapChange(value: int): void

Called just after the local ping handicap value has been changed.

Parameters:
- value: int: The new ping handicap value in milliseconds. Range: 0 <= value <= 300.
Return value: void.

RoomRecordingChange(value: true | ArrayBuffer): void

Called just after room recording has been started or stopped.

Parameters:
- value: true | ArrayBuffer:
  - If 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.
Return value: void.

4.3. API Events

PluginActiveChange(plugin: Plugin): void

Called just after a plugin has 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.
Return value: void.

ConfigUpdate(oldRoomConfigObj: RoomConfig, newRoomConfigObj: RoomConfig): void

Called just after the room's config object has been replaced by a new one.

Parameters:
- oldRoomConfigObj: RoomConfig: The old RoomConfig object.
- newRoomConfigObj: RoomConfig: The new RoomConfig object.
Return value: void.

RendererUpdate(oldRendererObj: Renderer, newRendererObj: Renderer): void

Called just after the room's renderer object has been replaced by a new one.

Parameters:
- oldRendererObj: Renderer: The old Renderer object.
- newRendererObj: Renderer: The new Renderer object.
Return value: void.

PluginUpdate(oldPluginObj: Plugin, newPluginObj: Plugin): void

Called just after an old plugin object has been replaced by a new one.

Parameters:
- oldPluginObj: Plugin: The old Plugin object.
- newPluginObj: Plugin: The new Plugin object.
Return value: void.

LibraryUpdate(oldLibraryObj: Library, newLibraryObj: Library): void

Called just after an old library object has been replaced by a new one.

Parameters:
- oldLibraryObj: Library: The old Library object.
- newLibraryObj: Library: The new Library object.
Return value: void.

LanguageChange(abbr: string): void

Called just after the API's language has been changed.

Parameters:
- abbr: string: The new language's abbreviation value.
Return value: void.

VariableValueChange(addonObject: Addon, variableName: string, oldValue: any, newValue: any): void

Called just after the value of a variable has been changed.

Parameters:
- addonObject: Addon: The Addon object that the variable belongs to.
- variableName: string: The name of the variable whose value has been changeed.
- oldValue: any: The old value of the variable.
- newValue: any: The new value of the variable.
Return value: void.

5. Common Events

PlayerSyncChange(playerId: int, value: boolean): void

Called just after a player's synchronization status has changed.

Parameters:
- playerId: int: Id of the player whose synchronization status has changed.
- value: boolean: The new synchronization status.
Return value: void.

AutoTeams(playerId1: int, teamId1: int, playerId2: int | null, teamId2: int | null, byId: uint16): void

Called just after an "auto" event has 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: uint16: Id of the player who has triggered the event.
Return value: void.

ScoreLimitChange(value: int, byId: uint16): void

Called just after the score limit has been changed.

Parameters:
- value: int: The new score limit value.
- byId: uint16: Id of the player who has triggered this event.
Return value: void.

TimeLimitChange(value: int, byId: uint16): void

Called just after the time limit has been changed.

Parameters:
- value: int: The new time limit value.
- byId: uint16: Id of the player who has triggered this event.
Return value: void.

PlayerAdminChange(id: int, isAdmin: boolean, byId: uint16): void

Called just after a player's admin rights have 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: uint16: Id of the player who has triggered this event.
Return value: void.

PlayerAvatarChange(id: int, value: string): void

Called just after a player has changed his/her avatar.

Parameters:
- id: int: Id of the player who has changed his/her avatar.
- value: string: The new avatar value.
Return value: void.

PlayerTeamChange(id: int, teamId: int, byId: uint16): void

Called just after 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: uint16: Id of the player who has triggered this event.
Return value: void.

StadiumChange(stadium: Stadium, byId: uint16): void

Called just after the room's current stadium has been changed.

Parameters:
- stadium: Stadium: The room's new Stadium object.
- byId: uint16: Id of the player who has triggered this event.
Return value: void.

TeamsLockChange(value: boolean, byId: uint16): void

Called just after the room's teams have been locked/unlocked.

Parameters:
- value: boolean: The room's new teams lock value.
- byId: uint16: Id of the player who has triggered this event.
Return value: void.

PlayerObjectCreated(playerObj: Player): void

Called just after a player object has been created. This callback can be used to define custom properties inside all player objects.

Parameters:
- playerObj: Player: The new Player object that has just been created.
Return value: void.

onPlayerDiscCreated(playerObj: Player): void

Called just after a disc object has been assigned to a player object.

Parameters:
- playerObj: Player: The new Player object that has just been assigned a disc object.
Return value: void.

onPlayerDiscDestroyed(playerObj: Player): void

Called just after a disc object has been removed from a player object.

Parameters:
- playerObj: Player: The Player object whose disc object has just been removed.
Return value: void.

PlayerJoin(playerObj: Player): void

Called just after a player has joined the room.

Parameters:
- playerObj: Player: The data representation of the player that has just joined the room.
Return value: void.

GamePauseChange(isPaused: boolean, byId: uint16): void

Called just after the game has been paused or resumed.

Parameters:
- isPaused: boolean: Whether the game has been paused or not.
- byId: uint16: Id of the player who has triggered this event.
Return value: void.

PlayerChat(id: int, message: string): void

Called just after a chat message has been received.

Parameters:
- id: int: Id of the player who has sent the chat message.
- message: string: The chat message.
Return value: void.

PlayerInputChange(id: int, value: int): void

Called just after a player's input has been changed.

Parameters:
- id: int: Id of the player whose input has been changed.
- value: int: The new input value of the player.
Return value: void.

PlayerChatIndicatorChange(id: int, value: boolean): void

Called just after a player has activated or deactivated his/her chat indicator. This happens when a player focuses/loses focus on the chat input component in the website.

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.
Return value: void.

PlayerLeave(playerObj: Player, reason: string | null, isBanned: boolean, byId: uint16): void

Called just after a player has 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: uint16: Id of the player who has kicked/banned the player. If reason is null, this value is ignored.
Return value: void.

TeamColorsChange(teamId: int, value: TeamColors, byId: uint16): void

Called just after a team's colors have been changed.

Parameters:
- teamId: int: The team whose colors have been changed.
- value: TeamColors: The new team colors value.
- byId: uint16: Id of the player who has changed the team colors.
Return value: void.

KickRateLimitChange(min: int, rate: int, burst: int, byId: uint16): void

Called just after the room's kick rate limit has 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: uint16: Id of the player who has changed the kick rate limit.
Return value: void.

GameStart(byId: uint16): void

Called just after the game has been started.

Parameters:
- byId: uint16: Id of the player who has started the game.
Return value: void.

GameStop(byId: uint16): void

Called just after the game has been stopped.

Parameters:
- byId: uint16: Id of the player who has stopped the game.
Return value: void.

6. Modifier Callbacks

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

modifyPlayerData(playerId: int, name: string, flag: string, avatar: string, conn: string, auth: string): [modifiedName: string, modifiedFlag: string, modifiedAvatar: string] | null

Called just before the player has joined the room. Using this callback, you may block all players or modify all players' name, flag and avatar properties just before they join 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.
Return value:
- null: Blocks the player from joining the room.
- [modifiedName: string, modifiedFlag: string, modifiedAvatar: string]: Modifies the name, flag and avatar values.
Example:
```
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
  ];
};
```

modifyPlayerPing(playerId: int, ping: int): 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.
Return value: The new ping value of the current player.

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

modifyClientPing(ping: int): 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.
Return value: The new ping value of the current player.

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

modifyFrameNo(frameNo: int): 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.
Return value: The new frameNo value of the physics engine.

Example: (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.
};
```

onOperationReceived(type: int, msg: object, globalFrameNo: int, clientFrameNo: int): boolean

If defined, runs for each message received from all clients in a host room, before they are processed and sent to all clients. This is the most important callback inside a host room; all permission logic should reside here. You are also allowed to modify the contents of all messages here.

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.
Return value:
- true: accept event.
- false: block message from being processed.
- throw exception: break the connection of the sender of this message.
Example:
```
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;
};
```

7. 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.

CustomEvent(type: int, data: object, byId: uint16): void

Called just after a custom event has 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: uint16: Id of the player who has triggered this custom event.
Return value: void.

BinaryCustomEvent(type: int, data: Uint8Array, byId: uint16): void

Called just after a binary custom event has been triggered.

Parameters:
- type: int: Any integer value to hold the type of the custom event.
- data: Uint8Array: Any Uint8Array to store the properties of the custom event. This object is directly sent/received by Haxball's original event mechanism.
- byId: uint16: Id of the player who has triggered this custom event.
Return value: void.

IdentityEvent(id: uint16, data: object, byId: uint16): void

Called just after an identity event has been triggered.

Parameters:
- id: uint16: Id of the player whose identity data is desired to be changed.
- data: object: The identity data that should be received from the backend. It can be any JSON object.
- byId: uint16: Id of the player who has triggered this custom event.
Return value: void.

node-haxball
- Installing
- Initialization
- API Overview
  Constants
  Interfaces
  - Callback
  - Utils
  - Room
  - Replay
  - EventFactory
  - Query
  - Errors
  - Impl
  Classes
  - Library
  - RoomConfig
  - Plugin
  - Renderer
  - Language

Provide feedback

Saved searches

Use saved searches to filter your results more quickly