本系列：把这两年用 Python 写的十几个小项目挨个开源、挨个说清楚。不讲”我做了什么”，讲”做的过程中被什么打脸、最后怎么想明白的”。 第 8 篇 · 立方之蛇 CubeSerpent（前几篇：离阵 / 胶囊医生 / 烬塔 / 回响回廊 / 砂漏 / 纯粹数独 / 方寸） 源码：github.com/ghostgorge/Snake3D 技术栈：Python + pygame + numpy，自写软件三维渲染器，无任何外部素材——音效程序合成，画面全是代码画的
这是整个系列里唯一一个被实机反馈直接推翻、然后整个重写的项目。所以这篇一半篇幅在讲 v1 错在哪。
一、v1 的推理链，每一步看起来都对
三维贪吃蛇的第一个问题是：六个方向怎么绑键？
最朴素的方案是六轴绑六个键（+X/-X/+Y/-Y/+Z/-Z）。这个必翻车——相机跟随之后，屏幕方向和世界轴对不上，每次转向你都要在脑子里做一次坐标变换。
所以 v1 用了 FPS/飞行游戏的通用解法：机体相对转向。
A/D偏航、W/S俯仰、Q/E滚转- 相机永远挂在蛇头后上方
- 于是”屏幕上的左永远是 A 键”
滚转键还有个精心设计的说法：它不改前进方向、只改”上”的定义，是垂直飞行时的心智对齐工具。
这套推理没有一步是错的。手眼协调确实解决了。我还为此做了一堆配套：屏幕边缘目标指向箭头、右下角 XY/XZ/ZY 三视图小地图、只画远侧三面的透视网格。
然后我把它交出去了。
二、实机反馈：一句话把整套方案否掉
“太难操控、视角转换很乱，明显不如平面贪吃蛇好掌控好操作。”
我最初的反应是”再优化优化”——降速、加阻尼、改小地图。这是错的反应。
真正的问题在更上游：
v1 的方法论错误是：把”相机跟着蛇头转”当成不可动摇的前提，然后去优化操作来迁就它。 正确的问法是——相机为什么必须跟着转？
追下去就找到了根子：
平面贪吃蛇好操控的原因，不是”只有两个转向选择”，而是地图是静止的。
那张静止的地图，是玩家全部策略思考的载体——你能看着它规划”绕外圈再回来”。而 v1 的跟随相机在速度 6 下每秒把整张地图转好几个 90°。机体相对操作保住了手眼协调，牺牲掉的恰恰是空间记忆——而贪吃蛇要的就是后者。
手不乱了，脑子还是乱的。
当一个解法要靠”训练玩家适应”才成立时，先回头查前提。
三、v2 三条核心规则
1. 相机固定世界朝向
等距视角，只有玩家按 J/L 才转 90°，永不自动旋转。水平锁死场地中心，只有高度跟着当前层升降。
2. 绝对方向输入
WASD 就是屏幕上的四个方向。空格/E 上一层，Q/Ctrl 下一层。
滚转键连根删掉。 它的代价是一个看不见的隐藏状态会重映射另外四个键——怎么算都是亏的。
3. 层是第一等公民
这是整个改版的关键。
三维贪吃蛇劝退人的从来不是”难”，是”一上来就要同时处理三个轴”。
所以加了一根层数轴 yh，逐章放开：
| 章 | 可玩层数 |
|---|---|
| 一 · 初启 | 1（纯平面贪吃蛇，上下键直接被吞掉） |
| 二 · 晶野 | 3 |
| 三 · 蛇窟 | 5 |
| 四 · 炮廊 | 7 |
| 五 · 迷窖 | 9 |
| 六 · 深核 | 全高 |
第一章先让你在熟悉的平面里，把”相机固定 + 绝对方向”建立成肌肉记忆。第二章第一关才第一次出现”上一层”。
实现上有个小巧思：不搞第二套坐标系，直接把层带以外的格子填成实心。于是碰撞、连通性、洪水填充、面掩码全都不用改一行代码——yh=1 的关卡在引擎眼里就是一个”上下都是墙”的三维盒子。
四、分层视觉：为什么上层要缩成小点
- 当前层：满亮、满尺寸，另外画一张地板网格——凭空造出立方体本来没有的”下”
- 低于当前层：按距离压暗，但尺寸不变（在视线下方不挡事，而且是深度参照）
- 高于当前层：缩成小幽灵点
第三条不是为了好看。等距相机从上往下看，上层的实心方块会正好糊住你要走的那一格。缩小是唯一能既保留信息又不遮挡的办法。
读第三维的三根拐杖
- 左侧层带竖条——等距视角唯独告诉不了你”竖直差几层”，透视深浅人眼分辨不出。竖条把 Y 轴抽象成一把尺子。
- 当前层俯视小地图——取代 v1 那三张正交视图。关键实现：直接用主相机的屏幕基向量投影，保证朝向和主画面严格一致。别自己再推一遍旋转公式——多推一遍就多一个可能反掉的符号。
- 果实光柱——垂直连到当前层平面，地面留一个十字标出水平位置。
另外，换层必须给一个和平面转向明显不同的音效，并让层带竖条闪烁。三维里”我刚才是不是换层了”这个疑问一旦出现，玩家就已经乱了。
五、整个方案里唯一绝对不能错的一处
屏幕方向 → 世界方向的那张映射表。
我按推导写完之后没有直接相信它：渲染一帧、投影三个测试点、量像素——发现右向量整个反了。
这个错误的可怕之处在于它的症状：
不崩溃、不报错。上线后玩家的反馈只会是”新版更难操控”，而且描述不出原因——按键有反应，只是反应错了。
右手系约定、视图矩阵构造、投影公式符号，任何一处翻一下都能掀翻它。
这类映射表只能实测，不能推导。
所以自测里加了一项：四个相机象限各渲染一帧，验证”右键向右、前键向上、上升键向上”。并且故意把符号翻回去，确认这条测试会变红——一个从来不会失败的测试等于没有测试。
六、渲染器：为什么自己写，以及两刀砍掉 70% 帧时间
不用 PyOpenGL，自写软件渲染器。理由是场景性质：全是同尺寸轴对齐立方体，一帧才两千来个面，瓶颈在 Python 循环不在数学。
管线：世界空间背面剔除 → 视图变换 → 近平面 Sutherland-Hodgman 裁剪 → 画家算法 → numpy 着色 + 雾 → pygame.draw.polygon。
背面剔除放在世界空间做（用外法线）。放视图空间会被左右手系的符号问题反复坑。
两刀优化，32ms → 9.5ms：
add_cube只登记不展开——把 6 面拆分推迟到 render 里一次向量化完成。原来每次调用都生成 numpy 行视图，最后np.asarray拼几千个小数组，奇慢。- 相邻实心块之间的面根本不生成——用三维数组切片算每块的”暴露面”位掩码并缓存，
set()时置脏。密集地形砍掉一半以上面数。
另外一个小到容易忽略的点：逐面调 polygon 前先 .tolist() 一次，比逐个索引 numpy 标量快数倍。
第三人称相机的两课（二维游戏没有，三维不修没法玩）
- 相机会钻进墙里/柱子里——而”贴着外壁绕”恰恰是贪吃蛇最主流的走法。必须做避障：从蛇头沿连线往回收，下限 2.1。
- 相机被迫收近之后，自己的身体就在蛇头正后方（即相机方向），紧跟的两三节直接怼镜头糊满屏。解法：离相机 < 4.2（距离平方）的自身几何体不画，且只对玩家自己 + 跟随视角生效。
三维项目性价比最高的调试手段
把连续六帧渲染成 PNG 拼成一张图看。
远墙判据符号写反（画成近墙糊住视线）、光晕炸屏、相机穿墙、自身身体糊屏——四个问题全是看图发现的，看代码一个都看不出来。
（顺带：加色光晕必须三道保险，否则相机一贴近就炸成满屏白光——屏幕半径硬性封顶 54px、深度 < 0.75 直接不画、贴图 alpha 峰值降到 118 且衰减指数提到 2.4。）
七、AI：只数空格会被骗
贪吃蛇 AI 的经典做法是洪水填充数空格，选空间大的方向。这个会被骗：填出 60 个空格，但那是个死胡同，长蛇进去就出不来。
必须加一条判据：能不能摸到自己的尾巴？（尾巴算通路，因为下一步它就挪走了。摸不到、又不宽敞，直接扣 420 分。)
三维死胡同比二维隐蔽得多，所以这个判据在三维里更值钱。
性能上：一次多源 BFS 距离场服务全部 5 个候选，别每个候选各跑一次。
v2 还把 AI 动作空间改成”六轴减反向”（和玩家完全一致），并加了一条小权重”换层比平移贵 -1.1“，免得它在层间乱窜。
八、三次”测试自己有问题”
这个项目在测试上翻车三次，每次的教训都不一样。
其一：自测框架自己有个洞。 约定是”通过返 True、失败返描述字符串”，而判定写成了 ok = (r is not False)——非空字符串是真值，于是所有带说明的失败全被当成通过放过去了。15 项测试里有效的只剩”没抛异常”。改成 r is True or r is None 之后立刻暴露两项真实失败。
一个从不报错的测试套件是可疑现象。测试框架本身也要被怀疑。
其二：症状会骗人，先测量再猜原因。 自测报”AI 60 秒最长 0 节”，我的第一反应是”AI 太笨全撞死了”。给 kill() 打桩一数——一次死亡都没有，它们根本没生成。真因在出生逻辑：取一个固定方向把身体往反方向铺 4 格，而出生点在角落时六个方向里有三个必然铺到盒外，铺不下就 continue 静悄悄放弃这条蛇。
（改法：出生点和方向都试一遍，且先验证再落笔——原写法在验证途中就已经 arena.set 把地形凿坏了。）
后来 v2 改完 AI 动作空间，自测又报”45 秒只长到 8 节”（改版前 22–31）。这次我先打桩测六个种子——死因只有 3 次中弹、长度分布 3~29，同一量级，是噪声。先测量的习惯省了一轮无用功。
其三：长期失败的测试，先怀疑测试写错了。 “36 关可玩性”用随机按键跑 20 秒、要求死亡 < 8 次，一直失败——但三维里随机转向必然一头撞墙，那测的是猴子不是关卡。改成让 AI 大脑驾驶玩家蛇（会避障会觅食），连它都反复暴毙才说明地形真有问题。改完 36 关全过。
九、内容
四种模式：闯关（6 章 36 关、108 星）、自由（自调盒子大小/地形/速度/AI 数量/是否穿墙）、AI 对战（最多 3 条蛇，四档强度、三种性格：贪吃/好斗/苟命）、首领（单挑或四连战）。
十二种符文：护盾、相位、超载、时缓、磁引、双倍、僚机、断尾、湮灭、贯穿、火力、补给。
其中相位是唯一能穿外壁的效果（穿出去从对面回来）——贪吃蛇的经典绝境是”被自己围死”，这给了它一个用道具化解的出口。
金苹果每 26 秒刷一颗、只停留 12 秒：60 分 + 清屏 + 短暂无敌 + 直接长 5 节。它总是刷在离你较远的地方，逼你在”稳”和”贪”之间做选择。
四位首领：方碑（六块装甲板，打掉一半才露核心）、环蛇（22 节的蛇，只有头能打，二阶段走过留毒）、蜂巢（外壳无敌、弱点在壳上游走、不停放无人机）、万花核（六颗卫星 → 核心，三相，最后会把整个立方体收缩）。
关卡难度做在三条独立轴上——空间（11³→19³、empty→maze/tunnels）、威胁（尖刺→炮台→无人机→AI 蛇→首领）、目标（吃够数量→限时收集→清场→打首领）。任一关只在一两条轴上加压。 第 5 章末尾故意不放首领、改放纯迷宫极限关，让节奏错拍。
（程序生成地形必须过连通性闸门：可达空格 ≥ 90%，最多重试 14 次，而且每次重试要降密度——只重试同样参数的话，高密度配置可能永远过不了，直接卡死在生成阶段。）
射击是怎么塞进贪吃蛇的：关键是”不占用操作”——自动开火、方向恒为蛇头正前方，火力等级只改弹幕形态，中弹惩罚是火力 -1（比掉命更疼，因为它是持续的）。玩家注意力仍然全在走位上，核心没被稀释。
上手
pip install pygame numpy
python main.py
python selftest.py # 18 项，打包前自动跑
双击 build_exe.bat # 单文件 exe
WASD 层内移动 · 空格/E 上升 · Q/Ctrl 下降 · J/L 转场地 90° · I/K 俯角 · +/- 缩放 · 连按两下 Shift 作弊台
尾巴
v2 交付时我说清了一件事：操作手感（尤其第一章 4.2 的速度、跟层的相机阻尼）只有上机才能定。 这是 v1 教我的——三维手感这种东西，自测跑再多轮也代替不了一次真人上手。
而 v1 留下的那条，我认为是整个系列里最值钱的一句：
当你在优化一个解法却总也优化不好时，先回头查它的前提。
我为”相机跟随”配了一整套补偿系统——机体相对转向、指向箭头、三视图小地图、透视网格——每一件都做得挺好。它们全都是在给一个错误的前提打补丁。
正确的动作不是把补丁做得更精致，是把前提删掉。
📦 源码：https://github.com/ghostgorge/Snake3D
下一篇：弈局 ChessForge——国际象棋引擎，一个”不写 perft 就永远发现不了 bug”的故事。回复「继续」。