西风逍遥游
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.
Fluid3D Lab（3D 体积流体实验室）
交互式 3D 体积流体 / 颗粒实验室：一个可运行项目里覆盖 19 个场景模式（mode 0–18），
外加 70 多个 opt-in 数值验收脚本。窗口标题 EVEngine | Fluid3D Lab，启动后默认暂停。
演示的能力：体积流体求解器（SPH 类）的材质 / 相态、表面重建与各向异性、颗粒发射器与 生命周期、碰撞体与接触抓取、热耦合、泡沫池、移动 SDF 障碍、重叠查询、网格化输出， 以及相机与渲染设置（折射 / 反射 / 粒子 impostor / 正交相机）等。
运行
cd examples/fluid3d
../../build/linux-debug/src/engine/eve run
或从仓库根目录：
make run/<platform>-debug GAME=examples/fluid3d # <platform> = win32 / linux / macosx
操作
| 按键 | 作用 |
|---|---|
Space |
暂停 / 继续（启动时是暂停状态） |
R |
按当前模式重建场景 |
1–9 |
Water / Viscous / Smoke / Granular / Jet / Mesh / Moving / Multiphase / Wheel |
0 |
Mixing（左侧加热、右侧冷却，颜色跟随黏度） |
T |
Thermal（热耦合与热色） |
S |
Solid attachment（固体附着，跟随运动碰撞体） |
F |
Foam（泡沫池与合成耗时） |
D |
SDF（只做变换更新的移动 SDF 障碍） |
Q |
Query（重叠触发器，红 / 黄计数） |
M |
Maze（迷宫；模式内用 A / D 调角速度） |
B |
Bucket（水桶） |
W |
Bottle（威士忌瓶；按住 D 倾倒） |
K |
Wake（卡门涡街尾流） |
HUD 会实时打印粒子数、掉帧丢弃的秒数以及 Sim / Surface / Upload 三个阶段的耗时；
求解失败时窗口内显示错误提示，控制台打印 VOLUME_FLUID_STOPPED: <原因>。
文件
| 路径 | 说明 |
|---|---|
main.nut |
入口：模式注册、按键分发、每帧求解与表面上传 |
config.nut |
引擎 config：960×720、hotReload = true |
maze-support.nut |
迷宫模式的几何与状态 |
bucket-support.nut |
水桶模式 |
bottle-support.nut |
威士忌瓶模式（姿态更新的 SDF） |
karman-support.nut |
卡门涡街尾流模式 |
wave-support.nut |
波浪发生器 |
*-check.nut |
opt-in 数值验收脚本（见下） |
assets/ |
OBJ 网格（发射环、酒瓶等） |
fonts/ |
DejaVuSans-Bold.ttf 与授权说明 |
eve_snapshot.json |
示例快照 |
opt-in 数值验收脚本
*-check.nut 都是可选探针，不会被 main.nut 自动加载；在运行中的示例里按需加载并
调用对应函数，例如：
dofile("thermal-check.nut"); verifyVolumeFluidThermalContact();
dofile("soak-check.nut"); beginVolumeFluidSoak();
它们用固定的步数与数值容差验证求解结果（粒子数、位移下限、表面能量等），失败时直接
throw。完整的脚本清单、每个探针覆盖的 API 与判定条件见
docs/usr/fluid3d.md。
契约
本示例是可运行示例（main.nut + config.nut），参与 scripts/smoke_examples.sh 的
帧循环契约：CI 在 Linux 上无头启动它，要求至少 2 秒仍然存活且日志中没有错误标记。