Nature’s Compass

基本信息

属性	值
注册名	`naturescompass:NaturesCompass`
unlocalizedName	`naturescompass.NaturesCompass`
物品类	`com.chaosthedude.naturescompass.items.ItemNaturesCompass`
创造栏	`tabTools`
纹理	`naturescompass:natures_compass_00`（基础纹理），动画用 `natures_compass_00` ~ `natures_compass_31` 共 32 帧
多 pass 渲染	是（`requiresMultipleRenderPasses()` 返回 `true`）
最大堆叠	64（Item 默认）
附魔适用	是
耐久度	无

Nature’s Compass 是一款群系定位器。手持右键打开 GUI 浏览所有可用群系，搜索/排序后选定一个群系，compass 会在服务器端异步螺旋扫描世界并把指针指向最近的匹配群系。FOUND 后玩家可以（若权限允许）一键传送。

compass 把状态和搜索结果存在 NBT 中：

使用方式	触发条件	使用效果	条件/限制
右键点击方块	未潜行	打开 GuiNaturesCompass，并向服务器发送 PacketRequestSync 同步传送权限	必须手持 Nature’s Compass
右键点击方块	潜行（Shift）	把状态强制置为 `INACTIVE`，指针重新指向世界出生点	取消当前搜索
快捷栏右键	同右键	同右键	—
悬浮使用（手持时）	始终	在 HUD 上叠加状态/坐标/距离信息（由 RenderTickHandler 渲染）	不可见时（debug screen / F3）不绘制
装备在物品展示框	始终	指针按展示框朝向 + 目标坐标计算并指向	旋转逻辑使用展示框 `hangingDirection`

S L S
L C L
S L S

输出物 = 1 个 Nature’s Compass。

NBT Key	类型	含义
`State`	int	搜索状态 ID（0=INACTIVE, 1=SEARCHING, 2=FOUND, 3=NOT_FOUND）
`BiomeID`	int	当前搜索的群系 ID（-1 = 仅扫描可见群系）
`FoundX`	int	已找到群系的 X 坐标
`FoundZ`	int	已找到群系的 Z 坐标
`SearchRadius`	int	已扫描的半径（500 的倍数）

触发	行为
左键	无
右键（未潜行）	打开 GUI、发送同步包
右键（潜行）	状态置 INACTIVE
双击 GUI 列表项	启动 BiomeSearchWorker
GUI 中点击 Teleport	服务端在 `FOUND` 状态下传送玩家到目标坐标（需 OP / cheat mode）

搜索：GUI 选完群系后，由 PacketCompassSearch 发到服务端，调用 searchForBiome() 启动一个 BiomeSearchWorker，螺旋扫描 maxDistance 以内、sampleSpace 为步长的所有方块柱，记录经过的群系，找到目标即停。
传送：PacketTeleport 服务端读取 NBT 坐标，加载区块，从 y=256 向下找到第一个非空气方块上表面执行 setPositionAndUpdate。需要 PlayerUtils.canTeleport() 通过——OP 或单机作弊模式。

属性	值
默认最大搜索距离	10000（来自 `ConfigHandler.maxSearchDistance`）
默认采样步长	32（来自 `ConfigHandler.sampleSpace`）
默认最大采样数	150000
默认黑名单	`[]`（无）
颜色（SEARCHING）	状态文字 0xFFFFFF、子文字 0xAAAAAA
颜色（FOUND）	状态 0xFFFFFF、子文字 0xAAAAAA
HUD 偏移	`ConfigHandler.lineOffset`（默认 1）