Hooks

Hooks are how you find out what’s going on in game. They are called when certain events happen, and you can use them to do things like log information, send messages, or even dispatch other actions.

If you’ve ever used Discord.JS or some other library with a .on system, that’s what a hook is, we just needed a creative name for it.

bot.on('playerJoin', (player) => {
    console.log(`${player.name} has joined the game!`);
});

​

Hook List

Each hook has a basic example and description of usage.

• authFail
• balanceUpdate
• banned
• challengeComplete
• chat
• close
• collectAmmo
• collectGrenade
• gameForcePause
• gameOptionsChange
• gameReset
• gameStateChange
• grenadeExploded
• packet
• pingUpdate
• playerBeginStreak
• playerChangeCharacter
• playerChangeGun
• playerDamaged
• playerDeath
• playerFire
• playerJoin
• playerLeave
• playerMelee
• playerPause
• playerReload
• playerRespawn
• playerSwapWeapon
• playerSwitchTeam
• playerThrowGrenade
• rocketHit
• selfDamaged
• selfMoved
• selfRespawnFail
• selfShieldHit
• selfShieldLost
• spawnItem
• tick

They are not individual files. I’m too lazy to create all of them!

​

Hooks

This is the entire list. My fingers will probably hurt.

​

authFail

This is called when the authentication flow fails.

• reason is a valid reason:
  • bad_json - auth returned a bad JSON - usually out of your control, check console for errors
  • firebase_no_credentials - you did not pass a valid email or password
  • firebase_no_token - firebase didn’t return an ID token, check console for info
  • firebase_too_many_retries - attempting to get auth info failed over 5 times
  • services_closed_early - the game websocket closed before sending back auth info - usually out of your control
  • unknown_socket_error - the websocket itself errored, usually out of your control

bot.on('authFail', (reason) => {
    console.log('ah, shoot. auth failed with reason', reason);
});

​

balanceUpdate

This is called when the bot’s egg balance updates, likely due to the bot killing someone.

• oldBalance is a number
• newBalance is a number

bot.on('balanceUpdate', (oldBalance, newBalance) => {
    console.log(`bot's balance was ${oldBalance}, now it's ${newBalance}`);
    console.log(`the bot gained ${newBalance - oldBalance} eggs!`);
});

​

banned

This is called when the bot is banned and cannot complete authentication. If you get this event, the Bot can’t be further used.

• banRemaining is a string in the format HH:MM:SS

bot.on('banned', (banRemaining) => {
    console.log(`bot is banned for ${banRemaining}, and cannot authenticate. RIP`);
});

​

challengeComplete

This is called when a challenge is completed.

• player - the player that completed the challenge
  • if the bot is in a game, this will be a GamePlayer object
  • if the bot is not in a game, this will be bot.account
• challenge - the challenge ID number
  • if the CHALLENGES intent is enabled AND the player is the bot, this will be from bot.account.challenges

bot.on('challengeCompleted', (player, challenge) => {
    if (player.id == bot.me.id) console.log(`${player.name} completed challenge ${challenge}!`);
    else console.log(`someone else completed challenge ${challenge}!`);
});

### chat
This is called when a chat message is sent in the game.

- `player` is a Player object
- `message` is a string
- `flags` is a number

```js
bot.on('chat', (player, message, flags) => {
    if (player) console.log(`${player.name} said: ${message}`);
    else if (flags === 255) console.log(`<SERVER (probably Harrison)> ${message}`);
    else if (flags === 254) console.log(`<Mod> ${message}`);
    else console.log(`Unknown sourced chat message: ${message}`);
});

​

close

This is called when the bot’s connection to the game is closed.

• code is a number

bot.on('close', (code) => {
    console.log('bot has disconnected from the game with code', code);
});

You can compare this to the CloseCode constant.

​

collectAmmo

This is called when a player collects an ammo pack.

• player is a Player object
• weapon is a Gun class (see Gun)

bot.on('collectAmmo', (player, weapon) => {
    console.log(`${player.name} collected ${weapon.ammo.pickup} ammo for their ${weapon.weaponName}!`);
});

​

collectGrenade

This is called when a player collects a grenade.

• player is a Player object

bot.on('collectGrenade', (player) => {
    console.log(`${player.name} collected a grenade, and now has ${player.grenades} grenades!`);
});

​

gameForcePause

This is called when the game is forcibly paused. It’s not horribly clear WHEN this is called.

bot.on('gameForcePause', () => {
    console.log('game has been forcibly paused, who knows why');
});

​

gameOptionsChange

This is called when the game options change by a host in a private room.

• oldOptions is an object (specifically Bot.game.options)
• newOptions is an object (specifically Bot.game.options)

bot.on('gameOptionsChange', (oldOptions, newOptions) => {
    console.log('game options have changed!');
    console.log('old options:', oldOptions);
    console.log('new options:', newOptions);
});

​

gameReset

This is called when the game is reset by the host. This is probably when gameForcePause is called.

bot.on('gameReset', () => {
    console.log('game has been reset!');
});

​

gameStateChange

This is called when the game state changes. This is MAINLY used in the spatula & KOTC gamemodes, wich signify whe things like the spatula is dropped or someone starts/stops capturing a coop, among many other things.

• oldState is an object (specifically Bot.game.state)
• newState is an object (specifically Bot.game.state)

bot.on('gameStateChange', (oldState, newState) => {
    console.log(`game state has changed`);
    console.log(`old state:`, oldState);
    console.log(`new state:`, newState);
});

The current game state can be accessed at any time with bot.game.state. The object is so large, documenting it here would be a headache. See the Bot class for more information.

​

grenadeExploded

This is called when a grenade explodes somewhere on the map.

• item is an item (if the COSMETIC_DATA intent is enabled), and if not, it will be the item ID #
• pos is an object with the x, y, and z properties
• damage is a number
• radius is a number (float)

bot.on('grenadeExploded', (item, pos, damage, radius) => {
    console.log(`a grenade exploded at ${pos}!`);
    console.log(`it did ${damage} damage with a ${radius} radius`);
});

​

packet

This is called when any packet is sent. It sends the raw packet, so you should create a CommIn and manually inspect it. Using this requires the Bot.Intents.PACKET_HOOK intent.

• packet is an encoded packet string

bot.on('packet', (packet) => {
    console.log('packet received!');
});

If you are trying to get every event, you are much better off with bot.onAny.

​

pingUpdate

This is called when the bot’s ping updates.

• oldPing is a number
• newPing is a number

bot.on('pingUpdate', (oldPing, newPing) => {
    console.log(`bot's ping was ${oldPing}, now it's ${newPing}`);
});

​

playerBeginStreak

This is called when a player begins a streak reward (2x damage, overheal, etc).

• player is a Player object
• streak is a value of the ShellStreaks enum

bot.on('playerBeginStreak', (player, streak) => {
    console.log(`${player.name} has begun a ${streak} killstreak!`);
});

​

playerChangeCharacter

This is called when a player changes their skin set.

• player is a Player object
• oldCharacter is an object (specifically Bot.game.players[player.id].character)
• newCharacter is an object (specifically Bot.game.players[player.id].character)

bot.on('playerChangeCharacter', (player, oldCharacter, newCharacter) => {
    console.log(`${player.name} has changed their skins`);
    console.log(`old skins:`, oldCharacter);
    console.log(`new skins:`, newCharacter);
});

​

playerChangeGun

This is called when a player changes their gun. The guns are a 0-6 index, with 0 being the eggk and 6 being the tri-hard (in order of gun list).

• player is a Player object
• oldGun is a number (0-6)
• newGun is a number (0-6)

bot.on('playerChangeGun', (player, oldGun, newGun) => {
    console.log(`${player.name} has changed their gun`);
    console.log(`old gun:`, oldGun);
    console.log(`new gun:`, newGun);
});

​

playerDamaged

This is called when a player is hurt (using gun/grenade/melee). It’s not clear if this is when ANYONE hits a player, or when just the bot hits a player.

• player is a Player object
• oldHp is a number
• newHp is a number

bot.on('playerDamaged', (player, oldHp, newHp) => {
    console.log(`${player.name} was hit! their health was ${oldHp}, now it's ${newHp}`);
});

​

playerDeath

This is called when a player dies.

• player is a Player object
• killer is a Player object

bot.on('playerDeath', (player, killer) => {
    console.log(`${player.name} was killed by ${killer.name}`);
});

​

playerFire

This is called when a player fires their gun.

• player is a Player object
• weapon is a Gun class (see Gun)

bot.on('playerFire', (player, weapon) => {
    console.log(`${player.name} fired their ${weapon.weaponName}!`);
});

​

playerJoin

This is called when a player joins the game.

• player is a Player object

bot.on('playerJoin', (player) => {
    console.log(`${player.name} has joined the game!`);
});

​

playerLeave

This is called when a player leaves the game.

• player is a Player object

bot.on('playerLeave', (player) => {
    console.log(`${player.name} has left the game, RIP :(`);
});

​

playerMelee

This is called when a player melees. Damage is not sent, nor what players it hits.

• player is a Player object

bot.on('playerMelee', (player) => {
    console.log(`${player.name} meleed!`);
});

​

playerPause

This is called when a player pauses the game (clicks ESC).

• player is a Player object

bot.on('playerPause', (player) => {
    console.log(`${player.name} has paused the game!`);
});

​

playerReload

This is called when a player reloads their gun.

• player is a Player object
• weapon is a Gun class (see Gun)

bot.on('playerReload', (player, weapon) => {
    console.log(`${player.name} reloaded their ${weapon.weaponName}!`);
});

​

playerRespawn

This is called when a player respawns.

• player is a Player object

bot.on('playerRespawn', (player) => {
    console.log(`${player.name} has respawned!`);
});

​

playerSwapWeapon

This is called when a player swaps their weapon (between primary and secondary).

• player is a Player object
• nowActive is a number (0 or 1)

bot.on('playerSwapWeapon', (player, nowActive) => {
    console.log(`${player.name} swapped to their ${nowActive == 0 ? 'primary' : 'secondary'} weapon!`);
});

​

playerSwitchTeam

This is called when a player switches teams.

• player is a Player object
• oldTeam is a number (see the Teams enum)
• newTeam is a number (see the Teams enum)

bot.on('playerSwitchTeam', (player, oldTeam, newTeam) => {
    console.log(`${player.name} switched from team ${oldTeam} to team ${newTeam}`);
});

​

playerThrowGrenade

This is called when a player throws a grenade.

• player is a Player object
• pos is an object with the x, y, and z properties
• dir is an object with the x, y, and z properties

bot.on('playerThrowGrenade', (player, pos, dir) => {
    console.log(`${player.name} threw a grenade at ${pos} with direction ${dir}`);
});

​

rocketHit

This is called when a rocket hits a location and creates an explosion.

• pos is an object with the x, y, and z properties
• damage is a number
• radius is a number (float)

bot.on('rocketHit', (pos, damage, radius) => {
    console.log(`a rocket hit at ${pos}!`);
    console.log(`it did ${damage} damage with a ${radius} radius`);
});

​

selfDamaged

This is called when the bot is hurt.

• oldHp is a number
• newHp is a number

bot.on('selfDamaged', (oldHp, newHp) => {
    console.log(`bot was hit! its health was ${oldHp}, now it's ${newHp}`);
});

​

selfMoved

This is called when the bot moves.

• oldPos is an object with the x, y, and z properties
• newPos is an object with the x, y, and z properties

bot.on('selfMoved', (oldPos, newPos) => {
    console.log(`bot moved from ${oldPos} to ${newPos}`);
});

​

selfRespawnFail

This is called when the bot fails to respawn. This ideally should never be called, as our dispatch checks should stop this from happening.

bot.on('selfRespawnFail', () => {
    console.log(`bot failed to respawn!`);
});

​

selfShieldHit

This is called when the bot’s shield is hit.

• oldShield is a number
• newShield is a number

bot.on('selfShieldHit', (oldShield, newShield) => {
    console.log(`bot's shield was hit! its shield was ${oldShield}, now it's ${newShield}`);
});

​

selfShieldLost

This is called when the bot’s shield is lost.

bot.on('selfShieldLost', () => {
    console.log(`bot's shield was lost!`);
});

​

spawnItem

This is called when an ammo pack or grenade is spawned in the game. The types are the numeric values of the CollectTypes.

bot.on('spawnItem', (type, _id, pos) => {
    console.log('a', type, 'spawned at', pos);
})

​

tick

This is called everytime an update fires. This is called incredibly often.

bot.on('tick', () => {
    console.log('tick!');
});