西风逍遥游
31880f0021
`examples/<name>/` was a tested surface in name only. The source-quality job had no examples check at all, and scripts/smoke_examples.sh accepted any process that had not printed one of its error markers: a project that died during startup, exited after a single frame, or crashed without a marker was reported as PASS. Nothing stopped a malformed or unregistered example from reaching dev, which is how 14 examples arrived without READMEs and 20 were never registered in the overview table. Source side - scripts/check_examples.py classifies every directory under examples/ as either runnable (main.nut plus a config.nut that assigns the engine `config` table) or as a reviewed non-runnable sample listed in NON_RUNNABLE_EXAMPLES with a reason. Both kinds must own a README.md and appear in examples/README.md. Stale exemptions and overview links to missing directories fail as well. - `make check/examples` and a new source-quality CI step run the gate. - scripts/tests/test_check_examples.py covers it and pins each failure mode against fixtures. Runtime side - scripts/smoke_examples.sh now enforces liveness, not just marker absence: every runnable example must still be running after MIN_RUN_SECONDS (default 2s; CI passes 2s), and a process that dies inside that window fails whatever its exit code. A clean self-exit after the window passes with an explicit note instead of being silently accepted as a pass. - The Linux CI step sets MIN_RUN_SECONDS=2 and keeps RUN_SECONDS=6, so the job's wall clock is unchanged (13.7 min of its 20 min budget on dev). Windows / GBK - scripts/utf8_stdio.py re-encodes stdout/stderr as UTF-8 and every scripts/*.py program calls it as the first statement of its __main__ block. On a Chinese Windows a redirected stream falls back to the ANSI code page (cp936), and printing a character that code page cannot encode (arrows, superscripts, bullet separators, emoji - all common in this repository) raised UnicodeEncodeError and turned a checker into a traceback. - The mirror image is input: read_text() without encoding= decoded UTF-8 repository text as cp936 and raised UnicodeDecodeError. - scripts/tests/test_utf8_stdio.py enforces both conventions for every script and test module; text file I/O and child-process decoding now pass encoding="utf-8" explicitly. - Unit-test invocations run with `python3 -X utf8` so the runner's own output never follows the host code page. Violations the new gates found on top of dev, fixed here: 14 examples shipped without a README (fluid3d, mesh-impact-lab, mesh-modifier-lab, spline-tube-lab on the earlier dev tip, plus pcg-depth-of-field, pcg-detail-overwrite, pcg-layer-culling, pcg-location-system, pcg-runtime-orchestration, pcg-scene-player-culling, pcg-snow-wind, pcg-thunder-strike, pcg-ui-scaler and pcg-underwater added by #397), 20 were missing from the overview table (those 14 plus archspace-editor, geometry-stroke-lab, interior-mapping, layered-animation, triplanar-decal, terrain-stamping), and scripts/export_meshret_onnx.py had no UTF-8 stdio guard. Verified locally: `python -m ruff check scripts` (All checks passed); scripts/check_test_manifest.py; scripts/check_quality_metadata.py; scripts/check_architecture_contracts.py --base HEAD; scripts/check_nodiscard.py; `make -n check/examples`; scripts/check_examples.py (125 examples: 118 runnable, 7 reviewed non-runnable); and `python -X utf8 -m unittest discover -s scripts/tests -p "test_*.py"` (155 tests, OK). The runtime half of the contract needs a Linux headless build, so it is verified by the CI examples smoke step rather than locally.
Mesh Modifier Lab（网格修饰图实验室）
把同一份源网格（prototype.cylinder1 圆柱，高 4.0、细分 32）用 13 种不同方式变形后
并排渲染，用来对比“类型化修饰图（MeshModifierGraph）”“可交互形变会话
（MeshDeformationSession）”和“程序化变形节点”三条路径的覆盖面与结果。没有输入，
启动即静态展示，适合当作 API 对照表逐个查。
运行
cd examples/mesh-modifier-lab
../../build/linux-debug/src/engine/eve run
或：
make run/<platform>-debug GAME=examples/mesh-modifier-lab
13 个变体
| 变体 | 用的节点 / API |
|---|---|
| 源网格 | mesh.input（未变形基准） |
| Bend + Twist | deform.bend（Y 轴 28°）→ deform.twist（Y 轴 150°） |
| Noise + Spherify | deform.noise（幅度 0.28、seed 17）→ deform.spherify |
| FFD | deform.ffd（自由变形控制点） |
| Cut Plane | mesh.cutPlane（沿 Y 切平并封盖） |
| Spline Path | mesh.subdivide → deform.splinePath（Catmull-Rom 路径，按弧长缩放截面） |
| Sculpt | MeshDeformationSession：inflate 笔刷 + 方向笔刷 + 塑性冲击 |
| Effector | deform.effector（两点密度场） |
| Interactive Surface | applySurfaceContact + recoverSurface，以及 configureColliderRefresh / updateColliderRefresh / requestColliderRefresh 的 interval 与 manual 两种碰撞体替换路径 |
| Slime | applySlimeImpulse + stepSlime（弹簧-阻尼回弹） |
| Mesh Fit | deform.transform 作为目标面 → deform.meshFit 双向贴合 |
| Vertex Editor | selectVerticesBox → moveSelectedVertices / manipulateSelectedVertices |
| Sound React | deform.soundReact（电平 / 阈值 / 频率驱动变形） |
图编译同时验证了融合优化：控制台会打印编译后的段数与融合的操作数
（getCompiledSegmentCount() / getFusedOperationCount()）。
成功标记：
- 控制台打印
MESH_MODIFIER_LAB_PASS variants=13 ... - 当前目录写出
mesh-modifier-lab.png
文件
| 路径 | 说明 |
|---|---|
main.nut |
全部逻辑：源网格、13 个变体、相机、截图 |
config.nut |
引擎 config：1280×720、hotReload = true |
mesh-modifier-lab.png |
期望产出的画面（示例自带参考图） |
契约
本示例是可运行示例（main.nut + config.nut），参与 scripts/smoke_examples.sh 的
帧循环契约：CI 在 Linux 上无头启动它，要求至少 2 秒仍然存活且日志中没有错误标记。