Screeps LLM Agent

✅ Architecture Plan

Architecture Plan

1. Data Flow Overview

Official Screeps Server  <--->  Screeps API (HTTPS)
                                    |
                                    v
                        Local "Brain" (Node.js + LLM)
                                    |
                  ------------------+---------------------
                  |                                    |
        Live Commands via API                 Code Edits on Disk
    (Memory updates, spawn orders)     (LLM rewrites / optimizes JS files)

2. Core Components
   

A. Screeps API Integration

Use the screeps-api NPM package.

Install:

npm install screeps-api node-fetch

Basic Setup:

const { ScreepsAPI } = require(‘screeps-api’);
const api = new ScreepsAPI({
email: ‘[email protected]’,
password: ‘yourPassword’,
serverUrl: ‘https://screeps.com’ // official server
});

(async () => {
await api.auth();
const memory = await api.memory.get(‘brainInput’);
console.log(‘Current Memory:’, memory.data);
})();

You’ll use:

api.memory.set() to push game state snapshots to the LLM or receive commands back.

api.rawSegment for larger data packets if needed.

B. Local LLM Processing

Your local model (Ollama/DeepSeek) runs continuously:

Polls Screeps API every X ticks (say every 10 seconds).

Reads game state (brainInput).

Generates:

    Immediate orders (e.g., {spawn: [{role:'miner',room:'W1N1'}]}).

    Suggestions for code changes (e.g., "optimize miner.js to use path caching").

Example prompt snippet:

const prompt = Game state: ${JSON.stringify(memory.data)} 1) Suggest immediate orders in JSON (no text). 2) Suggest code optimizations if needed (which file, what to change). ;

C. Writing Commands Back

Push orders directly:

await api.memory.set(‘brainOutput’, JSON.stringify(orders));

Then, in your Screeps code:

if (Memory.brainOutput) {
executeOrders(JSON.parse(Memory.brainOutput));
delete Memory.brainOutput;
}

D. Local Code Editing

Since you’re syncing code with the official server:

The LLM generates code patches (JS diffs or full file replacements).

Node.js applies changes to the local /scripts folder.

Screeps’ official client auto-syncs these changes.

Example:

const fs = require(‘fs’);
function updateFile(file, newCode) {
fs.writeFileSync(./screeps/scripts/${file}, newCode, ‘utf8’);
console.log(${file} updated, syncing with Screeps...);
}

You can even have the LLM generate diffs:

File: miner.js

Replace function runMiner with:

function runMiner(creep) {
if(!creep.memory.path) {creep.memory.path = creep.pos.findPathTo(Game.sources[0]);}
if(creep.harvest(Game.sources[0]) == ERR_NOT_IN_RANGE) {
creep.moveByPath(creep.memory.path);
}
}

Your Node.js script parses this and rewrites the file.

3. Recommended Flow Every 10–20 ticks: Pull game state via API → LLM → push back orders (brainOutput). Every few hours or on trigger: Ask the LLM for code refactors. Save changed files locally → Screeps client auto-syncs. Optional Safety: Auto-commit changes to Git after each edit, in case the LLM breaks something.