Molang 查询详解

基岩版Molang文档的不足是众所周知的。本页面将尽可能为各个查询提供额外细节以弥补这一缺陷。本页面适合按需搜索查阅，无需完整阅读。请使用侧边栏或Ctrl+F进行导航。

query.armor_texture_slot ​

格式：query.armor_texture_slot(x) = y

其中x和y均为整数参数，对应下表：

X参数 ​

Y参数（常规） ​

Y参数（马匹） ​

示例 ​

query.armor_texture_slot(3) == 1：检测是否穿着铁质靴子

query.armor_material_slot ​

格式：query.armor_material_slot(x) = y

其中x和y均为整数参数：

X参数 ​

Y参数 ​

具体含义未知，可能对应：

query.armor_color_slot ​

注意：截至版本1.16.100.51，此查询会导致游戏崩溃，可能在后续版本修复

格式：color = query.armor_color_slot(slot, channel)

其中slot和channel均为整数参数：

槽位参数 ​

通道参数 ​

返回值 ​

返回指定通道的颜色值

query.get_equipped_item_name ​

格式：query.get_equipped_item_name('main_hand') = 'item_name'

接受一个可选的手部槽位参数（0或'main_hand'表示主手，1或'off_hand'表示副手），以及第二个参数（0=默认）用于选择检测实际装备物品或当前渲染物品。返回请求槽位中的物品名称（未指定参数时默认检测主手），若无物品则返回空字符串。

其中item_name为要检测的物品名称（无需命名空间，注意使用引号）。

示例："query.get_equipped_item_name == 'diamond'"

能否检测背包物品？可以！使用新查询query.is_item_name_any

query.get_name ​

格式：query.get_name == 'Name'

当实体实际显示名称与指定名称匹配时返回true（可使用OnixClient查看第三人称视角的名称）。需在特定条件下使用。

<详情折叠标题="展开示例">

<代码头>animation_controllers/ac.json</代码头>

{
    "format_version": "1.10.0",
    "animation_controllers": {
        "controller.animation.ac": {
            "initial_state": "default",
            "states": {
                "default": {
                    "transitions": [
                        {
                            "active": "query.is_alive"
                        }
                    ]
                },
                "active": {
                    "transitions": [
                        {
                            "default": "(1.0)"
                        }
                    ],
                    "animations": [
                        {
                            "anim": "query.get_name == '...'" // 只能在此处使用！
                        }
                    ]
                }
            }
        }
    }
}

</详情>

query.is_name_any ​

格式：query.get_name('Name1', 'Name2') 接受一个或多个参数。 当实体实际显示名称与任一给定名称匹配时返回true。 需在特定条件下使用。

<详情折叠标题="展开示例">

<代码头>animation_controllers/ac.json</代码头>

{
    "format_version": "1.10.0",
    "animation_controllers": {
        "controller.animation.ac": {
            "initial_state": "default",
            "states": {
                "default": {
                    "transitions": [
                        {
                            "active": "query.is_alive"
                        }
                    ]
                },
                "active": {
                    "transitions": [
                        {
                            "default": "(1.0)"
                        }
                    ],
                    "animations": [
                        {
                            "anim": "query.is_name_any(...)" // 只能在此处使用！
                        }
                    ]
                }
            }
        }
    }
}

</详情>

query.is_item_name_any ​

格式：query.is_item_name_any('slot.weapon.mainhand', 0, 'namespace:item_name')

参数依次为：装备槽名称、槽位索引值，以及带命名空间的物品名称列表。

可用装备槽如下：

检测玩家背包物品 ​

格式：t.val = 0; t.i = 0; loop(27, {t.val = q.is_item_name_any('slot.inventory', t.i, 'namespace:item_name'); t.val ? break; t.i = t.i+1;});

将namespace:item_name替换为要检测的物品。此代码会遍历全部27个背包槽位，当发现指定物品时返回1.0。注意快捷栏与主背包槽位不同，需单独检测。

query.is_enchanted ​

格式：is_enchanted = query.is_enchanted

根据实体是否带有附魔效果返回1.0或0.0。

目前仅能在材质中使用

query.is_eating ​

此查询追踪某些实体的"进食"状态（不适用于玩家）。触发条件需使用以下组件之一：

• minecraft:behavior.eat_carried_item
• minecraft:behavior.snacking

query.is_ghost ​

格式：is_ghost = query.is_ghost

根据实体是否为幽灵返回1.0或0.0。

目前仅对守卫者幽灵返回1.0，用于其渲染器

query.is_grazing ​

格式：is_grazing = query.is_grazing

根据实体是否正在啃食方块返回1.0或0.0。

目前仅对绵羊及使用绵羊运行时ID的实体返回1.0

query.is_jumping ​

格式：is_jumping = query.is_jumping

根据实体是否处于跳跃状态返回1.0或0.0。

对玩家而言，触发条件包括：

• 按下跳跃键（包括水中和攀爬脚手架时）
• 或自动跳跃触发
• 或游泳时自动跳跃
• 或骑乘实体蓄力跳跃时

query.modified_move_speed ​

格式：modified_move_speed = query.modified_move_speed

返回受状态标志（如is_baby或on_fire）影响的实体当前移动速度。

典型值示例：

• 玩家行走：约0.86
• 玩家冲刺：1.0
• 玩家冲刺跳跃：0.35
• 玩家着火行走：1.0
• 玩家着火冲刺：1.0
• 玩家着火冲刺跳跃：0.525

query.log ​

内容日志与调试日志不同，属于独立文件。query.log仅输出至调试日志。

query.on_fire_time ​

格式：on_fire_time = query.on_fire_time

返回实体着火开始/结束后的刻数（tick），否则返回0.0。

典型行为：

• 实体生成：值为0
• 实体点燃：值从0开始每刻+1
• 实体着火2秒：值为40并持续递增
• 实体灭火：值重置为0并继续递增（即使未着火）
• 实体再次点燃：值重置为0并继续递增
• 实体第二次灭火：值重置为0并继续递增

本质上是记录实体首次点燃后持续计时的刻数计时器，在着火状态变化时重置。

query.scoreboard ​

格式：query.scoreboard('objective_name') > 0

当查询值符合指定范围时返回1.0或0.0。基于记分板数值、molang运算符和比较值。

注意：有时可能因未知原因失效，例如无法查询含大写字母的记分板名称（如testfoo可查但testFoo不可查）。

query.structural_integrity ​

格式：structural_integrity = query.structural_integrity

用于船和矿车的损毁机制。受攻击时减少，随时间恢复。可能仅适用于船和矿车。

variable.attack_time ​

说明 ​

该变量以查询形式实现，可在任何实体上使用（客户端/服务端皆可），无需预先定义。

对实体 ​

追踪实体攻击动作的挥动进度。未攻击时返回0.0，攻击时返回0.0至总攻击时间（约0.3）的线性递增值。对玩家而言范围是0.0到1.0。返回值表示攻击进度的百分比（小数形式），例如攻击动作过半时返回0.5。

对玩家 ​

追踪所有手臂骨骼挥动动作，包括：

• 放置方块
• 放置实体
• 交互（当启用挥动动画时）
• 近战攻击

query.is_roaring ​

当发生knockback_roar攻击时返回true。

query.head_x_rotation ​

格式：query.head_x_rotation(x)

其中x指定实体头部编号（对凋灵怪有意义）。返回头部俯仰角：

• 最大仰视：-89.9
• 最大俯视：89.9

query.head_y_rotation ​

格式：query.head_y_rotation(x)

其中x指定实体头部编号（对凋灵怪有意义）。返回头部偏航角：

• 范围：-179.9至179.9
• 数值会环绕（例如从-179.9轻微转动会跳至179.9）

query.target_x_rotation 与 query.target_y_rotation ​

功能分别对应query.head_x_rotation和query.head_y_rotation，但不接受头部编号参数。

query.time_of_day ​

返回实体所在维度的时间进度（午夜=0.0，日出=0.25，正午=0.5，日落=0.75）。计算公式：

f(x) = (x*0.25/2400)mod 1

<详情折叠标题="时间对应表">

完整表格参见原始分析

</详情>

query.eye_target_x_rotation 与 query.eye_target_y_rotation ​

对玩家无效。具体用途不明确。

variable.short_arm_offset_right ​

返回玩家右臂骨骼相对于默认皮肤几何的偏移系数：

• 细臂（3像素宽）皮肤：0.5
• 常规（4像素宽）皮肤：0.0

注意：玩家需进入第一人称视角至少一次才会初始化此变量。

variable.short_arm_offset_left ​

功能同variable.short_arm_offset_right，但对应左臂骨骼。

query.movement_direction ​

返回实体移动方向向量的三个归一化分量（模长范围0到1）。

注意：当前版本中，返回值会随实体速度变化（地面移动时值小于空中同向移动）。要获取真实的归一化速度向量需手动计算：

variable.mag = math.sqrt( math.pow( query.movement_direction(0), 2 ) + math.pow( query.movement_direction(1), 2) + math.pow( query.movement_direction(2), 2));
variable.xNorm = query.movement_direction(0) / variable.mag;
variable.yNorm = query.movement_direction(1) / variable.mag;
variable.zNorm = query.movement_direction(2) / variable.mag;

query.block_neighbor_has_any_tag 与 query.relative_block_has_any_tag ​

需启用实验性Molang功能。功能描述：接收相对坐标和一个或多个标签名，根据该位置方块是否具有指定标签返回0或1。适用于连接方块检测或实体探测。

区别：

• query.block_neighbor_has_any_tag：基于方块位置
• query.relative_block_has_any_tag：基于实体位置

语法：

• q.block_neighbor_has_any_tag(x,y,z,'tag_name')
• q.relative_block_has_any_tag(x,y,z,'tag_name')

示例：

• q.relative_block_has_any_tag(0,-1,0,'grass')：检测实体下方1格是否含"grass"标签方块
• q.block_neighbor_has_any_tag(0,-1,0,'grass')：检测方块下方1格是否含"grass"标签

多标签检测格式：q.correct_query(0,-1,0,'grass', 'plant')（将correct_query替换为正确查询名）

注意：可检测自定义标签及原版标签