Boilerplate Compiler

1.0.3 verified Fri May 01 auth: no javascript maintenance

A compiler for the Boilerplate cellular automaton game, converting grid layouts into executable JavaScript that simulates shuttle movement and pressure. Current version 1.0.3 (unstable, no recent updates). Includes a parser (coffee-script) from grid JSON to an AST-like structure and a JS codegen outputting either bare functions, Node modules, or IIFE wrappers. Key limitations: cannot compile worlds where two shuttles could conflict, lacks button support, and has a primitive pressure API. No TypeScript types, limited test coverage, and brittle against grid complexity.

Common errors

error Error: Grid contains overlapping shuttle states ↓

cause Two shuttles have potential states in the same cell, even if never simultaneously reachable.

fix

Modify shuttle paths or initial positions to eliminate overlap.

error Cannot read property '0' of undefined ↓

cause Missing or malformed grid data (e.g., key not in 'x,y' format).

fix

Ensure grid object uses string keys like '0,0' and values are valid Boilerplate cell types.

error TypeError: compiler.compileGrid is not a function ↓

cause Importing default export but calling as named method (wrong import style).

fix

Use const compiler = require('boilerplate-compiler'); then compiler.compileGrid(...).

Warnings

breaking The compiler rejects grids where two shuttles could ever occupy the same cell, even if path constraints prevent it. ↓

fix Redesign grid layout to ensure shuttles never have overlapping potential states.

deprecated The 'stream' option in compileFile/compileGrid is fragile and output may be silently lost if stream closes early. ↓

fix Avoid using stream; capture output via string concatenation or implement a wrapper.

gotcha The parser output format (AST structure) is unstable and may change between minor versions. ↓

fix Do not rely on specific property names or nesting; treat parser result as opaque.

gotcha No button support: any grid with buttons will cause compile errors or undefined behavior. ↓

fix Remove buttons from the grid before compiling.

gotcha Pressure querying is not exposed – the compiled output's step function returns states but not pressure values. ↓

fix Wrap the compiled module to track pressure manually by analyzing region geometry.

Install

npm install boilerplate-compiler

yarn add boilerplate-compiler

pnpm add boilerplate-compiler

Imports

default
wrong
```
const compiler = require('boilerplate-compiler')
```
correct
```
import compiler from 'boilerplate-compiler'
```
Package only provides CommonJS exports; default import works in ESM via bundlers.
compileFile
wrong
```
import { compileFile } from 'boilerplate-compiler';
```
correct
```
const { compileFile } = require('boilerplate-compiler');
```
CommonJS usage is safer; named import may fail in Node ESM or bundlers without named exports.

compileGrid

wrong

import compileGrid from 'boilerplate-compiler';

correct

const { compileGrid } = require('boilerplate-compiler');

compileGrid is not a default export; default export is an object with methods.

parse

wrong

import { parse } from 'boilerplate-compiler';

correct

const { parse } = require('boilerplate-compiler');

parse is a named export available via destructuring require.

Quickstart

Demonstrates importing the compiler, defining a simple grid, and compiling it with options. Note: compileGrid returns undefined when stream is set; output goes to stream.

const compiler = require('boilerplate-compiler');
const grid = {"0,0":"shuttle","1,0":"nothing","2,0":"negative"};
const result = compiler.compileGrid(grid, { stream: process.stdout, fillMode: 'shuttles', module: 'bare' });
console.log('Compiled output:');
console.log(result);