TaCZ 的 Veil Lights

TaCZ 的 Veil Lights

使TaCZ配件与Veil和Veil体积光兼容

TaCZ 的 Veil 灯光（Veil Lights for TaCZ）

这是一个 NeoForge 1.21.1 兼容性附加组件，通过独立的 Veil Volume Lights 库渲染已配置的 TaCZ 武器灯光。客户端安装需要同时包含 veiltaczlights 和 veilvolumelights；仅在服务器上安装 TaCZ 附加组件 JAR 是可选的，可启用数据包配置文件和多人游戏手电筒状态同步。TaCZ 集成代码位于 com.cappleapple.veiltaczlights 下，而通用渲染逻辑位于库构件中的 com.cappleapple.veilvolumelights 下。

功能说明

  • 在渲染期间捕获真实的动画 TaCZ 附件骨骼矩阵。因此，腰射、瞄准、换弹、冲刺、检视、晃动、后坐力、自定义动画以及每把枪的附件位置都会通过 TaCZ 自身的变换层级流转。
  • 每帧为每个渲染的玩家更新一个可复用的库 VolumeLight.Spot。
  • 支持第一人称和第三人称渲染，对远距离光源进行距离剔除，并在帧结束以及断开连接/卸载世界时移除过时光源。
  • 在活动的第三人称发射器处渲染一个带颜色、面向相机的镜头光晕。该光晕经过深度测试，直视灯具时最亮，从侧面看较暗，并且永远不会绘制在第一人称武器视图之上。
  • 通过服务器复制 L 键手电筒状态，使其他模组客户端能看到远程光束和光晕随其拥有者开启和关闭。
  • 使用库原生的 Veil 点光源、聚光灯和矩形区域光句柄。TaCZ 仅提交聚光灯。
  • 保留不透明世界的深度，并在遇到不透明几何体前应用连续、减法的透明介质透射。
  • 自动识别 TaCZ 的 LASER 附件，其模型包含类似手电筒的发射器骨骼，并可在 TOML 中提供显式的第三方配置文件。
  • 从数据包 JSON 加载每个附件的光束配置文件，并为标准 PEQ-15、PEQ-6 和 Nightstick 附件提供内置默认配置。Nightstick 需要显式配置文件，因为 TaCZ 仅将其声明为激光器且未提供手电筒标记。

按下 L 键可切换本地玩家的武器灯光。

客户端配置包括 thirdPersonFlare、thirdPersonFlareSize 和 thirdPersonFlareIntensity。光晕距离使用现有的 thirdPersonLightDistance 限制。

配置

NeoForge 会创建 config/veiltaczlights-client.toml 用于全局回退行为。每个数值选项都会强制执行范围限制。

附件配置文件是数据包文件，位于：

data/<attachment namespace>/veiltaczlights/attachment_profiles/<attachment path>.json

例如，data/addonpack/veiltaczlights/attachment_profiles/weapon_light.json 配置了 addonpack:weapon_light：

{
  "enabled": true,
  "emitter_bone": "flashlight",
  "beam": {
    "length": 40.0,
    "width": 14.0,
    "inner_width": 7.0,
    "color": "#F2FAFF",
    "intensity": 1.2,
    "shadows": true,
    "volumetric_strength": 0.4
  }
}

length 是最大距离（以方块为单位）。width 和可选的 inner_width 是该距离处的完整光束直径（以方块为单位），附加组件会将其转换为 Veil 锥角。color 接受 #RRGGBB 或三个数字的 RGB 数组。数据包配置文件具有优先权，并可通过 /reload 重新加载。

在单人游戏中，集成服务器会自动加载并同步这些文件和手电筒状态。对于专用的多人游戏服务器，请在服务器上安装附加组件 JAR，以将服务器数据包配置文件和玩家手电筒开关同步到客户端。服务器端不需要 TaCZ 和 Veil，客户端仍然可以加入未安装此附加组件的服务器；在这种情况下，仅使用客户端的旧版 TOML 回退配置，远程已识别灯光默认开启。

当附件没有数据包配置文件时，附加组件仍会创建 config/veiltaczlights-attachments.toml 作为旧版/本地回退配置：

[attachments."addonpack:weapon_light"]
enabled = true
emitterBone = "flashlight"
range = 40.0
intensity = 1.2
outerConeAngle = 30.0
innerConeAngle = 16.0
red = 1.0
green = 0.97
blue = 0.90
shadows = true
volumetricStrength = 0.0

仅当某个数据包的附件原点本身位于灯具处时，才设置 emitterBone = "@attachment"。设置 enabled = false 可覆盖对某附件的自动识别。

内置的 JSON 默认配置使用明显可见的体积强度。Veil Volume Lights 将透明表面从终止深度快照中排除，合并相邻的相同介质，并集成在每个体积内实际传播的距离。彩色介质沿光路乘以它们的波长透射率，而独立光源保持帧缓冲叠加。相同行为适用于点光源、聚光灯和区域光。

Veil Volume Lights 库

可复用库从 veil-volume-lights/ 构建，并公开三个快照定义以及一个持久化句柄：

VolumeLightHandle handle = VeilVolumeLights.create(
        new VolumeLight.Point(position, color, intensity, range, shadows, volumetricStrength)
);
handle.update(new VolumeLight.Spot(
        position, forward, up, color, intensity, range,
        outerConeDegrees, innerConeDegrees, shadows, volumetricStrength
));


handle.free();

VolumeLight.Area 还接受发射器宽度、高度和扩散角度。创建或更新句柄应在客户端渲染线程上进行；集成方拥有其句柄的生命周期。该库拥有所有 Veil 着色器覆盖、帧缓冲挂钩、不透明深度捕获、透明介质扫描和 GPU 上传。

集成细节和诚实的 API 限制

该实现针对 MUKSC TaCZ NeoForge 1.21.1 移植版 1.1.8-hotfix-r6 和 Veil 4.4.1。

TaCZ 的公共 API 暴露了附件 ID/类别，其渲染器暴露了最终的动画模型层级，但此移植版没有手电筒状态 API，并且持续渲染激光附件。因此，此附加组件拥有 L 键开关，并通过其可选的服务器安装进行同步。服务器仅为每个连接的玩家存储当前的启用标志，并向支持该负载的客户端广播更改；每个客户端仍根据 TaCZ 复制的模型变换在本地构建实际的 Veil 光源。未来的 TaCZ 状态 API 可以在 compat/tacz 中连接，而无需更改 Veil 生命周期代码。

TaCZ 在被检查的 1.21.1 源代码中也没有创建竞争性的动态/局部光照，因此不会禁用任何无关的 TaCZ 渲染。其激光束保持完整。

TaCZ 通过将 Minecraft 的主深度附件升级为 DEPTH24_STENCIL8 来启用模板渲染。Veil Volume Lights 集中提供匹配的深度-模板帧缓冲覆盖和第一人称合成保护，因此集成方无需各自独立修补 Veil。

Veil 4.4.1 暴露体素遮挡，而不是每光源阴影贴图分辨率。shadows 映射到该受支持的功能；没有呈现虚假的阴影分辨率选项。

变换挂钩有意保持狭窄：

  1. BedrockAttachmentModel.render 建立附件/枪/渲染拥有者上下文。
  2. BedrockPart.translateAndRotateAndScale 在 TaCZ 应用完整父级层级后捕获配置的发射器。
  3. 生成的相机相对矩阵被转换为世界位置以及前/上基向量。
  4. VeilFlashlightManager 更新或移除持久化的 Veil Volume Lights 聚光灯句柄。

如果附件缺少已识别/配置的发射器骨骼，则跳过。调试模式会记录其解析出的枪、附件、骨骼、位置、前向量和 Veil 句柄状态，每位玩家每秒最多记录一次。