Skip to content
Go to file

Screeps API

This is a nodejs API for the game Screeps

JavaScript Style Guide License Version Downloads CircleCI


Notice on authentication

As of 12/29/2017 Screeps now uses auth tokens obtained via your screeps account settings. User/pass auth will stop working February 1, 2018! Screeps Announcement

CLI Usage

As of 1.7.0, a small CLI program (screeps-api) is included.

Server config is specified via a .screeps.yml file conforming to the Unified Credentials File format


  Usage:  [options] [command]


    -V, --version                output the version number
    --server <server>            Server config to use (default: main)
    -h, --help                   output usage information


    raw <cmd> [args...]          Execute raw API call
    memory [options] [path]      Get Memory contents
    segment [options] <segment>  Get segment contents. Use 'all' to get all)
    download [options]           Download code
    upload [options] <files...>  Upload code

API Usage

As of 1.0, all functions return Promises

const { ScreepsAPI } = require('screeps-api');
const fs = require('fs');

// Supports @tedivm's [Unified Credentials File format]( (Pending [screepers-standard PR #8](
const api = await ScreepsAPI.fromConfig('main', 'appName')
// This loads the server config 'main' and the configs section 'appName' if it exists
// config section can be accessed like this:
// If making a CLI app, its suggested to have a `--server` argument for selection

// All options are optional
const api = new ScreepsAPI({
  token: 'Your Token from Account/Auth Tokens'
  protocol: 'https',
  hostname: '',
  port: 443,
  path: '/' // Do no include '/api', it will be added automatically

// You can overwrite parameters if needed
  protocol: 'https',
  hostname: '',
  port: 443,
  path: '/' // Do no include '/api', it will be added automatically

// If you want to point to the screeps PTR (Public Test Realm),
// you can set the 'path' option to '/ptr' and it will work fine.

// Dump Memory
  .then(memory => {
    fs.writeFileSync('memory.json', JSON.stringify(memory))
  .catch(err => console.error(err));

// Dump Memory Path
  .then(memory => {
    fs.writeFileSync('memory.rooms.W0N0.json', JSON.stringify(memory))
  .catch(err => console.error(err));

// Get user info>console.log(user))

// Socket API

// Events have the structure of:
// {
//   channel: 'room',
//   id: 'E3N3', // Only on certain events
//   data: { ... }
// }
	// Do stuff after connected
api.socket.on('auth',(event)=>{ contains either 'ok' or 'failed'
	// Do stuff after auth

// Events: (Not a complete list)
// connected disconnected message auth time protocol package subscribe unsubscribe console

// Subscribtions can be queued even before the socket connects or auths,
// although you may want to subscribe from the connected or auth callback to better handle reconnects

api.socket.on('console',(event)=>{ // List of console.log output for tick

// Starting in 1.0, you can also pass a handler straight to subscribe!
api.socket.subscribe('console', (event)=>{ // List of console.log output for tick

// More common examples
	main: 'module.exports.loop = function(){ ... }'
	console.log('E0N0 Memory',

Endpoint documentation

Server endpoints are listed in the docs folder:

You can’t perform that action at this time.