Class: API

API

Class representing the API.

Properties and functions begining with an underscore are low level objects exposed for users who know what they are doing and should generally not be used.

They are provided and documented for some specific situations like when you need to extent the API.

For information, tedivm has make a good summary of screeps server api detail on python-screeps

new API(email, password, server)

API constructor.
Required the user credentials in order to connect to the server (but connection occurs later on).

Name Type Default Description
email string

Account email address

password string

Account password

server string http://screeps.com optional

Server adress (ex: http://127.0.0.1:21025)

Extends

  • EventEmitter

Members

_emailstring

Account email.

_passwordstring

Account password.

_serverstring

Game server address including protocole and port.

_tokenstring

Authorization token (sent after authentication by the server).

codeObject

Provide methods to get and set user code (see code.push() and code.subscribe() functions).

consoleObject

Provide methods to execute and console commands and get results (see console.execute() and console.subscribe() functions).

leaderboardObject

Provide methods to access leaderboard statistics (see leaderboard.xxx() functions).

marketObject

Provide methods to access market data and statistics (see market.xxx() functions).

memoryObject

Provide methods to access memory (see memory.get() and memory.set() functions).

timeObject

Provide methods to get game data time (see time.get() function).

userObject

Provide methods to get user data and statistics (see user.xxx() functions).

Methods

_authenticate(){Promise}

Authenticate with the server in HTTP and get/save session token.

Returns:
Type Description
Promise Return a promise eventually resolved with autorization token given by the server.
Example

Initialization and authententication:

let API = require("screeps-js-api");
new API("user@maiL.com", "password");
api.authenticate();

_connect(){Promise}

Connect to server web socket.

Returns:
Type Description
Promise Promise eventually resolved when connection is confirmed and user authenticated.
Example
api._connect();

_disconnect(){Promise}

Disconnect the web socket (if connected).

Returns:
Type Description
Promise Promise eventually resolved when disconnection is confirmed.
Example
api._disconnect();

_subscribe(path){Promise}

Subscribe to the given socket path ("/console", "/memory", "/rom"...).

Name Type Description
path string

The path with a leading "/"

Returns:
Type Description
Promise Promise eventually resolved when message is sent.
Example
api._subscribe.("/code");

code.push(files, branch){Promise}

Push code to the given branch on the server.

  • All files are supposed to be UTF-8 encoded.
  • Does not read folders, only files.
    Query the /api/user/code server endpoint.
Name Type Description
files array.<string>

An array of file name to commit (any other file will be deleted on the server).

branch string

The name of the branch to push code to.

Returns:
Type Description
Promise Promise eventually resolved when upload finishes.
Example
let api = new API(email, password, server);
api.code.push(["file_1.js", "file_2.js"], "simulation");

code.subscribe(){Promise}

Subscribe to the /code endpoint.
Api will then emit events when code is changed on the server.

Fires:
  • API#event:code
Returns:
Type Description
Promise Promise eventually resolved once message sent.
Example
let api = new API(email, password, server);
api.on("console", (data) => console.log(JSON.stringify(data)));
api.code.subscribe().then(() => console.log("ok"));

console.execute(command){Promise}

Send a console command to execute.
Query the /api/user/console server endpoint.

Name Type Description
command string

The command to send (as a string).

Returns:
Type Description
Promise Promise eventually resolved when command is sent.
Example
let api = new API(email, password, server);
api.console.execute("console.log('Hello world')");

console.subscribe(){Promise}

Subscribe to the /console endpoint.
Api will then emit events every tick with executed commands (even out of the API) and results.

Fires:
Returns:
Type Description
Promise Promise eventually resolved once message sent.
Example
let api = new API(email, password, server);
api.on("console", (data) => console.log(JSON.stringify(data)));
api.console.subscribe().then(() => console.log("ok"));

leaderboard.find(username, season){Promise}

Get user statistics for the given season.
Query the /api/leaderboard/find server endpoint.

Name Type Description
username string

User name to look at.

season string

Season in the following format: YYYY-MM.

Returns:
Type Description
Promise Promise eventually resolved with the user stats.
Examples
// Script:
let api = new API(email, password, server);
api.leaderboard.find(USER_NAME, "2017-01").then(JSON.stringify).then(console.log);
// Results:
{ "ok": 1, "_id":"586846a0ec0e632daa907bfb", season": "2017-01",
  "user":"00000000000000000000000", "score":1855700, "rank": 883 }

leaderboard.list(limit, offset, season){Promise}

Get the list of top players. Query the /api/leaderboard/list server endpoint.

Name Type Description
limit number

Number of players to show.

offset number

Offset to start at.

season string

Season in the following format: YYYY-MM.

Returns:
Type Description
Promise Promise eventually resolved with the list.
Examples
// Script:
let api = new API(email, password, server);
api.leaderboard.list(10, 100, "2017-01").then(JSON.stringify).then(console.log);
// Results:
[ { "_id": "586846a0ec0e632daa907724", "season":"2017-01",
    "user":"5569aa587401fd4155440afa","score":34059838,"rank":100 },
  { "_id": "586846a0ec0e632daa9076d9", "season":"2017-01",
    "user":"579a8ce3ee9e0fb54b18cc4d", "score":33968274,"rank":101 },
  // ... (up to rank 110)

leaderboard.seasons(){Promise}

Get a list of the game seasons (one season = one month).
Query the /api/leaderboard/seasons server endpoint.

Returns:
Type Description
Promise Promise eventually resolved with the seasons list.
Examples
// Script:
let api = new API(email, password, server);
api.leaderboard.seasons().then(JSON.stringify).then(console.log);
// Results:
[
   {"_id":"2017-01","name":"January 2017","date":"2017-01-01T00:00:03.681Z"},
   {"_id":"2016-12","name":"December 2016","date":"2016-12-01T00:00:05.105Z"},
   // ...

market.history(){Promise}

Get user transaction history.
Query the /api/user/money-history server endpoint.

Returns:
Type Description
Promise Return a promise eventually resolved with the list of transactions.
Examples
// Script:
let api = new API(email, password, server);
api.market.history().then(JSON.stringify).then(console.log);
// Results:
[ {  _id: '5879547305128b021d4ee1d5', date: '2017-01-13T22:28:03.006Z', tick: '16726004',
     user: '000000000000000000000000', type: 'market.sell', balance: 64650, change: 450,
     market: { resourceType: 'O', roomName: 'W30N0', targetRoomName: 'W78N36',
               price: 0.45, npc: true, amount: 1000 } },
{    _id: '58794ed205128b021d4acfcf', date: '2017-01-13T22:04:02.260Z', tick: '16725625',
     user: '000000000000000000000000', type: 'market.sell', balance: 64200, change: 450,
     market: { resourceType: 'O', roomName: 'W60N0', targetRoomName: 'W78N36',
               price: 0.45, npc: true, amount: 1000 } },
  // ...

market.index(){Promise}

Get number of market order for each resourceType.
Query the /api/game/market/orders-index server endpoint.

Returns:
Type Description
Promise Promise eventually resolved with an array of orders count (see example).
Examples
// Script:
let api = new API(email, password, server);
api.market.index().then(JSON.stringify).then(console.log);
// Results:
[ { _id: 'GH2O', count: 1 },
  { _id: 'LH2O', count: 2 },
  { _id: 'XUHO2', count: 24 },
  // ...

market.orders(resourceType){Promise}

Get the lsit of market orders for given resourceType.
Query the /api/game/market/orders server endpoint.

Name Type Description
resourceType ResourceType

Reserouce type to query (one of the game RESOURCE_* values).

Returns:
Type Description
Promise Promise eventually resolved with an array of orders.
Examples
// Script:
let api = new API(email, password, server);
api.market.orders("energy").then(JSON.stringify).then(console.log);
// Results:
[ { _id: '581c5a8c580572317d776c98', type: 'buy', remainingAmount: 259,
      amount: 259, price: 0.04, roomName: 'E1S54' },
  { _id: '581c5a8c580572317d776c9c', type: 'buy', amount: 592,
      remainingAmount: 592, price: 0.04, roomName: 'E3S54' },
  // ...

market.stats(resourceType){Promise}

Get market statistics for given resourceType.
Query the /api/game/market/stats server endpoint.

Name Type Description
resourceType ResourceType

Reserouce type to query (one of the game RESOURCE_* values).

Returns:
Type Description
Promise Promise eventually resolved with an array of stats (one per day).
Examples
// Script:
let api = new API(email, password, server);
api.market.stats("energy").then(JSON.stringify).then(console.log);
// Results:
[ { _id: '587a7b197401dbc73aa28fb1', resourceType: 'energy', date: '2017-01-14',
      transactions: 2003, volume: 6407767, avgPrice: 0.06, stddevPrice: 0.02 },
  { _id: '587a7b197401dbc73aa28fb0', resourceType: 'energy', date: '2017-01-13',
      transactions: 3149, volume: 9359438, avgPrice: 0.06, stddevPrice: 0.02 },
  // ...

memory.get(path){Promise}

Get memory for requested path.
Query the /api/user/memory server endpoint.

Name Type Description
path string optional

Memory path to get.

Returns:
Type Description
Promise Promise eventually resolved with the memory contents.
Example
let api = new API(email, password, server);
api.memory.get("stats.room.E1N1").then(JSON.stringify).then(console.log);

memory.set(path, value){Promise}

Set memory for requested path.
Autenticate user if needed.
Query the /api/user/memory server endpoint.

Name Type Description
path string

Memory path to set.

value Object | undefined

Object to set (or undefined to delete the path).

Returns:
Type Description
Promise Promise eventually resolved once done.
Example
let api = new API(email, password, server);
api.memory.set("stats.room.E1N1", undefined).then(JSON.stringify).then(console.log);

time.get(){Promise}

Get game time in ticks.
Query the /api/game/time server endpoint.

Returns:
Type Description
Promise Promise eventually resolved with the time as a number of ticks.
Examples
// Script:
let api = new API(email, password, server);
api.time.get().then(console.log);
// Results:
16746363

user.findById(id){Promise}

Get general information for another user by id.
Query the /api/user/find server endpoint.

Name Type Description
id string

User id to look for.

Returns:
Type Description
Promise Promise eventually resolved with requested user data.
Examples
// Script:
let api = new API(email, password, server);
api.user.findById("user_id").then(JSON.stringify).then(console.log);
// Results:
{ "_id":"000000000000000000000000", "steam": { "id":"00000000000000000" },
    "username":"xxxxxx", "gcl":000000,
    "badge":{ "type":00, "color1":"#000000", "color2":"#000000", "color3":"#000000", "param":0, "flip":false } }

user.findByName(username){Promise}

Get general information for another user by name.
Query the /api/user/find server endpoint.

Name Type Description
username string

User name to look for (not case sensitive).

Returns:
Type Description
Promise Promise eventually resolved with requested user data.
Examples
// Script:
let api = new API(email, password, server);
api.user.findByName("user_name").then(JSON.stringify).then(console.log);
// Results:
{ "_id":"000000000000000000000000", "steam": { "id":"00000000000000000" },
    "username":"xxxxxx", "gcl":000000,
    "badge":{ "type":00, "color1":"#000000", "color2":"#000000", "color3":"#000000", "param":0, "flip":false } }

user.me(){Promise}

Get generic user information like subscribtion, authentication, stats, etc.
Query the /api/auth/me server endpoint.

Returns:
Type Description
Promise Promise eventually resolved with user data (see example).
Examples
// Script:
let api = new API(email, password, server);
api.user.me().then(JSON.stringify).then(console.log);
// Results:
{ ok: 1,  _id: '000000000000000000000000',
  email: 'xxxxx@xxxxx.xxx', username: 'xxxxxx', password: true,
  subscription: true, promoPeriodUntil: 0000000000000, subscriptionTokens: 0, credits: 0,
  badge: { type: 00, color1: '#000000', color2: '#000000', color3: '#000000', param: 0, flip: false },
  lastRespawnDate: 0000000000000, cpu: 000, gcl: 0000000, money: 000000,
  steam: { id: '00000000000000000', displayName: 'xxxxxx', ownership: [ 000000 ] } }

user.overview(statName, interval){Promise}

Get user global statistics.
Query the /api/user/overview server endpoint.

Name Type Default Description
statName StatName

Name of the stat to get (ex: energyHarvested).

interval number 8 optional

Time interval for aggregating stats (8, 180 or 1440, nothing else).

Returns:
Type Description
Promise Promise eventually resolved with requested stats.
Examples
// Script:
let api = new API(email, password, server);
api.user.overview("energyHarvested", 8).then(JSON.stringify).then(console.log);
// Results:
{ "W78N36":[
    {"value":1704, "endTime":3092527},
    {"value":1368, "endTime":3092528}
    // ... (8 times)
] }

user.rooms(id){Promise}

Get the list of owned rooms for given user id. Query the /api/user/rooms server endpoint.

Name Type Description
id string

User id to look for.

Returns:
Type Description
Promise Promise eventually resolved with the room list.
Examples
// Script:
let api = new API(email, password, server);
api.user.rooms("user_id").then(JSON.stringify).then(console.log);
// Results:
["W78N36"]

user.roomsStats(rooms, statName, interval){Promise}

Get statistics for the given rooms name.
Query the /api/game/map-stats server endpoint.

Name Type Default Description
rooms Array.<string>

Array of rooms name.

statName StatName

?

interval number 8 optional

Time interval for aggregating stats (8, 180 or 1440, nothing else).

Returns:
Type Description
Promise Promise eventually resolved with requested stats.
Examples
// Script:
let api = new API(email, password, server);
api.user.roomsStats(["W78N36"], undefined, 8).then(JSON.stringify).then(console.log);
// Results:
{ "W78N36": {
    "status": "normal", "novice": TIME_BEFORE_NOVICE_ENDS,
    "own": { "user": USER_ID, "level": RCL_LEVEL }
} }

user.subscribe(){Promise}

Subscribe to the /cpu endpoint.
Api will then emit events every tick with CPU and memory usage.

Fires:
Returns:
Type Description
Promise Promise eventually resolved once message sent.
Example
let api = new API(email, password, server);
api.on("cpu", (data) => console.log(JSON.stringify(data)));
api.user.subscribe();

Events

console

Event broadcasted every tick (if subscribed) with exectued commands and results.

Properties:
Name Type Description
cpu number

CPU used last tick

memory number

Memory currently used

Examples
// Script:
api.on("console", (data) => console.log(JSON.stringify(data)));
// 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)

Event broadcasted every tick (if subscribed) with user CPU and memory data.

Properties:
Name Type Description
messages object
Properties
Name Type Description
log array

Lines shown in console (like if printed by console.log())

results array

Array of console results

Examples
// Script:
api.on("cpu", (data) => console.log(JSON.stringify(data)));
// Results:
{ "cpu": 32, "memory": 126435 }