How to Make a Screeps Creep Upgrade the Room Controller

Build one complete Upgrader round trip

This lesson has one observable goal: make Upgrader1 harvest Energy, travel to the owned Room Controller, spend that Energy with upgradeController(), and return to harvesting when empty.

Empty → harvest. Full → upgrade. Partly full → continue the current trip.

The previous lesson explained that Upgrader is a player-defined responsibility. This lesson supplies the repeated behavior that makes the label useful.

Lesson boundary: the example uses one fixed Creep name and the first currently active Source. It does not optimize Source assignment, Controller throughput, Containers, Links, or automatic replacement.

Confirm the Creep and room can run the lesson

• Upgrader1 exists and has finished spawning.
• The Creep has active WORK, CARRY, and MOVE parts.
• The current room has a Controller that belongs to you.
• At least one Source is active when the Creep needs Energy.

Create the Creep with the previous spawnCreep() lesson when it does not exist. Keep the name in that spawn request and this main loop identical.

The learning body [WORK, CARRY, MOVE] is enough for this first cycle: WORK harvests and upgrades, CARRY provides the Energy Store, and MOVE allows travel.

Understand what upgradeController() actually does

creep.room.controller returns the Controller in the Creep's current room. Calling creep.upgradeController(controller) spends carried Energy through active WORK parts and adds upgrade progress when the target is valid.

The action works within range 3. That is different from harvest(), which requires the Creep to be adjacent to the Source.

This is why the movement code below requests range 1 for the Source but range 3 for the Controller.

Keep one two-state rule in Creep Memory

creep.memory.upgrading is a small persistent flag. It prevents the Creep from reversing direction after every individual unit of Energy changes.

An undefined flag behaves like false in the branch below, so a new empty Upgrader begins by harvesting. Review Screeps Memory basics when you want to inspect how the value persists.

Run the complete Upgrader1 loop

State impact: this main loop writes creep.memory.upgrading, moves the Creep, harvests Energy, and submits Controller upgrade actions.

const CREEP_NAME = 'Upgrader1';

function reportEveryTwentyTicks(message) {
  if (Game.time % 20 === 0) {
    console.log(message);
  }
}

function moveWithinRange(creep, target, range, label) {
  const moveResult = creep.moveTo(target, {
    range: range,
    reusePath: 5
  });

  if (moveResult !== OK && moveResult !== ERR_TIRED) {
    reportEveryTwentyTicks(
      creep.name + ' moveTo(' + label + ') returned ' + moveResult + '.'
    );
  }
}

module.exports.loop = function () {
  const creep = Game.creeps[CREEP_NAME];

  if (!creep) {
    reportEveryTwentyTicks(
      CREEP_NAME + ' was not found. Create it or check the exact name.'
    );
    return;
  }

  if (creep.spawning) {
    return;
  }

  if (creep.getActiveBodyparts(WORK) === 0 ||
      creep.getActiveBodyparts(CARRY) === 0 ||
      creep.getActiveBodyparts(MOVE) === 0) {
    reportEveryTwentyTicks(
      CREEP_NAME + ' needs active WORK, CARRY, and MOVE parts.'
    );
    return;
  }

  const controller = creep.room.controller;

  if (!controller || !controller.my) {
    reportEveryTwentyTicks(
      CREEP_NAME + ' cannot find an owned Controller in ' +
      creep.room.name + '.'
    );
    return;
  }

  const usedEnergy =
    creep.store.getUsedCapacity(RESOURCE_ENERGY);
  const freeEnergy =
    creep.store.getFreeCapacity(RESOURCE_ENERGY);

  if (usedEnergy === 0) {
    creep.memory.upgrading = false;
  } else if (freeEnergy === 0) {
    creep.memory.upgrading = true;
  }

  if (creep.memory.upgrading) {
    const upgradeResult =
      creep.upgradeController(controller);

    if (upgradeResult === ERR_NOT_IN_RANGE) {
      moveWithinRange(creep, controller, 3, 'Controller');
    } else if (upgradeResult === ERR_NOT_ENOUGH_RESOURCES) {
      creep.memory.upgrading = false;
    } else if (upgradeResult !== OK) {
      reportEveryTwentyTicks(
        CREEP_NAME + ' upgradeController() returned ' +
        upgradeResult + '.'
      );
    }

    return;
  }

  const activeSources =
    creep.room.find(FIND_SOURCES_ACTIVE);
  const source = activeSources[0];

  if (!source) {
    reportEveryTwentyTicks(
      CREEP_NAME + ' is waiting for an active Source.'
    );
    return;
  }

  const harvestResult = creep.harvest(source);

  if (harvestResult === ERR_NOT_IN_RANGE) {
    moveWithinRange(creep, source, 1, 'Source');
  } else if (harvestResult !== OK &&
             harvestResult !== ERR_NOT_ENOUGH_RESOURCES) {
    reportEveryTwentyTicks(
      CREEP_NAME + ' harvest() returned ' +
      harvestResult + '.'
    );
  }
};

Follow the loop across repeated ticks

1. The main loop finds Upgrader1 and validates its body and owned Controller.
2. An empty Store sets upgrading to false.
3. The Creep selects a currently active Source.
4. harvest() returns ERR_NOT_IN_RANGE until the Creep reaches range 1, so moveTo() advances it across later ticks.
5. A full Store sets upgrading to true.
6. upgradeController() returns ERR_NOT_IN_RANGE until the Creep is within range 3.
7. Successful upgrade actions consume Energy across later ticks.
8. When the Store reaches zero, the next tick switches back to harvesting.

The code does not attempt to harvest and upgrade in the same branch. Each tick reads current state and submits the action appropriate for that state.

Read the important action results

Use the ERR_NOT_IN_RANGE guide when movement succeeds but the action never becomes valid.

Verify one full Source-to-Controller cycle

Do not treat a single OK return value as proof of the whole loop. Watch several later ticks and confirm this sequence:

1. Upgrader1 approaches an active Source while empty.
2. Its Energy Store increases.
3. memory.upgrading becomes true only when the Store is full.
4. The Creep stops within range 3 of the owned Controller.
5. Its carried Energy decreases while Controller progress increases.
6. The flag becomes false after the Store reaches zero.
7. The Creep returns to an active Source.

Completing this full round trip is the acceptance test for the lesson. The page does not claim that this sequence has been run in a live Screeps room.

Diagnose the first failures without adding more systems

Do not add Builder, repair, population control, or Link logic until this one cycle is observable.

Finish the lesson, then build the first Extension

You have completed Lesson 9 when you can explain and observe all of the following:

• upgradeController() spends carried Energy and works within range 3;
• harvest() requires range 1;
• creep.memory.upgrading preserves one responsibility across ticks;
• empty and full Store boundaries switch the state;
• the code validates the Creep, active body parts, active Source, and owned Controller;
• one full harvest-upgrade-harvest round trip is visible across later ticks.

Continue to build the first Extension after reaching RCL 2 →

Return to the English beginner roadmap to review all twelve lessons.

Official sources

• Screeps Documentation: Room Controller Level
• Screeps API: Creep.upgradeController()
• Screeps API: Creep.harvest()
• Screeps API: Creep.memory