This guide provides an overview of how to load credentials and configuration options for ScreepsHttpClient and ScreepsSocketClient.

Supported File Formats

We recommend using the SS3 Screeps Unified Credential File format for your applications and tools. If you only have a screeps.json file, that format is also supported since v2.0.

Config File Paths

ScreepsConfigManager.loadConfig is used to find and load config files. searches for config files in a number of places.

If the SCREEPS_CONFIG environment variable is defined, the path it defines will be searched first.

If SCREEPS_CONFIG is undefined or does not point to a file, the config manager searches the following directories:

1. The current working directory
2. The user's HOME directory
3. Windows only: %APPDATA%
4. Linux/FreeBSD/OpenBSD only: ${XDG_CONFIG_HOME:-"${HOME}/.config"}
5. macOS only: ~/Library/Application Support

In each directory, it checks each of the following paths:

1. screeps/config.yaml
2. screeps/config.yml
3. .screeps.yaml
4. .screeps.yml
5. .screeps.json
6. screeps.json

If a YAML file exists at any of the default paths, the config manager will try to load it before attempting to load any JSON files.

The paths mentioned above may be outdated. You can get a complete, ordered list of the paths that will be searched by checking ScreepsConfigManager.defaultPaths:

import { ScreepsConfigManager } from 'screeps-api'

const manager = new ScreepsConfigManager()
console.log(manager.defaultPaths)
Copy

If your credential file is not located at any of the default locations and you'd prefer not to move it, you can also specify the correct path in LoadConfigOptions:

manager.loadConfig('main', { file: '/home/me/projects/myScreepsConfig.yaml' })
Copy

Configuring a Client

Let's suppose we have the following SS3 credential file in a place where ScreepsConfigManager can find it:

servers:
  main:
    host: screeps.com
    secure: true
    token: "35a345b9-bc6b-4855-8566-66b341913f9b"
  ptr:
    host: screeps.com
    secure: true
    token: "17f70980-eceb-46ba-a4c3-9677a1570f06"
    ptr: true
  screepsplus:
    host: screepspl.us
    secure: true
    port: 443
    username: bob
    password: password123
  myserv:
    host: 127.0.0.1
    secure: false
    username: bob
    password: password123
configs:
  screepsconsole:
    maxHistory: 20000
    maxScroll: 20000
  screepsplus-agent:
    token: screepsPlusToken
    checkForUpdates: false
  nuke-announcer:
    slack:
      webhook: "https://..."
      channel: "#thewarpath"
  nuke-announcer-sp:
    slack:
      webhook: "https://..."
      channel: "#screepsplus-warpath"
Copy

Configuration data can be passed to the client in a number of different ways.

One approach is new ScreepsHttpClient():

import { ScreepsConfigManager, ScreepsHttpClient } from 'screeps-api'

const manager = new ScreepsConfigManager()
const config = await manager.loadConfig('screepsplus', { app: 'nuke-announcer' })
const api = new ScreepsHttpClient(config)

console.log(api.server.url) // => https://screepspl.us/

// appConfig properties not used by node-screeps-api are typed as unknown,
// so type narrowing or type assertions are necessary to use them in TypeScript.
interface SlackWebhookConfig {
  slack: {
    webhook: string
    channel: string
  }
}

const appConfig = api.appConfig as SlackWebhookConfig
console.log(api.appConfig.slack.channel) // => #thewarpath
Copy

You can also pass configuration objects you create yourself:

const api = new ScreepsHttpClient({
  server: {
    token: 'Your Token from Account/Auth Tokens'
    protocol: 'https',
    hostname: 'screeps.com',
    port: 443,
    path: '/' // Do no include '/api', it will be added automatically
  }
});
Copy

If you are loading your credentials and server config directly from a file, it's more convenient to use ScreepsHttpClient.fromConfig():

import { ScreepsHttpClient } from 'screeps-api'

const api = await ScreepsHttpClient.fromConfig('screepsplus', { app: 'nuke-announcer' })
Copy

If you want to use a client configuration that is not available in your config file, you can pass those options directly instead of using an app name:

const api = await ScreepsHttpClient.fromConfig('screepsplus', { app: {
  defaultShard: 'shard2',
  retry429MaxRetries: 6
} })
Copy

The HTTP client can also be reconfigured after initialization:

import { ScreepsConfigManager, ScreepsHttpClient } from 'screeps-api'

const manager = new ScreepsConfigManager()
const config = await manager.loadConfig('screepsplus', { app: 'nuke-announcer' })
const api = new ScreepsHttpClient(config)

// ... operations on the screepsplus server ...

// Switch to MMO server (Config.parsed contains the full contents
// of the loaded credential file)
api.setServer(config.parsed.main)

// Keep previous nuke-announcer config, set a default shard,
// and enable automatic retries on HTTP 429 errors:
api.appConfig = {
  ...api.appConfig,
  defaultShard: 'shard2',
  retry429MaxRetries: 6
}
Copy

WebSocket API Config

ScreepsSocketClient leverages the HTTP client for auth credentials, but WebSocket-specific client params can be provided via ScreepsSocketClient.connect():

await api.socket.connect({
  // Don't automatically reconnect
  reconnect: false,
  // Don't ping the server to keep the connection open
  keepAlive: false
})
Copy

See ScreepsSocketConfig for a full list of options.