README.md

dsabp-js

A TypeScript library to decode, create, modify and encode blueprints for the Deep Space Airships (DSA) 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.
• 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 module is used for deflate and inflate operations, and the Buffer class is used for Base64 operations. In the browser, the fflate library (8.3KB) and the atob-btoa functions are used. The 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.10.tgz
• Or use a CDN:
  • https://cdn.jsdelivr.net/npm/dsabp-js/
  • https://unpkg.com/browse/dsabp-js/

Import

// 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

^{See the docs for all exports.}

Browser Extensions

There are some requirements when loading the library using a browser extension's content_scripts, which has to use the IIFE bundle:

• The JS file must be included in the 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
• DSA Tools uses dsabp-js for the blueprint related stuff.
• A Simple Example

  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 page.

Suggestions and Questions

Use the Discussions page.

Code Contribution

See the contributing guidelines.