Molang

From Minecraft基岩版开发Wiki

Molang是一种简单的基于表达式的语言,为实时且快速地计算数值而设计。它的设计重点是在JavaScript无法大规模执行的需要更高性能的系统中启用类似脚本的功能。Mojang提供这些底层系统中的脚本功能来支持用户修改模组,自定义实体渲染动画

语法结构[edit]

基本语法[edit]

Molang的语法结构大多基于简单的C语言语法。脚本可以由一个简单数学计算表达式构成,当需要更复杂的代码的时候,它也可以由多个语句组成。

简单表达式[edit]

简单表达式指仅包含一个语句的完整表达式,例如:

math.sin(query.anim_time * 1.23)


复杂表达式[edit]

复杂表达式指包含两个及两以上语句的完整表达式,每个语句都按顺序求值。复杂表达式中每个语句句末必须使用“;”结尾,最后一句句末也需要;,例如:

temp.moo = math.sin(query.anim_time * 1.23);
temp.baa = math.cos(query.life_time + 2.0);
return temp.moo * temp.moo + temp.baa;

在复杂表达式中,也就是当有多个语句的句末皆以;结尾时,若无“return”语句或其他语句求值,将直接返回0.0。“return”语句将用来退出当前脚本作用域并计算其后表达式的值,类似C语言。

大小写区分[edit]

除字符串外,Molang中的所有内容都是不用区分大小写的。

关键字[edit]

关键字 描述
1.23 数值常量。
! && || < <= >= > == != 逻辑运算符
* / + - 基本数学运算符。

()

用于控制运算表达式的先后顺序的圆括号。

{}

用于控制执行作用域的花括号
?? 空值合并运算符,用于定义在变量丢失或活动对象不存在时的值。
geometry.texture_name 用于对几何文件内命名的引用。
material.texture_name 用于对材质文件内命名的引用。
math.function_name 预设数学函数,用于进行各种数学运算。
query.function_name 预设查询函数,用于对游戏内各项数据进行查询。
temp.variable_name 可读写临时变量存储器。
texture.texture_name 用于对纹理命名的引用。
variable.variable_name 可读写变量存储器。
?: 三元条件运算符。当问号左边的表达式为真,则将问号与冒号中间表达式的值作为整个表达式的取值,反之则将冒号后面表达式的值作为整个表达式的取值。
? 二元条件运算符。当运算符左边的表达式为真,则将右边表达式的值作为整个表达式的取值,反之直接输出0。
this 该脚本(在指定上下文的情况下)最终写入值的当前值。
return 用于在复杂表达式中计算其后的语句并停止脚本的执行,然后返回计算出的值。
-> 指针运算符,用于访问来自不同实体的数据。
context.variable_name 只读变量存储器。
loop 用于重复执行一段或多段语句“n”次。
for_each 用于遍历迭代一个实体数组。
break 用于提前退出“loop”或“for_each”的作用域。
continue 用于跳过“loop”或“for_each”迭代语句的剩余部分,并进入到下一次迭代。
[] 用于访问数组的方括号。

逻辑运算符[edit]

运算符

描述
优先级

示例

! 逻辑非运算符(一元运算符)。用于反转其后表达式的真假,使一个表达式的结果从true变为false,从false变为true 1 !query.is_sleeping
&& 逻辑与运算符(二元运算符)。用于将两个表达式连接成一个。只有当两个表达式都为true,整个表达式的结果才能为true 3 query.health == 10 && query.is_moving
|| 逻辑或运算符(二元运算符)。用于将两个表达式连接成一个。只要其中任意一个表达式为true整个表达式都为true 4 query.moving || query.is_swimming
< 小于运算符。用于比较左右两边表达式数值的大小,左边小于右边即为true,反之则为false 5 query.health < 5
<= 小于等于运算符。用于比较左右两边表达式数值的大小,左边小于或等于右边即为true,反之则为false 5 query.block_face <= 2
>= 大于等于运算符。用于比较左右两边表达式数值的大小,左边大于或等于右边即为true,反之则为false 5 math.ceil(query.health) >=query.on_fire_time
> 大于运算符。用于比较左右两边表达式数值的大小,左边大于右边即为true,反之则为false 5 query.day > 7
== 等于运算符。当左边与右边表达式的结果相等时即为true,反之则为false 2 query.block_face == query.cardinal_player_facing
!= 不等于运算符。当左边与右边表达式的结果不相等时即为true,反之则为false 2 query.body_x_rotation != query.body_y_rotation

变量[edit]

一个变量的生命周期可以是以下三种之一:临时变量、实体变量和上下文变量:

  • 临时变量(例如:temp.moo = 1;)是可读写的,并且依照C语言的规则,它们应在它们所定义的作用域中是有效的。出于性能原因,在当前的脚本执行中,临时变量的生存周期仍是全局的,并且可能在它们所定义的最外层作用域之外仍能返回一个有效值。故在复杂的表达式中需多加注意。Mojang将尽快为上述这种本应无效访问的情形添加内容日志错误。
  • 实体变量(例如:variable.moo = 1;)是可读写的,并在实体的生命周期内将其值存储在实体上。请注意,当前这些变量都不会被保存,所以退出和重新加载世界将使它们重新初始化。同样,如果实体从世界中消失,实体上的任何变量都将丢失。
  • 上下文变量(例如:context.moo)是只读的,并且只对运行它们的脚本有效。游戏内部定义了这些变量。

[edit]

  • 所有的数字值都是浮点数。
  • 布尔值都会被转换并存储为浮点值(0.0或1.0),分别表示false和true。
  • 对于布尔检测,等于0.0的浮点值为假,不等于0.0的值为真。
  • 对于数组下标,浮点数将采用C语言形式的强制转换转换为整型,当出现负数时钳制为0,数字过大时顶封到与数组长度相同。
  • 其他支持的类型有:
  1. 几何
  2. 纹理
  3. 材质
  4. 活动对象引用
  5. 活动对象引用数组
  6. 字符串
  7. 结构体
  • 错误(如被零除、变量丢失、空引用等)通常返回0.0值。

查询函数[edit]

查询函数(例如:query.is_babyquery.is_item_equipped('main_hand'))允许脚本读取游戏数据。如果查询函数不含带参数,则括号()可以不写。有关查询函数的完整列表,可参见下方的查询函数清单

别名[edit]

为了减少打字负担并在阅读和编写Molang时提高可读性,以下关键字的别名可以使开发者在编写过程中更轻松。下表左侧和右侧的功能相同。

别名映射[edit]

全名 别名
context.moo c.moo
query.moo q.moo
temp.moo t.moo
variable.moo v.moo

下方是一个示例:

math.cos(query.anim_time * 38) * variable.rotation_scale + variable.x * variable.x * query.life_time;

该示例也可以也可以写成:

math.cos(q.anim_time * 38) * v.rotation_scale + v.x * v.x * q.life_time

这两种语法还可以根据需要来混合使用,例如:

math.cos(q.anim_time * 38) * variable.rotation_scale + v.x * variable.x * query.life_time

结构体[edit]

与C语言不同,数据结构是通过使用方法隐式定义的。它们的目的是更有效地传递数据,例如传递v.location而非v.xv.yv.z。例如:

v.location.x = 1;
v.location.y = 2;
v.location.z = 3;
v.another_mob_set_elsewhere->v.first_mobs_location = v.location;

下方给出的更多脚本示例中,每个都会返回1.23

v.cowcow.friend = v.pigpig; v.pigpig->v.test.a.b.c = 1.23; return v.cowcow.friend->v.test.a.b.c;
v.cowcow.friend = v.pigpig; v.pigpig->v.test.a.b.c = 1.23; v.moo = v.cowcow.friend->v.test; return v.moo.a.b.c;
v.cowcow.friend = v.pigpig; v.pigpig->v.test.a.b.c = 1.23; v.moo = v.cowcow.friend->v.test.a; return v.moo.b.c;
v.cowcow.friend = v.pigpig; v.pigpig->v.test.a.b.c = 1.23; v.moo = v.cowcow.friend->v.test.a.b; return v.moo.c;
v.cowcow.friend = v.pigpig; v.pigpig->v.test.a.b.c = 1.23; v.moo = v.cowcow.friend->v.test.a.b.c; return v.moo;

嵌套或递归的结构可以拥有任意深度。也就是说,尽量不要将一个完整的结构体复制到其他结构中,以免由于被复制的结构体层次过深导致游戏在遍历时出现内存溢满,也不要将结构体做得太深,因为每深一层游戏都会损失部分性能。

字符串[edit]

Molang中的字符串用单引号引起来,例如:'minecraft:pig''hello world!'。空字符串定义为两个相对的单引号,此时对字符串的操作仅支持==!=[注 1]

参数[edit]

函数的参数写在函数末尾的圆括号中,每两个参数之间使用,隔开,例如:

math.random(0,3)

函数名math.random与参数括号(0,3)之间不能有空格,每个参数两边允许有任意数量的空格。

Molang中并不是所有的函数都能使用参数;不同函数中参数的位置不同,作用也不同。

运算表达[edit]

公共变量[edit]

通常,一个生物的变量被认为是该生物的私有变量,而另一个生物无法访问。要向其他生物开放此变量的只读访问权限,需要在所拥有实体的资源定义中对该变量设置"public"。另外,建议默认初始化变量。

{
  "format_version": "1.10.0",
  "minecraft:client_entity": {
    "description": {
      ...
      "scripts": {
        "variables": {
          "variable.oink": "public"
        },
        "initialize": [
          "variable.oink = 0;"
        ],
        ...
      },
      ...
    }
  }
}


{}花括号作用域定界符[edit]

通过用{}符号限定,可以将一系列语句划分为一个组。这主要用于循环和条件语句中:

(v.moo > 0) ? {
  v.x = math.sin(q.life_time * 45);
  v.x = v.x * v.x + 17.3;
  t.sin_x = math.sin(v.x);
  v.x = t.sin_x * t.sin_x + v.x * v.x;
  v.x = math.sqrt(v.x) * v.x * math.pi;
}


loop[edit]

“loop”函数用于多次执行表达式,其包含两个参数:loop(count,expression);,第一个参数用于设置循环次数,第二个参数为需要循环执行的表达式。为了安全起见,Mojang对该函数设置了循环次数限制,其循环计数器最大次数为1024。另外,尽量不要将过多循环函数套用。

使用该函数可以编写出一些特别的功能,例如斐波那契数计算器:

v.x = 1;
v.y = 1;
loop(10, {
  t.x = v.x + v.y;
  v.x = v.y;
  v.y = t.x;
});


for_each[edit]

为了遍历一个数组,需要使用“for_each”函数(例如query.get_nearby_entities将返回一个包含实体的数组)。它需要三个参数:for_each(variable, array, expression);,其中的第一个参数可以是任何的变量,包括temp.variable.,使用temp.可以防止污染实体的变量空间;第二个参数是一个数组;第三个参数是为数组中的每个元素执行的任何Molang表达式。

->指针运算符[edit]

查询函数的一些返回值,或者存储在临时/实体/上下文变量中的值可以是对另一个实体的调用。“->”运算符允许脚本访问变量或对该实体进行查询。例如,下面的示例将查询当前实体四米范围内的所有羊(如果该实体是羊,则包括其自身),如果每只羊正上方的方块带有stone标签,则增加变量v.x

"v.x = 0;
for_each(v.pig, query.get_nearby_entities(4, 'minecraft:sheep'), {
    v.x = v.x + v.pig->query.relative_block_has_all_tags(0, 1, 0, 'stone');
});"

如果“->”运算符的左侧有错误(值为null,该实体之前已被清除,或者存在其他问题),则表达式不会计算右边的值,并返回0。

break[edit]

该运算符用于提前退出“loop”或“for_each”。例如:

v.x = 1;
v.y = 1;
loop(10, {t.x = v.x + v.y; v.x = v.y; v.y = t.x; (v.y > 20) ? break;});

根据C风格的语言规则,这将立即退出最内部的活动循环。

如果使用下方示例:

v.x = 0;
loop(10, {loop(10, {v.x = v.x + 1; (v.x > 5) ? break;});});

v.x大于5时,“break”语句将终止内部循环,并继续处理外部循环的脚本。由于v.x未在外部循环之间重置,因此第二次进入内部循环时,这将使v.x再添加1,然后再次退出内部循环,从而导致v.x的最终值为6+1+1+1+…+1=15。

continue[edit]

“continue”函数按照C风格的语言规则执行函数,当前仅在循环中受支持。使用该函数可跳到当前循环的下一个迭代。关于内部/外部循环的更多详细信息,请参见上方的“break”。

下方示例将导致v.x变为6.0,因为一旦达到该值,剩余增量将被跳过。[注 2]

v.x = 0;
loop(10, {
  (v.x > 5) ? continue;
  v.x = v.x + 1;
});


??空值合并运算符[edit]

C#中的空值合并运算符的工作方式类似,使用空值合并运算符可以引用可能存在或可能不存在的变量,而不会看到内容错误。以前,如果变量不存在,则会出现内容错误。这是为了确保变量始终正确初始化,以避免未初始化的变量错误,但这需要初始化脚本,或者在某些情况下需要一些复杂的解决方案来确保变量被初始化。现在,如果提前知道某个变量不会在脚本的第一次运行中初始化,则可以使用该运算符:

variable.x = (variable.x ?? 1.2) + 0.3;

上述示例中,如果有效,则使用variable.x的值;如果variable.x无效,则会使用1.2

下方列出了变量无效的情况:

  • 尚未初始化
  • 对已删除实体的引用
  • 无效的引用
  • 包含错误内容

“??”运算符仅对variable.temp.context.有效,它们包含对数字或实体的引用,但不包含诸如材质纹理几何等资源(因为这些必须存在且有效,否则这将是内容错误)。如果第一个参数出现错误,它将返回第二个参数。[注 3]

分域示例[edit]

实体脚本定义[edit]

在定义文件中有一个预计算值的部分,这些值在动画和渲染控制器被处理之前立即执行,并存储在实体中。其目的是预先计算您可能希望在脚本中再次使用的任何昂贵的复杂值,长作用域索引变量更新,或者通常是任何一次性计算的呈现刻。

"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);",
    ]
  },

动画与动画控制器文件[edit]

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

渲染控制器[edit]

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.

数组表达式[edit]

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

资源表达式[edit]

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: 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 a specific geometry

"geometry": "geometry.my_geo"

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]"

资源段落[edit]

几何[edit]

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.

材质[edit]

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" }
    ],
  1. This will start by applying Material.default to all model parts.
  2. 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.
  3. It will look up the same material as the expression is identical, and apply it to the Mane model part.
  4. 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.

函数表达[edit]

数学函数[edit]

名称 描述
math.abs(value) value的绝对值。
math.acos(value) value的反余弦值。
math.asin(value) value的反正弦值。
math.atan(value) value的反正切值。
math.atan2(y,x) y/x的反正切值(注:注意参数的顺序)。
math.ceil(value) 将value向上取整。
math.clamp(value,min,max) 将value限定在最小值(min)到最大值(max)之间。
math.cos(value) value的余弦值。
math.die_roll(num,low,high) 返回num个随机数的总和,每个值的范围在最低(low)到最高(high)范围之间(注:生成的随机数不是像一般骰子那样的整数,若为此,请使用math.die_roll_integer)。
math.die_roll_integer(num,low,high) 返回num个随机整数的总和,每个值的范围在最低(low)到最高(high)范围之间。
math.exp(value) 计算value以e为底数的指数函数。
math.floor(value) 将value向下取整。
math.hermite_blend(value) 待补充
math.lerp(start,end,0_to_1) 待补充
math.lerprotate(start,end,0_to_1) 待补充
math.ln(value) value的自然对数。
math.max(A,B) 返回A和B中的最大值。
math.min(A,B) 返回A和B中的最小值。
math.min_angel(value) 将value(角度)最小化到[-180,180)的范围(单位:度)。
math.mod(value,denominator) 返回value除以denominator(分母)后的余数。
math.pi 返回常量π的浮点数形式。
math.pow(base,exponent) 返回base(底数)的exponent(指数)次幂。
math.random(low,high) 最低(low)到最高(high)范围内的随机数(注:随机数不包含low)。
math.random_integer(low,high) 最低(low)到最高(high)范围内的随机整数(注:随机整数包含low和high)。
math.round(value) 将value四舍五入取整。
math.sin(value) value的正弦值。
math.sqrt(value) value的平方根。
math.trunc(value) 截短法取整。

查询函数[edit]

查询函数是布尔表达式,允许您查询引擎在不同情况下拥有的值。它们可以用在Molang表达式中。可用于控制位置,纹理,动画等内容。

例如:

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

查询函数清单[edit]

名称 描述
query.above_top_solid 返回位于(x,z)位置正上方最高固体方块的高度。
query.actor_count 返回上一帧中渲染的活动对象的数量。
query.all_animations_finished (仅在动画中有效)如果当前动画控制器下的所有动画至少播放了一次则返回1.0,否则返回0.0。
query.all_tags 返回物品方块所具有的所有指定标签
query.anim_time 返回动画自开始以来的时间(以秒为单位),如果动画未被调用则返回0.0。
query.any_animation_finished (仅在动画控制器中有效)如果当前动画控制器下的任意动画至少播放了一次则返回1.0,否则返回0.0。
query.any_tag 返回物品或方块所具有的任意指定标签。
query.approx_eq 如果所有参数都在0.000000之内,则返回1.0,否则返回0.0。
query.armor_color_slot 将护甲栏编号作为参数,并返回所查询的护甲栏中护甲的颜色。
query.armor_material_slot 将护甲栏编号作为参数,并返回所查询的护甲栏中护甲的材料类型。
query.armor_texture_slot 将护甲栏编号作为参数,并返回所查询的护甲栏中护甲的纹理类型。
query.average_frame_time 以秒为单位返回过去n帧中的平均每帧的时间。如果输入的参数已过效,则认定为您要查询的是过去的帧数。query.average_frame_time(或相同效果的query.average_frame_time(0))将返回当前帧之前的帧的时间。query.average_frame_time(1)将返回前两帧的平均帧的时间。目前,游戏会存储最近30帧的历史记录,但将来可能会有所变化。请求更多帧只会导致对存储的帧数进行采样。
query.block_face 返回该方块的面(仅对某些触发器有效,例如minecraft:on_player_placingminecraft:on_interact)(下=0.0,上=1.0,北=2.0,南=3.0,西=4.0,东=5.0,未定义=6.0)。
query.block_property 返回所查询的方块属性的值。
query.block_neighbor_has_all_tags 查询方块边上的某个块(根据填入的x,y,z)所有tag是否等于填入的那个tag,如果是,返回1.0,否则返回0.0
query.block_neighbor_has_any_tag 查询方块是否有tag等于填入的tag,如果是,返回1.0,否则返回0.0
query.blocking 如果实体正在搬运或放置方块(例如末影人),则返回1.0,否则返回0.0。
query.body_x_rotation 若对活动对象调用,则返回活动对象身体的x轴旋转角度,否则返回0.0。
query.body_y_rotation 若对活动对象调用,则返回活动对象身体的y轴旋转角度,否则返回0.0。
query.camera_distance_range_lerp 取两个距离(任意顺序),并根据相对于这两个距离范围之间的视角距离返回从0到1的数字。例如,对于小于或等于10的任何距离,query.camera_distance_range_lerp(10,20)将返回0;对于12的距离,则返回0.2;对于15的距离,则返回0.5;对于大于等于20的距离,会返回1。如果您输入(20,10),则距离为20时将返回0.0。
query.camera_rotation 返回视角的旋转角度。需要一个参数代表您想要的旋转轴(0=x轴,1=y轴)。
query.can_climb 如果实体可以攀爬,则返回1.0,否则返回0.0。
query.can_damage_nearby_mobs 如果实体可以对附近的生物造成伤害,则返回1.0,否则返回0.0。
query.can_fly 如果实体可以飞行,则返回1.0,否则返回0.0。
query.can_power_jump 如果实体可以蓄力跳跃,则返回1.0,否则返回0.0。
query.can_swim 如果实体可以游泳,则返回1.0,否则返回0.0。
query.can_walk 如果实体可以行走,则返回1.0,否则返回0.0。
query.cape_flap_amount 返回0.0到1.0之间的值,其中0.0表示披风完全垂下,1.0表示披风完全飘起。
query.cardinal_block_face_placed_on 已废弃(请使用query.block_face。)
query.cardinal_facing 返回玩家当前的面部朝向(下=0.0,上1.0,北=2.0,南=3.0,西=4.0,东=5.0,未定义=6.0)。
query.cardinal_facing_2d 返回玩家当前面部在2D平面上的朝向(忽略上/下朝向,北=2.0,南=3.0,西=4.0,东=5.0,未定义=6.0)。
query.cardinal_player_facing 返回玩家当前的面部朝向(下=0.0,上1.0,北=2.0,南=3.0,西=4.0,东=5.0,未定义=6.0)。
query.combine_entities 将来自所有参数的任何有效实体引用组合到单个数组中。注意:不保留顺序,并且会删除重复值和无效值。
query.count 计数读取该内容包含的值的数量(将数组计为它们包含的元素数;非数组计为1)。
query.current_squish_value 返回当前实体的压缩值,如果没有意义,这返回0.0。
query.day 返回当前存档中度过的天数。
query.debug_output
query.delta_time 以秒为单位返回自上一帧以来的时间。
query.distance_from_camera
query.effect_emitter_count
query.effect_particle_count
query.equipment_count 返回活动对象携带的装备数量。
query.equipped_item_all_tags
query.equipped_item_any_tags
query.equipped_item_is_attachable 如果物品是附着物,则返回1.0,否则返回0.0。
query.eye_target_x_rotation
query.eye_target_y_rotation
query.frame_alpha
query.get_actor_info_id 返回活动对象的数字ID,多用于配方中作为minecraft:spawn_egg特殊值传入。
query.get_animation_frame 返回动画当前帧,如果无意义,则返回0.0
query.get_equipped_item_name 返回实体手持物品名,如果无意义,则返回0.0
query.get_locator_offset
query.get_name 返回实体的名称,如果有的话,否则返回''。
query.get_root_locator_offset
query.ground_speed 返回实体米/每秒的速度值。
query.has_any_family 如果实体携带所查询的任一家族名称,则返回1.0,否则返回0.0。该查询允许接受多个家族名称作为参数。
query.has_armor_slot 将护甲栏编号作为参数,如果实体在请求的护甲栏中有护,则返回1.0,否则返回0.0
query.has_biome_tag
query.has_block_property
query.has_cape 如果玩家有披风,则返回1.0,否则返回0.0。
query.has_collision 如果实体有碰撞箱,则返回1.0,否则返回0.0。
query.has_gravity 如果实体受重力影响,则返回1.0,否则返回0.0。
query.has_owner 如果实体有主人ID,则返回true,否则返回false。
query.has_rider 如果实体有乘骑者,则返回1.0,否则返回0.0。
query.has_target 如果实体有目标,则返回1.0,否则返回0.0。
query.head_roll_angel
query.head_x_rotation 让实体(如凋灵)的第N个头跟随第1个头(动画列表第1个列出的头)关于x轴旋转,如果无意义则返回0.0。
query.head_y_rotation 让实体(如凋灵)的第N个头跟随第1个头(动画列表第1个列出的头)关于y轴旋转。如果无意义则返回0.0。
query.health 返回当前实体的生命值,如果调用该实体的生命值没有意义,则返回0.0。
query.heightmap 获取高度图。
query.hurt_direction
query.hurt_time
query.invulnerable_ticks
query.is_admiring 如果实体羡慕你手上的物品,则返回1.0,否则返回0.0
query.is_alive 如果实体正存活着,则返回1.0,否则返回0.0。
query.is_angry 如果实体处于愤怒状态,则返回1.0,否则返回0.0。
query.is_attached_to_entity 如果活动对象(特指附着物)正附加在实体上,则返回1.0,否则返回0.0。
query.is_avoiding_block 如果实体正在避开方块,则返回1.0,否则返回0.0。
query.is_avoiding_mobs 如果实体正在躲避生物,则返回1.0,否则返回0.0。
query.is_baby 如果实体处于幼年,则返回1.0,否则返回0.0。
query.is_breathing 如果实体正在呼吸,则返回1.0,否则返回0.0。
query.is_bribed 如果实体通过投喂等为玩家做事(比如喂食海豚使之为你寻找遗迹)则返回1.0,否则返回0.0
query.is_carrying_block 如果实体拿着方块,则返回1.0,否则返回0.0。
query.is_casting
query.is_celebrating 如果实体正在庆贺,则返回1.0,否则返回0.0。
query.is_celebrating_special 如果实体正在特殊庆贺,则返回1.0,否则返回0.0。
query.is_charged 如果实体变为闪电苦力怕,则返回1.0,否则返回0.0。
query.is_charging
query.is_chested 如果实体装配有箱子(例如羊驼),则返回1.0,否则返回0.0。
query.is_critical
query.is_dancing 如果实体正在跳舞,则返回1.0,否则返回0.0。
query.is_delayed_attacking 如果实体携带minecraft:behavior.delayed_attack行为并处于攻击状态时,则返回1.0,否则返回0.0。
query.is_eating 如果实体正在进食,则返回1.0,否则返回0.0。
query.is_elder 如果实体处于成年,则返回1.0,否则返回0.0。
query.is_emoting
query.is_enchanted 如果活动对象(特指附着物)被附魔,则返回1.0,否则返回0.0。
query.is_fire_immune 如果实体对火焰免疫,则返回1.0,否则返回0.0。
query.is_first_person 如果实体(特指玩家)处于第一人称视角,则返回1.0,否则返回0.0。
query.is_ghost 如果实体处于死亡状态,则返回1.0,否则返回0.0。
query.is_gliding 如果实体正在滑动,则返回1.0,否则返回0.0。
query.is_grazing 如果实体正在吃方块(例如),则返回1.0,否则返回0.0。
query.is_idling 如果实体处于闲置状态,则返回1.0,否则返回0.0。
query.is_ignited 如果实体被点燃,则返回1.0,否则返回0.0。
query.is_illager_captain 如果实体是袭击队长,则返回1.0,否则返回0.0。
query.is_in_love 如果实体正在发情,则返回1.0,否则返回0.0。
query.is_in_ui 如果实体正在UI中,则返回1.0,否则返回0.0。
query.is_in_water 如果实体处于水中,则返回1.0,否则返回0.0。
query.is_in_water_or_rain 如果实体处于水中或中,则返回1.0,否则返回0.0。
query.is_interested 如果实体感兴趣,则返回1.0,否则返回0.0。
query.is_invisible 如果实体处于隐身状态,则返回1.0,否则返回0.0。
query.is_item_equipped 根据输入参数返回主手或副手是否持有物品(0或main_hand代表主手,1或off_hand代表副手)。
query.is_jumping 如果实体正在跳跃,则返回1.0,否则返回0.0。
query.is_laying_down 如果实体处于躺下的状态,则返回1.0,否则返回0.0。
query.is_laying_egg 如果实体正在产卵(例如海龟),则返回1.0,否则返回0.0。
query.is_leashed 如果实体被栓绳牵引,则返回1.0,否则返回0.0。
query.is_levitating
query.is_moving 如果实体正在移动,则返回1.0,否则返回0.0。
query.is_on_fire
query.is_on_ground 如果实体正处于地面上,则返回1.0,否则返回0.0。
query.is_on_screen
query.is_onfire 如果实体着火了,则返回1.0,否则返回0.0
query.is_orphaned 如果实体是孤儿,则返回1.0,否则返回0.0
query.is_persona_or_premium_skin
query.is_powered 如果实体携带minecraft:is_charged组件,则返回1.0,否则返回0.0。
query.is_pregnant 如果实体怀孕了(海龟怀蛋等),则返回1.0,否则返回0.0
query.is_ram_attacking
query.is_resting 如果实体在休息(狐狸),则返回1.0,否则返回0.0
query.is_riding 如果实体正处于骑乘状态,则返回1.0,否则返回0.0。
query.is_roaring 如果实体携带minecraft:behavior.knockback_roar行为并处于吼叫时间时,则返回1.0,否则返回0.0。
query.is_rolling
query.is_saddled 如果实体携带minecraft:is_saddled组件,则返回1.0,否则返回0.0。
query.is_scared
query.is_selected_item
query.is_shaking
query.is_shaking_wetness
query.is_sheared 如果实体携带minecraft:is_sheared组件,则返回1.0,否则返回0.0。
query.is_shield_powered
query.is_silent
query.is_sitting
query.is_sleeping 如果实体正在睡觉,则返回1.0,否则返回0.0。
query.is_sneacking
query.is_sneezing
query.is_sprinting 如果实体正在冲刺,则返回1.0,否则返回0.0。
query.is_stackable 如果实体携带minecraft:is_stackable组件,则返回1.0,否则返回0.0。
query.is_stalking 如果实体携带minecraft:behavior.stalk_and_pounce_on_target行为且处于匍匐靠近的时间内,则返回1.0,否则返回0.0。
query.is_standing
query.is_stunned 如果实体携带minecraft:is_stunned组件,则返回1.0,否则返回0.0。
query.is_swimming 如果实体在游泳,则返回1.0,否则返回0.0
query.is_tamed 如果实体携带minecraft:is_tamed组件,则返回1.0,否则返回0.0。
query.is_transforming 如果实体在转变(僵尸村民转村民等),返回1.0,否则返回0.0
query.is_using_item 如果实体正在使用一个物品,则返回1.0,否则返回0.0。
query.is_wall_climbing 如果实体在爬墙(蜘蛛,玩家爬梯),则返回1.0,否则返回0.0
query.item_in_use_duration
query.item_is_charged 如果物品被充能,则返回1.0,否则返回0.0
query.item_max_use_duration
query.item_remaining_use_duration
query.item_slot_to_bone_name
query.key_frame_lerp_time
query.last_frame_time
query.last_hit_by_player 如果实体的上一次受伤记录是否由玩家造成,则返回1.0,否则返回0.0。
query.lie_amount
query.life_span
query.life_time
query.lod_index
query.log
query.main_hand_item_max_duration
query.main_hand_item_use_duration
query.mark_variant 查询实体变体标记,如果无意义,则返回0.0
query.max_durability 查询物品最大耐久度,若无意义,则返回0.0
query.max_health 查询实体最大生命值,若无意义,则返回0.0
query.max_trade_tire
query.maximum_frame_item
query.minimum_frame_time
query.model_scale 查询实体模型缩放比例,若无意义,则返回0.0
query.modified_distance_moved 查询实体修改过的移动方向,若无意义,则返回0.0
query.modified_move_speed 查询实体更改过的移速,若无意义,则返回0.0
query.moon_brightness 查询当前月亮亮度,若无意义,则返回0.0
query.moon_phase 查询月亮当前阶段(满月,下弦月,上弦月等),若无意义,则返回0.0
query.movement_direction 查询实体运动方向,若无意义,则返回0.0
query.noise 获取柏林噪声
query.on_fire_time 查询实体着火时间,若无意义则返回0.0
query.out_of_control 查询实体是否失控,若无意义,则返回0.0
query.overlay_alpha 已废弃(请勿使用!此函数已被废弃,并将会被删除。)
query.owner_identifier 返回一串父类实体携带的以"<namespace>": "<identifier>"为格式的字符串,常用来判断物品持有者的类型。
query.player_level 返回实体(特指玩家)的等级,否则返回0.0。
query.position 返回实体在世界中的绝对坐标。它根据一个参数来返回对应轴的坐标,0代表x轴,1代表y轴,2代表z轴。
query.position_delta 返回实体上一帧的相对位移。它接收一个参数来返回对应轴的坐标,0代表x轴,1代表y轴,2代表z轴。
query.previous_squish_value
query.remaining_durability 返回物品的剩余耐久度
query.roll_counter
query.rotation_to_camera
query.shake_angel
query.shack_time
query.shield_blocking_bob
query.sit_amount
query.skin_id
query.sleep_rotation
query.sneeze_counter
query.spellcolor
query.standing_scale
query.structural_integrity
query.swell_amount
query.swelling_dir
query.swim_amount
query.tail_angel
query.target_x_rotation
query.target_y_rotation
query.texture_frame_index
query.time_of_day
query.time_stamp
query.total_emitter_count
query.total_particle_count
query.trade_tier
query.unhappy_counter
query.variant
query.vertical_speed
query.walk_distance
query.wing_flap_position
query.wing_flap_speed
query.yaw_speed

实验性查询函数清单[edit]

名称 描述
query.biome_has_all_tags
query.biome_has_any_tag
query.block_has_all_tags
query.block_has_any_tag
query.bone_orientation_matrix
query.bone_orientation_trs
query.client_input_type 根据当前客户端使用的操作方式返回"mouse"(鼠标),"touch"(触屏),"gamepad"(手柄)或"motion_controller"(运动传感器)。
query.get_nearby_entities 返回当前实体周围筛选出的实体,它接收两个参数,其中第二个参数为缺省参数。第一个指代长度距离,第二个指代实体的命名空间:标识符。
query.get_nearby_entities_except_self 返回当前实体周围筛选出的不包括自己的实体,它接收两个参数,其中第二个参数为缺省参数。第一个指代长度距离,第二个指代实体的命名空间:标识符。
query.get_ride 如果该实体正在乘骑某实体,则返回被乘骑的实体,否则返回0.0。
query.get_riders 以数组的形式返回该实体的乘骑者。
query.has_player_rider 如果实体被玩家乘骑,则返回1.0,否则返回0.0。
query.is_attaches 如果一个活动对象附着于另一个活动对象上,则返回1.0(例如被持有或被穿戴),否则返回0.0。
query.relative_block_has_all_tags 根据相对实体坐标,如果该方块拥有所有指定的标签,则返回1.0,否则返回0.0。
query.relative_block_has_any_tag 根据相对实体坐标,如果该方块拥有任意指定的标签,则返回1.0,否则返回0.0。
query.scoreboard 返回当前实体的计分板信息,它接受一个参数用来指代记分项。
query.self 返回当前实体。
query.target 返回当前实体目标(如果存在)。

内置变量[edit]

Mojang为游戏内置了一些特殊的变量,这些变量可以在对应的地方起特殊作用。

实体变量[edit]

名称
描述
variable.aabb.x
variable.aabb.y
variable.aabb.z
variable.aabb_dimension.x
variable.aabb_dimension.y
variable.actor.speed
variable.cloud_lifetime
variable.cloud_radius
variable.color.a
variable.color.b
variable.color.g
variable.color.r
variable.direction.x
variable.direction_x
variable.direction.y
variable.direction_y
variable.direction.z
variable.direction_z
variable.direction_vector.x
variable.direction_vector.y
variable.direction_vector.z
variable.emitter_age Age since the current loop started for the emitter
variable.emitter_intensity
variable.emitter_lifetime How long the current loop lasts for the emitter
variable.emitter_radius
variable.emitter_random_1 A random from 0.0 to 1.0 that is constant for the current loop of the emitter
variable.emitter_random_2 Another random from 0.0 to 1.0 that is constant for the current loop of the emitter
variable.emitter_random_3 A third random from 0.0 to 1.0 that is constant for the current loop of the emitter
variable.emitter_random_4 A fourth random from 0.0 to 1.0 that is constant for the current loop of the emitter
variable.emitter_texture_coordinate.u
variable.EmitterTextureCoord.u
variable.emitter_texture_coordinate.v
variable.EmitterTextureCoord.u
variable.emitter_texture_size.u
variable.EmitterTextureSize.u
variable.emitter_texture_size.v
variable.EmitterTextureSize.u
variable.entity_scale When the effect is attached to an entity, this value is the scale of the entity
variable.is_outside_water
variable.particlecount
variable.particlesize
variable.particle_age How long the particle has lived
variable.particle_lifetime

How long the particle lives for

variable.particle_multiplier
variable.particle_random_1 A random from 0.0 to 1.0 that is constant for the lifetime of the particle
variable.particle_random_2 Another random from 0.0 to 1.0 that is constant for the lifetime of the particle
variable.particle_random_3 A third random from 0.0 to 1.0 that is constant for the lifetime of the particle
variable.particle_random_4 A fourth random from 0.0 to 1.0 that is constant for the lifetime of the particle
variable.size_modifier
variable.speed_modifier
variable.velocity_scalar

上下文变量[edit]

名称 描述
context.is_first_person
context.item_slot
context.player_offhand_arm_height
context.other

实验性运算符[edit]

未来的一些运算符可能暂时属于实验性玩法,它们将在此处列出。目前Mojang尚未添加任何实验性运算符。

版本化变更[edit]

清单文件中的"min_engine_version"决定了Molang表达式在附加包中以哪个游戏版本的规则进行运作。任何版本小于或等于"min_engine_version"的版本化变更都能够起作用。

最低引擎版本[注 4] 变更内容
1.17.30 修复了query.item_remaining_use_duration从刻到秒转换时的问题(乘以20而不是除以)。还修复了该查询函数中从1降到0而不是从0升到1的正规化逻辑。
1.17.40 为以前可能会产生意外结果的无效表达式添加了一些新的报错信息。例如'text'+1现在将导致内容日志报错。
1.18.10 修复了嵌套的条件(三元)运算符解析顺序应该为从右到左而不应该是从左到右的问题。以前嵌套的条件表达式如A?B:C?D:E将计算为为(A?B:C)?D:E,现在它们计算为A?B:(C?D:E)


历史[edit]

基岩版
1.7.01.7.0.2加入了MoLang。
1.16.2001.16.200.51修复了当在已重命名的物品上使用query.get_equired_item_name无法返回正确的结果的问题。现在将其与游戏版本绑定,以便在世界绑定了指定版本时返回其旧的名称。
1.16.200.52新增了query.cardinal_facing_2d来获取一个不包含上下的水平面方向。
1.16.200.55修复了query.cardinal_block_face_placed_on不与minecraft:on_player_placing一起工作的问题。
GeometryMaterialTexture变量名现在可以包含“.”。
1.16.2301.16.230.50修复了query.is_in_ui使其可以对数据驱动实体在UI中渲染时使用。
1.17.01.17.0.52新增了一个查询函数以获取默认骨骼枢轴。
更新了查询函数,用于返回基于给定参数的正规化物品剩余使用时间。
1.17.101.17.10.20现在可以对末影龙使用query.wing_flap_position了。
新增了query.show_bottom来用于确定实体底部是否被渲染。
新增了query.death_time用于确定生物开始死亡后经过的时间。
新增了math.min_angel来将角度最小化到[-180,180)的范围。
1.17.201.17.20.23附加包清单文件中的min_engine_version字段现在可以被传入MoLang解析。
1.17.301.17.30.20修复了query.item_remaining_use_duration缩放不正确或结果倒置的问题(这是为了添加文档中对1.17.30引擎版本以后的版本化变更)。
新增了facing_target_to_range_attack来返回被查询活动对象的minecraft:behavior.ranged_attack AI意向当前是否在执行。
实验性查询函数和语言表达式现在在文档中列出。
文档从query.item_remaining_use_duration开始详细介绍版本化变更。
1.17.30.21query.bone_orientation_trs现在会返回正确的Y轴平移及缩放结果。
新增了query.block_neighbor_has_any_tagsquery.block_neighbor_has_all_tags两项查询函数(需要实验性玩法)。
当进入一个资源包中使用了含有query.armor_color_slot的世界时,将不再发生崩溃。
将实验性的查询函数(除与活动对象属性相关的查询函数外)移到了新的“实验性MoLang功能”实验性玩法选项中。
1.17.30.23MoLang改名为Molang。
物品冷却加入了相关的查询函数: query.is_cooldown_typequery.cooldown_time,和query.cooldown_time_remaining
更新了更多的Molang内容日志报错来表示对应的运算符或查询函数。
1.17.401.17.40.20text + 3等在之前被忽略的表达式加入了新的编译错误报告。
修复了query.item_remaining_use_duration给出的结果会不正确缩放或倒置的问题。
1.17.40.21现在包含大写字母的Molang表达式会被正确解析了。
query.get_equipped_item_name查询函数现在会正确识别海晶灯
1 + (9 10)等在之前被忽略的表达式加入了新的编译错误报告。
1.18.01.18.0.25修复了未将Molang表达式的min_engine_version标记为仅1.17.40或更高版本时触发的内容日志报错。
1.18.101.18.10.22加入非实验性的is_name_anyis_item_name_anyis_owner_identifier_any查询函数。
修复了relative_block_has_all_tagsblock_neighbor_has_all_tagsbiome_has_all_tags查询函数应该需要所有标签而不应该是任何标签的问题。
修复了嵌套的条件(三元)运算符解析顺序应该为从右到左而不应该是从左到右的问题。

漏洞[edit]

关于“Molang”的漏洞在国际版中由漏洞追踪器维护,请在此汇报漏洞。

你知道吗[edit]

  • 1.8.0.24起官方文档中开始出现Molang,而从1.16.200.51起,Mojang才开始在更新日志中写入关于Molang的更新内容。
  • Molang最初就是为了动画动画控制器渲染控制器数据驱动而加入的。
  • 全局参数是旧版本游戏中Molang的一种关键字,它从1.10.0.3起被查询函数取代。全局参数有以下5种:global.anim_timeglobal.delta_timeglobal.key_frame_lerp_timeglobal.life_timeglobal.frame_alpha,它们分别对应现在的query.anim_timequery.delta_timequery.key_frame_lerp_timequery.life_timequery.frame_alpha
  • 1.8.0.11及更早的版本中,查询函数的格式为entity.flags.fooentity.member.foo,并且函数名使用驼峰命名法而非现在的蛇形命名法;实体变量的格式为entity.foo;全局参数的格式为params.foo

参见[edit]

注释[edit]

  1. 字符串不支持'字符,因为目前不支持字符转义。
  2. 在这种人为设计的情况下最好打破循环,因为它比继续执行所有的10次迭代更高效。
  3. Molang的法则是:如果某个内容出错或值不正确,则会将其转换为0.0(并且通常会在屏幕上抛出内容错误)。内容错误可能会阻止将内容上传到市场。
  4. 即附加包清单文件"min_engine_version"的最低取值。



Template:Navbox Addon