本文还有配套的精品资源，点击获取

简介：用纯Python写的迷你方块世界演示程序，不装OpenGL、不编译C扩展、不连数据库，只要pip install pyglet就能直接运行。主逻辑集中在main.py里，配合一张texture.png贴图和清晰注释，把3D视角控制、WASD移动、鼠标瞄准、左右键破坏/放置方块、数字键切换方块类型这些功能全打包进不到500行代码里。世界尺寸、默认方块、鼠标灵敏度等参数都写在开头常量区，改完保存就能立刻看到效果，特别适合边学边调。配套README写明了每步操作：怎么装依赖、怎么启动、怎么走动、怎么放方块，连新手家长都能照着带孩子试。整个项目按教学逻辑组织，World类封装了方块存取，set_block这类方法命名已贴近未来可复用的教学API，但当前仍保持单文件轻量结构，方便逐行理解渲染循环和事件响应机制。

1. 项目概述：为什么这个“方块世界”对初学者真正友好？

你有没有试过给一个刚接触Python的孩子讲“事件循环”？或者对着屏幕里一闪而过的黑窗口，解释“OpenGL上下文”和“顶点缓冲区”是什么？我带过三届青少年编程夏令营，每次看到孩子盯着一堆报错信息发呆、家长在旁边反复刷新pip install命令却卡在“building wheel for pyopengl…”那一步时，就知道——不是孩子学不会，是工具链太重了，把“我想放一块砖”的直觉，硬生生拖进了编译器和驱动兼容性的泥潭里。

这个Pyglet方块世界小样例，就是我用三年时间反复打磨出来的“教学锚点”。它不叫Minecraft克隆，也不标榜“高性能3D引擎”，它就干一件事：让一个写过print(“Hello World”)的孩子，在5分钟内亲手移动视角、瞄准、点击鼠标，把一块方块放进世界里，并立刻看见它立在那里。整个过程不需要装显卡驱动更新包，不需要配环境变量，不需要理解GLSL着色器语法，甚至不需要知道“渲染管线”这个词——但等他跑通第一遍，再回头翻《流畅的Python》里关于生成器和协程的章节，会突然发现：“哦，原来那个while True循环，就是在模拟游戏里永不停歇的‘心跳’。”

核心关键词“Pyglet教学”“Python方块世界”“编程入门示例”不是标签，而是设计铁律。Pyglet被选中，不是因为它最炫，而是因为它零依赖、纯Python、自带音频/窗口/输入抽象层。它把OpenGL底层封装成pyglet.graphics.Batch()和pyglet.gl.glEnable()这样可读性强的接口，又不像Pygame那样强制你处理像素级Surface blit，也不像Arcade那样预设太多场景管理逻辑——它给你留出足够空间去理解“世界怎么存”“视角怎么算”“鼠标坐标怎么转成三维射线”，又不至于让你从头手写矩阵乘法。而“方块世界”这个载体，是经过验证的教学最优解：孩子天然理解“方块能堆、能拆、有不同材质”，这比教“面向对象的银行账户类”直观十倍；“数字键切换方块类型”比“输入字符串选择材质”更符合手指肌肉记忆；“WASD移动+鼠标拖拽视角”是他们玩过最多的游戏操作，迁移成本几乎为零。

更重要的是，它真的“开箱即玩”。你只需要一台装了Python 3.8+的电脑（Windows/macOS/Linux全支持），执行一条命令：

pip install pyglet

然后双击main.py，或者终端里敲python main.py——世界就加载出来了。没有cmake，没有rustc，没有nvidia-smi，没有.so/.dll文件找不到的报错。texture.png只是一张64×64的PNG图，用系统自带画图工具就能改；所有参数都集中在main.py开头20行常量区：WORLD_WIDTH = 16、MOUSE_SENSITIVITY = 0.005、DEFAULT_BLOCK = GRASS……改完保存，Ctrl+R刷新，效果立现。这不是“演示程序”，这是给孩子搭的第一座可触摸的编程脚手架——他摸到的不是抽象概念，是自己敲出来的坐标、自己调出来的灵敏度、自己换上去的木头方块。

2. 整体架构与设计思路：为什么不用Pygame、Arcade或Panda3D？

很多人看到“3D方块世界”，第一反应是“该上Pygame了吧？”或者“直接用Arcade做教育项目不是更成熟？”——这恰恰是我花半年时间对比七种Python图形库后，最终锁死Pyglet的核心原因。不是因为它功能最强，而是因为它在“教学穿透力”这个维度上做到了极致平衡。下面我用一张实际对比表说明取舍逻辑（数据来自我实测的MacBook M1、Windows 10 i5-8250U、Ubuntu 22.04三台机器）：

这张表背后，是我在教学现场踩过的所有坑。比如用Pygame时，有个孩子写的pygame.display.set_mode((800,600))总报错，查了半小时才发现他装的是pygame-2.0.1，而教程用的是1.9.x，set_mode参数签名变了；用Arcade时，另一个孩子想“只显示方块不加物理”，结果删掉self.physics_engine后整个世界坐标乱飞——因为Arcade默认把所有Sprite坐标绑定到物理引擎；而Panda3D，光是让一个方块出现在屏幕上，就得先理解NodePath、SceneGraph、Camera Lens这些概念，这已经超出“入门”范畴，进入“专业引擎开发”领域了。

Pyglet的胜出，在于它把“必须暴露给初学者的部分”控制在最小集：窗口管理、事件分发、纹理加载、基础3D绘制（glBegin(GL_QUADS)）、键盘/鼠标状态查询——全部用Python方法名直译，没有魔法字符串，没有隐式依赖。比如on_mouse_press(x, y, button, modifiers)这个回调，参数名就是真实含义，button是pyglet.window.mouse.LEFT这样的枚举，modifiers是pyglet.window.key.MOD_SHIFT这样的标志位，孩子看一眼就知道“左键按下时触发，可以判断是否按着Shift”。再比如世界数据结构，它没用复杂的Chunk系统或Octree，而是最朴素的三维列表world[x][y][z] = BLOCK_ID，内存占用可控（16×16×16=4096个元素），打印出来就是清晰的坐标矩阵，debug时print(world[5][3][2])直接看到当前格子是什么方块——这种“所见即所得”的调试体验，对建立编程信心至关重要。

至于为什么不用WebGL（如Pyodide）或更轻量的TinyGL？前者需要HTTP服务器环境，孩子在家用记事本改完代码还得开终端起服务；后者缺乏成熟的输入事件抽象，鼠标瞄准逻辑得自己算视锥体截面，教学成本陡增。Pyglet是目前唯一能把“3D交互感”和“Python纯文本可读性”焊死在一起的方案。它不追求工业级性能，但确保每一行代码都在教孩子一件确定的事：这一行创建窗口，这一行注册事件，这一行更新视角，这一行绘制方块。当孩子第一次成功用鼠标右键在空中“种”下一棵树，那种“我造出了东西”的震撼，远胜于背一百条语法糖。

3. 核心模块解析：World类、渲染循环与交互逻辑如何协同工作

现在我们钻进main.py的血肉里。整个项目不到500行，但麻雀虽小五脏俱全。我把核心拆成三个齿轮：World类（世界数据容器）、渲染循环（视觉输出引擎）、交互逻辑（用户意图翻译器）。它们不是孤立模块，而是像钟表齿轮一样咬合转动——World提供数据，渲染循环把它变成画面，交互逻辑则根据鼠标键盘动作实时修改World并触发重绘。下面逐层剥开，重点讲清“为什么这么设计”。

3.1 World类：用三维列表实现的极简世界模型

打开main.py，找到class World:定义。它没有继承任何父类，没有抽象方法，就是一个纯粹的数据持有者。核心只有两个属性：

def __init__(self): # 初始化三维列表：x, y, z 坐标范围均为 [-WORLD_WIDTH//2, WORLD_WIDTH//2) self.world = [[[AIR for z in range(WORLD_DEPTH)] for y in range(WORLD_HEIGHT)] for x in range(WORLD_WIDTH)] # 方块材质ID映射表，用整数代替字符串，节省内存且便于索引 self.block_types = { 'air': 0, 'grass': 1, 'dirt': 2, 'stone': 3, 'wood': 4, 'leaves': 5 }

这里藏着三个关键教学点。第一，坐标系设计：WORLD_WIDTH = 16，但世界范围是[-8, 8)，不是[0, 16)。为什么？因为孩子更容易理解“以玩家为中心，前后左右各8格”，而不是“从左上角开始数16格”。当你站在(0,0,0)，往前走是z+1，往右走是x+1，这和现实空间直觉一致。第二，数据结构选择：用嵌套列表而非NumPy数组或字典。NumPy需要额外安装，且world[x,y,z]这种索引对初学者不够透明；字典虽节省稀疏世界内存，但world.get((x,y,z), AIR)的写法增加了认知负担。三层列表world[x][y][z]，打印出来就是活生生的三维矩阵，for x in range(-8,8): for y in range(-8,8): for z in range(-8,8): print(world[x][y][z])，孩子能亲手“看到”整个世界。第三，材质ID化：不存字符串'grass'，而存整数1。这有两个好处：一是内存占用小（int比str轻得多），二是为后续扩展预留空间——比如你想加光照计算，world[x][y][z]可以扩展为元组(block_id, light_level)，而字符串拼接会变得无比笨重。

World类提供的核心方法只有三个：

• get_block(self, position)：根据(x,y,z)坐标返回方块ID。内部做了边界检查——如果坐标超出[-8,8)范围，直接返回AIR（空气），避免IndexError。这是安全网，让孩子随便乱走也不会崩。
• set_block(self, position, block_id)：在指定位置放置方块。同样做边界检查，且只允许放置非AIR方块（防止误删空气）。
• hit_test(self, position, vector, max_distance=8)：这是整个交互的灵魂！它接收玩家位置position、视线方向向量vector（由鼠标移动计算得出），以及最大探测距离，返回(block_position, face_position)元组。原理是沿着视线方向做步进采样（Bresenham直线算法简化版），每步检查该坐标是否有实体方块。一旦碰到，立即返回碰撞点坐标和法向量（用于确定放置位置）。这个方法不涉及任何数学库，纯整数运算，孩子跟着注释一行行读，能亲手推演“从眼睛出发，第一步到(0,0,1)，第二步到(0,0,2)……第7步碰到石头”。

提示：hit_test的步进精度设为max_distance=8是刻意为之。世界尺寸16，8刚好覆盖一半视野，既保证探测足够远（能看到远处方块），又避免无限循环（万一前方全是空气）。你可以让孩子把8改成2，立刻看到“只能打到眼前两格”的效果，这就是参数调整的即时反馈魅力。

3.2 渲染循环：如何用50行代码画出3D世界？

Pyglet的渲染循环极其干净：重写on_draw()方法，里面调用batch.draw()即可。但batch是怎么构建的？这才是教学重点。main.py里有一个initialize_world_batch()函数，它遍历整个世界，对每个非AIR方块，调用add_cube_to_batch()：

def add_cube_to_batch(batch, x, y, z, texture_coords): # 定义立方体6个面的顶点（x,y,z）和纹理坐标（u,v） vertices = [ # 顶面 (y+1) x, y+1, z, x+1, y+1, z, x+1, y+1, z+1, x, y+1, z+1, # 底面 (y) x, y, z+1, x+1, y, z+1, x+1, y, z, x, y, z, # 其他4个面类似... ] # 纹理坐标映射到texture.png的6个区域（草、土、石等各占1/6） tex_coords = [u1,v1, u2,v1, u2,v2, u1,v2] * 6 # 重复6次，每面4个点 # 批量添加到渲染批次 batch.add(24, pyglet.gl.GL_QUADS, None, ('v3f/static', vertices), ('t2f/static', tex_coords))

这里没有着色器，没有VBO，只有最原始的GL_QUADS（四边形）绘制。vertices是24个浮点数（6个面×4个顶点×每个顶点3坐标），tex_coords是48个浮点数（6个面×4个点×每个点2坐标）。'v3f/static'告诉Pyglet：“这是静态顶点坐标，3个float一组”，'t2f/static'同理。这种写法看似低效，但对孩子极其友好：他能清楚看到“一个方块=24个数字”，修改x,y,z就能平移方块，调整tex_coords就能换贴图区域。当你把texture.png打开，会发现它被均分为6行，每行一种材质（草、土、石、木、叶、空），texture_coords里的u1,v1就对应某一行某一列的像素范围——这比教“UV映射”概念直观一万倍。

整个渲染批次（batch）在on_draw()里只调用一次batch.draw()，Pyglet自动把所有顶点交给GPU绘制。没有glClear()手动清屏（Pyglet默认做），没有glFlush()手动提交（draw()内部封装），孩子只需关注“我往batch里加了什么”，而不必操心OpenGL状态机。这也是Pyglet的教学优势：它把“必须懂”的部分压缩到最小，把“可以以后学”的部分彻底隐藏。

3.3 交互逻辑：从鼠标坐标到方块放置的完整链条

这是孩子最兴奋的部分——“我动鼠标，方块就动！”。整个链条只有四步，全部在on_mouse_press()和on_mouse_drag()里完成：

1. 获取玩家位置与视线：self.position是玩家三维坐标（初始(0,0,0)），self.rotation是水平角（yaw）和垂直角（pitch）组成的元组。鼠标拖拽时，dx,dy乘以MOUSE_SENSITIVITY累加到rotation上，实现“鼠标移动=视角转动”。

2. 计算视线向量：这是唯一需要一点三角函数的地方，但代码已封装成self.get_sight_vector()：
   python def get_sight_vector(self): # 根据yaw和pitch计算单位向量 rot_x, rot_y = self.rotation # pitch限制在-89°到89°，防止翻滚 rot_y = max(-89, min(89, rot_y)) # 计算x,z平面投影长度 m = math.cos(math.radians(rot_y)) # 向量分量 dx = math.cos(math.radians(rot_x - 90)) * m dy = math.sin(math.radians(rot_y)) dz = math.sin(math.radians(rot_x - 90)) * m return (dx, dy, dz)
   注释里写了“-90°是为了让0°朝向正Z轴（前方）”，孩子改rot_x - 90为rot_x，立刻看到“鼠标往右移，视角往左转”的反直觉效果——这就是调试的乐趣。

3. 射线检测（hit_test）：调用World.hit_test(self.position, sight_vector)，得到被瞄准的方块坐标block_pos和碰撞面法向量face_pos。

4. 执行动作：如果是左键（button == mouse.LEFT），调用world.set_block(block_pos, AIR)删除方块；如果是右键（button == mouse.RIGHT），计算face_pos外侧一格的位置（即block_pos[0]+face_pos[0], ...），调用world.set_block(new_pos, self.block_to_place)放置新方块。

整个过程没有异步、没有回调地狱、没有事件总线，就是线性执行：鼠标按→算向量→射线检测→改数据→重绘。孩子打断点跟踪block_pos值的变化，能亲眼看到“我瞄准石头，它告诉我坐标(3,2,5)，我往(3,2,6)放木头”，这种因果链的清晰度，是任何框架文档都无法替代的教学资产。

4. 实操全流程：从零开始运行、调试到二次开发的每一步

现在我们动手。假设你是一个完全没碰过Python图形编程的家长，或者一个刚学完if/else的初中生，我带你走一遍真实操作流。所有步骤基于main.py原始代码，不依赖任何额外工具。

4.1 运行前准备：三步确认，杜绝90%的报错

第一步：确认Python版本
打开终端（macOS/Linux）或命令提示符（Windows），输入：

python --version

必须显示Python 3.8.0或更高。如果显示2.7或报错“不是内部命令”，请先去python.org下载安装最新版Python（勾选“Add Python to PATH”）。这是唯一必须的前置条件。

第二步：安装Pyglet
在同一终端窗口，执行：

pip install pyglet

等待出现Successfully installed pyglet-x.x.x。如果卡在Building wheel for pyopengl...，说明你误装了PyOpenGL——Pyglet不需要它！直接按Ctrl+C中断，然后执行：

pip uninstall pyopengl pip install pyglet

Pyglet自带OpenGL绑定，额外装PyOpenGL反而冲突。

第三步：检查文件完整性
确保你的项目文件夹里有且仅有以下文件（大小可忽略，关键是存在）：
-main.py（主程序，约480行）
-texture.png（64×64像素，打开能看到6种方块贴图）
-README.md（操作指南）

如果texture.png缺失，程序会启动但显示黑方块——因为贴图加载失败返回空纹理。此时不要慌，用系统画图工具新建一个64×64白底图片，保存为texture.png，就能看到白色方块了（证明渲染逻辑正常）。

注意：不要双击main.py在文本编辑器里打开！要右键→“使用Python运行”，或在终端里cd到该目录后执行python main.py。很多孩子第一次失败是因为双击打开了代码，而不是运行它。

4.2 首次运行与基础操作：5分钟建立掌控感

执行python main.py，你会看到一个黑色窗口弹出，几秒后出现绿色草地和灰色石头——成功了！此时：
-移动：按住W向前，S向后，A向左，D向右。注意不是“角色移动”，是“相机移动”，所以按W时世界向你扑来，这是3D第一人称的正确感觉。
-视角：按住鼠标左键不放，拖动鼠标——世界随之旋转。向右拖，视角转向右边；向上拖，抬头看天空。这是on_mouse_drag在实时更新self.rotation。
-瞄准与破坏：把鼠标移到一块石头上，单击左键——石头消失！hit_test找到了它，set_block把它设为AIR，下一帧渲染时该位置不再绘制。
-放置方块：按数字键1切换到草方块（屏幕右上角会显示Block: grass），把鼠标移到石头旁边空白处，单击右键——一块绿草方块凭空出现！hit_test返回了石头表面坐标，代码自动计算外侧一格，set_block把它设为草。

实操心得：第一次操作时，孩子常犯两个错误。一是鼠标移动太快，导致视角疯狂旋转——这是因为MOUSE_SENSITIVITY = 0.005太敏感。让他打开main.py，把这行改成0.002，保存后Ctrl+R重启，立刻变稳。二是右键放不出方块，其实是鼠标没对准“空白面”，而是悬停在空气里。提醒他：“右键要放在已有方块的表面上，就像往墙上钉钉子，钉子得有墙可钉”。

4.3 参数调试实战：改三行代码，创造新世界

现在进入“边学边调”环节。打开main.py，找到开头的常量区（第15-30行左右）：

# ======== 可调节参数区 ======== WORLD_WIDTH = 16 # 世界X轴宽度（格数） WORLD_HEIGHT = 16 # Y轴高度 WORLD_DEPTH = 16 # Z轴深度 MOUSE_SENSITIVITY = 0.005 # 鼠标拖拽灵敏度 DEFAULT_BLOCK = GRASS # 默认放置方块 # ===========================

实验一：扩大世界
把WORLD_WIDTH = 16改成32，保存，Ctrl+R重启。世界瞬间变大一倍！但注意：内存占用从4096格升到32768格（32³），老电脑可能轻微卡顿。这时可以教孩子“内存和性能的权衡”——为什么手机游戏世界比PC小？因为内存有限。顺便提一句：WORLD_WIDTH必须是偶数，否则[-WORLD_WIDTH//2, WORLD_WIDTH//2)范围会不对称，这是个隐藏的编程细节。

实验二：更换默认方块
把DEFAULT_BLOCK = GRASS改成DEFAULT_BLOCK = WOOD，保存重启。一开局，手里拿的就是木头方块！再按2键，发现切换到了土方块——因为block_types字典里'dirt': 2，数字键2对应土。让孩子自己找texture.png里木头在哪一行，然后改DEFAULT_BLOCK = LEAVES，试试树叶方块。

实验三：调整视角限制
找到get_sight_vector()函数里的rot_y = max(-89, min(89, rot_y))，把89改成45。保存重启，你会发现抬头只能看到45°，再也看不到头顶天空了。问孩子：“为什么不能设成90？如果设成90，math.sin(math.radians(90))等于多少？会导致什么问题？”——自然引出“除零错误”和“数值稳定性”概念。

4.4 二次开发入门：添加新方块、新功能的最小改动

项目预留了API化接口，现在我们做两个真实扩展，全程不超过10行代码：

添加“玻璃”方块
1. 在block_types字典末尾加一行：'glass': 6
2. 在texture.png里，用画图工具在第六行画一个半透明蓝色方块（或直接填满蓝色）
3. 在main.py开头，找到GRASS = 1那一段，加一行：GLASS = 6
4. 在数字键处理逻辑里（on_key_press函数），找到elif symbol == key._2:那段，复制粘贴，把_2改成_3，DIRT改成GLASS
5. 保存重启，按3键就能切换玻璃方块！

添加“跳跃”功能
1. 在Player类的__init__里，加一行：self.velocity_y = 0（初始Y方向速度）
2. 在update()方法里（玩家状态更新），加一段重力逻辑：
python # 重力：每帧向下加速 self.velocity_y -= 0.05 # 地面碰撞检测（简单版：Y<0时停止下落） if self.position[1] <= 0: self.velocity_y = 0 self.position = (self.position[0], 0, self.position[2]) # 应用速度 self.position = ( self.position[0], self.position[1] + self.velocity_y, self.position[2] )
3. 在on_key_press里，加elif symbol == key.SPACE:，设置self.velocity_y = 0.5（向上跳）
4. 保存重启，按空格键就能跳起来了！

注意事项：跳跃代码里self.velocity_y -= 0.05的0.05是重力加速度，改成0.01就变成月球跳跃，改成0.1就变成超级英雄——这就是物理参数的魔力。但要提醒孩子：self.position[1] <= 0只是简易地面检测，真实项目要用射线检测下方是否有方块，否则会穿模。不过作为入门，够用了。

5. 常见问题与排查技巧：那些年我们踩过的坑

在上百次教学实践中，这些问题出现频率最高。我把它们整理成“问题-现象-原因-解决”四栏表，并附上独家排查口诀。记住：所有问题都有迹可循，没有玄学报错。

除了表格，还有三条血泪经验：

1. “Ctrl+C永远是你最好的朋友”：当程序卡死（如无限循环），不要关窗口，直接在终端按Ctrl+C，Pyglet会优雅退出并打印最后一行报错。很多孩子习惯狂点关闭按钮，结果进程残留，下次运行报端口占用——其实Ctrl+C就能干净退出。

2. “print是初级调试神器，logging是进阶武器”：不要怕在关键位置加print(f"x={x}, y={y}, z={z}")。比如在set_block开头加print(f"Setting block at {position} to {block_id}")，能立刻看到“我点右键时，程序确实收到了指令”。等孩子熟悉后，再教他用import logging; logging.basicConfig(level=logging.INFO)替换print。

3. “备份再修改，改一行，测一次”：强烈建议孩子养成习惯：每次改代码前，把main.py复制一份叫main_v2.py。改完一行，保存，Ctrl+R测试。如果崩了，双击main_v1.py秒回。我见过太多孩子激情修改20行，结果全崩，最后哭着问我“能不能恢复昨天的版本”——而答案永远是“有备份吗？”。

最后分享一个真实案例：有个12岁男孩想加“火把”方块，折腾一小时没成功。我让他打开texture.png，问他：“火把应该长什么样？”他说“黄色细长条”。我让他用画图工具在第七行画一个黄色竖条，保存。然后教他照着GLASS的例子加TORCH = 7，改数字键4。他完成后兴奋地喊：“老师，火把会发光！”——其实没发光，只是黄色而已。但那一刻，他理解了“贴图→ID→代码→显示”的完整链条。这比学会一百个语法点更有价值。

6. 教学延伸与能力跃迁：从方块世界到真实项目的思维升级

这个小样例的价值，远不止于“能放方块”。它是一块跳板，帮孩子完成从“语法消费者”到“系统构建者”的思维跃迁。下面我列出三条清晰路径，每条都对应真实项目能力，且都能用现有代码基座平滑升级。

6.1 路径一：从静态世界到动态系统——加入重力与物理

当前世界是静态的：方块放上去就固定不动。但孩子很快会问：“为什么沙子不往下掉？”“为什么水不流动？”这就是引入物理引擎的契机。不需要重写，只需在World类里加一个update_physics()方法：

def update_physics(self): # 简单沙子下落：遍历每一列，检查上方是否有空气 for x in range(-8, 8): for z in range(-8, 8): # 从顶部开始扫描 for y in range(15, 0, -1): # y从15降到1 if self.world[x][y][z] == SAND and self.world[x][y-1][z] == AIR: # 把沙子移到下方 self.world[x][y][z] = AIR self.world[x][y-1][z] = SAND break # 本次下落结束，跳出y循环

把这个方法挂到主循环的update()里（每帧调用一次）。孩子立刻看到沙子像雨一样簌簌落下。这时可以讨论：“为什么从顶部扫描？如果从底部扫描会怎样？”——引出“迭代顺序影响结果”的经典算法思想。再进一步，把SAND换成WATER，加一条“水往低处流”的规则（检查四周更低的格子），他就亲手实现了简易流体模拟。这不再是“调用API”，而是“设计规则”。

6.2 路径二：从单机世界到多人协作——用Socket实现双人联机

孩子玩熟后，自然想“和朋友一起建城堡”。这时引入网络编程。Pyglet本身不处理网络，但Python标准库socket足够轻量。核心思路：一台电脑当服务器（server.py），另一台当客户端（client.py），通过TCP同步世界状态。

服务器只需监听连接，接收客户端发来的{"action":"place","pos":[3,2,5],"block":4}，然后广播给所有客户端。客户端在on_key_press里，不直接调用world.set_block()，而是send(socket, {"action":"place", ...})。main.py里加一个network_thread后台线程接收消息，收到后调用本地world.set_block()。整个过程，孩子只新增约50行代码，却第一次触摸到“分布式系统”概念——数据一致性、网络延迟、消息序列化。而这一切，都建立在他亲手写过的world[x][y][z]之上。

6.3 路径三：从Python脚本到可执行程序——打包发布给同学

当孩子做出满意的作品，他会想“发给同学玩”。这时教他用PyInstaller打包：

pip install pyinstaller pyinstaller --onefile --windowed --icon=icon.ico main.py

生成的dist/main.exe（Windows）或dist/main（macOS）可以直接双击运行，无需安装Python。过程中会遇到“找不到texture.png”的问题——因为PyInstaller把资源打进exe，路径变了。这时教他用sys._MEIPASS获取临时解压路径：

import sys import os def resource_path(relative_path): """获取资源绝对路径，兼容PyInstaller打包""" if getattr(sys, 'frozen', False): base_path = sys._MEIPASS else: base_path = os.path.abspath(".") return os.path.join(base_path, relative_path) # 使用 texture = pyglet.image.load(resource_path('texture.png'))

这短短10行代码，教会孩子“程序运行时环境”和“资源定位”的真实复杂性。当他把打包好的exe发给同学，看到对方电脑上顺利运行出自己的方块世界时，那种成就感，是任何考试分数都无法比拟的。

最后分享一个小技巧：鼓励孩子给README.md写中文版操作指南，配上自己截图的GIF动图（用系统录屏工具即可）。这不仅是技术输出，更是沟通能力训练——他得思考“同学第一次打开，最需要知道什么？”“哪一步最容易卡住？”“怎么用最少文字说清？”这种以用户为中心的思维，正是工程师的核心素养。而这一切，都始于那个5分钟就能跑起来的、轻如鸿毛的Pyglet方块世界。

本文还有配套的精品资源，点击获取

简介：用纯Python写的迷你方块世界演示程序，不装OpenGL、不编译C扩展、不连数据库，只要pip install pyglet就能直接运行。主逻辑集中在main.py里，配合一张texture.png贴图和清晰注释，把3D视角控制、WASD移动、鼠标瞄准、左右键破坏/放置方块、数字键切换方块类型这些功能全打包进不到500行代码里。世界尺寸、默认方块、鼠标灵敏度等参数都写在开头常量区，改完保存就能立刻看到效果，特别适合边学边调。配套README写明了每步操作：怎么装依赖、怎么启动、怎么走动、怎么放方块，连新手家长都能照着带孩子试。整个项目按教学逻辑组织，World类封装了方块存取，set_block这类方法命名已贴近未来可复用的教学API，但当前仍保持单文件轻量结构，方便逐行理解渲染循环和事件响应机制。

本文还有配套的精品资源，点击获取