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: |
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()
andcode.subscribe()
functions). -
consoleObject
-
Provide methods to execute and console commands and get results (see
console.execute()
andconsole.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()
andmemory.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");
- All files are supposed to be UTF-8 encoded.
-
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)
-
cpu
-
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 }