Creep Roles.md

Creep Roles

Creep roles in Hivemind define the behavior and logic for each type of creep in your empire. The creep manager uses these roles to determine what each creep should do every tick, based on the role property in the creep's memory.

How Creep Roles Work

• Each creep has a role property in its memory (e.g., creep.memory.role = 'builder').
• The creep manager (CreepManager) is responsible for running the correct logic for each creep, based on its role.
• Roles are registered with the creep manager, and each role is a class that extends the base Role class.
• On each tick, the creep manager iterates over all creeps and calls the run method of the appropriate role class.

Writing a New Creep Role

To add a new role, create a new class that extends Role (see src/role/role.ts):

import Role from 'role/role';

export default class MyCustomRole extends Role {
  run(creep: Creep) {
    // Your custom logic here
    if (!creep.memory.working && creep.store.getFreeCapacity() === 0) {
      creep.memory.working = true;
    } else if (creep.memory.working && creep.store[RESOURCE_ENERGY] === 0) {
      creep.memory.working = false;
    }
    if (creep.memory.working) {
      // Do work
    } else {
      // Gather energy
    }
  }
}

Register your new role with the creep manager (usually in the spawn manager or using the onGlobalReset callback):

creepManager.registerCreepRole('myCustomRole', new MyCustomRole());

A creep's role is usually set when it is spawned, based on the desired behavior. You can change a creep's role at any time by updating its memory:

creep.memory.role = 'myCustomRole';

Throttling and Role Execution

• The creep manager uses throttling to limit how often each creep's logic runs, especially under CPU pressure.
• Each role can define its own throttleAt and stopAt values (inherited from the Role base class), which control when creeps of that role are skipped based on available bucket.
• Creeps at room borders are never throttled, to avoid getting stuck.
• Throttled creeps will have their logic skipped for the tick, and statistics are tracked and reported to the console.
• Creeps are throttled individually, so if one creep of a role is throttled, others can still run. Roughly, the percentage of creeps that run is determined by how much bucket is available compared to the throttleAt and stopAt values.

Best Practices

• Keep role logic focused and modular—each role should only handle one type of behavior.
• Use the preRun method for checks or setup before the main run logic.
• Adjust throttleAt and stopAt if your role is critical or can be deprioritized under CPU pressure.