logo bannerlogo banner

yolkbot 1.5 migration guide

last edited: 2026-01-26

hi! migrating to yolkbot 1.5 is relatively easy, and there's just a quick list below that you need to go through to make sure your bot works as you expect.

error handling

before we delve in, we need to briefly discuss error handling in yolkbot 1.5.

instead of returning strings or logging (most) errors, yolkbot 1.5 now returns objects with an ok property. for example, bot.join will either return:

{ ok: true, game: Game }

or:

{ ok: false, error: JoinError.GameNotFound }

JoinError is one of our new enums. enums come from yolkbot/enums, and you can import them like so:

import { JoinError } from 'yolkbot/enums';

a full list of enums can be found in the yolkbot/enums documentation.

this applies to almost ALL functions that returned string errors in API and Bot; it is a MAJOR change and the biggest breaking one here.

  • the old error hook (bot.on('error', ...)) has been removed
  • bot.processError has been removed
  • the NO_EXIT_ON_ERROR intent has been removed
  • pathfinding errors are now hooked with the 'pathfindError' hook, not 'error'
  • most error types (the old string lists) have been removed, because enums are typed

enums aren't just used for errors. for example, Intents have been turned into an enum as well. on that note...

migrating!

  • weapon changes
    • if you reference weapons in any of the following ways:
      • bot.me.weapons[X]
      • bot.players[X].weapons[Y]
      • yolkbot/constants/guns
    • some of the properties on these weapons (i.e. recoil) have been removed
    • you will need to manage these yourself
    • if you use yolkbot/constants/guns, you don't need to run new Gun(...) anymore; the constants now just direct objects
    • "Eggk47" has been renamed to "EggK47" (capital K)
  • URLRewards from yolkbot/constants has been removed; maintain it yourself
  • bot.game.collectables has been renamed to bot.game.collectibles (US vs UK spelling)
  • when pathfinding fails, it no longer logs to the console but emits a pathfindError error with the parameter of a PathfindError enum from yolkbot/enums
  • you can no longer import dispatches like import { ChatDispatch } from 'yolkbot/dispatches'; the new bot.emit (see the 1.5 infosheet for more) should be used instead (or import from yolkbot/dispatch/ChatDispatch directly)
  • playerReload has been split into playerStartReload and playerEndReload
  • pathfinding has had LOTS of internal changes
    • MapNode.positionStr and MapNode.position have been removed; use MapNode.positionKey - it is a unique key for the node's position
    • MapNode.flatCenter() has been replaced with MapNode.flatCenter (it is no longer a function)
    • the pather property no longer exists on GoTo dispatches, use bot.pathing.astar
  • yolkbot/wasm/util has been removed; any utilities you used from there will need to be reimplemented by you
  • some parameters to Bot & API have been removed
    • apiMaxRetries / maxRetries - this was misused; 5 is good enough
    • suppressErrors - use the new errorLogger with an empty function
  • yolkws / yolkbot/socket has the second parameter now as an object and now a string
    • old: new YolkWS(url, 'socks5h://proxy')
    • new: new YolkWS(url, { proxy: 'socks5h://proxy' })
    • this is to add errorLogger support!
  • bot.state.left has been removed in favor of bot.state.inGame
  • bot.game.map.nodes has been removed. i have absolutely no idea what this is, maybe it's bot.pathing.nodeList? i forgot. if you used this, please reach out on discord and tell me what this was.
  • Intents have been moved to yolkbot/enums
    • old: bot.Intents.PATHFINDING
    • new: import { Intents } from 'yolkbot/enums'; Intents.PATHFINDING
  • the gameStateChange packet has a new syntax! see its documentation for more info.
  • bot.game.kotc has been created
    • bot.game.stage -> bot.game.kotc.stage
    • bot.game.zoneNumber -> bot.game.kotc.zoneIdx (NOTE: NAME CHANGED)
    • bot.game.activeZone -> bot.game.kotc.activeZone
    • bot.game.capturing -> bot.game.kotc.capturing
    • bot.game.captureProgress -> bot.game.kotc.captureProgress
    • bot.game.capturing -> bot.game.kotc.teamCapturing (NOTE: NAME CHANGED; changed in 1.5.1)
    • bot.game.numCapturing -> bot.game.kotc.numCapturing
    • bot.game.capturePercent -> bot.game.kotc.capturePercent
  • bot.account.isDoubleEggWeeknd() is now imported from yolkbot/util
  • the NO_LOGIN intent has been renamed to SKIP_LOGIN
  • bot.once has been removed because your LLMs you use to vibe code keep fucking it up and i'm tired of handling the DMs about it
  • bot.initMatchmaker has been removed; use bot.initSession (it is basically the same)
    • to JUST init the matchmaker and not automatically log in anonymously, use bot.createMatchmaker()
  • bot.matchmaker (aka yolkbot/matchmaker) has been removed and merged into Bot
    • the NO_REGION_CHECK intent has been removed; call bot.getRegions with a custom instance that returns your custom region
    • bot.matchmaker.connected is the same
    • bot.matchmaker.regionList -> bot.regionList
    • bot.matchmaker.proxy -> bot.proxy
    • bot.matchmaker.sessionId -> bot.account.sessionId
    • bot.matchmaker.send -> bot.matchmaker.send
      • JSONs are no longer auto stringified
    • bot.matchmaker.getRegions -> bot.getRegions (different output due to error handling changes, beware)
    • bot.matchmaker.waitForConnect / bot.matchmaker.on('open') -> removed; if bot.matchmaker is null just run bot.createMatchmaker()
    • bot.matchmaker.on('msg', cb) -> add/remove callbacks from bot.matchmakerListeners
    • if not listed, it has been removed
  • yolkbot/comm has been removed
    • CommIn is at yolkbot/comm/CommIn
    • CommOut is at yolkbot/comm/CommOut
    • CommCode is at yolkbot/constants/CommCode
    • CloseCode is at yolkbot/constants/CloseCode
  • the AccountFirebase type in yolkbot/bot has been renamed to RawFirebase and moved to yolkbot/api
  • the legacy onYolkReady in browser bundles has been removed
  • bot.process* has been removed and split into different files
    • if you need to override packets or add your own packets, modify bot.packetHandlers
  • bot.quit has had the primary param changed into levels: see CleanupLevel enum in yolkbot/enums
    • previous default behavior / quit(true): CleanupLevel.Full
    • quit(false): CleanupLevel.None
    • new mode: CleanupLevel.Partial - cleans up functions like websockets but not bot.account, bot.players, etc