Screeps API

This is a Node.js API for the game Screeps

Application Usage

As of v1.0, all endpoint methods are asynchronous.

import { ScreepsHttpClient, ScreepsSocketClient } from 'screeps-api'
import { writeFile } from 'node:fs/promises'

// `ScreepsHttpClient.fromConfig()` finds your configuration file and picks
// server and client configs from it.
// It supports @tedivm's Unified Credentials File format
// (https://github.com/screepers/screepers-standards/blob/master/SS3-Unified_Credentials_File.md)
// and screeps.json
// (https://github.com/screepers/screeps-typescript-starter/blob/master/screeps.sample.json)

// This example initializes the HTTP client using the `servers` section 'main'
// and the `configs` section 'nuke-announcer' from the config file.
// In a real application, consider reading the server/app names from env vars,
// or accepting `--server <serverName>` and `--app <appName>` CLI arguments.
const api = await ScreepsHttpClient.fromConfig('main', { app: 'nuke-announcer' })

// Client config can be accessed like this:
console.log(api.appConfig)

// HTTP API

// Dump entire Memory object to a file
api.userMemoryGet()
  .then(memory => {
    writeFile('memory.json', JSON.stringify(memory), { encoding: 'utf-8' })
  })
  .catch(console.error)

// Dump a subset of Memory to a file
api.userMemoryGet('rooms.W0N0')
  .then((memory) => {
    writeFile('memory.rooms.W0N0.json', JSON.stringify(memory), { encoding: 'utf-8' })
  })
  .catch(console.error)

// Get user info
api.authMe().then(me => console.log('My user info:', me)).catch(console.error)

// Download code from the "default" branch and log it
api.userCodeGet('default')
  .then((data) => console.log('My code:', JSON.stringify(data, undefined, 2)))
  .catch(console.error)

// Upload code to the "apiDemo" branch
api.userCodeSet({
  branch: 'apiDemo',
  modules: {
    main: 'module.exports.loop = function() { console.log("Hello, world!") }'
  }
}).catch(console.error)

// WebSocket API

// Connect and authenticate
await api.socket.connect()

// Events follow this format:
// {
//   type: 'room',
//   id: 'shard0', // Only on certain events, otherwise undefined
//   path: 'E3N3', // Only on certain events, otherwise an empty string
//   data: { ... }
// }
api.socket.on(ScreepsSocketClient.CONNECTED, () => {
  console.log('WebSocket client connected')
})
api.socket.on(ScreepsSocketClient.DISCONNECTED, () => {
  console.log('WebSocket client disconnected')
})
api.socket.on(ScreepsSocketClient.AUTH, (event) => {
  // Contains either 'ok' or 'failed'
  console.log('WebSocket auth:', event.data.status)
})

// Subscriptions can be queued even before the client connects or auths
function onConsole(event) {
  const { messages, error, shard } = event.data
  const shardTag = shard ? `[${shard}] ` : ''
  if (error) console.error(shardTag + error)

  // messages is undefined if nothing was logged or evaluated
  if (!messages) return

  // `console.log()` output from the previous tick
  messages.log.map(l => shardTag + l).forEach(console.info)

  // `POST /api/user/console` results from the previous tick
  messages.results.map(r => `< ${r}`).forEach(console.info)
}
api.socket.subscribe('console')
api.socket.on('console', onConsole)

// Starting in v1.0, you can also pass a handler straight to subscribe!
api.socket.subscribe('console', onConsole)

// Starting in v2.0, you can use specialized subscribe methods for each known
// event type. These specialized versions automatically determine the correct
// event string to use and provide better type safety for callback arguments.
api.socket.subscribeUserConsole(onConsole)

// ScreepsSocketClient tracks which callbacks are registered for which events.
// By default, `subscribe` and its specialized versions will ignore duplicate
// callbacks for any given event, so after running all of the previous examples,
// `onConsole` will still only be invoked once per `UserConsoleEvent`.

// Watch CPU/Memory usage
api.socket.subscribeUserCpu((event) => {
  console.log('CPU used:', event.data.cpu)
  console.log('Memory used (bytes):', event.data.memory)
})

// Watch for updates to Memory paths
api.socket.subscribeUserMemory('stats', (event) => {
  console.log('Memory.stats:', JSON.stringify(event.data, undefined, 2))
})
api.socket.subscribeUserMemory('rooms.E0N0', (event) => {
  console.log('Memory.rooms.E0N0:', JSON.stringify(event.data, undefined, 2))
})
Copy

CLI Usage

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

Server/auth credentials are located using ScreepsConfigManager.loadConfig(). All commands aside from help accept a --server <name> option to specify the name of the server to use from your config file.

> screeps-api --help
Usage: screeps-api [options] [command]

Options:
  -V, --version                   output the version number
  -h, --help                      display help for command

Commands:
  call [options] <cmd> [args...]  Call an API endpoint method on ScreepsHttpClient
  memory [options] [path]         Read from or write to Memory
  segment [options] <segments>    Read or write RawMemory segments
  download [options]              Download code and WASM binaries
  upload [options] <files...>     Upload code and WASM binaries
  help [command]                  display help for command
Copy

Endpoint Documentation

Check the docs for a detailed list of supported endpoints:

• HTTP API: ScreepsHttpClient
• WebSocket API: ScreepsSocketClient

Please note that the listed endpoints and WebSocket events are not exhaustive.

Development

First, make sure you're using a compatible version of Node.js. We recommend installing a node version manager like nvm or a general runtime version manager like asdf, mise-en-place, etc. Once you have one of these installed and configured for node, ensure you have the target version of node installed:

# nvm example:
nvm install "$(cat .node-version)"
Copy

This project uses the yarn package manager. The correct yarn version is pinned in package.json using corepack. To ensure you're using the correct version of yarn instead of the legacy v1.x:

# Enable corepack: https://yarnpkg.com/corepack
corepack enable

# If using asdf, update node shims after enabling corepack:
# https://github.com/asdf-vm/asdf-nodejs#corepack
if [[ -n "$(which asdf)" ]] ; then asdf reshim nodejs ; fi

# Install dependencies using the version of yarn from package.json's
# "packageManager" field:
yarn install
Copy

Configuration

The documentation goes into detail on how to set up a configuration file, but the simplest way to get started is to copy a screeps.yaml or screeps.json file to the repo root directory.

Running Scripts

tsx is used to execute TypeScript scripts without having to run tsc to transpile them:

# Run an example script
yarn exec tsx examples/console.ts

# Run the screeps-api CLI tool
yarn exec tsx bin/screeps-api.ts call version

# package.json defines a cli script to make testing the CLI more convenient.
# The following command is functionally identical to the previous one:
yarn cli call version
Copy