dsabp-js
Version:
DSA (drednot.io) Blueprint implementation and API for Node.js and the browser, in TypeScript.
76 lines (58 loc) • 4.58 kB
Markdown
# dsabp-js
[](https://www.npmjs.com/package/dsabp-js) [](https://www.npmjs.com/package/dsabp-js) [](https://github.com/Blueyescat/dsabp-js) [](https://blueyescat.github.io/dsabp-js/modules)
A TypeScript library to decode, create, modify and encode blueprints for the [Deep Space Airships (DSA)](https://drednot.io) game.
- It works in Node.js and the browser. Not meant to support *older* Node.js versions or browsers.
- The API design is subject to frequent changes for the time being.
- Follows the official [blueprint specification](https://drednot.io/c/coder-docs/t/blueprint-specification).
- Encoded blueprint values aren't forced to be valid in the game. (Allows experimenting)
- The generated blueprint strings won't be identical to what the game generates and may be shorter or longer.
- In Node.js, the built-in [zlib](https://nodejs.org/api/zlib.html) module is used for deflate and inflate operations, and the [Buffer](https://nodejs.org/api/buffer.html) class is used for Base64 operations. In the browser, the [fflate](https://github.com/101arrowz/fflate) library (8.3KB) and the [atob-btoa](https://github.com/Blueyescat/dsabp-js/blob/main/src/injBrowser.ts) functions are used. The [Compression Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Compression_Streams_API) is not used for a few reasons.
## Install
#### Node.js
- `npm install dsabp-js` or `yarn add dsabp-js`
#### Browser
- Get the files you need from `/dist` in the package: https://registry.npmjs.org/dsabp-js/-/dsabp-js-0.4.11.tgz<!---->
- Or use a CDN:
- https://cdn.jsdelivr.net/npm/dsabp-js/
- https://unpkg.com/browse/dsabp-js/
## Import
```js
// node
import { decode, encode } from "dsabp-js"
import * as dsabp from "dsabp-js"
const { decode, encode } = require("dsabp-js")
const dsabp = require("dsabp-js")
// browser
import { decode, encode } from "https://cdn.jsdelivr.net/npm/dsabp-js@latest/dist/browser/esm/index.js"
// put the .d.ts file next to .js for better IntelliSense
import * as dsabp from "lib/dsabp-js/index.js"
// the global name for the IIFE build is "dsabp"
<script src="https://unpkg.com/dsabp-js@latest/dist/browser/iife/index.min.js"></script>
const { decode, encode } = dsabp
```
<sup>See the docs for all exports.</sup>
### Browser Extensions
There are some requirements when loading the library using a browser extension's [content_scripts](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts), which has to use the IIFE bundle:
* The JS file must be included in the [web_accessible_resources](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources).
* The JS file must be in a folder containing `dsabp` in its name, or the file must be named `dsabp.js` or `dsabp.min.js`. Some examples: `/lib/dsabp/index.js`, `/dsabp.min.js` and `/lib/dsabp.js`.
If you load it using methods such as `import()` (ESM) from a content script or by injecting a `script` tag (ESM or IIFE) into the page, it will work without any requirements.
## Usage
* [Documentation](https://blueyescat.github.io/dsabp-js/modules)
* [DSA Tools](https://dsa.fr.to) uses dsabp-js for the blueprint related stuff.
* **A Simple Example**
```js
import { decode, BuildCmd, Item, encode } from "dsabp-js"
const bp = await decode("DSA:m8DAxDRhAgMDY8OLiRMYGBkaXk6cOBEA") // decode a blueprint string
for (const cmd of bp.commands) { // loop all commands of the bp
if (!(cmd instanceof BuildCmd)) continue // ignore if the cmd is not a BuildCmd
if (cmd.item == Item.BLOCK) // if the build item is iron block
cmd.item = Item.BLOCK_ICE_GLASS // replace it with ice block
}
console.log("DSA:" + await encode(bp)) // log string for the modified bp
```
## Issues / Bugs
Create a detailed issue in the [Issues](https://github.com/Blueyescat/dsabp-js/issues) page.
## Suggestions and Questions
Use the [Discussions](https://github.com/Blueyescat/dsabp-js/discussions) page.
## Code Contribution
See the [contributing guidelines](https://github.com/Blueyescat/dsabp-js/blob/main/.github/contributing.md).