提示渲染系统（Hologram）

基本信息

属性	值
实现类	com.gtnewhorizon.structurelib.ClientProxy
提示数据入口	com.gtnewhorizon.structurelib.StructureLibAPI

这是本 mod 的核心功能：把多方块结构中"该放什么方块"的信息，以半透明全息方块的形式叠加显示在世界中，帮助玩家按图施工。所有渲染都在客户端完成，服务端不参与。

全息组（HintGroup）

提示按批次组织。一次右键产生的全部提示归入同一组 HintGroup，ClientProxy 维护两个集合：

集合	类型	作用
allGroups	List<HintGroup>	所有仍存活的全息组，按创建时间从旧到新排列
currentHints	HintGroup	当前正在累积的组，结束时置为 null

startHinting 结束上一组并新建一组，endHinting 把它追加进 allGroups 并记录 creationTime = 玩家 ticksExisted。顺序排列这一点被 onClientTick 利用，以便从头扫描就能定位过期区段，无需遍历全部。

allHints 是一个 Map<HintParticleInfo, HintGroup>，用于快速反查某个提示属于哪一组。

生命周期与清理

onClientTick 在 ClientTickEvent 的 END 阶段执行：

1. 算出 deadline = 玩家 ticksExisted - hintLifespan
2. 从 allGroups 头部顺序扫描，跳过创建时间晚于 deadline 的组
3. 把扫描到的过期前缀批量移除并清空
4. 玩家移动距离超过阈值时，额外触发一次全量重排序

存活上限由 maxCoexisting 控制：新增全息前若 allGroups.size() >= maxCoexisting，从最旧的一组开始裁剪。removeColliding 为 true 时，还会检查新提示位置是否与既有提示重复，命中则直接移除那一组。

渲染

每个提示在世界中渲染为一个边长 0.5 的立方体（居中于方块坐标，加 0.25 偏移），使用 Tessellator 直接绘制：

• 亮度取自方块位置的天空光亮度
• 颜色为提示的 RGBA 染色 × 全局 hintTransparency
• allHintsForRender 列表按由远及近排序，保证半透明叠加顺序正确；该列表预分配 10000 容量
• renderThrough 计数器跟踪"穿透方块渲染"的提示数量，为 0 时可跳过对应优化

染色与错误态

提示支持两种染色状态：

状态	RGBA	来源
无染色	{255, 255, 255, 255}	RGBA_NO_TINT
错误态	{255, 128, 128, 0}	RGBA_RED_TINT，alpha 为 0（穿透渲染）

错误态由通道 show_errors 控制：生成提示时若该通道开启且 couldBeValid 返回 false，就调用 markHintParticleError 把该位置标记为错误。show_errors 通道由 mod 自身注册，翻译键为 channels.structurelib.show_errors。

网络消息

提示状态的同步使用 SimpleNetworkWrapper，共注册 5 条消息（判别值 0–5）：

判别值	消息	方向	用途
0	AlignmentMessage.AlignmentQuery	服务端	请求某个位置的对齐数据
1	AlignmentMessage.AlignmentData	客户端	回传对齐数据
2	UpdateHintParticleMessage	客户端	更新某个提示的 RGBA 染色
3	SetChannelDataMessage	服务端	同步触发器物品上的通道数据
4	ErrorHintParticleMessage	客户端	把某个提示标记为错误态
5	RegistryOrderSyncMessage	服务端	同步 SortedRegistry 的排序与禁用列表

染色更新与错误标记这两条消息只修改已有提示的状态，不负责创建提示。

装饰粒子

每条提示还会附带一个 Weightless Particle FX 粒子，由客户端本地生成。

相关条目：配置、Hint Block、通道系统。