Getting Started

This guide helps you install BattleScript tools, compile .bst source into different formats (AST, binary, bytecode), and use the @irrelon/battlescript module from Node/TypeScript. Use the table of contents to jump to a section.

Install @irrelon/battlescript
Use the module (Node/TypeScript)
Use the CLI with npx
Output formats (AST, Mini AST, Binary, Bytecode)
Next steps

Install @irrelon/battlescript

Install the package. If you only plan to use the CLI, a dev dependency is fine. If you will import it in your runtime code, install it as a regular dependency.

# npm (CLI only)
npm i -D @irrelon/battlescript
# npm (programmatic use)
npm i @irrelon/battlescript

# yarn
yarn add -D @irrelon/battlescript
# or
yarn add @irrelon/battlescript

# pnpm
pnpm add -D @irrelon/battlescript
# or
pnpm add @irrelon/battlescript

BattleScript files use the .bst extension.

Use the module (Node/TypeScript)

You can compile source code to various representations directly from code using the exported helpers.

import { fromSourceCodeToFullAst, fromSourceCodeToMiniAst, fromSourceCodeToBinary } from '@irrelon/battlescript';

const source = `

void greet(string name) => {
  std::console.log("Hello, "+name+"!");
}

greet("BattleScript");`;

// Full AST (rich tree)
const fullAst = fromSourceCodeToFullAst(source);

// Mini AST (compact JSON form)
const miniAst = fromSourceCodeToMiniAst(source);

// Binary (buffer representing the Mini AST, ready for a BattleCore device)
const binary = fromSourceCodeToBinary(source);

console.log({ fullAst, miniAst, binaryLength: binary.length });

Conversions between representations are also available individually if you already have a particular form:

fromBinaryToMiniAst(binary) → Mini AST
fromMiniAstToBinary(miniAst) → Binary
fromMiniAstToAst(miniAst) → Full AST
fromMiniAstToSourceCode(miniAst) → .bst source
fromFullAstToSourceCode(ast) → .bst source

Use the CLI with npx

Run CLI commands without installing globally using npx. The general form is:

npx @irrelon/battlescript <command> <input> <output>

Supported commands:

toAst — Compile .bst → full AST JSON
fromAst — Decompile full AST JSON → .bst
toMiniAst — Compile .bst → Mini AST JSON
fromMiniAst — Decompile Mini AST JSON → .bst
toBinary — Compile .bst → binary (.bin)
fromBinary — Decode binary (.bin) → decompiled Mini AST JSON
miniAstToBinary — Encode Mini AST JSON → binary (.bin)
toCpp — Generate optimised C++ (.h/.cpp) from a protocol .bst file

If you omit the output path, a default path is derived from the input file (e.g. a .json or .bin extension).

Examples:

# Compile a script to full AST JSON
npx @irrelon/battlescript toAst ./scripts/hello.bst ./out/hello.ast.json

# Compile to Mini AST JSON (compact)
npx @irrelon/battlescript toMiniAst ./scripts/hello.bst ./out/hello.mini.json

# Compile to binary, ready for a BattleCore device
npx @irrelon/battlescript toBinary ./scripts/hello.bst ./out/hello.bin

# Decode a binary back to a (decompiled) Mini AST
npx @irrelon/battlescript fromBinary ./out/hello.bin ./out/hello.decompiled.json

# Encode a Mini AST JSON to binary
npx @irrelon/battlescript miniAstToBinary ./out/hello.mini.json ./out/hello.bin

# Decompile an AST JSON back to source
npx @irrelon/battlescript fromAst ./out/hello.ast.json ./out/hello.fromAst.bst

# Generate C++ encode/decode functions from a protocol file
npx @irrelon/battlescript toCpp ./scripts/protocol_p2p.bst ./out/

Tip: Create the output folder first (e.g. mkdir -p out on macOS/Linux) or point to an existing path.

Output formats

Full AST JSON: A detailed tree of the entire program, great for analysis and tooling.
Mini AST JSON: A compact form tuned for size; the intermediate stage before binary output, still human-readable.
Binary (.bin): The Mini AST encoded as a compact binary stream for upload to a BattleCore device or the online interpreter.
C++ (.h/.cpp): For protocol files, optimised C++ encode/decode functions generated with toCpp.

Next steps