Getting Started

Table of Contents

• 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, fromSourceCodeToByteCode } 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 (Uint8Array buffer representing Mini AST)
const binary = fromSourceCodeToBinary(source);

// Bytecode (for execution engines / VMs)
const bytecode = fromSourceCodeToByteCode(source);

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

Common conversions are also available individually if you already have a particular representation:

• fromBinaryToMiniAst(binary) → Mini AST
• fromMiniAstToBinary(miniAst) → Binary
• 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
• toBinary — Compile .bst → binary (.bin)
• fromBinary — Decode binary (.bin) → Mini AST JSON
• toByteCode — Compile .bst → bytecode JSON
• fromByteCode — Disassemble bytecode JSON → readable text

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
npx @irrelon/battlescript toBinary ./scripts/hello.bst ./out/hello.bin

# Decode binary back to Mini AST
npx @irrelon/battlescript fromBinary ./out/hello.bin ./out/hello.mini.json

# Produce bytecode JSON
npx @irrelon/battlescript toByteCode ./scripts/hello.bst ./out/hello.bcode.json

# Disassemble bytecode to a human-readable listing
npx @irrelon/battlescript fromByteCode ./out/hello.bcode.json ./out/hello.bcode.disassembled.txt

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

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; ideal for transport and storage.
• Binary (.bin): The Mini AST encoded as a binary buffer for efficient transmission.
• Bytecode JSON: A low-level representation for interpreters/VMs; can be disassembled to readable text.

Next steps

• Read the Examples to learn the language quickly.
• Browse the API Reference for language features and standard libraries.