Using Callbacks.md

Using Callbacks

Hivemind provides two special settings—onTick and onGlobalReset—that allow you to run your own code at key points in the bot's lifecycle. This lets you extend or customize the bot's behavior without modifying core files, making it easy to keep your changes compatible with upstream updates.

Callback Settings

• onTick: A function that runs at the start of every game tick, after the bot's memory and core systems are initialized but before most processes run.
• onGlobalReset: A function that runs once every time the bot is reloaded (e.g., after a global reset or code upload).

You can set these callbacks in your src/settings.local.ts file:

import {myOnTick, myOnGlobalReset} from './my-custom-callbacks';

const settings: Partial<SettingsObject> = {
  onTick: myOnTick,
  onGlobalReset: myOnGlobalReset,
};
export default settings;

Example: Logging a Message Every Tick

Create a file src/my-custom-callbacks.ts:

export function myOnTick() {
  if (Game.time % 100 === 0) {
    console.log('100 ticks have passed!');
  }
}

export function myOnGlobalReset() {
  console.log('Hivemind global reset!');
}

Then import and use these in your settings as shown above.

Best Practices

• Keep your callback logic in separate files and only reference them in settings.local.ts.
• Avoid heavy logic in onTick to prevent performance issues. Instead, use processes since they include built-in throttling and management.
• Use onGlobalReset for one-time setup, such as initializing global variables or logging.
• This approach ensures your custom code is not affected by upstream changes to the bot's main loop or process management.