{"id":19299183,"url":"https://github.com/bmatcuk/starbound.js","last_synced_at":"2025-04-22T09:32:55.901Z","repository":{"id":57369472,"uuid":"64518099","full_name":"bmatcuk/starbound.js","owner":"bmatcuk","description":"A Starbound RCON client","archived":false,"fork":false,"pushed_at":"2016-08-04T21:38:48.000Z","size":15,"stargazers_count":3,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-15T13:50:22.733Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bmatcuk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-07-30T00:35:38.000Z","updated_at":"2021-02-15T20:34:00.000Z","dependencies_parsed_at":"2022-08-26T04:51:48.145Z","dependency_job_id":null,"html_url":"https://github.com/bmatcuk/starbound.js","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmatcuk%2Fstarbound.js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmatcuk%2Fstarbound.js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmatcuk%2Fstarbound.js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmatcuk%2Fstarbound.js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bmatcuk","download_url":"https://codeload.github.com/bmatcuk/starbound.js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250215385,"owners_count":21393788,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T23:10:27.072Z","updated_at":"2025-04-22T09:32:55.647Z","avatar_url":"https://github.com/bmatcuk.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![license](https://img.shields.io/npm/l/starbound.js.svg?style=flat-square)](https://www.npmjs.com/package/starbound.js)\n[![npm version](https://img.shields.io/npm/v/starbound.js.svg?style=flat-square)](https://www.npmjs.com/package/starbound.js)\n[![npm downloads](https://img.shields.io/npm/dm/starbound.js.svg?style=flat-square)](https://www.npmjs.com/package/starbound.js)\n\n# starbound.js\nA Starbound RCON client\n\nThis client is fairly barebones at the moment as it's under active development.\nHowever, some basic functionality is working...\n\n## Install\nInstall via npm:\n\n```bash\nnpm install --save starbound.js\n```\n\n## Example Code\nHere's some sample code to get you started...\n\n```javascript\nvar Starbound = require('starbound.js');\n\nvar sb = new Starbound(host, port);\nsb.timeout = 30000;\n\nsb.on('close', function(dueToError) {\n  console.log('Connection to Starbound has been closed.');\n});\n\nsb.on('timeout', function() {\n  console.log('Connection timed out.');\n});\n\nsb.on('error', function(err) {\n  console.log(\"There's been an error:\", err.message);\n});\n\nsb.connect('password', function(successful) {\n  if (successful) {\n    console.log('Successfully connected to Starbound');\n\n    sb.listUsers(function(message) {\n      message.users.forEach(function(info) {\n        console.log(info.clientId, info.username, info.uuid);\n      });\n      sb.disconnect();\n    });\n  }\n});\n```\n\n## Basic Functionality\nBasic functionality is implemented by these functions:\n\n* `new Starbound(host, port, options)`\n  \u003e Create a new instance of the Starbound RCON client.\n  \u003e\n  \u003e * `host` - the host to connect to _(default: localhost)_\n  \u003e * `port` - the port to connect to _(default: 21026)_\n  \u003e * `options`\n  \u003e   * `timeout` - socket timeout in milliseconds _(default: 0 meaning \"never\")_\n  \u003e     Note that this timeout only affects _our_ side of the connection.\n  \u003e     Starbound will timeout its side eventually.\n\n* `sb.connect(password, callback)`\n  \u003e Connects to the server\n  \u003e\n  \u003e `function callback(success)` _(optional)_\n  \u003e * Called after attempting to connect. If `success` is true, authentication\n  \u003e   was successful.\n\n* `sb.disconnect()`\n  \u003e Disconnect from the server.\n\n* `sb.timeout`\n  `sb.timeout = X`\n  \u003e Get or set the socket timeout in milliseconds (see `options.timeout` in the\n  \u003e constructor).\n\n* `sb.connected`\n  \u003e Is `true` if the server is currently connected; `false` otherwise.\n\n## Supported Commands\nThe following commands are supported. I can't find any \"official\" list of RCON\ncommands for Starbound, so I've only implemented the commands I'm aware of. If\nI'm missing any, or if one of these commands no longer work, please submit an\n[issue].\n\nPlease note: I haven't tested all of these functions... I haven't had a need\nto kick or ban anyone from my server, for example =) If you have any issues,\nplease submit an [issue].\n\nEach of these functions returns the \"message id\". This can be used to pair a\nresponse with the message if you're listing to the `message` event (see\n[Events] below).\n\n* `sb.ban(user, reason, time, callback)`\n  \u003e Kicks and bans a `user` (which may be specified using the clientId, username,\n  \u003e or uuid returned by `listUsers()`) for `reason`. If `time` is specified, the\n  \u003e ban will be temporary and will automatically be lifted after `time` seconds\n  \u003e have passed. This is an optional parameter. For permanent bans, either pass\n  \u003e something falsey (`null`, `false`, `0`), or skip this parameter. Note: temp\n  \u003e bans might not survive a server restart.\n  \u003e\n  \u003e `function callback()` _(optional)_\n  \u003e * Called after the ban hammer falls.\n\n* `sb.broadcast(message, callback)`\n  \u003e Broadcasts `message` to all players.\n  \u003e\n  \u003e `function callback()` _(optional)_\n  \u003e * Called after the broadcast is sent.\n\n* `sb.echo(message, callback)`\n  \u003e The server will reply with `message`. Useful for \"pinging\" the server.\n  \u003e\n  \u003e `function callback(response)` _(optional)_\n  \u003e * `response.body` should be equal to `message`.\n\n* `sb.kick(user, reason, callback)`\n  \u003e Kicks a `user` (which may be specified using the clientId, username, or\n  \u003e uuid returned by `listUsers()`) for `reason`.\n  \u003e\n  \u003e `function callback()` _(optional)_\n  \u003e * Called after the user has been kicked.\n\n* `sb.listUsers(callback)`\n  \u003e Return a list of users that are currently logged in to the server.\n  \u003e\n  \u003e `function callback(response)` _(optional)_\n  \u003e * `response.users` is an array of `{clientId, username, uuid}` objects.\n  \u003e * `response.body` is the raw response from the server.\n\n* `sb.sendCommand(command, callback)`\n  \u003e For forward compatibility: sends raw `command` to the server.\n  \u003e\n  \u003e `function callback(response)` _(optional)_\n  \u003e * `response.body` contains the raw response from the server, if any.\n\n* `sb.serverReload(callback)`\n  \u003e Reload the server's assets (including mods). Does not reread the config.\n  \u003e Note: this will cause the server to appear to freeze for a few moments.\n  \u003e\n  \u003e `function callback()` _(optional)_\n  \u003e * Called after the reload.\n\n* `sb.stopServer()`\n  \u003e Cleanly shuts down the server.\n\n* `sb.timewarp(amount, callback)`\n  \u003e Jumps the entire server ahead in time by `amount`. `amount` is a positive\n  \u003e integer representing the number of seconds to jump ahead.\n  \u003e\n  \u003e `function callback()` _(optional)_\n  \u003e * Called after the timewarp.\n\n* `sb.whereIs(user)`\n  \u003e Returns the coordinates of the `user` (may be specified via clientId,\n  \u003e username, or uuid as returned by `listUsers()`). These coordinates could\n  \u003e be used to `/warp` to the player in-game.\n  \u003e\n  \u003e `function callback(response)` _(optional)_\n  \u003e * `response.body` will have the coordinates.\n\n* `sb.whisper(username, message, callback)`\n  \u003e Sends a private `message` (whisper) to the specified user via `username`.\n  \u003e\n  \u003e `function callback()` _(optional)_\n  \u003e * Called after the whisper is sent.\n\n## Events\nThe client is an [EventEmitter].\nThe following events are fired from the client. Some of these events are\npassed, unmolested, from the underlying [Socket].\n\n* `close`\n  \u003e Connection to Starbound has closed.\n  \u003e * `hadError` - `true` if the connection closed due to an error.\n\n* `connect`\n  \u003e Connection to Starbound has been opened.\n  \u003e * `successful` - `true` if authentication was successful.\n\n* `data`\n  \u003e Data has been received on the socket\n  \u003e * `buffer` - received data as a [Buffer]\n\n* `drain`\n  \u003e Write buffer is empty.\n\n* `end`\n  \u003e Starbound closed the connection on its end. Starbound.js will automatically\n  \u003e disconnect in response.\n\n* `error`\n  \u003e An error has occurred. Starbound.js will automatically disconnect.\n  \u003e * `err` - the Error that has occurred.\n\n* `lookup`\n  \u003e Emitted after resolving the hostname, but before connecting. See\n  \u003e [dns.lookup()].\n  \u003e * `err` - if non-null, indicates a lookup error.\n  \u003e * `address` - the IP address of the host\n  \u003e * `family` - the address type\n\n* `message`\n  \u003e Message received from Starbound. Messages are always in response to a\n  \u003e command you've sent, therefore, it's typically easier to pass in a\n  \u003e callback when you issue the command, rather than try to receive\n  \u003e responses via this event.\n  \u003e * `response` - the message has the following fields:\n  \u003e   * `response.id` - the id will match the \"message id\" of the command.\n  \u003e     Every [command] returns the message id. You can\n  \u003e     use this id to pair a response to the command you issued.\n  \u003e   * `response.body` - the raw server response\n\n* `timeout`\n  \u003e Socket has timed out due to inactivity. User should disconnect manually.\n\n## Some Additional Notes\nIf you plan on keeping a connection open to Starbound indefinitely, you'll need\nto occasionally \"ping\" the server so that the server will keep the connection\nalive. The easiest way to do this is to setup an interval to send the \"echo\"\ncommand... something like:\n\n```javascript\nvar Starbound = require('starbound.js');\n\nvar sb = new Starbound(host, port);\n\nvar interval = null;\nfunction ping() {\n  if (sb.connected)\n    sb.echo('ping');\n}\n\nsb.on('close', function() {\n  if (interval) {\n    clearInterval(interval);\n    interval = null;\n  }\n});\n\nsb.connect('password', function(success) {\n  if (success) {\n    // \"ping\" the server every 30 seconds\n    interval = setInterval(ping, 30000);\n  }\n\n  // etc\n});\n```\n\nI find 30 seconds works well.\n\n[issue]: https://github.com/bmatcuk/starbound.js/issues\n[command]: #supported-commands\n[events]: #events\n[EventEmitter]: https://nodejs.org/dist/latest-v4.x/docs/api/events.html#events_class_eventemitter\n[Socket]: https://nodejs.org/dist/latest-v4.x/docs/api/net.html#net_class_net_socket\n[Buffer]: https://nodejs.org/dist/latest-v4.x/docs/api/buffer.html#buffer_class_buffer\n[dns.lookup()]: https://nodejs.org/dist/latest-v4.x/docs/api/dns.html#dns_dns_lookup_hostname_options_callback\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbmatcuk%2Fstarbound.js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbmatcuk%2Fstarbound.js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbmatcuk%2Fstarbound.js/lists"}