头像模板
头像模板、遮罩、占位图和目标字段参考
头像模板位于 core/template/head。顶层节点是模板 ID。
需要完整操作流程时，先阅读玩家头像制作。本页代码未标为完整文件时，均为对应节点中的片段。
文件关系
tutorial.yml
rounded.png
loading_face.png
missing_face.png
模板完整结构
portrait:
size: 32
overlay: true
render: flat
mask: square
loading: default
failure: default
target:
type: viewer模板字段
| 字段 | 类型 / 省略值 | 范围或可选值 | 说明 | 生效 |
|---|---|---|---|---|
size | 整数 / 16 | 8～64，必须是 8 的倍数 | 头像边长，GUI 像素 | 打包 |
overlay | 布尔 / true | true/false | 显示帽子、头发等皮肤外层 | 打包 |
render | 字符串 / flat | flat、layered | 外层重叠或向左上偏移 1px | 打包 |
mask | 字符串 / square | square、circle、masks/xxx.png | 头像形状 | 打包 |
loading | 字符串 / default | default 或 fallback 文件名 | 加载中占位头像 | 打包 |
failure | 字符串 / default | default 或 fallback 文件名 | 失败、无目标时占位头像 | 打包 |
target | 对象 / viewer | 见下表 | 模板默认目标 | 视目标而定 |
Layout 引用字段
head:
template: portrait
target:
type: player
name: Steve| 字段 | 说明 |
|---|---|
head.template | 模板 ID，必填 |
head.target | 可选；填写后整体覆盖模板中的 target |
目标字段
| 字段 | 类型 / 省略值 | 生效条件 |
|---|---|---|
type | 字符串 / viewer | viewer、player、variable、kether |
name | 字符串 / 无 | player 与 uuid 二选一 |
uuid | 字符串 / 无 | player 与 name 二选一 |
key | 字符串 / 无 | variable 必填 |
script | Kether / 无 | kether 必填 |
refresh | 正整数 / 20 | kether 目标求值间隔，tick |
按目标类型填写
viewer
当前观看 HUD 的玩家，不需要其它字段：
target:
type: viewerplayer
固定玩家，name 和 uuid 必须且只能填写一个：
target:
type: player
name: Steve| 字段 | 范围 |
|---|---|
name | 3～16 位字母、数字或下划线 |
uuid | 标准 UUID 字符串 |
variable
读取 Layout 变量：
target:
type: variable
key: target_uuidkey 必填，变量值可以是玩家名或 UUID。
kether
动态执行 Kether：
target:
type: kether
script: "get target_uuid"
refresh: 20| 字段 | 类型 / 省略值 | 说明 |
|---|---|---|
script | Kether / 必填 | 返回 Player、UUID、玩家名或 null |
refresh | 正整数 / 20 | 两次完成求值之间的 tick 间隔 |
自定义遮罩
core/template/head/masks/rounded.png必须是 8×8 PNG。Alpha 小于 128 的像素会隐藏头像区域。
自定义占位图
loading: default 和 failure: default 使用内置 Steve 头像。成功取得目标皮肤后显示目标头像。
core/template/head/fallback/loading_face.png
core/template/head/fallback/missing_face.png必须是 8×8 PNG。配置只写文件名，不含 .png。