Stonehenge - Smart colony management for the game Screeps. Written in TypeScript.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Smart colony management for the game Screeps. Written in TypeScript.

MIT License

Stonehenge is a proof-of-concept of a smart, robust, and maintainable Screeps codebase. It is developed in TypeScript, and designed with modularity in mind.

Table of Contents

Design Principles


The codebase has to be simple and easily readable in order for the code to be easily built upon. In this case, the code quality is kept to a high standard and every part of the Stonehenge codebase is painstakingly documented to improve the readability and maintainability.


The code is structured by modules, which means expanding on the codebase could be done with minimal overhead.

Configuration over Convention

Anyone who wants to build their Screeps colony with with Stonehenge must not be forced to follow conventions beyond the initial setup. The configurations available in the config/ folder will allow you to fine-tune the codebase according to your workflow and needs.

Quick Start

By far, the easiest and quickest way to get started with TypeScript development on Screeps is to follow @bonzaiferroni's guides on Screeps World. Go read them!


We'll assume you have already downloaded/cloned the starter kit.

  • Node.js (latest LTS is recommended)
  • Typings
  • Yarn - Optional. You can use npm if you don't want to, but this is for your own sanity.

Installing the Modules

Run the following the command to install the required packages and TypeScript declaration files if you are using yarn:

$ yarn

or, for npm:

$ npm install

Initial configuration

Configuring Screeps credentials

Create a copy of config/credentials.example.json and rename it to config/credentials.json.

WARNING: This file contains your secret credentials. DO NOT commit it into your repository!

# config/credentials.json
$ cp config/credentials.example.json config/credentials.json

In the newly created credentials.json file, change the email and password properties with your Screeps credentials. The serverPassword, token, and gzip options are only for private servers that support them. If you are uploading to the public Screeps server, you should delete these fields from your credentials file.

Changing the upload branch

Go to config/, and you'll find the following lines:

const credentials: Credentials = require("./credentials.json");
credentials.branch = "dev";

Change the credentials.branch property you want to initially build and upload to, e.g. "default". Note that due to the Screeps API limitations, you still have to create a branch with a matching name in the Screeps client by cloning an existing branch. The compiler will yell at you when you forgot to do so.

Advanced configuration

See Configuration page on the screeps-typescript-starter wiki for more in-depth info on configuration options.

Running the compiler

# To compile and upload your TypeScript files on the fly in "watch mode":
$ npm start

# To compile and deploy once:
$ npm run deploy

First-time deploy

If you just installed this code for the first time, it is very important that you perform the following tasks first!

Pre-deploy steps

  • Delete your currently active code. (This stops the game until you push the new code.)
  • Delete ALL currently active memory entries. (This will remove any memory conflicts.)
  • Kill ALL of your creeps.

You can also perform the above tasks to clean up your memory should things go wrong.

Post-deploy steps

After deploying, you should manually set the build priorities for your rooms. Go to your respective room's memory in the memory tree, go to jobs, and set the number of creeps you'd like each role.

Further reading

To find out more about what else you can do with screeps-typescript-starter, head over to the screeps-typescript-starter wiki to find more guides, tips and tricks.


List of things that need to be finished.

High-Priority Tasks

  • Actual defensive/war code
  • Creep Action/State code
  • Controlled room job assignments:
    • Defender
    • Mineral miners
  • Reserved rooms
    • Colony management logic
    • Job assignments
      • Scout
      • Reserver
      • Remote builder
      • Remote harvester
      • Remote hauler
      • Remote upgrader
      • Remote defender

Future Ideas

These might not be implemented in the near future, but we thought these would be cool things to have in the codebase.

  • Improved job system.
  • Migration support (no more cleaning up your entire field before deploying).
  • Write up a proper documentation of code.


Issues and Pull Requests are welcome! Please read the Contributing Guidelines beforehand.

Special Thanks

Marko Sulamägi, for the original Screeps/TypeScript sample project.