### q.position() example

Source: https://ysm.cfpa.team/wiki/molang/misc

Gets the specified component (0-2 for X, Y, Z) of the entity's position. The example gets the Y coordinate and returns 1003.23.

```molang
q.position(1)
```

--------------------------------

### ysm.mod_version() example

Source: https://ysm.cfpa.team/wiki/molang/misc

Gets the version of the specified mod (by mod id) installed on the client. Returns the version string if installed, otherwise null. The example returns '0.3.10.5'.

```molang
ysm.mod_version('tac')
```

--------------------------------

### ysm.weather example

Source: https://ysm.cfpa.team/wiki/molang/misc

Gets the current weather: 0 for clear, 1 for rain or snow, 2 for thunderstorm or blizzard. The example returns 1.

```molang
ysm.weather
```

--------------------------------

### ysm.texture_name examples

Source: https://ysm.cfpa.team/wiki/molang/misc

Gets the player's texture name as a string with extension. The first example returns 'blue.png'. The second example checks if the texture is 'blue.png' and returns true.

```molang
ysm.texture_name
```

```molang
ysm.texture_name == 'blue.png'
```

--------------------------------

### math.min_angle() example

Source: https://ysm.cfpa.team/wiki/molang/misc

Calculates the equivalent angle within [-180, 180). The example returns 60.

```molang
math.min_angle(780)
```

--------------------------------

### q.position_delta() examples

Source: https://ysm.cfpa.team/wiki/molang/misc

Gets the position delta component (0-2 for X, Y, Z). The first example returns -0.076. The second example calculates the speed from position deltas and returns 19.03.

```molang
q.position_delta(0)
```

```molang
v.time0 > 0 && q.life_time - v.time0 > 0 ? (v.speed_x = (q.position_delta(0) - v.x0) / (q.life_time - v.time0)); v.x0 = q.position_delta(0); v.time0 = q.life_time; return v.speed_x;
```

--------------------------------

### query.equipped_item_all_tags() example

Source: https://ysm.cfpa.team/wiki/molang/misc

Checks if the equipped item in the specified slot has all the given item tags. The example checks the mainhand for 'minecraft:tools' and 'minecraft:swords'.

```molang
query.equipped_item_all_tags('Mainhand', 'minecraft:tools', 'minecraft:swords')
```

--------------------------------

### q.is_item_name_any() example

Source: https://ysm.cfpa.team/wiki/molang/misc

Checks if the equipped item in the specified slot is any of the given item ids. The example checks for cooked beef in the mainhand.

```molang
q.is_item_name_any('Mainhand', 'cooked_beef')
```

--------------------------------

### query.debug_output() example

Source: https://ysm.cfpa.team/wiki/molang/misc

Outputs the given arguments to the chat box. Only works in animation debug mode. The example shows that non-string arguments are concatenated without separators, and the return value is null.

```molang
query.debug_output('喵', 1, 2, 3)
```

--------------------------------

### q.cape_flap_amount example

Source: https://ysm.cfpa.team/wiki/molang/misc

Gets the cape flap amount, a value from 0 to 1, even if the player is not wearing a cape. The example returns 0.35.

```molang
q.cape_flap_amount
```

--------------------------------

### ysm.dimension_name example

Source: https://ysm.cfpa.team/wiki/molang/misc

Gets the current dimension id as a string. The example returns 'twilightforest:twilightforest' (Twilight Forest).

```molang
ysm.dimension_name
```

--------------------------------

### q.relative_block_has_all_tags() example

Source: https://ysm.cfpa.team/wiki/molang/misc

Checks if the block at the given relative position has all the specified block tags. The example checks for 'minecraft:sand' and 'minecraft:enderman_holdable'.

```molang
q.relative_block_has_all_tags(0, -0.5, 0, 'minecraft:sand', 'minecraft:enderman_holdable')
```

--------------------------------

### Check texture name equality

Source: https://ysm.cfpa.team/wiki/log/120

Checks if the player's texture name equals 'blue.png'. Example returns true.

```molang
ysm.texture_name == 'blue.png'
```

--------------------------------

### ysm.in_ground example

Source: https://ysm.cfpa.team/wiki/molang/misc

Checks if the arrow is on the ground. Returns a boolean. The example returns true.

```molang
ysm.in_ground
```

--------------------------------

### Dump mods with ysm.dump_mods

Source: https://ysm.cfpa.team/wiki/log/120

Outputs installed mod information to the chat. Only works in animation debug mode. Returns null.

```molang
ysm.dump_mods
```

--------------------------------

### 服务器配置文件 serverconfig/yes_steve_model-server.toml

Source: https://ysm.cfpa.team/wiki/config

服务器配置文件，位于 存档目录/serverconfig/yes_steve_model-server.toml，2.3.0 才有此文件。2.2.2 及之前时此处配置在 config/yes_steve_model-common.toml 里。无需重启，自动热重载。

```toml
#玩家首次进入游戏时的默认模型 ID
DefaultModelId = "default"
#玩家首次进入游戏时的默认模型材质名称
DefaultModelTexture = "default"
#玩家是否能自由切换模型
CanSwitchModel = true
#客户端选择界面不会显示的模型，用于隐藏不想显示的默认模型（2.3.0 新增）
#示例：["default", "misc_3_default_boy", "misc_1_alex", "misc_2_steve", "wine_fox_1_taisho_maid", "wine_fox_7_jk"]
ClientNotDisplayModels = []

[server_scheduler]
	#处理模型的线程数，设置为 0 表示由程序自动决定
	#范围：0 ~ 你的服务器 CPU 核心数
	ThreadCount = 0
	#服务端分发模型时，每个玩家分配的带宽（单位：Mbps）
	#范围：1 ~ 999
	BandwidthLimit = 5
	#玩家响应同步的超时时间。值小于 10 时表示由程序自动决定。（单位为秒）
	#范围：0 ~ 120
	PlayerSyncTimeout = 0
	#抑制部分功能的网络同步以降低带宽占用
	#仅在大规模玩家场景下生效
	LowBandwidthUsage = false
	#跳过音效处理以降低服务器带宽占用及客户端内存占用
	#0: 接收所有音效（默认值）
	#1: 仅接收短音效（时长小于 4 秒且文件体积小于 40 KB）
	#2: 拒绝所有音效（不推荐）
	# 注意：该选项需重新加载模型后生效。提高此选项值不会触发模型重新同步，降低此值则会触发。
	# 取值范围：0 ~ 2
	AcceptSoundFX = 0
```

--------------------------------

### ysm.relative_block_name() example

Source: https://ysm.cfpa.team/wiki/molang/misc

Gets the block id at the given relative position around the player. The example gets the block below the player and returns 'minecraft:sand'.

```molang
ysm.relative_block_name(0, -1, 0)
```

--------------------------------

### 客户端配置文件 config/yes_steve_model-common.toml

Source: https://ysm.cfpa.team/wiki/config

客户端配置文件，位于 config/yes_steve_model-common.toml。2.2.2 之前和 2.3.0 之后该文件内容有所不同。包含通用设置、额外玩家渲染和加载状态界面等选项。

```toml
[general]
	#是否显示声明界面
	DisclaimerShow = false
	#是否在聊天框打印轮盘动画播放信息
	PrintAnimationRouletteMsg = false
	#是否禁用自身的 YSM 模型渲染
	DisableSelfModel = false
	#是否禁用其他玩家的 YSM 模型渲染
	DisableOtherModel = false
	#是否禁用自己的第一人称 YSM 手臂渲染
	DisableSelfHands = false
	#是否禁用 YSM 箭模型替换渲染
	DisableArrowsModel = false
	#当玩家首次进入服务器时，默认给予玩家的模型 ID
	DefaultModelId = "default"
	#当玩家首次进入服务器时，默认给予玩家的模型材质
	DefaultModelTexture = "default"
	#当与 Optifine 同时使用时，如果遇到了渲染问题，
	UseCompatibilityRenderer = false
	#动画里声音播放时，全局音量大小（2.3.0 有此配置）
	#范围：0.0 ~ 100.0
	SoundVolume = 100.0
	#是否禁用 YSM 弹射物模型替换渲染
	DisableProjectileModel = false
	#是否禁用 YSM 载具模型替换渲染
	DisableVehicleModel = false
	#模型选择界面是否优先显示模型 ID，而不是模型作者设置的模型名称
	ShowModelIdFirst = false

[extra_player_render]
	#是否禁用额外玩家渲染
	DisablePlayerRender = false
	#额外玩家渲染位置 X 坐标
	#范围：> 0
	PlayerPosX = 10
	#额外玩家渲染位置 Y 坐标
	#范围：> 0
	PlayerPosY = 10
	#玩家模型展示大小
	#范围：8.0 ~ 360.0
	PlayerScale = 40.0
	#玩家模型旋转角度偏移量
	#范围：4.9E-324 ~ 1.7976931348623157E308
	PlayerYawOffset = 5.0

[loading_state_screen]
	# 是否禁用加载状态界面
	DisableLoadingStateScreen = false
	# 加载状态界面显示位置
	# 允许值：TOP_LEFT（左上）、TOP_CENTER（中上）、TOP_RIGHT（右上）、BOTTOM_LEFT（左下）、BOTTOM_CENTER（中下）、BOTTOM_RIGHT（右下）
	LoadingStatePosition = "TOP_CENTE
```

--------------------------------

### ysm.equipped_enchantment_level() example

Source: https://ysm.cfpa.team/wiki/molang/misc

Gets the enchantment level of the specified enchantment on the equipped item. Returns an integer, or 0 if the enchantment is not present. The example gets the mending level from the mainhand.

```molang
ysm.equipped_enchantment_level('Mainhand', 'minecraft:mending')
```

--------------------------------

### 在 ysm.json 中添加 gui_foreground 和 gui_background 字段

Source: https://ysm.cfpa.team/wiki/foreground-and-background

在 ysm.json 的 properties 字段中添加 gui_foreground 和 gui_background 字段，分别指定前景图和背景图的路径。示例中路径为 textures/gui/foreground.png 和 textures/gui/background.png。推荐图片比例为 52x90。

```json
{
  // ...
  "properties": {
    // ...
    "extra_animation_classify": [],
    "preview_animation": "gui",
    "disable_preview_rotation": true,
    "gui_no_lighting": false,
    "gui_foreground": "textures/gui/foreground.png",    // 这里是前景图路径
    "gui_background": "textures/gui/background.png",    // 这里是背景图路径
    "default_texture": "default",
    "render_layers_first": false,
    "free": true
  }
  // ...
}
```

--------------------------------

### Model preview and rendering settings

Source: https://ysm.cfpa.team/wiki/struct

Global settings for model preview behavior, lighting, and rendering layers.

```json
"preview_animation": "idle",
"default_texture": "default",
"free": false,
"render_layers_first": false,
"disable_preview_rotation": false,
"gui_no_lighting": false,
"gui_foreground": "textures/gui/foreground.png",
"gui_background": "textures/gui/background.png",
"all_cutout": false
```

--------------------------------

### 示例：@player_ctrl_main.molang 动画控制函数

Source: https://ysm.cfpa.team/wiki/molang/script

示例动画控制函数，根据 v.test_main 的值播放不同动画：值为 1 时播放 run，值为 2 时播放 walk，其他情况返回 ctrl.state_bypass 使用内置逻辑。

```molang
v.test_main == 1 ? {
    ctrl.set_animation('run');
    return ctrl.state_continue;
};

v.test_main == 2 ? {
    ctrl.set_animation('walk', ctrl.loop);
    return ctrl.state_continue;
};

return ctrl.state_bypass;
```

--------------------------------

### Get position delta component with q.position_delta()

Source: https://ysm.cfpa.team/wiki/log/120

Gets the specified component (0-2 for X, Y, Z) of the position delta since the last animation update. Example returns the X component, e.g., -0.076.

```molang
q.position_delta(0)
```

--------------------------------

### ysm.projectile_owner example

Source: https://ysm.cfpa.team/wiki/molang/misc

Gets the flame enchantment level from the player's mainhand when the arrow is shot. The example is meant to be placed in the first frame of a parallel animation instruction keyframe. It stores the level in v.flame_level and returns 0.

```molang
ysm.projectile_owner->ysm.equipped_enchantment_level('Mainhand', 'minecraft:flame')
```

--------------------------------

### BlockBench 变量占位符文本

Source: https://ysm.cfpa.team/wiki/molang/common

复制此文本到 BlockBench 可快速添加变量滑块和开关，用于调试 molang 效果。包含 query 和 ysm 前缀的变量，如 query.ground_speed 和 ysm.has_chest_plate。

```molang
query.ground_speed = slider('地面速度')
query.vertical_speed = slider('垂直速度')
ysm.head_yaw = slider('左右视角')
ysm.head_pitch = slider('上下视角')
query.health = slider('当前生命值')
query.max_health = slider('最大生命值')
ysm.food_level = slider('玩家饱食度')
query.player_level = slider('玩家等级')
query.time_of_day = slider('时间')
query.moon_phase = slider('月相')
ysm.armor_value = slider('玩家护甲值')
query.distance_from_camera = slider('摄像机距离')
ysm.has_chest_plate = toggle('胸甲')
ysm.has_leggings = toggle('护腿')
ysm.has_helmet = toggle('头盔')
ysm.has_boots = toggle('鞋子')
ysm.has_elytra = toggle('鞘翅')
ysm.is_close_eyes = toggle('眨眼')
ysm.has_mainhand = toggle('主手持握')
ysm.has_offhand = toggle('副手持握')
query.is_on_fire = toggle('着火')
query.is_in_water_or_rain = toggle('在水和雨中')
query.is_spectator = toggle('观察者模式')
query.is_first_person = toggle('第一人称视角')
query.is_jumping = toggle('跳跃中')
query.is_on_ground = toggle('在地面上')
```

--------------------------------

### Get movement length with ysm.delta_movement_length

Source: https://ysm.cfpa.team/wiki/log/120

Returns the length of the arrow's movement between two ticks, useful for judging speed. If speed is abnormal, try installing Fast Projectile Fix.

```molang
ysm.delta_movement_length
```

--------------------------------

### 修改 config/carryon-client.toml 禁用手臂渲染

Source: https://ysm.cfpa.team/wiki/animation/carryon

在 1.18.2 及以前版本中，将 renderArms 设置为 false 以关闭搬运时的额外手臂渲染。

```toml
#Settings
[settings]
	#If the front of the Tile Entities should face the player or should face outward
	facePlayer = false
	#Arms should render on sides when carrying
	renderArms = true
```

--------------------------------

### 使用 loop 计算 1 到 10 的和（molang）

Source: https://ysm.cfpa.team/wiki/molang/script

使用 loop 执行固定次数的循环，计算 1 到 10 的和。注意循环体后需要分号结尾。

```molang
// 从 1 加到 10
t.num = 0;
t.sum = 0;
loop(10, {
    t.num = t.num + 1;
    t.sum = t.sum + t.num;
});	// 不要忘了分号结尾
return t.sum;
```

--------------------------------

### 订阅 sync 事件并输出参数（molang）

Source: https://ysm.cfpa.team/wiki/molang/script

订阅 sync 事件的函数文件 test@sync.molang 的内容，用于输出同步参数。该函数会在服务器上所有玩家以相同参数触发 sync 事件时被调用。

```molang
q.debug_output('同步完成！参数为：', args[0], ' 和 ', args[1])
```

--------------------------------

### 调试指令：查看当前拔刀剑动画名

Source: https://ysm.cfpa.team/wiki/animation/slashblade

使用 /ysmclient molang watch add 指令添加监视，然后按 Alt B 打开调试界面，触发剑技即可看到当前动画名。

```command
/ysmclient molang watch add post "当前拔刀剑动画" ctrl.slashblade_animation
```

--------------------------------

### Get Flame enchantment level from projectile owner

Source: https://ysm.cfpa.team/wiki/log/120

Gets the Flame enchantment level from the player's mainhand bow when the arrow is shot. Place in the first frame of any parallel animation instruction keyframe. Stores the result in v.flame_level and does not repeat. Returns 0 if not applicable.

```molang
v.flame_level ?? (v.flame_level = ysm.projectile_owner->ysm.equipped_enchantment_level('Mainhand', 'minecraft:flame'))
```

--------------------------------

### 使用变量作为 args 索引（molang）

Source: https://ysm.cfpa.team/wiki/molang/script

展示 args 索引不仅支持数值字面量，也支持变量和表达式。

```molang
t.a = 1;
return args[0] + args[t.a] + args[t.a + 1];
```

--------------------------------

### Get time on ground with ysm.on_ground_time

Source: https://ysm.cfpa.team/wiki/log/120

Returns an integer (in ticks) of how long the arrow has been on the ground.

```molang
ysm.on_ground_time
```

--------------------------------

### 配置 ysm.json 添加第一人称动画 fp_arm

Source: https://ysm.cfpa.team/wiki/animation/first-person-anim

在 ysm.json 的 animation 字段中添加 fp_arm 键，指向第一人称手臂动画文件。该配置启用第一人称手臂模型动画，需在 2.5.0 及以上版本使用。

```json
{
  //...
  "files": {
    //...
    "animation": {
      "main": "animations/main.animation.json",
      "arm": "animations/arm.animation.json",
      "extra": "animations/extra.animation.json",
      "tac": "animations/tac.animation.json",
      "carryon": "animations/carryon.animation.json",
      "parcool": "animations/parcool.animation.json",
      "swem": "animations/swem.animation.json",
      "slashblade": "animations/slashblade.animation.json",
      "tlm": "animations/tlm.animation.json",
      // 这个是第一人称动画
      "fp_arm": "animations/fp.arm.animation.json"
    }
  }
}
```

--------------------------------

### Calculate arrow speed with position_delta

Source: https://ysm.cfpa.team/wiki/log/120

Calculates the speed of the arrow using position deltas. Example returns 19.03.

```molang
v.time0 > 0 && q.life_time - v.time0 > 0 ? (v.speed_x = (q.position_delta(0) - v.x0) / (q.life_time - v.time0)); v.x0 = q.position_delta(0); v.time0 = q.life_time; return v.speed_x;
```

--------------------------------

### 使用 for_each 遍历参数求和（molang）

Source: https://ysm.cfpa.team/wiki/molang/script

使用 for_each 遍历参数并求和。注意循环体后需要分号结尾。

```molang
// 将任意个参数相加并返回
t.sum = 0;
for_each(t.arg, args, {
    t.sum = t.sum + t.arg;
});	// 不要忘了分号结尾
return t.sum;
```

--------------------------------

### 执行 molang 表达式：/ysmclient molang execute

Source: https://ysm.cfpa.team/wiki/molang/index

在本地玩家身上执行 molang 表达式并输出结果至聊天框，仅单人游戏有效。

```command
/ysmclient molang execute <expr>
```

--------------------------------

### Get projectile owner with ysm.projectile_owner

Source: https://ysm.cfpa.team/wiki/log/120

Returns the player entity that shot the arrow. Can be used with arrow expressions to query its properties.

```molang
ysm.projectile_owner
```

--------------------------------

### 配置 disable_preview_rotation 字段

Source: https://ysm.cfpa.team/wiki/animation/gui

在 ysm.json 的 properties 下新增 disable_preview_rotation 字段并设为 true，以取消模型选择界面的诡异旋转角度，使正视图与 GUI 选择界面角度一致。

```json
{
    "properties": {
        // 设置为 true 禁用模型选择界面角度
        "disable_preview_rotation": true
    }
}
```

--------------------------------

### Check biome category with ysm.biome_category

Source: https://ysm.cfpa.team/wiki/log/120

Returns the biome category as a string. Only works in 1.16.5 and 1.18.2. Example checks if the category is 'forest'.

```molang
ysm.biome_category == 'forest'
```

--------------------------------

### 添加调试表达式：/ysmclient molang watch add

Source: https://ysm.cfpa.team/wiki/molang/index

向自定义调试屏幕添加 molang 表达式，实时计算和更新。pre 在动画更新前执行，post 在动画更新后执行。2.2.2 及之前需按两次 Alt+B 进入调试屏幕，2.3.0 及之后只需按一次。

```command
/ysmclient molang watch add [pre|post] <name> <expr>
```

--------------------------------

### 使用 PBR 材质时 ysm.json 的 arrow 字段配置

Source: https://ysm.cfpa.team/wiki/animation/arrow

当箭矢贴图使用 PBR 材质时，texture 字段需按此格式填写。uv 字段必选，normal 和 specular 为可选，支持 Oculus 和 Iris PBR。

```json
"arrow": {
    "model": "models/arrow.json",
    "animation": "animations/arrow.animation.json",
    // 如果您要使用 PBR ，请按如下格式修改
    "texture": {
        // uv 字段必选，以下两种 PBR 材质为可选，都不填则按照正常贴图处理
        "uv": "textures/arrow.png",
        // Oculus 和 Iris PBR 支持
        "normal": "textures/arrow_n.png",
        "specular": "textures/arrow_s.png"
    }
}
```

--------------------------------

### 在 ysm.json 中添加 irons_spell_books 动画类型

Source: https://ysm.cfpa.team/wiki/animation/iron-spell

在 ysm.json 的 animation 字段中添加 irons_spell_books 键，指向铁魔法施法动画文件。这是启用铁魔法动画的必要步骤。

```json
"animation": {
    "main": "animations/main.animation.json",
    "arm": "animations/arm.animation.json",
    "extra": "animations/extra.animation.json",
    "tac": "animations/tac.animation.json",
    "carryon": "animations/carryon.animation.json",
    "parcool": "animations/parcool.animation.json",
    "swem": "animations/swem.animation.json",
    "slashblade": "animations/slashblade.animation.json",
    "tlm": "animations/tlm.animation.json",
    "immersive_melodies": "animations/im.animation.json",
    // 这就是铁魔法的施法动画
    "irons_spell_books": "animations/iss.animation.json",
    "fp_arm": "animations/fp.arm.animation.json"
}
```

--------------------------------

### 在指定玩家上执行 molang：/ysm molang execute

Source: https://ysm.cfpa.team/wiki/molang/index

在指定玩家身上执行 molang 表达式，多人游戏下可用，需要管理员权限，不会输出执行结果。

```command
/ysm molang execute <player> <expr>
```

--------------------------------

### 配置 preview_animation 字段

Source: https://ysm.cfpa.team/wiki/animation/gui

配置 ysm.json 的 preview_animation 字段为自定义动画名称（如 gui），以在模型选择界面播放该动画。

```json
{
    "properties": {
        // 在模型选择界面播放的预览动画
        "preview_animation": "gui"
    }
}
```

--------------------------------

### 在 ysm.json 中添加 immersive_melodies 字段

Source: https://ysm.cfpa.team/wiki/animation/immersive-melodies

在 ysm.json 的 animation 字段中添加 immersive_melodies 字段，用于指定沉浸式奏乐动画文件的路径。默认路径为 animations/im.animation.json。

```json
"animation": {
    "main": "animations/main.animation.json",
    //...
    //这里填你的路径
    "immersive_melodies": "animations/im.animation.json"
}
```

--------------------------------

### 自动眨眼 molang 表达式（眼睛）

Source: https://ysm.cfpa.team/wiki/molang/common

自动根据是否需要闭眼而闭眼（通常为 4 秒一次），适用于 pre_parallel 动画，部位为眼睛，关键帧为缩放。

```molang
ysm.is_close_eyes ? 0 : 1
```

--------------------------------

### 在 loop 循环中使用 break 和 continue（molang）

Source: https://ysm.cfpa.team/wiki/molang/script

展示 loop 循环中支持 break 和 continue。第一个循环计算斐波那契数列并在 v.y 大于 20 时跳出；第二个循环在 v.x 大于 5 时跳过累加。

```molang
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;
});

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

--------------------------------

### Define model files and textures

Source: https://ysm.cfpa.team/wiki/struct

Specifies the main model paths, animation files, controllers, and texture mappings including PBR support.

```json
"files": {
    "player": {
        "model": {
            "main": "models/main.json",
            "arm": "models/arm.json"
        },
        "animation": {
            "main": "animations/main.animation.json",
            "arm": "animations/arm.animation.json",
            "extra": "animations/extra.animation.json",
            "tac": "animations/tac.animation.json",
            "carryon": "animations/carryon.animation.json",
            "parcool": "animations/parcool.animation.json",
            "swem": "animations/swem.animation.json",
            "slashblade": "animations/slashblade.animation.json",
            "tlm": "animations/tlm.animation.json",
            "fp_arm": "animations/fp.arm.animation.json"
        },
        "animation_controllers": [
            "controller/parallel.controller.json"
        ],
        "texture": [
            "textures/default.png",
            {
                "uv": "textures/blue.png",
                "normal": "textures/pbr/blue_n.png",
                "specular": "textures/pbr/blue_s.png"
            }
        ]
    },
    "projectiles": {
        "minecraft:arrow": {
            "model": "models/arrow.json",
            "animation": "animations/arrow.animation.json"
```

--------------------------------

### 在 ysm.json 中配置 animation_controllers 字段

Source: https://ysm.cfpa.team/wiki/controller

在 ysm.json 中添加 animation_controllers 字段，用于注册动画控制器文件。该字段为数组，可添加多个文件，程序读取时会自动合并。

```json
"files": {
    "player": {
      "model": {
        "main": "models/main.json",
        "arm": "models/arm.json"
      },
      "animation": {
        "main": "animations/main.animation.json",
        "parcool": "animations/parcool.animation.json"
      },
      // 可以添加多个文件
      "animation_controllers": [
        "controller/随便起名字都行啊.json"
      ],
      "texture": [
        "textures/texture.png"
      ]
    }
}
```

--------------------------------

### 在 ysm.json 中添加 parcool 动画字段

Source: https://ysm.cfpa.team/wiki/animation/parcool

在 ysm.json 的 animation 字段中添加 "parcool" 类型，指向 parcool.animation.json 文件。修改跑酷动画前必须填写此处，否则动画不会生效。

```json
"animation": {
    "main": "animations/main.animation.json",
    "arm": "animations/arm.animation.json",
    "extra": "animations/extra.animation.json",
    "tac": "animations/tac.animation.json",
    "carryon": "animations/carryon.animation.json",
    // 这就是跑酷的动画
    "parcool": "animations/parcool.animation.json",
    "swem": "animations/swem.animation.json",
    "slashblade": "animations/slashblade.animation.json",
    "tlm": "animations/tlm.animation.json"
}
```

--------------------------------

### ysm.play_sound flags 参数示例

Source: https://ysm.cfpa.team/wiki/sound

从 2.5.3 起，`ysm.play_sound` 的第三个参数由 boolean 改为 flags（整数标志位，可叠加）。`+1` 强制重播，`+2` 按全局上下文创建播放实例，`+4` 循环播放；可只取一项或叠加，例如 7 表示 1+2+4。

```Molang
ysm.play_sound('fx', 'sample', 1) // 强制重播
```

```Molang
ysm.play_sound('fx', 'sample', 2) // 全局上下文
```

```Molang
ysm.play_sound('fx', 'sample', 4) // 循环播放
```

```Molang
ysm.play_sound('fx', 'sample', 7) // 1+2+4：强制 + 全局 + 循环
```

--------------------------------

### 在 ysm.json 中添加 slashblade 动画类型

Source: https://ysm.cfpa.team/wiki/animation/slashblade

在 ysm.json 的 animation 字段中添加 "slashblade" 键，指向拔刀剑动画文件。必须填写此字段才能启用拔刀剑动画，否则修改不会生效。

```json
"animation": {
    "main": "animations/main.animation.json",
    "arm": "animations/arm.animation.json",
    "extra": "animations/extra.animation.json",
    "tac": "animations/tac.animation.json",
    "carryon": "animations/carryon.animation.json",
    "parcool": "animations/parcool.animation.json",
    "swem": "animations/swem.animation.json",
    // 这就是拔刀剑的动画
    "slashblade": "animations/slashblade.animation.json",
    "tlm": "animations/tlm.animation.json"
}
```

--------------------------------

### 在 ysm.json 中添加 tlm 动画类型

Source: https://ysm.cfpa.team/wiki/animation/tlm

在 ysm.json 的 animation 字段中添加 tlm 类型，指向女仆动画文件。必须填写此字段，否则自定义女仆动画不会生效。

```json
"animation": {
    "main": "animations/main.animation.json",
    "arm": "animations/arm.animation.json",
    "extra": "animations/extra.animation.json",
    "tac": "animations/tac.animation.json",
    "carryon": "animations/carryon.animation.json",
    "parcool": "animations/parcool.animation.json",
    "swem": "animations/swem.animation.json",
    "slashblade": "animations/slashblade.animation.json",
    // 这就是女仆的动画
    "tlm": "animations/tlm.animation.json"
}
```

--------------------------------

### ysm.dump_equipped_item()

Source: https://ysm.cfpa.team/wiki/log/120

输出玩家已装备物品的信息至聊天框，仅在动画调试模式下有效。

```APIDOC
## ysm.dump_equipped_item()

### Description
输出玩家已装备物品的信息至聊天框，仅在动画调试模式下有效。

### Method
N/A

### Endpoint
N/A

### Parameters
#### Path Parameters
- 无

#### Query Parameters
- 无

#### Request Body
- 无

### Request Example
无

### Response
#### Success Response (200)
- 无

#### Response Example
无

```

--------------------------------

### 自动眨眼 molang 表达式（眉毛）

Source: https://ysm.cfpa.team/wiki/molang/common

配合自动眨眼，眉毛位置随闭眼状态变化。适用于 pre_parallel 动画，部位为眉毛，关键帧为位置。

```molang
0
```

```molang
ysm.is_close_eyes ? -1 : 0
```

```molang
0
```

--------------------------------

### ysm.json 自定义 sound_path 示例

Source: https://ysm.cfpa.team/wiki/sound

在 `ysm.json` 的 `files` 字段中新增 `sound_path` 字段，可自定义音频文件夹路径。填写后，动画音频关键帧中只需填写文件名，不需要添加文件夹前缀和 ogg 后缀。

```json
{
    "files": {
        // 支持任意字符
        // 后续基岩版动画里音频关键帧填写的名称和上述一致，不需要添加此文件夹前缀和 ogg 后缀
        "sound_path": "声音文件夹"
    }
}
```

--------------------------------

### 在 ysm.json 中声明 swem 动画文件

Source: https://ysm.cfpa.team/wiki/animation/swem

在 ysm.json 的 animation 字段中添加 swem 类型，指向马术动画文件。若修改的马术动画不起作用，请先检查此处是否已声明文件。

```json
"animation": {
    "main": "animations/main.animation.json",
    "arm": "animations/arm.animation.json",
    "extra": "animations/extra.animation.json",
    "tac": "animations/tac.animation.json",
    "carryon": "animations/carryon.animation.json",
    "parcool": "animations/parcool.animation.json",
    // 这就是马术的动画
    "swem": "animations/swem.animation.json",
    "slashblade": "animations/slashblade.animation.json",
    "tlm": "animations/tlm.animation.json"
}
```

--------------------------------

### 管理调试表达式：/ysmclient molang watch remove/clear

Source: https://ysm.cfpa.team/wiki/molang/index

管理自定义调试屏幕上的条目：移除指定名称的表达式或清空所有条目。

```command
/ysmclient molang watch remove <name>
/ysmclient molang watch clear
```

--------------------------------

### query.biome_has_any_tags

Source: https://ysm.cfpa.team/wiki/log/120

也是占位符。只能在 1.18 以上的版本可用。

```APIDOC
## query.biome_has_any_tags

### Description
也是占位符。只能在 1.18 以上的版本可用。

### Method
N/A

### Endpoint
N/A

### Parameters
#### Path Parameters
- 无

#### Query Parameters
- 无

#### Request Body
- 无

### Request Example
无

### Response
#### Success Response (200)
- 无

#### Response Example
无

```

--------------------------------

### Configure language path in ysm.json

Source: https://ysm.cfpa.team/wiki/i18n

在 ysm.json 文件中配置 language_path 以指定存放语言文件的文件夹名称。

```json
{
	// ...其他配置
  	"files": {
		"player": {
			// ...其他配置
			"animation": {
				"main": "animations/主动画.json",
				"arm": "animations/手臂动画.json",
				"extra": "animations/轮盘动画.json",
				"tac": "animations/TAC动画.json",
				"carryon": "animations/搬运动画.json",
				"swem": "animations/马术动画.json",
				"parcool": "animations/跑酷动画.json",
				"tlm": "animations/女仆动画.json"
			},
			"animation_controllers": ["controller/主动画修改.json", "controller/并行动画修改.json"]
		},
		"language_path": "语言文件夹" // 这里填写你要修改成的语言文件夹名称
	}
}
```

--------------------------------

### ysm.play_sound 数字 id 示例

Source: https://ysm.cfpa.team/wiki/sound

`ysm.play_sound` 的 `id` 参数旧版本只能是字符串，新版本也可以是不小于 0 的数值。示例展示了使用数字 id 创建播放实例并停止该实例。

```Molang
ysm.play_sound(1, 'sample') // 创建并命名为 1
ysm.stop_sound(1)           // 停止 id 为 1 的播放实例
```

--------------------------------

### 换装设计 molang 变量

Source: https://ysm.cfpa.team/wiki/molang/common

用于检测护甲栏是否有护甲，通过穿脱护甲实现换装。适用于 parallel 动画，部位为衣服/盔甲，关键帧为缩放。

```molang
ysm.has_helmet
```

```molang
ysm.has_chest_plate
```

```molang
ysm.has_leggings
```

```molang
ysm.has_boots
```

--------------------------------

### 在 ysm.json 中声明箭矢模型、动画和材质

Source: https://ysm.cfpa.team/wiki/animation/arrow

在 ysm.json 的 files 字段中添加 arrow 字段，声明箭矢模型、动画和材质文件。自 2.2.1 版本起必须声明，否则自定义箭矢不会生效。

```json
"files": {
    "player": {
        // 玩家模型部分
    },
    // 在这之后添加箭矢模型和动画
    "arrow": {
        // 箭矢模型
        "model": "models/arrow.json",
        // 箭矢动画
        "animation": "animations/arrow.animation.json",
        // 箭矢材质
        "texture": "textures/arrow.png"
    }
}
```

--------------------------------

### ysm-pack.json 模型包描述文件示例

Source: https://ysm.cfpa.team/wiki/model-pack

用于模型包的自描述文件，提供默认名称、描述及多语言配置。若缺少该文件，游戏将使用文件夹名作为标题并采用默认封面。

```json
{
  // 模型包的默认名字，如果没有下面翻译所对应的语言则会默认显示这个
  "name": "Wine Fox & Friends",  
  // 模型包的默认描述，如果没有下面翻译所对应的语言则会默认显示这个   
  "description": "Cute Wine Fox and her friends",   
  // 多语言配置（可选）
  "lang": {
    // 中文
    "zh_cn": {      
      "name": "酒狐与小伙伴",
      "description": "可爱酒狐和她的小伙伴们"
    }
  }
}
```

--------------------------------

### 主动停止音频示例

Source: https://ysm.cfpa.team/wiki/sound

主动停止音频的示例。`ysm.stop_sound(id, global?)` 和 `ysm.stop_all_sounds(global?)` 从 2.5.3 起默认只停止当前上下文内的播放实例；`global = 1` 停止全局上下文，`global = 0` 或不写停止当前上下文。

```Molang
ysm.stop_sound('fx', 1)
```

```Molang
ysm.stop_all_sounds(0)
```

```Molang
ysm.stop_all_sounds
```

--------------------------------

### Define Model Files and Textures in ysm.json

Source: https://ysm.cfpa.team/wiki/struct

Configures the main model components, animation files, controllers, and texture paths including PBR support for the player and arrow models.

```json
{
        // 主模型文件
        "player": {
            "model": {
                // 路径和文件名都可以自定义，注意严格区分大小写，即使是在 Windows 上
                "main": "models/main.json",
                "arm": "models/arm.json"
            },
            // 可选字段，内部八个字段也都是可选
            // 没有的话，会自动调用默认模型
            "animation": {
                "main": "animations/main.animation.json",
                "arm": "animations/arm.animation.json",
                "extra": "animations/extra.animation.json",
                "tac": "animations/tac.animation.json",
                "carryon": "animations/carryon.animation.json",
                "swem": "animations/swem.animation.json",
                "parcool": "animations/parcool.animation.json",
                "slashblade": "animations/slashblade.animation.json",,
                "tlm": "animations/tlm.animation.json"
            },
            // 2.3.0 新增内容
            // 动画控制器的索引，可以包含多个控制器。你如果喜欢，也可以将其拆分成多个⽂件
            "animation_controllers": [
                "controller/parallel.controller.json"
            ],
            // 读取时保留顺序
            "texture": [
                // 可以直接书写材质路径
                "textures/default.png",
                // 也可以写成这样的形式
                {
                    // 仅 uv 字段必选，以下两种 PBR 材质为可选
                    "uv": "textures/blue.png",
                    // Oculus 和 Iris PBR 支持
                    "normal": "textures/pbr/blue_n.png",
                    "specular": "textures/pbr/blue_s.png"
                }
            ]
        },
        // 可选字段，替换箭的渲染
        "arrow": {
            "model": "models/arrow.json",
            // 可选字段
            "animation": "animations/arrow.animation.json",
            // 同样支持 PBR
            "texture": "textures/arrow.png"
        }
    }
```

--------------------------------

### 实现 if-else 三元运算符（molang）

Source: https://ysm.cfpa.team/wiki/molang/script

使用三元运算符实现 if-else 逻辑。过去版本的大括号语句有 bug，此快照版已修复。建议在复杂逻辑表达式时用括号括起判断部分，并注意以分号结尾。

```molang
v.a ? { 
    ...; // v.a 为 true（非 0 且非 null 值）时执行
    ...;
} : {
    ...; // v.a 为 false（0 或 null 值）时执行
    ...;
};	// 不要忘了分号结尾

// 虽没有强制要求，但是建议在逻辑表达式较为复杂时，把判断的部分用括号括起来
(v.b || v.c && v.d) ? { 
    ...;
} : {
    ...;
};	// 不要忘了分号结尾
```

--------------------------------

### Worker 服务器 server.properties 配置示例

Source: https://ysm.cfpa.team/wiki/freesia-plugin

Worker 服务器 server.properties 的配置示例，需与 Freesia-Velocity 配置保持一致，指定服务器 IP 和端口。

```properties
# 需与 Freesia-Velocity 配置保持一致
server-ip=127.0.0.1
server-port=19199
```