Molang 脚本

Molang 在 Behemiron 用于动画/特效/表达式驱动的轻量脚本语言。 在本项目里，Molang 只在客户端执行，服务端不解析表达式。Behemiron 实现了 90% 左右的 Molang 语法

---

1. Molang 在哪里用

• 动画 Graph 条件：State/Transition 的 condition
• 动画参数：关键帧/曲线/参数值
• 特效/粒子：Snowstorm 等特效驱动表达式
• UI/渲染：在特定场景下作为参数表达式

服务器只负责下发配置与变量，Molang 的执行与混合发生在客户端。

---

2. 执行位置与数据流

• 服务端：下发 Graph（YAML → JSON）、vars / flags 等变量
• 客户端：加载图与模型，执行 Molang，计算动画混合

典型流程：

服务端配置/Graph → 下发 JSON
            ↓
客户端 Molang 运行时 → 执行动画/特效

---

3. 命名空间与别名

Molang 内置命名空间（均可用英文/缩写/中文）：

命名空间	作用	常用写法	中文别名
query	只读查询	query.xxx / q.xxx	查询.xxx
variable	实体变量	variable.xxx / v.xxx	局部变量.xxx
context	上下文变量	context.xxx / c.xxx	上下文变量.xxx
temp	临时变量	temp.xxx / t.xxx	临时变量.xxx
math	数学函数	math.xxx	数学.xxx
func	脚本函数	func.xxx	方法.xxx

---

4. 变量生命周期

• variable.*：实体级变量，可读写。实体销毁后变量消失（不持久化）
• temp.*：临时变量，仅在表达式执行期间有效
• context.*：只读上下文变量，由运行时注入
• query.*：只读查询变量，由实体与世界状态推导

---

5. 常用 Query 变量（完整清单）

5.1 Context 变量

• query.anim_time
• query.life_time
• query.actor_count
• query.is_first_person

5.2 Level 变量

• query.time_of_day
• query.time_stamp
• query.moon_phase

5.3 Entity 变量

• query.position_x / query.position_y / query.position_z
• query.eye_target_x_rotation / query.eye_target_y_rotation
• query.head_x_rotation / query.head_y_rotation
• query.yaw_speed / query.ground_speed / query.vertical_speed
• query.cardinal_facing_2d
• query.distance_from_camera
• query.modified_distance_moved
• query.walk_distance
• query.has_rider
• query.is_in_water
• query.is_in_water_or_rain
• query.is_on_fire
• query.is_on_ground
• query.is_riding
• query.is_sneaking
• query.is_jumping
• query.is_spectator
• query.is_sprinting
• query.is_swimming

5.4 LivingEntity 变量

• query.body_x_rotation / query.body_y_rotation
• query.health / query.max_health
• query.hurt_time
• query.is_playing_dead
• query.is_eating
• query.is_sleeping
• query.is_using_item
• query.item_in_use_duration
• query.item_max_use_duration
• query.item_remaining_use_duration
• query.equipment_count

5.5 Player 变量

• query.has_cape
• query.cape_flap_amount
• query.player_level

---

6. Query 函数

• query.biome_has_all_tags(...)
• query.biome_has_any_tag(...)
• query.relative_block_has_all_tags(...)
• query.relative_block_has_any_tag(...)
• query.is_item_name_any(...)
• query.equipped_item_all_tags(...)
• query.equipped_item_any_tag(...)
• query.position(...)
• query.position_delta(...)
• query.max_durability(...)
• query.remaining_durability(...)
• query.debug_output(...)

示例：

query.is_on_ground && query.ground_speed > 0.02

---

7. Math 函数与常量

常量：

• math.pi
• math.e

函数：

abs, acos, asin, atan, atan2, ceil, clamp, cos, die_roll, die_roll_integer, exp, floor, hermite_blend, lerp, lerprotate, ln, max, min, min_angle, mod, pow, random, random_integer, round, sin, sqrt, to_deg, to_rad, trunc

---

8. 内置函数

• loop(count, expression)：最多 1024 次
• for_each(var, array, expression)：遍历数组
• print(...)：调试输出

---

9. RPG 场景示例

9.1 移动判定

query.is_on_ground && query.ground_speed > 0.02

9.2 技能蓄力

variable.charge = math.clamp(variable.charge + 0.02, 0, 1)

9.3 动画权重

math.lerp(0.0, 1.0, query.ground_speed)

---

10. 常见问题

Q: 为什么服务端不解析 Molang？
A: Molang 运行依赖渲染/实体状态，在客户端执行更稳定且性能更好。

Q: 变量从哪里来？
A: 动画系统会把服务端下发的 vars / flags 注入到 variable.*。

Q: 可以自定义函数吗？
A: 可以。通过脚本注册机制挂到 func.* 命名空间。