# Gameplay Raycaster Depth Correction

> 修复已有平面方格、等高墙 raycaster 用斜射线全长投影导致的墙面鱼眼弯曲，改用视线前向深度并保护近墙除法；不负责从零构建渲染器或镜头震动。

- Skill: `ziyou-lu/gameplay-raycaster-depth-correction` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add ziyou-lu/gameplay-raycaster-depth-correction`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ziyou-lu/gameplay-raycaster-depth-correction/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ziyou-lu (https://skillmd.com/u/ziyou-lu)
- Updated: 2026-11-19
- Page: https://skillmd.com/skills/ziyou-lu/gameplay-raycaster-depth-correction

---


# Raycaster 墙柱前向深度修正

## 效果预览

相同接近平墙运动，逐列柱高对比欧氏射线全长与视线前向深度；不改变地图或碰撞。

左侧为使用前，右侧为使用后；斜视 2.5D 短循环，用途示意（非引擎实测；音频相关预览仅示意触发关系，不含声音）。

![直墙不该弯成鱼眼：使用前后对比](assets/before-after.webp)

## 触发条件与输入

已有逐屏幕列投射射线、命中墙并画垂直墙柱的自定义渲染器；正对平直墙时，上下边缘向屏幕两侧弯曲。限水平观察平面、方格世界和等高墙，不以此补齐任意三维场景、坡面或抬头俯视投影。

先取得相机平面位置 C、非零前向向量 F、每列射线及命中点 P（或距离及其精确定义）、墙世界高度 H、视口尺寸与 FOV、现有墙柱高度与屏幕裁切流程。记录世界单位、射线是否归一化，以及遍历返回的是欧氏距离、参数 t，还是已修正的前向/垂直投影距离。只有名称叫 distance 不足以判断。

## 实施步骤

1. **隔离距离错误。** 固定相机正对一面连续平墙，暂时关闭震动、动态 FOV 和后处理。记录中心及左右边缘列的命中点、全长、最终投影分母和柱高。若最终分母已经是前向深度，不再乘余弦；继续检查列射线生成、相机基向量、画幅与投影比例。
2. **明确转换路径，只执行一次。** 推荐用单位前向 f = normalize(F)，求 z = dot(P - C, f)。这不依赖射线方向是否归一化。只有已经确认 L 是欧氏射线全长、r 是单位射线方向时，才可用等价形式 z = L * dot(r, f)。若命中由 P = C + t * r 定义且 r 未归一化，直接用 z = t * dot(r, f)，不能把 t 当欧氏长度再套单位射线余弦。DDA 只是遍历方法：有些实现返回的 t 已等于前向深度，有些不是；核对公式和 dot(r, f)，不要按 DDA 名字自动修正。
3. **先剔除无效命中，再保护除法。** 无命中、非有限命中点/深度、z <= 0 均不绘制墙柱，沿用项目背景路径。不要先 clamp 而把无命中或相机后方对象变成贴脸巨墙。对有效正深度才取 zSafe = max(z, nearDepth)。nearDepth 必须有限、严格为正且与世界坐标同单位，由项目最近合法观察距离和数值范围确定；不提供万能数值。保护投影不是替代相机与墙的碰撞处理。
4. **保留逆深度投影。** 用 columnHeight = H * focalPixels / zSafe。沿用项目已校准的垂直像素焦距；若需要重建比例，可在方形像素、水平 FOV 契约下取 focalPixels = viewportWidth / (2 * tan(horizontalFOV / 2))，或垂直 FOV 下取 viewportHeight / (2 * tan(verticalFOV / 2))。两种 FOV 不可混用，角度单位必须与三角函数一致。射线方向应对应平面投影屏幕列位置，不把等角度射线采样误作等间距透视像素。保留原有相机眼高与墙顶/底定位，不强行把所有墙柱绕屏幕中线居中。
5. **接回输出并裁切。** 用修正深度替换墙高分母，不改命中选择、碰撞或地图数据。先以有限浮点值计算墙顶/底并裁切到视口，再转换为绘制整数，避免近墙巨大柱高造成溢出。若有墙纹理，屏幕裁切后仍按未裁切墙段的位置采样，不能把整张纹理挤进可见片段。FOV/画幅变化时同步更新射线与投影尺度；不要额外再做一次“鱼眼补偿”。

## 调参与失败恢复

- 两侧仍弯：比较 dot(P - C, f) 与实际使用的分母，查遗漏转换、双重余弦、角度单位、非单位前向及射线列映射；不要先改墙高补偿曲线。
- 直墙正常但整体比例错：检查 H 与距离单位、水平/垂直 FOV、像素焦距和宽高比，而非再次修正深度。
- 近墙跳变或过早停止变大：检查 nearDepth 是否过大及是否使用正深度后保护；减小阈值前确认中间运算与绘制坐标范围。相机穿墙产生的失效命中应修相机/碰撞，不以绝对值深度遮掩。
- 斜墙变成等高：不要把所有列强制成中心距离；每个命中点独立计算前向深度。

## 验收

- [ ] 正对连续平墙，左右及中心的前向深度一致到项目容差内，上下边缘保持水平；沿墙横移仍成立。
- [ ] 转向形成斜视时，墙边按透视形成直线并有合理远近变化，没有被强制拉平；检查最外侧列与转角连接。
- [ ] 切换支持的窄/宽 FOV、画幅及分辨率，直墙不重新弯曲，比例变化符合投影契约；已是前向深度的输入不被重复修正。
- [ ] 从正常距离连续靠近墙，柱高增大直到保护范围，无 NaN、无穷或整数溢出；近墙裁切与纹理采样不突然压缩。
- [ ] 无命中、无效数值与后方/零深度测试列走背景/拒绝路径，不因最小正值保护绘制假墙。

本技能拥有墙柱距离分母修正。[固定相机插画投影](../gameplay-fixed-camera-art-projection/SKILL.md)负责插画到几何的映射，不替代本流程；[镜头冲击](../gameplay-camera-feedback/SKILL.md)负责临时相机偏移，应在基础投影验收后接回，使用同一帧一致的相机位置和方向。

需要核查署名、历史归因或工程推导边界时，读取[来源参考](references/sources.md)。

