能力边界
本文说明「3D 编程闯关」的代码解释器支持哪些语法、有哪些安全护栏，以及通关判定能验证与不能验证什么。
1. 解释器是什么
闯关页执行的是平台自研的轻量 Python 子集解释器（纯浏览器端运行，不使用 eval），它支持常见的入门语法，但不是完整的 Python。
2. 支持的语法
语句
- 变量赋值（含
+=、-=等复合赋值） - 表达式语句（如函数调用）
- 条件：
if/elif/else - 循环：
while、for ... in range(...) - 函数定义：
def、return break、continue、pass
表达式
- 数字、字符串、布尔值（
True/False）、None - 列表、下标取值（
lst[i]）、属性访问（obj.method） - 函数调用、一元运算（
-/not） - 二元运算：
+-*/%//** - 比较运算：
<<=>>===!= - 逻辑运算：
and/or/not
内置函数
| 函数 | 说明 |
|---|---|
print(...) |
输出到「运行结果」面板 |
get_object('id') |
获取 3D 物体对象（等价于直接用变量名） |
wait(秒) |
暂停一段时间（可配合速度调节做动画演示） |
str / int / float |
类型转换 |
len(...) |
字符串或列表长度 |
range(n) / range(a, b) / range(a, b, step) |
生成整数序列 |
3D 物体方法
move(dx, dy, dz)、move_to(x, y, z)rotate(axis, deg)（axis 取'x'/'y'/'z'）set_color('#rrggbb')get_position()（返回[x, y, z]）
3. 不支持的语法
import/ 第三方库、文件与网络操作- 类与对象定义（
class）、装饰器、上下文管理器（with） - 字典 / 集合、异常处理（
try/except）、三元表达式 - 字典推导、生成器、lambda 等高级特性
提示：如果用了不支持的语法，页面会给出带行号的中文错误提示，请按提示改用上面的语法子集。
4. 安全护栏
为了让学生即使写出死循环也不会卡死浏览器，解释器内置了多重护栏：
| 护栏 | 默认上限 | 触发后 |
|---|---|---|
| 最大执行步数 | 20000 步 | 自动停止并提示「执行步数超限」 |
| 最大墙钟时长 | 10 秒 | 自动停止并提示「执行超时」 |
| 单个循环最大迭代次数 | 5000 次 | 自动停止并提示「循环迭代次数超限」 |
| 函数递归深度 | 200 层 | 抛出中文错误 |
此外还会在长时间运行时主动让出浏览器事件循环，因此 while True 也不会把页面卡死，且随时可以「暂停 / 停止」。
提示：程序执行是可中断、可单步、可调速的；所有报错都是可读的中文提示，而不是浏览器崩溃。
5. 判定能验证什么
判定基于程序结束时的场景快照（各物体的位置、旋转、颜色、数量等），支持五类条件：
- 位置：物体的三维坐标与目标点的距离是否在容差内。
- 旋转：物体绕指定轴的欧拉角是否接近目标角度（考虑 360° 环绕）。
- 颜色：物体颜色与目标颜色的逐通道差值是否在容差内。
- 碰撞：两个物体中心距离是否小于「半径之和 ×(1+容差)」。
- 数量：场景中（全部或仅动态）物体数量是否达到目标数量。
条件可用 AND（全部满足）或 OR（满足任一）组合。
6. 判定不能验证什么
- 不检查代码写法：只看最终场景状态，循环还是展开、用积木还是代码，只要结果达标即通关。
- 不检查过程：判定发生在运行结束时，无法验证「中途必须经过某点 / 顺序」这类过程性要求（如需此类关卡，请拆成多关或用
count等间接约束）。 - 不做精确几何碰撞：碰撞条件用包围球半径近似，不适合判断复杂形状的精细贴合。
- 不校验性能与代码质量：护栏只防止死循环、超时等失控情况，不评价算法效率或代码风格。
7. 物理与模型的边界
- 物理：关卡可在
scene_json中开启物理（引擎为 cannon-es）。动态物体会受重力下落并与静态物体碰撞，刚体形状为盒体或球体（根据图元推导）；暂不支持关节、约束、布料等复杂物理。 - 物理关卡请等物体稳定后再判定；判定读取的是物理同步后的真实位置。
- 外部模型：引擎不支持外部 GLB / GLTF 模型加载——场景元素一律由内置图元（立方体 / 球体 / 圆柱 / 圆锥 / 平面）程序化拼装，不依赖外部素材文件。如需手绘 / 定制素材，走
sprite图集通道：主题变体声明atlas/size/anchor/frame/fallbackShape，图集缺失或加载失败时自动回退程序化造型，不影响关卡游玩。