molang

Molang to Python Translator & interpreter written in pure Python.

Installation

Install the module with pip:

pip3 install molang

Update existing installation: pip3 install molang --upgrade

Links

• Documentation
• Source Code

Requirements

Features

• Pure-Python Molang parser and AST representation
• Interpreter: evaluate Molang expressions against a runtime context
• Compiler / emitter: convert parsed AST back to Molang source
• DSL convenience objects: query, variable, math, temp, array, etc.
• Assignment support for dotted variables (e.g. variable.x = 1, temp.a.b = 2)
• Full math.* function implementations and callable math functions (e.g. math.sqrt(4))
• Function-call support in expressions and argument evaluation
• CLI to run Molang files or execute inline Molang code

See the docs for more information.

Example

Parse / Compile / Eval

Parse, compile and evaluate with a context

import molang

expr = "math.sqrt(16) + variable.x"
node = molang.parse(expr)
print(molang.compile(expr))
ctx = molang.create_context()
ctx['variable']['x'] = 9
print(molang.eval(expr, ctx))  # prints 13.0

Multiline expressions and blocks

Use semicolons to separate statements and braces to group statements in a conditional branch. Newlines and indentation are treated as whitespace.

ctx = molang.create_context()
ctx["temp"]["RANDOMISE_SE_WALLS"] = True
molang.eval("""
t.RANDOMISE_SE_WALLS ? {
  t.WALL_SOUTH = math.random_integer(1, 5) < 3;
  t.WALL_EAST = math.random_integer(1, 5) < 3;
} : {
  t.WALL_SOUTH = 0;
  t.WALL_EAST = 0;
};
""", ctx)

Only the selected branch executes. Statements execute in order, returning the last statement's value (or zero for an empty block). The same syntax works with parse, compile, and their file helpers.

DSL usage

from molang.dsl import variable, math, query

variable.x = 4
print(variable.x)           # MolangExpr("variable.x = 4;") when used as assignment
print(math.sqrt(variable.x))

expr = query.block_state("minecraft:cardinal_direction") == "north"
print(expr) # MolangExpr("query.block_state('minecraft:cardinal_direction') == 'north'")

Assignment to dotted variables

import molang

ctx = molang.create_context()
molang.eval('variable.health = 20', ctx)
print(ctx['variable']['health'])  # 20.0

Function calls and math helpers

import molang

ctx = molang.create_context()
print(molang.eval('math.lerp(0, 10, 0.5)', ctx))  # 5.0

Pydantic Support

from pydantic import BaseModel
from molang.dsl import MolangExpr, query

class Test(BaseModel):
  condition: MolangExpr

x = Test(condition=query.block_state("facing") == "north")
print(x.model_dump()) # {"condition": "query.block_state('facing') == 'north'"}

Command-line interface

usage: molang [-h] [-c <cmd>] [-V] [<file>]

Run molang files

positional arguments:
  <file>                execute the molang code contained in a file.

options:
  -h, --help            show this help message and exit
  -c <cmd>              execute the molang code in cmd. cmd can be one or more statements separated by newlines, with significant leading whitespace as in normal module code.
  -V, --version         print the molang version number and exit.