罗盘模板
方位、刻度、目标样式、排序和碰撞字段参考
Compass 模板位于 core/template/compasses。顶层节点是模板 ID，只负责外观；目标由命令、Kether、API 或 Provider 提供。
需要完整操作流程时，先阅读Compass 罗盘制作。本页代码未标为完整文件时，均为对应节点中的片段。
文件关系
tutorial.yml
tutorial_compass.yml
tutorial_compass.yml
顶层字段
navigation:
width: 216
fov: 240
refresh: 1
marker-refresh: 5
distance-mode: horizontal
# directions、ticks、indicator、markers...| 字段 | 类型 / 省略值 | 范围 | 说明 | 生效 |
|---|---|---|---|---|
| 顶层节点 | 字符串 | 全局唯一 | Compass 模板 ID | 打包 |
width | 整数 / 180 | 16～1024 | 罗盘显示宽度，GUI 像素 | 打包 |
fov | 小数 / 180 | 大于 0 且不超过 360 | 可见角度范围 | 打包 |
refresh | 整数 / 1 | 1～1200 tick | 朝向和目标位置刷新 | 重载 |
marker-refresh | 整数 / 5 | 1～1200 tick | 目标文字、头像和动态内容刷新 | 重载 |
distance-mode | 字符串 / horizontal | horizontal、3d | 水平或三维距离 | 重载 |
outside | 字符串 / hide | hide、edge | 视野外目标隐藏或贴边 | 打包 |
max-markers | 整数 / 0 | 0～4096 | 最大显示数；0 不限制 | 重载 |
sort | 列表 / priority-desc, distance-asc | 见下文 | 目标排序规则 | 重载 |
collision | 对象 | 见下文 | 重叠处理 | 打包 |
directions | 映射 / {} | 八个已知方位 | 方位到内容布局 ID | 打包 |
ticks | 对象 | 见下文 | 重复刻度 | 打包 |
indicator | 布局 ID / 无 | 非空布局 | 固定中心内容 | 打包 |
markers | 映射 / {} | 样式 ID 到布局 ID | 目标样式，可以为空 | 打包 |
Layout 中绑定模板
compass:
template: navigation
id: quest_navigation| 字段 | 默认值 | 说明 |
|---|---|---|
template | 必填 | 模板 ID |
id | 模板 ID | 目标集合 ID；相同外观可绑定不同数据 |
directions
允许的键：
north east south west northeast southeast southwest northwest只显示给出的方位。每个方位引用一个普通布局；图片、文字、字体和锚点在布局中制作。
directions:
north: compass_north
east: compass_east
south: compass_south
west: compass_west
northeast: compass_northeast
southeast: compass_southeast
southwest: compass_southwest
northwest: compass_northwest默认方位图片属于 xerr_ui/compass，ID 使用 north、southeast 等完整方位名称；中心、刻度、横线和目标图标都在同一 compass 组，通过明确的图片 ID 区分用途。目录与独立包见默认图片资产包。
方位元素可使用 direction 和 bearing 变量。
ticks
ticks:
step: 15
layout: compass_tick| 字段 | 类型 / 省略值 | 范围 | 说明 |
|---|---|---|---|
step | 整数 / 15 | 1～90 度 | 刻度间隔 |
layout | 布局 ID / 无 | 非空布局 | 每个刻度重复的内容 |
刻度元素可读取 step 变量。
indicator
一个普通布局的引用，固定在罗盘中心，不随方向滚动：
indicator: compass_centersort
可选项：
priority-desc: 优先级高者先。priority-asc: 优先级低者先。distance-asc: 距离近者先。distance-desc: 距离远者先。
同一类别不能同时写升序和降序。按列表顺序逐项比较，全部相同时使用稳定目标 ID。max-markers 在排序后截取，未显示目标不会被删除。
collision
collision:
mode: stack
rows: 2
row-offset-y: -32| 字段 | 类型 / 省略值 | 范围 | 说明 |
|---|---|---|---|
mode | 字符串 / stack | overlap、hide、stack | 重叠处理方式 |
rows | 整数 / 2 | 1～8 | stack 最大行数 |
row-offset-y | 整数 / -24 | -512～512 | 换行垂直偏移 |
overlap: 全部显示，优先目标绘制在前层。hide: 保留先排序的目标，隐藏重叠目标。stack: 优先目标先占用空行，所有行都冲突时次要目标暂时隐藏，不删除数据。
markers
每个样式引用一个普通布局，可以同时包含图标、文字、头像和背景。字体来自该布局，不再配置 option.font。
markers:
default: compass_target
home: compass_home
quest: compass_quest
distance: compass_distance
teammate: compass_teammate可以不配置任何目标样式。default 不是必填节点；命令或 API 省略样式时使用名为 default 的样式，需要先定义它，或明确指定其它已定义样式。
内置变量：
| 变量 | 内容 |
|---|---|
id | 稳定目标 ID |
label | 显示名称，空时使用 ID |
distance | 取整距离 |
distance_raw | 原始距离 |
height_diff | 目标相对玩家的取整高差 |
world | 世界名 |
target_uuid | 跟随实体 UUID；固定点通常为空 |
outside | none、left、right |
方位、刻度、中心和目标共用普通布局，引用布局不能嵌套 Compass 或 Progress。源布局可以保留屏幕锚点；罗盘使用局部内容，不改写源布局。
目标优先级
普通命令创建的目标优先级固定为 0。需要自定义优先级时，通过 Kether 或 API 传入；数字越大，在 priority-desc 中越靠前。