MOLANG DOCUMENTATION
Version: 1.13.0.9

This is documentation for a beta release of Minecraft. New features, components, and capabilities in this release are not final and might change without notice before the final release.
Be sure to check the documentation once the release is out of beta if your add-on isn't working properly. Resource and Behavior Packs created for the beta are not guaranteed to work on the final release.

Index

Why Does MoLang Exist?

MoLang is a simple expression-based language designed for fast calculation of values at run-time. Its focus is solely to enable script-like capabilities in high-performance systems where JavaScript is not performant at scale. We need scripting capabilities in these low-level systems to support end-user modding capabilities, custom entities, rendering, and animation.

Lexical Structure

The language structure is largely based on simple C-style syntax, focusing on handling math expressions. A script is made of either one expression for simple cases, or can be made of several where intermediate values are required or to help reduce compute time.

In all cases, the value of the last expression in a script provides the script's value. In a multi-expression script, all but the last expression must assign a value to a variable. The last expression can as well, but doesn't need to as its value is assumed to be the used as the return value.

Values

- Value types are concretely specified, or numeric if not.
- All numerical values are floats.
- Boolean values such as actor flags are converted to a float value of either 0.0 or 1.0 for values of false or true respectively.
- For boolean tests, a float value equivalent to 0.0 is false, and anything not equal to 0.0 is true.
- For array indices, floats are c-style cast to ints, and clamped at zero for negative values or wrapped by the array size for large values.
- Other supported types are textures, materials, and geometry where they make sense (such as render controllers).
- Errors generally return a value of 0.0.

Variables

There are several domains a variable may belong to:

Parameters

Domain Scope Example
temp current expression temp.foo = math.sin(query.anim_time); return temp.foo * temp.foo;
variable read-write values, usually related to the current entity variable.my_saved_var = variable.my_saved_var + 1;
query read-only values, usually related to current entity query.is_baby
geometry current render controller "geometry": "array.geos[query.is_sheared]"
material current render controller "materials": [ { "*": "material.default" }, { "leg*": "material.legs" } ]
texture current render controller "textures": ["array.skins[query.is_saddled]"]

Keywords

All identifiers not in a scope listed below are reserved for future use

Parameters

Keyword Description
`float` `Numerical constant value`
`( )` `Parentheses for expression term evaluation control`
` `Brackets for array access`
`query.function_name` `Access to an entity's properties`
`math.function_name` `Various math functions (see below)`
`temp.variable_name` `Store an intermediate value for the duration of the current expression`
`variable.variable_name` `Store a value on the attached entity for later use`
`geometry.texture_name` `A reference to a texture named in the entity definition`
`material.texture_name` `A reference to a texture named in the entity definition`
`texture.texture_name` `A reference to a texture named in the entity definition`
`! && || < <= >= > == !=` `Logical operators`
`* / + -` `Basic math operators`
`test ? if true : if false` `Conditional operator`
`this` `The current value before executing the script (context sensitive)`
`return` `For complex expressions, this evaluates the following statement and stops execution of the script, returns the value computed`

Math Functions

`

Parameters

Function Description
`math.abs(value)` `Absolute value of value`
`math.sin(value)` `Sine (in degrees) of value`
`math.cos(value)` `Cosine (in degrees) of value`
`math.exp(value)` `Calculates e to the value'th power`
`math.ln(value)` `Natural logarithm of value`
`math.pow(base, exponent)` `Elevates base to the exponent'th power`
`math.sqrt(value)` `Square root of value`
`math.random(low, high)` `Random value between low and high inclusive`
`math.ceil(value)` `Round value up to nearest integral number`
`math.round(value)` `Round value to nearest integral number`
`math.trunc(value)` `Round value towards zero`
`math.floor(value)` `Round value down to nearest integral number`
`math.mod(value, denominator)` `Return the remainder of value / denominator`
`math.min(A, B)` `Return lowest value of A or B`
`math.max(A, B)` `Return highest value of A or B`
`math.clamp(value, min, max)` `Clamp value to between min and max inclusive`
`math.lerp(start, end, 0_to_1)` `Lerp from start to end via 0_to_1`
`math.lerprotate(start, end, 0_to_1)` `Lerp the shortest direction around a circle from start degrees to end degrees via 0_to_1`

Types, Values, and Variables

In general, all expression values are floats. In render controllers, some expressions result in a texture or material depending on the context. All array index expressions are processed as floats, and cast to integers when performing the final lookup into the array. Positive array indices wrap by the size of the array. Negative array indices clamp to 0.

Simple vs Complex Expressions

A simple expression is a single statement, the value of which is returned to the system that evaluated the expression. eg:

math.sin(query.anim_time * 1.23)


A complex expression is one with multiple statements, each ending in a ';'. Each statement is evaluated in order. In the current implementation, the last statement requires the use of the return keyword and defines the resulting value of the expression. eg:

temp.my_temp_var = Math.sin(query.anim_time * 1.23);
temp.my_other_temp_var = Math.cos(query.life_time + 2.0);
return temp.my_temp_var * temp.my_temp_var + temp.my_other_temp_var;


Note that in a simple expression, ';' is not allowed, whereas in a complex expression, each statement requires a ';' including the last.





Domain Examples

Entity Definition Scripts

In the definition file there is a section for pre-computing values. These are executed immediately before animation and render controllers are processed, and stored in the entity. The purpose is to pre-compute any expensive and complex values you may want to reuse in your scripts, long-living index variable updates, or generally any one-off computation per render tick.

"scripts": {
    "pre_animation": [
      "variable.my_constant = (Math.cos(query.modified_distance_moved * 38.17) * query.modified_move_speed;",
      "variable.my_constant2 = Math.exp(1.5);",
    ]
  },


Animation and Animation Controller Files

These are always numerical operations to control which animations are playing and how to animate bones. "variable.variable_name" and "query.function_name" refers to the entity currently being rendered. They have access to everything in the language except material, texture, and geometry types.

Render Controllers

There are a few different kinds of expressions here, where context implies what is allowed. As with animations, the entity accessors refer to the current entity, however depending on the context one also has access to materials, textures, and geometries. There are two sections in a render controller:
-Array definitions (optional)
-Resource usage (required)
The array definition section allows you to create arrays of resources by resource type if you so desire. These can then be referenced in the resource usage section.

Parameters

Array Expressions

For each of the three resource types (materials, textures, and geometry), you can define an array of resources. The name of the resource is the nice-name from the definition file. Using materials as an example:

"arrays":
{
  "materials": {
    "array.my_array_1": ["material.a", "material.b", "material.c"],
    "array.my_array_2" : ["material.d", "material.e"],
    "array.my_array_3" : ["array.my_array_1", "material.my_array_2"],
    "array.my_array_4" : ["array.my_array_2", "material.my_array_3"],
    "array.my_array_5" : ["array.my_array_1", "material.my_array_1", "material.my_array_4"],
    "array.my_array_6" : ["array.my_array_1", "material.f"],
    ...
  },


Note that all elements of an array must be of the same type. eg: a texture array must only contain textures.

An array can reference any combination of zero or more arrays (including duplicates if desired) and/or zero or more materails (again, including duplicates if you like), and you can have as many arrays as you like, each with as many elements as you like. If an array includes arrays in its members, they do not need to be the same length. When indexing into an array in the resource usage section, you use numerical expressions. If the resulting number is negative, it will use zero as the index. Any non - negative index will converted to an integer, and will wrap based on the size of the array:

index = max(0, expression_result) % array_size




Resource Expression

A resource expression must return a single resource of a specific type depending on the context.
For example, in the "geometry" section, you must produce an expression that will result in a single geometry. Some examples:
Always use a specific geometry
"geometry": "geometry.my_geo"

Cycle through an array of geometries at a rate of one per second
"geometry": "array.my_geometries[query.anim_time]"

Pick a geo based on an entity flag
"geometry": "query.is_sheared ? geometry.sheared : geometry.woolly"

Use specific geo when sleeping, otherwise flip through an array based on a cosine curve, using index zero for almost half the time while the cosine curve is negative
"geometry": "query.is_sleeping ? geometry.my_sleeping_geo : array.my_geos[math.cos(query.anim_time * 12.3 + 41.9) * 10 + 0.6]"


Resource Sections

Geometry

The geometry section specifies which geometry to use when rendering. As you can specify as many render controllers as you like in the definition file, a single render controller is only concerned with how to render a single geometry. Note that a geometry can be arbitrarily complex using any number of bones and polygons.

Materials

The materials section specifies how to map what material to what bone of the geometry. A single material is mapped to a whole bone. Material expressions are evaluated in the order listed. The first part of each statement is the name of the model part to apply the material to, and the second part is the material to use. The model part name can use * for wild - card matching of characters. For example :

  "materials": [
      { "*": "Material.default" },
      { "TailA": "array.hair_colors[variable.hair_color]" },
      { "Mane": "array.hair_colors[variable.hair_color]" },
      { "*Saddle*": "variable.is_leather_saddle ? material.leather_saddle : material.iron_saddle" }
    ],


- This will start by applying Material.default to all model parts.
- Next, it will set the material on a model part named "TailA" to the result of the expression "Array.hairColors[variable.hair_color]". This will look up some previously created variable on the entity named hair_color and use that to index into a material array called "array.hair_colors" defined in this render controller. This will overwrite the Material.default material set in the line above.
- Third, it will look up the same material as the expression is identical, and apply it to the "Mane" model part.
- Lastly, if will find any model part starting with, ending with, or containing "Saddle" (case sensitive) and change its material to either material.leather_saddle or material.iron_saddle depending on the previously set entity variable variable.is_leather_saddle.









Query Functions

Query Functions are boolean expressions that allow you to query for values owned by the engine under different circumstances. They can be used in MoLang expressionsUseful for controlling things like changing positions, textures, animations, etc if a mob is a baby. For example:

"position": [ 0.0, "query.is_baby ? -8.0 : 0.0", "query.is_baby ? 4.0 : 0.0" ]


List of Entity Queries

Name Description

query.all_animations_finished

Only valid in an animation controller. Returns 1.0 if all animations in the current animation controller state have played through at least once, else it returns 0.0

query.anim_time

Returns the time in seconds since the current animation started, else 0.0 if not called within an animation

query.any_animation_finished

Only valid in an animation controller. Returns 1.0 if any animation in the current animation controller state has played through at least once, else it returns 0.0

query.armor_color_slot

Takes the armor slot index as a parameter, and returns the color of the armor in the requested slot

query.armor_material_slot

Takes the armor slot index as a parameter, and returns the armor material type in the requested armor slot

query.armor_texture_slot

Takes the armor slot index as a parameter, and returns the texture type of the requested slot

query.blocking

Returns 1.0 if the entity is blocking, else it returns 0.0

query.body_y_rotation

Returns the body yaw rotation if called on an actor, else it returns 0.0

query.can_climb

Returns 1.0 if the entity can climb, else it returns 0.0

query.can_fly

Returns 1.0 if the entity can fly, else it returns 0.0

query.can_power_jump

Returns 1.0 if the entity can power jump, else it returns 0.0

query.can_swim

Returns 1.0 if the entity can swim, else it returns 0.0

query.can_walk

Returns 1.0 if the entity can walk, else it returns 0.0

query.cape_flap_amount

returns value between 0.0 and 1.0 with 0.0 meaning cape is fully down and 1.0 is cape is fully up

query.cape_height_offset

Returns the body armor offset value used to adjust height on Elytra or Capes. Returns 0.0 if there's no body armor offset

query.current_squish_value

Returns the squish value for the current entity, or 0.0 if this doesn't make sense

query.delta_time

Returns the time in seconds since the previous frame

query.equipment_count

returns the equipment count for an actor

query.eye_target_x_rotation

returns the X eye rotation of the entity if it makes sense, else it returns 0.0

query.eye_target_y_rotation

returns the Y eye rotation of the entity if it makes sense, else it returns 0.0

query.frame_alpha

Returns the ratio (from 0 to 1) of how much between AI ticks this frame is being rendered

query.get_equipped_item_name

takes one optional hand slot as a parameter (0 or 'main_hand' for main hand, 1 or 'off_hand' for off hand), and returns the name of the item in the requested slot (defaulting to the main hand if no parameter is supplied) if there is one, otherwise returns ''.

query.get_name

get the name of the mob if there is one, otherwise return ''

query.get_rendered_item_name

takes one optional hand slot as a parameter (0 or 'main_hand' for main hand, 1 or 'off_hand' for off hand), and returns the name of the item in the requested slot that is currently being rendered (defaulting to the main hand if no parameter is supplied) if there is one, otherwise returns ''.

query.ground_speed

Returns the ground speed of the entity in metres/second

query.has_armor_slot

Takes the armor slot index as a parameter, and returns 1.0 if the entity has armor in the requested slot, else it returns 0.0

query.has_cape

Returns 1.0 if the player has a cape, else it returns 0.0

query.has_collision

Returns 1.0 if the entity has collisions enabled, else it returns 0.0

query.has_gravity

Returns 1.0 if the entity is affected by gravity, else it returns 0.0

query.has_owner

Returns true if the entity has an owner ID else it returns false

query.has_rider

Returns 1.0 if the entity has a rider, else it returns 0.0

query.has_target

Returns 1.0 if the entity has a target, else it returns 0.0

query.head_roll_angle

returns the roll angle of the head of the wolf entity

query.head_x_rotation

Takes one argument as a parameter. Returns the nth head x rotation of the entity if it makes sense, else it returns 0.0

query.head_y_rotation

Takes one argument as a parameter. Returns the nth head y rotation of the entity if it makes sense, else it returns 0.0

query.invulnerable_ticks

Returns the number of ticks of invulnerability the entity has left if it makes sense, else it returns 0.0

query.is_alive

returns 1.0 if the entity is alive, and 0.0 if it's dead

query.is_angry

Returns 1.0 if the entity is angry, else it returns 0.0

query.is_avoiding_mobs

Returns 1.0 if the entity is fleeing from mobs, else it returns 0.0

query.is_baby

Returns 1.0 if the entity is a baby, else it returns 0.0

query.is_breathing

Returns 1.0 if the entity is breathing, else it returns 0.0

query.is_bribed

Returns 1.0 if the entity has been bribed, else it returns 0.0

query.is_carrying_block

Returns 1.0 if the entity is carrying a block, else it returns 0.0

query.is_casting

Returns 1.0 if the entity is casting, else it returns 0.0

query.is_celebrating

Returns 1.0 if the entity is celebrating, else it returns 0.0

query.is_charged

Returns 1.0 if the entity is charged, else it returns 0.0

query.is_charging

Returns 1.0 if the entity is charging, else it returns 0.0

query.is_chested

Returns 1.0 if the entity has chests attached to it, else it returns 0.0

query.is_critical

Returns 1.0 if the entity is critical, else it returns 0.0

query.is_dancing

Returns 1.0 if the entity is dancing, else it returns 0.0

query.is_delayed_attacking

returns 1.0 if the entity is attacking using the delayed attack, else it returns 0.0

query.is_eating

Returns 1.0 if the entity is eating, else it returns 0.0

query.is_elder

Returns 1.0 if the entity is an elder version of it, else it returns 0.0

query.is_enchanted

Returns 1.0 if the entity is enchanted, else it returns 0.0

query.is_fire_immune

Returns 1.0 if the entity is immune to fire, else it returns 0.0

query.is_first_person

Returns 1.0 if the entity is being rendered in first person mode, else it returns 0.0

query.is_ghost

returns 1.0 if an entity is a ghost, else it returns 0.0

query.is_gliding

Returns 1.0 if the entity is gliding, else it returns 0.0

query.is_grazing

Returns 1.0 if the entity is grazing, or 0.0 if not

query.is_idling

Returns 1.0 if the entity is idling, else it returns 0.0

query.is_ignited

Returns 1.0 if the entity is ignited, else it returns 0.0

query.is_illager_captain

Returns 1.0 if the entity is an illager captain, else it returns 0.0

query.is_in_love

Returns 1.0 if the entity is in love, else it returns 0.0

query.is_in_ui

Returns 1.0 if the entity is rendered as part of the UI, else it returns 0.0

query.is_in_water

Returns 1.0 if the entity is in water, else it returns 0.0

query.is_in_water_or_rain

Returns 1.0 if the entity is in water or rain, else it returns 0.0

query.is_interested

Returns 1.0 if the entity is interested, else it returns 0.0

query.is_invisible

Returns 1.0 if the entity is invisible, else it returns 0.0

query.is_jumping

Returns 1.0 if the entity is in water or rain, else it returns 0.0

query.is_laying_down

Returns 1.0 if the entity is laying down, else it returns 0.0

query.is_laying_egg

Returns 1.0 if the entity is laying an egg, else it returns 0.0

query.is_leashed

Returns 1.0 if the entity is leashed to something, else it returns 0.0

query.is_levitating

Returns 1.0 if the entity is levitating, else it returns 0.0

query.is_lingering

Returns 1.0 if the entity is lingering, else it returns 0.0

query.is_moving

Returns 1.0 if the entity is moving, else it returns 0.0

query.is_on_ground

Returns 1.0 if the entity is on the ground, else it returns 0.0

query.is_onfire

Returns 1.0 if the entity is on fire, else it returns 0.0

query.is_orphaned

Returns 1.0 if the entity is orphaned, else it returns 0.0

query.is_powered

Returns 1.0 if the entity is powered, else it returns 0.0

query.is_pregnant

Returns 1.0 if the entity is pregnant, else it returns 0.0

query.is_resting

Returns 1.0 if the entity is resting, else it returns 0.0

query.is_riding

Returns 1.0 if the entity is riding, else it returns 0.0

query.is_roaring

returns 1.0 if the entity is currently roaring, else it returns 0.0

query.is_rolling

Returns 1.0 if the entity is rolling, else it returns 0.0

query.is_saddled

Returns 1.0 if the entity has a saddle, else it returns 0.0

query.is_scared

Returns 1.0 if the entity is scared, else it returns 0.0

query.is_selected_item

returns true if the player has selected an item in the inventory

query.is_shaking

Returns 1.0 if the entity is casting, else it returns 0.0

query.is_shaking_wetness

returns true if the entity is shaking water off

query.is_sheared

Returns 1.0 if the entity is able to be sheared and is sheared, else it returns 0.0

query.is_shield_powered

Returns 1.0f if the entity has an active powered shield if it makes sense, else it returns 0.0

query.is_silent

Returns 1.0 if the entity is silent, else it returns 0.0

query.is_sitting

Returns 1.0 if the entity is sitting, else it returns 0.0

query.is_sleeping

Returns 1.0 if the entity is sleeping, else it returns 0.0

query.is_sneaking

Returns 1.0 if the entity is sneaking, else it returns 0.0

query.is_sneezing

Returns 1.0 if the entity is sneezing, else it returns 0.0

query.is_sprinting

Returns 1.0 if the entity is sprinting, else it returns 0.0

query.is_stackable

Returns 1.0 if the entity is stackable, else it returns 0.0

query.is_stalking

Returns 1.0 if the entity is stalking, else it returns 0.0

query.is_standing

Returns 1.0 if the entity is standing, else it returns 0.0

query.is_stunned

returns 1.0 if the entity is currently stunned, else it returns 0.0

query.is_swimming

Returns 1.0 if the entity is swimming, else it returns 0.0

query.is_tamed

Returns 1.0 if the entity is tamed, else it returns 0.0

query.is_transforming

Returns 1.0 if the entity is transforming, else it returns 0.0

query.is_using_item

Returns 1.0 if the entity is using an item, else it returns 0.0

query.is_wall_climbing

Returns 1.0 if the entity is climbing a wall, else it returns 0.0

query.item_in_use_duration

Returns the amount of time an item has been in use in seconds up to the maximum duration, else 0.0 if it doesn't make sense

query.item_is_charged

takes one optional hand slot as a parameter (0 or 'main_hand' for main hand, 1 or 'off_hand' for off hand), and returns 1.0 if the item is charged in the requested slot (defaulting to the main hand if no parameter is supplied), otherwise returns 0.0.

query.item_max_use_duration

Returns the maximum amount of time the item can be used, else 0.0 if it doesn't make sense

query.item_remaining_use_duration

Returns the amount of time an item has left to use in seconds, else 0.0 if it doesn't make sense

query.key_frame_lerp_time

Returns the ratio between the previous and next key frames

query.last_hit_by_player

Returns 1.0 if the entity was last hit by the player, else it returns 0.0. If called by the client always returns 0.0

query.lie_amount

Returns the lie down amount for the entity

query.life_span

returns the limited life span of an entity, or 0.0 if it lives forever

query.life_time

Returns the time in seconds since the current animation started, else 0.0 if not called within an animation

query.log

debug log a value

query.main_hand_item_max_duration

returns the use time maximum duration for the main hand item.

query.main_hand_item_use_duration

returns the use time for the main hand item.

query.mark_variant

Returns the entity's mark variant

query.max_trade_tier

Returns the maximum trade tier of the entity if it makes sense, else it returns 0.0

query.model_scale

Returns the scale of the current entity

query.modified_distance_moved

Returns the total distance the entity has moved horizontally in metres (since the entity was last loaded, not necessarily since it was originally created) modified along the way by status flags such as is_baby or on_fire

query.modified_move_speed

Returns the current walk speed of the entity modified by status flags such as is_baby or on_fire

query.overlay_alpha

Do not use - this function is deprecated and will be removed

query.owner_identifier

Returns the root actor identifier

query.player_level

returns the players level if the actor is a player, otherwise returns 0

query.position_delta

returns the position delta for an actor

query.previous_squish_value

Returns the previous squish value for the current entity, or 0.0 if this doesn't make sense

query.roll_counter

Returns the roll counter of the entity

query.shake_angle

returns the shaking angle of the wolf entity

query.shake_time

Returns the shake time of the entity.

query.sit_amount

Returns the current sit amount of the entity

query.skin_id

Returns the entity's skin ID

query.sleep_rotation

returns the rotation of the bed the player is sleeping on.

query.sneeze_counter

Returns the sneeze counter of the entity

query.spellcolor.b

Returns the blue colour channel of the current entity spell colour if it makes sense, else it returns 0.0

query.spellcolor.g

Returns the green colour channel of the current entity spell colour if it makes sense, else it returns 0.0

query.spellcolor.r

Returns the red colour channel of the current entity spell colour if it makes sense, else it returns 0.0

query.standing_scale

Returns the scale of how standing up the entity is

query.swell_amount

Returns how swollen the entity is

query.swelling_dir

Returns the swelling direction of the entity if it makes sense, else it returns 0.0

query.tail_angle

returns the angle of the tail of the wolf entity else it returns 0.0

query.target_x_rotation

Returns the x rotation required to aim at the entity's current target if it has one, else it returns 0.0

query.target_y_rotation

Returns the y rotation required to aim at the entity's current target if it has one, else it returns 0.0

query.time_stamp

Returns the current time stamp of the level

query.trade_tier

Returns the trade tier of the entity if it makes sense, else it returns 0.0

query.unhappy_counter

Returns how unhappy the entity is

query.variant

Returns the entity's variant index

query.vertical_speed

Returns the speed of the entity up or down in metres/second, where positive is up

query.walk_distance

Returns the walk distance of the entity.

query.wing_flap_position

Returns the wing flap position of the entity, or 0.0 if this doesn't make sense

query.wing_flap_speed

Returns the wing flap speed of the entity, or 0.0 if this doesn't make sense

query.yaw_speed

Returns the entity's yaw speed



This website is not affiliated with Mojang Studios or Microsoft