Currently known endpoints are listed below.

• This list is clearly not exhaustive and comes from empirical observations.
• If you want to add more data, feel free to make a pull request.

Shards

Any subscription taking a room name is different on servers with shards, the room name should be prefixed with the shard name ex shard0/E0N0.

Note that adding a shard to a server not expecting it may cause an error.

Subscribing to web sockets endpoints

• Connect the socket and wait for connection establishment using api.socket.connect().
• You can then subscribe to different endpoints using api.socket.subscribe().
• The server will then send periodic events with requested information.

Complete example:

// If installed from npm, use:
// import { ScreepsHttpClient } from 'screeps-api'
import { ScreepsHttpClient, UserConsoleEvent, UserCpuEvent } from '../src';

// Instantiate client from config file and connect to the WebSocket API
const api = await ScreepsHttpClient.fromConfig('main')
await api.socket.connect()

// Subscribe to 'cpu' event path and register a callback separately
api.socket.subscribe('cpu')
api.socket.on('cpu', (event: UserCpuEvent) => {
  // CPU and Memory usage from the previous tick
  const { cpu, memory } = event.data;
  console.log(`CPU used: ${cpu}; Memory used: ${(memory / 1024).toFixed(1)} KiB`)
});

// You can also pass a callback directly to subscribe()
api.socket.subscribe('console', (event: UserConsoleEvent) => {
  const { messages, error, shard } = event.data
  const shardTag = shard ? `[${shard}]` : undefined
  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.forEach(console.info)

  // `POST /api/user/console` results from the previous tick
  messages.results.map(r => `< ${r}`).forEach(console.info)
})
Copy

code

Description:

Once subscribed, the server will send a new event with full code base every time code base changes.

Parameters of event.data:

Name	Type	Description
branch	String	Name of the updated branch
modules	Object	Map of files (using file name as key and file content as value)
timestamp	Number	Date of the modification expressed as the number of milli-seconds since 01/01/1970
hash	Number	Some kind of hash, I guess ? (don't ask me how to compute it #FIXME)

Example:

// Subscription
api.socket.subscribe('code', event => console.log(JSON.stringify(event.data)));
Copy

// Results
{
    "branch": "simulation",
    "modules":{
        "main":"console.log(\"Hello world!\");\n",
        // other modules...
    },
    "timestamp": 1500930041802,
    "hash": 424324
}
Copy

console

Description:

Once subscribed, the server will send a new event every tick with console logs and return value of commands (if any).

Parameters of event.data:

Name	Type	Description
messages.log	Array	Lines shown in console (like if printed by console.log())
messages.results	Array	Array of command results

Example:

// Subscription
api.socket.subscribe('console', event => console.log(JSON.stringify(event.data)));
Copy

// Results after executing `Game.time` in game:
{
    "messages": {
        "log": [],
        "results": ["16746996"]
    }
}
// (`Game.time` does not show any log in the console, which is why `messages.log` is empty)
Copy

cpu

Description:

Once subscribed, the server will send a new event every tick with cpu and memory usage.

Parameters of event.data:

Name	Type	Description
cpu	Number	Cpu used last tick
memory	Number	Current memory usage

Example:

// Subscription
api.socket.subscribe('cpu', event => console.log(JSON.stringify(event.data)));
Copy

// Results every tick
{
    "cpu": 32,
    "memory": 126435
}
Copy

room:ROOM_NAME

Description:

Once subscribed, the server will send a new event every tick with the RoomObjects of present in selected room (ROOM_NAME). RoomObjects seem to have the same properties as within game scripts.

Atention, only the first event actually returns the object full properties. Subsequent events only return the modified properties.

Parameters of event.data:

Name	Type	Description
objects	Object	Map of RoomObjects indexed by id
gameTime	Number	Current game tick
info	Object	Contains game mode (usually "world")
visual	Object	Room visuals (contents currently unknown #FIXME)

Example:

// Subscription
api.socket.subscribe('room:W7N7', event => console.log(JSON.stringify(event.data))); // For non-sharded servers
api.socket.subscribe('room:shard0/W7N7', event => console.log(JSON.stringify(event.data))); // For sharded servers
Copy

// First event results:
{
    "objects": {
        "58dbc28b8283ff5308a3c0ba": {
            "_id": "58dbc28b8283ff5308a3c0ba",
            "room": "W97S73",
            "type": "source",
            "x": 12, "y": 14,
            "energy": 1908,
            "energyCapacity": 3000,
            "ticksToRegeneration": 300,
            "nextRegenerationTime": 20308471,
            "invaderHarvested": 45324
        },
       "59663a8e82b5ab1b911ca1a9": {
           "_id": "59663a8e82b5ab1b911ca1a9",
           "type": "road",
           "x": 17,"y": 42,
           "room": "W97S73",
           "notifyWhenAttacked": true,
           "hits": 22080,
           "hitsMax": 25000,
           "nextDecayTime": 20308833
       },
       // other RoomObjects...
    },
    "gameTime": 20307112,
    "info": { "mode": "world" },
    "visual": ""
}
Copy

// Results for subsequent events:
{
    "objects": {
        "58dbc28b8283ff5308a3c0ba": { "energy": 948, "invaderHarvested": 34284 },
        "5967d460eebe3d6404c26852": { "nextDecayTime": 20307861 },
        // Other modified RoomObjects...
    },
    "gameTime": 20307112,
    "info": { "mode": "world" },
    "visual": ""
}
Copy