Pinco 中文

Pinco is a strongly typed imperative language that compiles to standard Minecraft Bedrock Molang. It provides functions, local variables, conditionals, loops, fixed-size arrays, narrow integer types, and bitwise operations, then lowers those constructs at compile time.

Generated code uses standard Molang without the CustomMolang-specific function(...), f.*, or a.* forms. The compiler inlines user functions and assigns every local and parameter a unique t.__scvar* temporary slot to prevent name collisions.

Quick start

Pinco requires Node.js 18 or newer.

npm install
node main.js examples/algorithms.pin
node main.js examples/algorithms.pin -o algorithms.molang
npm test

Source can also be read from stdin:

'number main() { return 6 * 7; }' | node main.js -

After package installation, use npx pinco or pinco. Run node main.js --help for all command-line options.

Example

number gcd(number a, number b) {
  a = abs(floor(a));
  b = abs(floor(b));
  while (b != 0) {
    number remainder = a % b;
    a = b;
    b = remainder;
  }
  return a;
}

number main() {
  return gcd(84, 30);
}

The output uses standard Molang assignments, ternaries, loop, math.*, and one final return. A while statement lowers to a loop with at most 1024 iterations, and % lowers to math.mod.

The example guide covers sorting, binary search, the Sieve of Eratosthenes, state machines, Newton iteration, bitwise operations, 32-bit limb arithmetic, and slime chunk detection.

Documentation

• Language reference: program structure, types, statements, expressions, arrays, and engine namespaces.
• Command line and JavaScript API: options, exit codes, error handling, and resource-pack integration.
• Molang target contract: function inlining, type normalization, loop lowering, and bitwise lowering.
• Example guide: inputs, expected results, and algorithm notes for every example.

Types

Pinco type	Runtime representation	Semantics
number	binary32	Molang single-precision floating-point value
short	binary32	Truncated toward zero and wrapped into the signed 16-bit range
byte	binary32	Truncated toward zero and wrapped into the signed 8-bit range
boolean / bool	binary32	Normalized to 0.0 or 1.0
void	No value	Available only to helper functions with no return value

Explicit conversion uses short(value), byte(value), or boolean(value). C-style casts such as (short)value are also supported.

Molang exactly represents every integer with an absolute value up to 2^24. Algorithms requiring 32-bit or 64-bit integers must use limbs, such as 16-bit limbs with 8-bit sub-limbs for multiplication.

Language features

• C-style functions such as number fn(number x) { ... } and the alternative fn fn(number x) -> number syntax.
• number, short, byte, boolean, let, and const declarations.
• if/else, while, do/while, for, loop/repeat, break, and continue control flow.
• Arithmetic, comparison, logical, conditional, compound assignment, increment, remainder, power, and & | ^ ~ << >> >>> operators.
• Fixed-size arrays such as number values[4] = [1, 2, 3, 4];, with dynamic indexes lowered to conditional selection.
• Molang q.*/query.*, v.*/variable.*, t.*/temp.*, c.*/context.*, and math.* namespaces, including entity-reference -> access.
• Common mathematical built-ins including abs, floor, ceil, round, trunc, min, max, clamp, sqrt, pow, sin, cos, tan, lerp, and smoothstep.

The q.* and c.* namespaces are read-only. The v.* and t.* namespaces are writable. Query function names are passed through without a static allowlist because availability depends on the Minecraft engine version.

JavaScript API

const pinco = require('pinco');

const molang = pinco.compile(`
  number main() {
    return 21 * 2;
  }
`);

const ast = pinco.parse('number main() { return 0; }');
const tokens = pinco.tokenize('number main() { return 0; }');

The package itself is also a shorthand for compile: pinco(source, options).

Primary compiler options:

pinco.compile(source, {
  filename: 'example.pin',
  maxIterations: 1024, // 1..1024
  bitWidth: 16,        // 8, 16, or 24
  pretty: false,
});

compileDetailed additionally returns the AST, diagnostics, and compiler instance.

Scope and limitations

• Generated code targets Molang 1.18.20 or newer and uses explicit parentheses around mixed operators.
• Molang limits loop to 1024 iterations. Pinco applies maxIterations to while, for, and do/while.
• Standard Molang has no recursive calls, so Pinco rejects recursive call graphs.
• Fixed arrays are scalarized. Generated code for dynamic access grows linearly with array length.
• Strings are limited to query arguments and equality comparisons. Standard Molang strings have no escape syntax.
• Bitwise operations on number use a 16-bit exact domain by default. Set bitWidth to 8 or 24 to change it.
• Returns inside inline functions become result assignments and completion flags. Generated output contains one outermost return.

See the documentation index above for the complete syntax and lowering rules.

License

MIT