@minecraft/creator-tools/lib/minecraft/MolangEvaluator.d.ts

Minecraft Creator Tools command line and libraries.

/**
 * ARCHITECTURE: MolangEvaluator
 *
 * Evaluates Molang expressions used in Minecraft render controllers, animations,
 * and entity definitions. This is a subset evaluator focused on the expression
 * patterns found in render controllers:
 *
 * - Literals: `1.0`, `0`, `42`
 * - Query references: `query.is_baby`, `q.variant`
 * - Variable references: `variable.index`, `v.armor_texture_slot`
 * - Ternary conditionals: `query.is_baby ? Texture.baby : Texture.default`
 * - Nested ternary: `query.is_angry ? A : (query.is_tamed ? B : C)`
 * - Comparison operators: `==`, `!=`, `<`, `>`, `<=`, `>=`
 * - Logical operators: `&&`, `||`, `!`
 * - Arithmetic: `+`, `-`, `*`, `/`
 * - String references: `Texture.default`, `Geometry.baby`, `Array.geos`
 * - Array indexing: `Array.geos[query.is_sheared]`
 *
 * This evaluator uses a recursive descent parser rather than the existing
 * Molang.ts shunting-yard parser, because render controller expressions
 * contain string references (Texture.*, Geometry.*) and ternary operators
 * that the basic parser doesn't support.
 *
 * Related files:
 * - IMolangContext.ts — query/variable context for evaluation
 * - RenderControllerResolver.ts — uses this to resolve render controller fields
 * - IRenderControllerSet.ts — render controller data structures
 */
import IMolangContext from "./IMolangContext";
/**
 * Result of evaluating a Molang expression. Can be a number (for arithmetic/boolean)
 * or a string (for reference resolution like "Texture.default").
 */
export type MolangValue = number | string;
/**
 * Evaluates Molang expressions against an entity context.
 *
 * Design: stateless evaluator — create once, call evaluate() many times with
 * different expressions and contexts. Array definitions are passed per-call
 * since they come from the render controller, not the entity.
 */
export default class MolangEvaluator {
    /**
     * Evaluate a Molang expression string and return the result.
     *
     * @param expression The Molang expression (e.g., "query.is_baby ? Texture.baby : Texture.default")
     * @param context Entity state context (query values, variables)
     * @param arrays Optional array definitions from render controller (e.g., {"Array.geos": ["Geometry.default", "Geometry.sheared"]})
     * @returns The evaluated result — a number or a string reference
     */
    evaluate(expression: string, context: IMolangContext, arrays?: Map<string, string[]>): MolangValue;
    /**
     * Evaluate a Molang expression and return only the numeric result.
     * String references resolve to 0.
     */
    evaluateNumber(expression: string, context: IMolangContext, arrays?: Map<string, string[]>): number;
    /**
     * Evaluate a Molang expression and return only the string result.
     * Numeric results resolve to empty string.
     */
    evaluateString(expression: string, context: IMolangContext, arrays?: Map<string, string[]>): string;
}