BattleScript

BattleScript is a programming language designed to allow event-driven logic to be executed at runtime inside resource-constrained microcontrollers.

It was created to enable custom logic to be implemented in the BattleCore Laser Tag system so that new game types, IR protocols, comms protocols, and functionality could be written and uploaded to the device without needing to flash new firmware.

BattleScript logic executes at runtime when events occur based on the finite state machine's current state.

You can read, learn, and try out BattleScript at the language's home domain: https://battlescript.io

Compile BattleScript

If you have a BattleScript file and want to compile it, you can run the compiler using the npx command line.

Compile to a JSON AST Tree

This outputs a JSON file containing the Abstract Syntax Tree representation of the source code, useful for linting, debugging, code cleanup, or modifying source code using a structured tree.

If no output path is specified, the same input file path will be used with a .json extension.

npx @irrelon/battlescript toAst <input file path> <output file path>

Compile to a JSON Mini-AST Tree

This outputs a minified AST JSON file. Minified ASTs are useful for inspecting the intermediate stage before binary output is generated but where the data is still human-readable. This is really only relevant from an academic point of view or when debugging the final binary output.

If no output path is specified, the same input file path will be used with a .miniAst.json extension.

npx @irrelon/battlescript toMiniAst <input file path> <output file path>

Compile to a Binary File

This generates a binary representation of the source code for use in a BattleCore device or online interpreter. The binary representation encodes the source code to an integer stream describing operations to execute at a very low level. It is not human-readable. If you want a human-readable version of the binary, see the decompiler command below.

If no output path is specified, the same input file path will be used with a .bin extension.

npx @irrelon/battlescript toBinary <input file path> <output file path>

Decompile BattleScript

If you have a binary file and want to convert it back to a mini-ast JSON representation, you can do so using the "fromBinary" command.

The decompiled binary is human-readable but is still very low-level as most values are encoded or mapped by integer index to real data. This is primarily used for ensuring that the binary format is operating correctly via automated tests.

If no output path is specified, the same input file path will be used with a .decompiled.json extension.

npx @irrelon/battlescript fromBinary <input file path> <output file path>

Install in Another Project

npm i @irrelon/battlescript

Once installed, you can parse and compile BattleScript programmatically.

Compile to a JSON AST Tree

import {fromSourceCodeToFullAst} from "@irrelon/battlescript";

const myCode = `program {
\tname "Test Program";
}`;

const ast = fromSourceCodeToFullAst(myCode);

Compile to a JSON Mini-AST Tree

import type {MiniAstJson} from "@irrelon/battlescript";
import {fromSourceCodeToMiniAst} from "@irrelon/battlescript";

const myCode = `program {
\tname "Test Program";
}`;

const miniAst: MiniAstJson = fromSourceCodeToMiniAst(myCode);

Compile to a Binary File

import type {MiniAstBinary} from "@irrelon/battlescript";
import {fromSourceCodeToBinary} from "@irrelon/battlescript";

const myCode = `program {
\tname "Test Program";
}`;

const bin: MiniAstBinary = fromSourceCodeToBinary(myCode);

Irrelon Software Limited

This software was made with ❤️ love by Irrelon Software Limited, a company incorporated in the United Kingdom.