Class: API

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} api.js.html, line116

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} api.js.html, line215

Connect to server web socket.

Returns:

Type	Description
Promise	Promise eventually resolved when connection is confirmed and user authenticated.

Example

api._connect();

_disconnect(){Promise} api.js.html, line255

Disconnect the web socket (if connected).

Returns:

Type	Description
Promise	Promise eventually resolved when disconnection is confirmed.

Example

api._disconnect();

_subscribe(path){Promise} api.js.html, line316

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} api.js.html, line348

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} api.js.html, line376

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} api.js.html, line397

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} api.js.html, line410

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

Fires:

API#event:console

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} api.js.html, line455

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} api.js.html, line480

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} api.js.html, line437

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} api.js.html, line632

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} api.js.html, line569

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} api.js.html, line589

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} api.js.html, line609

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} api.js.html, line528

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} api.js.html, line542

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} api.js.html, line507

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} api.js.html, line737

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} api.js.html, line719

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} api.js.html, line661

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} api.js.html, line699

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} api.js.html, line753

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} api.js.html, line774

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} api.js.html, line678

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

Fires:

API#event:cpu

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 api.js.html, line39

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)

cpu api.js.html, line25

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 }