Python+Pyglet体素沙盒：面剔除与批处理冲到60帧

简介这是一份面向 Python 初学者、编程教育者及 Minecraft 爱好者的轻量级开源示例项目借助 Python 与 Pyglet 复现沙盒世界的基本交互可用于课堂演示、少儿编程启蒙或自学者练手帮助读者在可视化环境中理解三维渲染、方块世界与事件循环等概念。压缩包共 4 个文件包含 1 个 Python 主程序脚本、1 个 Markdown 说明文档、1 个许可证文件和 1 张纹理图片整体仅 16KB结构精简便于快速运行与二次修改。已有 514 人学习说明其作为小型教学案例具有一定参考价值。代码侧重可读性与可配置性读者可据此观察世界生成、方块设置和窗口渲染的组织方式并尝试调整参数、扩展方块类型或整理为更易复用的模块对希望用 Minecraft 题材激发学习兴趣的读者尤为友好适合作为 Python 图形编程与游戏逻辑入门的实践素材。1. 一份 Python Pyglet 的方块沙盒60 帧和 9 帧之间差的是什么很多人第一次想自己搭一个能走、能挖、能放的方块世界都是从 Python 起步的装个解释器、pip两个包就能跑不用配编译链。可真动手就会撞上一个反直觉的事实——画出第一个立方体只要二十行代码画到第三千个立方体时帧率掉到个位数而屏幕上看起来“也没什么变化”。这份用 Python Pyglet 写的方块沙盒最小实现价值不在于又复刻了一遍经典玩法而在于它把从“能看见”到“能跑满 60 帧”中间那几道坎用尽量少的代码摊开面剔除、纹理图集、批处理、AABB 碰撞、体素射线。它适合两类人——想入门体素渲染但被 C 教程劝退的 Python 开发者以及手里已经有原型、却说不清性能为什么塌掉的从业者。它不打算做成一个完整的游戏只保证你能在两千行以内看懂每个常数为什么这么设。2. Pyglet 地基怎么搭窗口状态、批处理与一张 16×16 图块的图集动手之前先把“地基”这部分吃透。体素渲染的性能上限八成在打开窗口的那三十行代码里就决定了GL 状态开没开对、几何有没有合并、纹理有没有做成图集。后面章节再优化也只是在这个基础上打补丁。2.1 选 Pyglet 的理由一次 draw call 和六千次 draw callPygame 是 2D 的 SDL 封装要做 3D 就得自己叠一层 PyOpenGL窗口、上下文、缓冲全手动管直接写 PyOpenGL 又等于放弃事件循环键盘鼠标要自己轮询。Pyglet 的位置刚好卡在中间窗口、输入事件、纹理加载、批处理都是现成的底下露出来的就是裸 OpenGLpyglet.graphics.Batch能把上万个四边形合并进少数几次绘制调用。这个能力对体素场景几乎是决定性的。两千个方块做了面剔除之后每个方块平均还剩不到三个可见面加起来就是六千个四边形不做合并的话每帧六千次绘制调用CPU 光在提交命令和切换状态上就耗光了GPU 反而在闲着。合并之后是几次调用瓶颈才回到真正该在的地方。版本上有个血泪经验Pyglet 1.5 和 2.x 的pyglet.gl差异不小2.x 清掉了一批固定管线的接口矩阵栈、部分常量、glBegin系列网上大量老教程的代码直接跑会抛AttributeError: module pyglet.gl has no attribute ...。这份实现是按固定管线写的装的时候直接把上限锁死最省事# 固定管线写法依赖 1.x 的 pyglet.gl装 2.x 会在启动阶段就报 AttributeError pip install pyglet2如果你坚持用 2.x那就得把整条渲染路径改成着色器 VertexList那是另一个工程量不适合作为第一次跑通的目标。2.2 窗口与 GL 状态只设一次别塞进 on_drawimport pyglet from pyglet.gl import * from pyglet.window import key, mouse # vsyncTrue 把帧率钉在显示器刷新率上省掉自己写帧率限制 window pyglet.window.Window(width1280, height720, captionVoxel Sandbox, vsyncTrue) # 全局状态在启动时设一次就够放进 on_draw 里每帧重设纯属浪费 glClearColor(0.55, 0.72, 0.95, 1.0) # 天空色顺便当雾的底色 glEnable(GL_DEPTH_TEST) # 不开深度测试后画的方块会盖住前面的 glDepthFunc(GL_LEQUAL) glEnable(GL_CULL_FACE) # 背面剔除配合面剔除能再省掉一半顶点 glCullFace(GL_BACK) glEnable(GL_TEXTURE_2D) def on_resize(width, height): # 视口和投影必须跟着窗口走否则拉伸后画面会被压扁 glViewport(0, 0, width, height) glMatrixMode(GL_PROJECTION) glLoadIdentity() gluPerspective(70.0, width / max(height, 1), 0.1, 200.0) glMatrixMode(GL_MODELVIEW) window.on_resize on_resize window.set_exclusive_mouse(True) # 锁鼠标第一人称视角必需几个参数值得单独说。视场角 70 度是个经验值太小视野憋屈转身时容易迷路太大边缘畸变明显方块看起来像被拉长了。近裁剪面 0.1 是为了手里的方块贴脸时不被裁掉远裁剪面 200 对应大约一百多米的可视距离再远就该上雾了。set_exclusive_mouse(True)会隐藏光标并把鼠标锁在窗口内不给它加个ESC退出的快捷键调试时会很难受。提示on_resize必须挂上很多人开发时窗口固定大小、跑起来没问题一拖窗口画面就变形然后开始怀疑投影矩阵写错了其实只是没接这个回调。2.3 纹理图集把几十张 16×16 拼成一张 256×256每个方块类型单独一张纹理会导致渲染时不断切换纹理绑定批处理直接失效。正确做法是把所有图块打进一张大图所有面共用一次绑定import pyglet.image TILE 16 # 单个图块的像素边长 COLS 16 # 图集横向能放 16 个图块总共 256 格够用很久 atlas pyglet.image.Texture.create(COLS * TILE, COLS * TILE) def load_tile(path, col, row): 把一张 16x16 的 png 贴进图集的第 (col, row) 格 img pyglet.image.load(path) atlas.blit_into(img.get_image_data(), col * TILE, row * TILE, 0) load_tile(tex/grass_top.png, 0, 0) load_tile(tex/dirt.png, 1, 0) load_tile(tex/stone.png, 2, 0) # 关键一步过滤方式改成最近邻否则放大后糊成一片方块边缘还会出现彩边 glBindTexture(GL_TEXTURE_2D, atlas.id) glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST) glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_NEAREST) glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE) glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE)UV 坐标的换算有个坑必须一起处理直接拿图块的边界当 UV采样时会正好落在两块图块的接缝上再叠加线性过滤就会出现一圈黑边或者隔壁图块的颜色渗过来。解决办法是把 UV 往内缩半个像素EPS 0.5 / (COLS * TILE) # 半个像素换算到 0~1 的 UV 空间 def tile_uv(col, row): 返回该图块的 (u0, v0, u1, v1)注意 pyglet 的图像原点在左下角 u0 col * (1.0 / COLS) EPS u1 (col 1) * (1.0 / COLS) - EPS v1 1.0 - row * (1.0 / COLS) - EPS v0 1.0 - (row 1) * (1.0 / COLS) EPS return u0, v0, u1, v1EPS这个量看着微不足道但它是“贴图看起来脏”和“贴图干净”的分界线。半像素内缩意味着每个图块实际只用中间 15 个像素对 16×16 的像素画来说视觉上几乎无感代价可以忽略。2.4 主循环与视角变换的顺序window.event def on_draw(): window.clear() glLoadIdentity() glRotatef(-pitch, 1, 0, 0) # 先抬头低头 glRotatef(-yaw, 0, 1, 0) # 再左右转 glTranslatef(-px, -py - EYE_H, -pz) # 最后把世界平移到脚下 batch.draw() # 固定步长推进物理1/60 秒一次比跟着帧率走稳得多 pyglet.clock.schedule_interval(update, 1.0 / 60.0) pyglet.app.run()变换顺序反了是最常见的翻车现场先平移再旋转得到的不是“你在世界里走”而是“世界绕着你转”症状是走动时整个地形跟着甩。记住“先转视角、再平移世界”这个口诀就不会错。另外物理用固定步长而不是dt累加跳跃高度才不会因为帧率波动而忽高忽低。3. 从体素数组到顶点列表面剔除把六面砍到平均不到三面地基搭好之后真正决定帧率的是这一章。一个 16×16×64 的区块全填满就是一万六千多个方块每个方块六个面直接画就是十万个四边形——这个量级在 Python 里连拼顶点数组都要好几秒更别提渲染了。而实际上绝大部分面永远看不见。3.1 世界数据的组织字典、三维数组还是分区块字节流选型上有三条路各自适用场景不一样方案内存开销单次读取适用场景dict[(x,y,z)] id每格约 100 字节以上哈希最慢无限地图、稀疏结构、快速验证整块bytearray一维索引每格 1 字节数组下标最快固定大小的封闭世界分区块bytearray 区块字典每格 1 字节 区块表两次寻址需要局部重建的中大型世界这份实现走的是第三条世界按 16×16 的水平区块切开每个区块内部是一个连续的一维bytearray下标按(y * 16 z) * 16 x排。把 y 放到最外层不是随便排的——挖竖井、堆柱子这类操作会让同一列上的格子连续命中局部性好反过来如果按 x 最外层排纵向移动就会在大数组里来回跳。CHUNK 16 WORLD_H 64 class World: def __init__(self): self.chunks {} # (cx, cz) - bytearray(CHUNK * WORLD_H * CHUNK) self.dirty set() # 网格需要重建的区块坐标 def get(self, x, y, z): if y 0 or y WORLD_H: return 0 # 世界上下边界之外一律当空气 c self.chunks.get((x 4, z 4)) if c is None: return 0 return c[(y * CHUNK (z 15)) * CHUNK (x 15)] def set(self, x, y, z, b): key (x 4, z 4) c self.chunks.setdefault(key, bytearray(CHUNK * WORLD_H * CHUNK)) c[(y * CHUNK (z 15)) * CHUNK (x 15)] b # 改一个方块自己和相邻区块的网格都可能失效 for dx in (-1, 0, 1): for dz in (-1, 0, 1): self.dirty.add((key[0] dx, key[1] dz)) 4就是除以 16 15就是取模 16这两个位运算在这里既快又能避免负数取模的坑——Python 的-1 % 16是 15而-1 15也是 15结果一致但-1 4得 -1 而-1 // 16也是 -1两者都对用位运算只是习惯。3.2 六面剔除邻居是实心就整面丢弃面剔除的逻辑一句话讲完一个方块的面只有当它的邻居是空气或者世界边界时才需要画邻居是实心的这面永远被挡住直接不生成。代码上就是六次get判断# 每个面(法线, 四个角点相对坐标, 亮度系数) # 角点顺序必须从面外侧看是逆时针否则会被 GL_CULL_FACE 整片吃掉 FACES [ (( 0, 1, 0), ((0,1,0), (0,1,1), (1,1,1), (1,1,0)), 1.00), # 顶 (( 0, -1, 0), ((0,0,1), (0,0,0), (1,0,0), (1,0,1)), 0.50), # 底 (( 1, 0, 0), ((1,0,1), (1,0,0), (1,1,0), (1,1,1)), 0.80), # 东 ((-1, 0, 0), ((0,0,0), (0,0,1), (0,1,1), (0,1,0)), 0.80), # 西 (( 0, 0, 1), ((0,0,1), (1,0,1), (1,1,1), (0,1,1)), 0.65), # 南 (( 0, 0, -1), ((1,0,0), (0,0,0), (0,1,0), (1,1,0)), 0.65), # 北 ] QUAD_UV ((0, 0), (1, 0), (1, 1), (0, 1)) # 与上面四个角点一一对应 def rebuild_chunk(world, cx, cz, batch, group, tiles): verts, uvs, colors [], [], [] for y in range(WORLD_H): for z in range(CHUNK): for x in range(CHUNK): wx, wz cx * CHUNK x, cz * CHUNK z b world.get(wx, y, wz) if not b: continue for (nx, ny, nz), corners, shade in FACES: if world.get(wx nx, y ny, wz nz): continue # 邻居实心这面永远看不见不生成 u0, v0, u1, v1 tiles[b] for (ox, oy, oz), (uu, vv) in zip(corners, QUAD_UV): verts.append(wx ox) verts.append(y oy) verts.append(wz oz) uvs.append(u0 (u1 - u0) * uu) uvs.append(v0 (v1 - v0) * vv) colors.extend((shade, shade, shade)) batch.add(len(verts) // 3, GL_QUADS, group, (v3f/static, verts), (t2f/static, uvs), (c3f/static, colors))batch.add的第一个参数是顶点总数GL_QUADS要求能被 4 整除写错了会直接抛ValueError。三个属性名里的/static后缀告诉 Pyglet 这批数据不会每帧改动可以走更快的上传路径如果世界是动态的、每帧重建去掉这个后缀反而更稳。3.3 用一个灰度系数换掉整套光照shade那一列不是装饰。顶面 1.0、侧面 0.8 和 0.65、底面 0.5四个数字就构成了一套“假光照”不用算法线、不用开着色器、不用算光照向量顶面自然最亮、底面自然最暗玩家一眼就能分清哪面朝上。这套东西在体素场景里性价比极高因为方块只有六个固定朝向光照结果本来就是常数实时算一遍纯属浪费。颜色的设置方式是(c3f/static, colors)配glColorMaterial或者直接依赖默认的纹理调制GL_MODULATE。默认状态下顶点色会和纹理颜色相乘所以贴图本身保持原色、亮度完全由shade控制改起来只动一个数字。3.4 剔除的效果有多明显拿一个 16×16 的平地加几根柱子做基准粗略量一下就能感受到差距不做剔除时每个方块稳定输出 6 个四边形做了之后地平线以下的面全部消失地面方块平均只剩 1 个顶面。经验值是整体面数降到原来的 15% 到 25%而batch合并之后绘制调用从“每个方块一次”变成“每个区块一次”。这两件事叠在一起才是从 9 帧到 60 帧的真实原因只做其中一件通常只能到二三十帧。注意面剔除只对“实心且不透明”的方块成立。真要做玻璃、树叶这类半透明方块得单独一个批次、开混合、关深度写入并且不能剔除相邻的透明面否则会看到方块内部。4. 玩家能走能挖AABB 碰撞、分步推进与 DDA 射线三件套渲染跑顺了接下来才是“能玩”。这部分代码量不大但每一个参数都会直接影响手感而且几乎没有现成的库能替你决定这些数字。4.1 玩家参数表每个数字都有来处参数取值为什么是这个数碰撞盒宽度0.6 格比方块窄1 格宽的通道能顺畅通过不卡边碰撞盒高度1.8 格两格高的空间刚好能站直蹲下另算视点高度1.62 格接近成年人眼高相对身高的比例视角不显得贴地重力加速度-30 格/秒²比真实重力大得多落地方便、不飘起跳初速8.4 格/秒由 h v²/2g 得 1.18 格刚好能上一格台阶单步最大位移0.2 格小于 1 格从根本上杜绝高速穿墙射线长度8 格够得着、又不至于隔半座山选中方块起跳初速这个数是最容易被随手填错的。填 5跳跃高度只有 0.42 格玩家永远上不了一格台阶会以为是碰撞写错了填 12能跳两格半整个关卡设计就废了。8.4 这个值配上 -30 的重力滞空时间大约 0.56 秒手感干脆。4.2 逐轴分离的 AABB 碰撞体素世界的碰撞检测可以做得极其廉价玩家是一个轴对齐盒子世界是一堆单位立方体判断相交只需要把盒子覆盖的整数格子遍历一遍。W, H 0.6, 1.8 def collides(world, px, py, pz): 玩家碰撞盒左下角在 (px, py, pz)判断是否与任何实心方块相交 r W / 2.0 x0, x1 int(px - r // 1) if False else int((px - r) // 1), int((px r) // 1) y0, y1 int(py // 1), int((py H) // 1) z0, z1 int((pz - r) // 1), int((pz r) // 1) for x in range(x0, x1 1): for y in range(y0, y1 1): for z in range(z0, z1 1): if world.get(x, y, z): return True return False这里刻意用int(x // 1)而不是int(x)Python 的int()对负数向零取整int(-0.3)得 0而-0.3 // 1得 -1后者才是“这个坐标落在哪个格子里”的正确答案。这个差别只在负坐标区域暴露所以很多人第一次测试时完全正常走到地图原点另一侧才开始穿墙。移动时逐轴拆开处理是让“贴着墙滑行”这种手感成立的关键def move(world, pos, delta): pos 是长度 3 的列表原地修改返回是否踩在地面上 # 把这一帧的位移切成若干小段每段都不超过 MAX_STEP steps max(1, int(math.ceil(max(abs(d) for d in delta) / 0.2))) step [d / steps for d in delta] on_ground False for _ in range(steps): for axis in (0, 1, 2): if step[axis] 0.0: continue pos[axis] step[axis] if collides(world, *pos): pos[axis] - step[axis] # 撞上了就退回原位 if axis 1 and step[axis] 0: on_ground True # 向下撞 落地 step[axis] 0.0 # 这个轴本帧不再尝试 return on_ground逐轴拆的好处是撞到墙时只有 x 或 z 被清零另一个轴继续走玩家沿墙滑动而不是被粘住。如果三个轴一起判、一起退贴着墙走就会变成一顿一顿的。4.3 分步推进防隧穿的最后一道保险steps那三行是整个物理里最容易被删掉、删掉之后又最难排查的部分。玩家下落速度超过 20 格/秒时一帧1/60 秒的位移就是 0.33 格速度再快一点单帧位移超过 1 格玩家就会直接穿过一层地板掉进虚空。切成 0.2 格的小段之后任何一段都不会跨过一整格collides一定能捕捉到。代价是每帧多几次collides调用一次调用最多遍历 2×3×2 共 12 个格子对现代 CPU 来说完全可以忽略。判断“要不要分步”的那个max(abs(d))用的是三个轴里最大的位移垂直下落时就是它触发。4.4 DDA 体素射线鼠标指哪打哪拾取和放置靠的是一条从眼睛出发的射线沿着它一格一格往前推进遇到的第一个实心方块就是选中的目标。做法是 Amanatides Woo 的体素遍历核心是维护“到达下一个格子边界的距离”def raycast(world, origin, direction, max_dist8.0): 返回 (选中方块坐标, 命中面的法线)没打中返回 (None, None) ox, oy, oz origin dx, dy, dz direction x, y, z int(ox // 1), int(oy // 1), int(oz // 1) sx 1 if dx 0 else -1 sy 1 if dy 0 else -1 sz 1 if dz 0 else -1 # 每个方向上前进一格需要走过的参数 t 增量 tdx abs(1.0 / dx) if dx else float(inf) tdy abs(1.0 / dy) if dy else float(inf) tdz abs(1.0 / dz) if dz else float(inf) # 从起点走到三个方向第一条格子边界的 t 值 tmx ((x (1 if sx 0 else 0)) - ox) / dx if dx else float(inf) tmy ((y (1 if sy 0 else 0)) - oy) / dy if dy else float(inf) tmz ((z (1 if sz 0 else 0)) - oz) / dz if dz else float(inf) normal (0, 0, 0) t 0.0 while t max_dist: if world.get(x, y, z): return (x, y, z), normal # 沿三个轴里最早到达边界的那个方向前进一格 if tmx tmy and tmx tmz: x sx; t tmx; tmx tdx; normal (-sx, 0, 0) elif tmy tmz: y sy; t tmy; tmy tdy; normal (0, -sy, 0) else: z sz; t tmz; tmz tdz; normal (0, 0, -sz) return None, None循环最多执行 8 次射线 8 格长比逐点采样精确得多也不会漏掉斜着穿过的薄墙。返回的法线是放置方块的关键新方块要放在命中坐标 法线的位置也就是贴着被打中的那个面往外长而不是替换掉被打中的方块本身。放置之前必须做一次相交检查否则玩家会把自己封在方块里def try_place(world, hit, normal, pos): if hit is None: return tx, ty, tz hit[0] normal[0], hit[1] normal[1], hit[2] normal[2] if world.get(tx, ty, tz): return # 目标位置已经占用 # 临时放上去看玩家有没有被卡住卡住就撤回 world.set(tx, ty, tz, STONE) if collides(world, *pos): world.set(tx, ty, tz, 0)这种“先放后测、冲突回滚”的写法比手写 AABB 相交判断短得多也更不容易出错。5. 避坑与排查五个把工程按在地上摩擦的现场代码照着写完之后跑起来大概率还是会有问题。下面这五条是我在实际拼这套东西时踩过、并且在别人的复现记录里反复看到的按“现象 → 原因 → 解决”整理。5.1 渲染相关的三个坑现象一方块接缝处出现一圈黑边或彩色细线放大看尤其明显。原因UV 坐标正好取在图块的边界上最近邻采样尚可一旦有缩放或 mipmap 参与就会采到隔壁图块的像素另一种情况是图集的WRAP模式没设成GL_CLAMP_TO_EDGE边界像素被环绕采样了。解决按 2.3 节的做法把 UV 往内缩半个像素同时把GL_TEXTURE_WRAP_S/T都设成GL_CLAMP_TO_EDGE过滤方式保持GL_NEAREST。别再给图集生成 mipmap体素方块本来就不需要。现象二窗口打开了背景色正常但一个方块都看不见控制台也没有任何报错。原因通常有三个batch建好了但从来没在on_draw里draw()深度测试没开导致远处的内容把近处的覆盖掉又反向覆盖画面看起来是空的或者变换顺序写反摄像机其实被推到了世界外面。解决按这个顺序排查——先在on_draw里临时画一个固定坐标的方块确认管线是通的再检查glEnable(GL_DEPTH_TEST)是否在窗口创建之后、第一次绘制之前执行最后在on_draw里打印一次glGetFloatv(GL_MODELVIEW_MATRIX)或者干脆把平移量手动清零看画面有没有变化。这三个里最隐蔽的是第二个因为不开深度测试时某些角度依然能看到东西只是前后关系全乱。现象三帧率随方块数量线性下跌一千个方块 40 帧三千个方块 9 帧。原因面剔除做了但每个方块还是单独一次draw或者每次重建都把整个世界的Batch清空重来。前者是没合并后者是重建开销吃掉了渲染省下来的时间。解决确认所有顶点进的是同一个Batch用group区分纹理状态而不是每次重新绑定重建只针对被修改的区块用 3.1 节的dirty集合记录。判断有没有合并成功看任务管理器里的 CPU 单核占用——没合并时 CPU 会先到瓶颈。5.2 逻辑相关的两个坑现象四玩家走着走着掉出世界或者在高速下落时穿过地板。原因单帧位移超过一个方块宽度碰撞检测的采样点直接跳过了薄地板另一种是 y 坐标低于 0 之后没有兜底一路往下掉。解决按 4.3 节把位移切成不超过 0.2 格的小段。同时在update里加一条硬性约束if pos[1] -10: pos [0.0, 40.0, 0.0]把掉出世界的玩家送回出生点。这条兜底看着粗糙但它能把“莫名其妙的黑屏”变成一个可以继续调试的状态。现象五右键放方块之后玩家瞬间被弹飞或者彻底动不了。原因新方块和玩家碰撞盒重叠了下一帧的碰撞检测发现玩家卡在实心格子里逐轴退回逻辑会把所有轴的位移都清零表现就是原地定本文还有配套的精品资源点击获取