← 都来码 / Dolaima← 例程索引README.md 原文

README.md · 24745 字节 · 下载原文

# 示例与游戏合集

手机 App 启动时会把这些示例解包到 **`<工作区>/examples/<语言>/`**
(`MauiBootstrap.EnsureExamples`),在「文件」页点开就能编译运行:

```bash
vml run examples/c/tetris.c        # 各语言各自一个目录:c/ python/ basic/ csharp/ java/ …
```

**目录就是语言**:`examples/` 下每个子目录是一种语言,目录里放该语言的示例 ——
从前是平铺的(十来种语言堆在一个目录里,只能靠文件名猜语言),v0.96.184 起按语言分开。

## 分类

每种语言目录下**再按用途分一层**(2026-10-02 整理)—— 从前所有示例平铺在
`examples/<语言>/` 里,几十个文件混着演示、自检与游戏,找东西只能靠文件名猜:

| 子目录 | 放什么 | 例 |
|---|---|---|
| `demo/` | **标准输出**示例(各语言的"hello 级别") | `examples/c/demo/demo_std.c` |
| `test/` | **接口自检**:跑了要能判断对错的那种(不是演示) | `examples/c/test/sysinfo.c`、`catch.*`、`bench.*` |
| `ui/` | **宿主 UI**(`ui_*`)示例 | `examples/c/ui/demo_ui.c`、`draw_*.c` |
| `tty/` | **ANSI 终端**示例(光标/颜色/清屏) | `examples/c/tty/demo_tty.c`、`conio_*`、`curses_*` |
| `bgi/` | **BGI 图形**(老程序那套 `graphics.h`) | `examples/c/bgi/demo_bgi.c` |
| `3d/` | **3D**(`ui_3d_*`,号段 600–634) | `examples/c/3d/solar3d.c`、`g3_all.c`、各语言 `3d/demo_3d.*` |
| `app/` | **能玩的程序**(游戏与工具) | `examples/c/app/tetris.c`、`gorilla.*` |
| (语言目录根) | 说明书 / 许可证 / 构建脚本 | `CREDITS.md`、`LICENSES.txt`、`c/c.bat` |

**已有的语料目录原地不动**(`cpp/stm32/`、`c/old/`、`basic/freebasic/` 这类是"整块第三方素材",
不是按用途分的类;`pascal/swag_*` 那一批老程序语料也**保持在语言目录根**,
因为打包脚本的排除正则就是按 `Examples/pascal/<前缀>` 写的)。

⚠ 打包(`scripts/make-vml-lib.sh`)**收 1~3 层**,所以多这一层分类目录**自动进包** ✓;
手机上 `MauiBootstrap.EnsureExamples()` 按 zip 条目**保留目录结构**解包 ✓。

## 每门语言的最小示例(2026-10-26)

27 门前端统一按 **std / tty / bgi / ui2d / ui3d** 五层各放一个最小示例
(文件名固定 `demo/demo_std.*`、`tty/demo_tty.*`、`bgi/demo_bgi.*`、`ui/demo_ui.*`、`3d/demo_3d.*`),
已经有同名的就跳过。3D 示例同目录带一份 `box.glb`(**CC0**,复制自 `c/3d/models/BoxVertexColors.glb`)。

| 层 | 覆盖 | 说明 |
|---|---|---|
| std | 27/27 | — |
| tty | 27/27 | — |
| ui2d | 27/27 | — |
| bgi | 27/27 | 实测每门至少画出一组彩色图元(`--frames` 非背景像素 0.43%–99.69%) |
| ui3d | 27/27 | 实测每门都载入 `box.glb` 并渲染出立方体(非背景像素 9.3%–27%) |

⚠ **这五层起初是 bgi 24/27、ui3d 20/27,缺口全部出在「声明文件」而不是示例**(2026-10-26 已全部补掉,
修复落在 GenLib 与链接配置侧):

- **Ada**:原本没有 `vml3d.adb` / `bgi.adb` / `vmlsys.adb`(`vml_alloc` 在里面)⇒ `genlib -u` 生成;
  同时把 `LangSpecs` 里 Ada 的 `RefForm` 从写死的 `"with VML_UI;"` 改成 `"with {lib};"`
  (否则每个库的声明文件头部都写 `VML_UI`,`vml3d` 的声明看起来"没被引用")。
- **PHP**:`bgi.php` / `vmlsys.php` / `vml3d.php` 不存在 ⇒ 生成;PHP 走**逐文件编译**、不适用
  `AutoDetectSharedLibs` ⇒ `vmltool.config.xml` 的 PHP `Libs=` 里必须补上 `bgi.vml`。
- **Forth**:`bgi.fth`(声明)与 `bgi.vml`(`forth_*` 包装)不存在 ⇒ `modules.json` 里先补 `bgi` 模块,
  再 `genlib -m -l forth` / `genlib -u -c bgi`;示例里还要 `#param lib("bgi.vml")`(Forth 不自动链库)。
- **D / Rust / Swift / R / Scheme**:`Lib/<lang>/vml3d.*` 是**带函数体的旧声明**(`{ return 0 }`),
  而链接器对重名裸标签是「后链的赢」⇒ 程序里那份空壳把库实现顶掉 ⇒ `ui_3d_viewport_create` **恒返回 0**。
  已用 `genlib -u -c vml3d` 重生成(DocTable:只有注释、无函数体)。⚠ 早前把这一格归因成
  "5 参 wrapper 返回 0"是**错的**——同一个 5 参调用在 C 里一直正常;判据要查**链接结果里那个名字的实体**(E210/E215)。

⚠ **编译过 ≠ 画面对**:3D 的几何量是 `float`(4 字节)形参。Ruby/Lua/Dart/PHP/Perl 等前端按
8 字节 double 压栈(或整值浮点按整数压),直接写 `0.0` 会让参数整体错位 ⇒ **空白场景**。
这些语言的最小示例统一传 **float32 位模式整数**;C/C++/C#/Java/Kotlin/D 用 `f`/`f32` 后缀。
新增 3D 示例时**必须真跑一次看画面**(`--frames` + 读一帧像素),不能只看"编译完成"。

⚠ BGI 的 `initgraph(gd, gm, path)` 前两个实参是 `int*`:没有取地址符的前端用 `vml_alloc`
拿地址(`gd` 与 `gd + 4` 两格),Forth 用 `VARIABLE` 的地址。画完要先 `ui_2d_present()` 再
`closegraph()`,否则桌面 `--frames` 导出 0 帧(手机上同样可能是黑屏)。

## 接口验收程序(C)

`ui_all.c` / `ui_input.c` 是 **C 语言 UI 接口的逐条验收**(3D 那边对应 `3d/g3_all.c`)。
它们不是演示:每条接口都必须留下**能分辨"生效 / 没生效"的证据**(返回值语义、像素读回前后对比、
`REVERSE:` 反证),末尾打 `OK= FAIL= UNIMPL=` 汇总。

| 文件 | 覆盖 | 跑法 |
|---|---|---|
| `ui/ui_all.c` | 2D 图元 / 像素读回 / 裁剪·透明·图层·蒙版 / 画刷渐变 / 文字 / 图像图块 / 洪水填充 / 截图 / 存储·剪贴板·错误槽 / JSON 通道 / 音频 / 传感器电池定位契约 | `vml run examples/c/ui/ui_all.c` |
| `ui/ui_input.c` | 消息队列 / 键盘触摸轮询 / 定时器 / msg_drop·keep·clear / 四类对话框 / 文件·相机选择器 / 注入的传感器·电量·定位 / resize·orient·close | 手机:`vml run examples/c/ui/ui_input.c`(交互档,屏上显示事件);桌面:见下 |

桌面自动化(与手机同一条编译+运行流水线):

```bash
dotnet scripts/vmlcli/bin/Release/net10.0/vmlcli.dll \
       third_party/vml/Examples/c/ui/ui_all.c --screen 480x640 --timeout 120

scripts/vml-ui-api-probe.sh          # 两个程序 + 反证(注入一条必败断言,判据必须变红)
```

实测基线(2026-10-26,`--screen 480x640`):`ui_all` **OK=158 FAIL=0 UNIMPL=3 NUMS=43**
(`UNIMPL` = 桌面没有传感器/电池/GPS,**不是失败**);`ui_input` **OK=52 FAIL=0**。

⚠ 两条容易踩的接线:`ui_2d_get_pixel` 回 **0xRRGGBB**,而 `ui_2d_flood_fill` 的边界色要
**0xAARRGGBB**(传 `0x008000` 会整屏被灌满,实测);`ui_touch_fetch` 是**刷新缓存**,
必须单独一个语句调用(塞进 `printf` 实参会因「从右到左求值」读到上一拍的值)。

## 游戏

| 文件 | 说明 | 操作 |
|---|---|---|
**屏幕范围**:`app/` 下的例程统一按 **240×240 ~ 1920×1080(竖屏 1080×1920)** 适配(布局每帧按画布现算;判据 `scripts/vml-app-size-sweep.py`)。

| `c/gomoku.c` | **五子棋**(人机对战)。最后一手有记号,结束点任意处再来一局。 | 点棋盘落子 |
| `c/unitconv.c` | **单位换算**。长度/重量/温度三类,整数定点换算(百万分之一精度),结果列成一页;全整数、不依赖浮点库 | 选类别/输入单位 · `-10/-1/+1/+10` 调值 |
| `c/linkgame.c` | **连连看**。6×6 图案,**≤2 折连通**(直连 / 一拐角 / 两拐角三段路线),可走棋盘外框;提示、重排、无解自动重排 | 点两张相同图案消掉 · 底部「提示/重排/新局」 |
| `c/expense.c` | **记账本**。四个分类 + 步进金额 + 流水(最新在上)+ 合计;全整数、不依赖输入法 | 选分类 · 调金额 · 「记一笔」/「清零」 |
| `c/typing.c` | **打字练习**。内置单词 + 屏幕 QWERTY 键盘(无物理键盘也能练),正确率/速度实时统计 | 按字母键或点屏幕键盘 |
| `c/baseconv.c` | **进制转换**。十进制 0~65535 → HEX / 16 位 BIN / OCT,底部小键盘输入 | 数字键 · `<` 退位 · `C` 清零 |
| `c/password.c` | **密码生成器**。8/12/16/24 长度、大写/数字/符号开关,每类保底一个再洗牌 | 选长度/开关 · 「生成」/「复制」 |
| `c/cat.c` | **减压猫咪**。摸摸冒爱心呼噜、喂鱼、玩球、睡觉(Zzz);无失败态,纯放松 | 点猫 · 底部「喂鱼/玩球/睡觉」 |
| `c/dog.c` | **减压小狗**。摇尾巴、垂耳吐舌,摸摸/喂骨头/玩球/睡觉 | 点狗 · 底部「喂骨头/玩球/睡觉」 |
| `c/fish.c` | **鱼缸**。三条鱼游动、水草气泡,点鱼摸一下;喂食会聚过来、可关灯/换水 | 点鱼/点水喂食 · 底部「喂食/关灯/换水」 |
| `c/bird.c` | **小鸟**。站在树枝上扇翅,点它唱歌冒音符,喂食/唱歌/睡觉 | 点鸟 · 底部「喂食/唱歌/睡觉」 |
| `c/mathquiz.c` | **口算练习**。60 秒加减乘挑战,屏幕小键盘输入,答对换题、答错显示答案 | 数字键 · `<` 退位 · `OK` 提交 |
| `c/metronome.c` | **节拍器**。40~220 BPM、4/4 重拍、摆锤动画;墙钟排程,不靠定时消息精度 | `-10/-1/+1/+10` · 「开始/停止」 · 「点拍」测速 |
| `c/colorlab.c` | **颜色工具**。RGB 三通道调色、HEX/RGB 实时显示、6 个预设;点预览区复制 HEX | 通道 ±1/±10 · 点预设 · 点预览复制 |
| `c/tetris.c` | **俄罗斯方块**。消行计分升级、下一块预览、长按方向键连发。 | 方向键移动 · `旋转` · `直落` · `暂停`/`重开` |
| `swift/plane.swift` | **飞机空战**(Swift)。自动开火、横向跑位拦敌机,**漏 3 架结束**(右上角三条命)| 方向键移动 · `SELECT` 暂停 · `回车` 重开 |
| `csharp/racer.cs` | **赛车**(C#)。三车道向下滚,躲开红车,躲过一辆 +10 分并提速;**刷车保证每排至少一条空道**(生成线往下 2×车身高内不叠车) | 点/拖屏幕换道(方向键兜底)· `SELECT` 暂停 · `回车` 重开 |
| `go/snake.go` | **贪吃蛇**(Go)。吃到食物变长并提速 | 方向键转向 · `SELECT` 暂停 · `回车` 重开 |
| `swift/snake.swift` · `csharp/snake.cs` | **贪吃蛇**(Swift / C#)| 同上 |
| `c/piano.c` | **钢琴**。两行黑白键(键数**按屏宽自适应**,一行整若干个八度)、键上标音名、**多指按和弦**(轮询 `ui_touch_read`)、示范曲、录音回放 | 按琴键 · 「−/+」移调 · 「示范」放小星星 · 「录音」 · 「清音」急停 |
| `c/audio_test.c` | **音频测试**(不是游戏)。音阶 / 和弦同时响 / 旋律 / 与旧式音效共存,四段 | 自动播放,看屏幕提示 |
| `c/tilt.c` | **水平仪 + 小球**(不是游戏)。把**加速度计 / 陀螺仪 / 融合姿态**三个传感器的实时读数画在屏幕上,小球跟着手机倾斜滚,底部还画着**电量 / 充电 / 省电模式**。写倾斜控制照它抄 | 歪手机 · 点屏幕任意处 = 校准水平 |
| `c/bench3d.c` | **3D 压力测试**(不是游戏)。每 60 帧新建 20 个物体各自公转+自转,一路加到 250(宿主 `MaxObjects`=256),看帧率在哪个物体数上开始掉。相位用**黄金角**散开(等差会与轨道档数共振,见 `docs/开发教训.md` E123)| 自动跑,`Esc` 退出 |
| `c/g3_all.c` | **3D 号段 600–632 逐号验收**(不是游戏)。33 个号每个都有一条能分辨「生效 / 没生效」的证据:返回值按语义断言、**同一个像素**调前调后必须不同、外加 5 条标 `REVERSE:` 的**反证**(该没效果时读数必须不变;另有「恢复后逐位相同」「非法参数被拒」等同类断言)。末行打 `OK=/FAIL=/UNIMPL=`,机器可判读。桌面跑 `vmlcli … --screen 393x757 --timeout 60`,秒级闭环 | 自动跑,不用操作 |
| `c/gyro.c` | **拧螺丝**。**转手机来拧** —— 20 秒内拧满 5 圈算赢,松手会回退。用的是陀螺仪的**角速度**(本游戏刻意不区分转动方向,理由见文件头)。结束后有个「分享成绩」按钮(**`ui_share_text` 的活样例**)| 像拧方向盘那样转手机 · 点屏幕重开 |
| `cpp/gorilla.cpp` | **大猩猩扔香蕉**(C++,QBasic GORILLA 的重新实现)。弹道 + 风 + 会塌的楼、飞过的鸟 / 飞机 / 飞碟、**天黑天亮**。**音效最完整的一个**:发射 / 命中 / 空中爆炸 / 轰鸣 / 警报 / 胜负各是一种音色 | 拖动调角度力度 · 「发射」 · 键盘方向键 + 回车也行 |
| `basic/gorilla.bas` · `basic/gorilla_pro.bas` | 同一玩法的 BASIC 两版(pro 多了飞过的鸟 / 飞机 / 飞碟与天黑天亮)。**音效与 C++ 版同一套设计** | 同上 |
| `cpp/1945.cpp` | **1945 竖版卷轴射击**(C++)。6 种敌机 / 6 种敌弹(含追踪弹)/ 3 种掉落物(武器 · 生命 · 护盾)/ 3 种 BOSS(扇形弹幕 · **激光**带充能预警 · 追踪弹幕);越往后敌人越密;通关有大奖杯、失败是墓碑 | 按住拖动移动(**自动开火**)· 键盘方向键兜底 |
| `cpp/minesweeper.cpp` | **扫雷**(C++,用类写)。列数固定 9、格子边长取"按宽 / 按高"两个上界的小者、行数随剩余高度算;**首点安全**、泛洪展开走显式栈不递归。排版全部由画布坐标空间推导 | 轻点翻开 · 长按插旗 |
| `csharp/g2048.cs` | **2048**(C#)。4×4 滑动合并,每步随机补一块 2(90%)/ 4(10%),凑出 2048 获胜 | 手指滑动(方向键兜底)· `R`/回车重开 |
| `csharp/breakout.cs` | **打砖块**(C#)。拖动挡板、点一下发球;打光一片砖过关(提速 + 加一行),三条命 | 拖动 / 方向键移挡板 · 点按或空格发球 |
| `csharp/pong.cs` | **乒乓(单人)**(C#)。上半屏滑动控制左挡板、右边是电脑;每次回球加速,先得 7 分胜。整数物理(像素×10)+ 墙钟补步,`--arg demo` 跑两段固定物理并打印判据 | 上半屏滑动 / `W`·`S` · `回车` 重开 · `ESC` 退出 |
| `csharp/angrybirds.cs` | **愤怒的小鸟(简化版)**(C#)。按住小鸟往后拉蓄力、松手射出抛物线,打碎木屋里的三只绿猪;三只鸟,全部打掉过关。三种碰撞按固定顺序判(地面→木块→猪),`--arg demo` 跑三段固定物理并打印判据 | 按住小鸟拖拽松手发射 · 方向键调拉弓点 + 空格 · `R` 重开 · `ESC` 退出 |
| `swift/minesweeper.swift` | **扫雷**(Swift)。9 列自适应行数,**首点安全**;长按**还按着就开始计时**,≥450ms 立刻插旗(不等抬手);泛洪用显式栈 | 轻点翻开 · 长按插旗 |
| `swift/flappy.swift` | **过管子(Flappy 式)**(Swift)。点一下扇翅膀,穿过管子 +1 分,撞管或落地结束,**最高分存进设备** | 点屏幕 / 空格 / 上键扇翅膀 |
| `swift/g2048.swift` | **2048**(Swift)。4×4 滑动合并;滑动**不靠 `TOUCHUP`**(按下记起点、移动过阈值判一次方向),四行四列共用一条 `moveLine`。`--arg demo` 用固定棋盘跑三步已知移动并打印判据 | 滑动 / 方向键 · `R` 重开 · `ESC` 退出 |
| `swift/pocketmon.swift` | **口袋妖怪风格对战**(Swift)。三系(草/火/水)互相克制、每回合四招选一、连胜继续下一场;角色全部用圆形线条**现场画**(无任何原作素材/名字)。回合状态机收在 `battleTick` 一处,`--arg demo` 断言克制倍数、一场固定对局与回复量 | 点招式按钮(键盘 `1`–`4` 兜底)· 点任意处继续 · `ESC` 退出 |
| `python/breakout.py` | **打砖块**(Python)。界面走共享调用库 `Lib/shared/src/vmlui.c`(Python 前端没有内联 `asm()`,只能按标签调 C 函数)| 拖动挡板 · 点按发球 |
| `python/wordle.py` | **猜词(Wordle)**(Python)。5 字母 6 次机会、逐位三色反馈(绿=位对 / 黄=有但位错 / 灰=没有)、内置词表 | **屏幕字母键盘**(物理键盘兜底)|
| `python/tetris.py` | **俄罗斯方块**(Python)。棋盘 10×20,消行计分 | 点左右两侧横移 · 点中间旋转 · 点最下直落 |
| `python/contra.py` | **横版枪战(魂斗罗风格)**(Python)。跑跳射击、子弹与敌人碰撞、三条命与无敌帧、滚动镜头;角色与地形全部**现场画**(无任何原作素材/名字)。`--arg demo` 跑一段固定操作并打印判据(命中 / 得分 / 跳跃 / 受伤 / 剩命)| 左下三颗按钮(`<` `>` `JUMP` `FIRE`)· 方向键 + 空格射击 · `R` 重开 · `ESC` 退出 |
| `kotlin/snake.kt` | **贪吃蛇**(Kotlin)。16×13 竞技场,吃到红点变长并提速(240→90ms),撞墙或咬到自己结束 | 方向键 / WASD 转向 · 屏幕十字键 · `P` 暂停 · `R` 重开 |
| `kotlin/minesweeper.kt` | **扫雷**(Kotlin)。9×9 / 10 雷,**首击必安全**,翻到 0 连带掀一片,「插旗」是模式按钮(不绑长按) | 点格子挖开 · 「挖开/插旗」切模式 · 方向键+回车 · `F` 切模式 · `R` 重开 |
| `kotlin/breakout.kt` | **打砖块**(Kotlin)。7×5 砖块、三条命;**一步之内先判墙、再判挡板、最后判砖块**(球与挡板同高时不会被砖块抢走)。整数物理 + 墙钟补步,`--arg demo` 跑三段固定物理并打印判据 | 滑动 / 方向键移挡板 · 点按或空格发球 · `ESC` 退出 |
| `java/snake.java` | **贪吃蛇**(Java)。吃到食物长一节、快一档;撞墙或咬到自己结束,棋盘塞满通关 | 方向键/WASD 转向 · 点屏幕往那边拐 · `SELECT` 暂停 · `回车` 重开 |
| `java/minesweeper.java` | **扫雷**(Java)。9×12 埋 15 颗雷,**首点必安全**(雷在首次点击后才埋、避开点中格及八邻域);摊开 93 个非雷格算赢 | 轻点翻开 · **按住 0.4 秒插旗** · 方向键+空格/`F` · `H` 提示 · `回车` 重开 |
| `java/lightsout.java` | **关灯(Lights Out)**(Java)。5×5 灯阵,点一格连自己带上下左右一起翻转;全灭过关。回合制、无物理,`--arg demo` 用固定按键序列验证「翻转两次回到原状」与过关判定 | 点格子 · 方向键移动光标 + 空格按下 · `R`/`回车` 重开 · `ESC` 退出 |
| `lua/snake.lua` | **贪吃蛇**(Lua)。吃到食物变长并提速(220→96ms),撞墙或咬到自己结束,长到 40 节通关;HUD 分数/长度是**自绘点阵数字** | 方向键/WASD 转向 · `SELECT` 暂停 · `回车` 重开 · 触摸朝那边拐 |
| `lua/g2048.lua` | **2048**(Lua)。四方向滑动合并同值方块,每滑一次补一块(90% 2 / 10% 4),合出 2048 通关,满盘无路可走结束 | 方向键/WASD · 触摸滑动 · `回车`/`R` 重开 |
| `dart/snake.dart` | **贪吃蛇**(Dart)。棋盘随屏自适应(竖屏 14×18 / 横屏 21×11),每局**第一个食物固定在头行尽头**(开局第一口必定吃到,无头测试才有确定分数)、每 12 步提速 6ms | 方向键/十字键转向 · `A` 暂停 · `B`/`ESC` 退出 · 结束后 `A`/空格/回车 重开 |
| `dart/minesweeper.dart` | **扫雷**(Dart)。11×14 埋 22 雷(密度随盘子自适应),**首击必安全**、泛洪走显式栈;踩雷全盘亮雷,翻满非雷格通关 | 方向键移光标 · `A`/空格翻开 · `B`/`X` 插旗 · `ESC` 退出 · 结束后 `A`/空格/回车 重开 |
| `javascript/typing_rain.js` | **打字坠落**(JavaScript)。单词从顶上落下,敲对字母逐位消掉;敲满 15 个通关、3 条命掉光结束 | 点屏幕 A–Z 键盘 · 物理键盘字母 · `回车` 重开 |
| `javascript/maze.js` | **迷宫寻路**(JavaScript)。随机挖一座 11×15 迷宫(DFS + 显式栈),点任意一格沿唯一通路朝它走一步;`H` 用 BFS 提示最短路,步数超过最优 3 倍算输 | 方向键/WASD · 点任意格自动寻路 · `H` 提示 · `R` 换迷宫 |

**音效**:游戏音效**默认用 `ui_audio_beep(freq, ms)` 单音** —— ⚠ **本段原先写"已全部换成复音音效
(`ui_sfx_add`/`ui_sfx_tick`)",那是过期的**:共享库那套音序器**真机上会破音**
(多声部叠加削波 + 长音拖尾),2026-09-26(v0.96.507~509)**已把全部 28 个游戏退回单音**。
"每种事件一种音色"仍然成立 —— 靠的是**不同频率**,不是和弦。
仍直接用音序器的只剩 `c/audio_all.c`(音频演示)、`c/piano.c` 那类**乐器**,
以及几份老的 BASIC 例程;判据与两条破音原因见 `docs/VML游戏开发指南.md` §4.5。

两个都用 `Lib/c/vml_ui.h` 那套接口(窗体 / 绘图 / 触摸与按键消息 / 定时器),
界面全用绘图指令画出来,**不依赖任何图片资源**;尺寸按 `ui_scr_get_w/h` 报的**实测可用绘图区**
自适应,所以手机、平板、模拟器上都能铺满(`ui_scr_get_h` 在手机上只有 578 左右 —— 标题栏与
手柄区都扣掉了;按屏幕尺寸算成 744 的话,底部内容会落到可视区外)。

## 暂时跑不了的(**已知**,别当新问题查)

| 文件 | 卡在哪 |
|---|---|
| `basic/tetris.bas` | BASIC 前端三个既有缺陷:SUB 内局部 `FOR` 循环死循环、SUB 内局部数组赋值读回 0、FUNCTION+SUB 组合挂起(回归语料见仓库 `scripts/basic-tests/` 的 t9/t10/t11)。`draw_board` 整片都是 SUB 内局部 FOR,一个都绕不过去。 |

**`python/tetris.py` 已经从这张表里移走了**(v0.96.592):它原先卡在"列表读可以、写不生效"
(`b[i] = v` 之后读回还是 0),真因是 **`def main()` 的程序顶层语句一条都不执行** ——
不是列表写不生效,是那段代码根本没跑过。前端修好后 `--frame` 出的图里棋盘、下落块、底部方块都在。

BASIC 那版先用 C 版交付;那几处前端缺陷要单独修。

## 再加一个游戏

1. 源文件放 **`Examples/c/xxx.c`**(或对应语言目录;`Examples/` 整个目录**不参与 sync**,
   上游同步不会覆盖本地加的文件 —— 见 `sync.sh` 的 `--exclude 'Examples/'`)。
2. 全用 `vml_ui.h` 的接口:`ui_win_open` → `ui_2d_clear`/`ui_*` 画 → `ui_2d_present`,
   输入走 `ui_msg_wait(msg, 0)`(触摸 / 按键 / 定时器**同一个队列**),退出看 `ui_win_is_closed()`。
   **不要去碰 500–599 的裸 syscall** —— 那层包装是各语言共用的一份实现。
3. **先开窗还是先排版**:一律 `sw = ui_scr_get_w(); sh = ui_scr_get_h(); ui_win_open(title, sw, sh);`
   —— 窗口宽高就是画布的坐标空间,按 395 排版却开 360 宽的窗,右边会被切掉。
4. 在下面的无头模拟器里过一遍(**别为了看一眼效果重打 APK**)。
5. 跑 `scripts/make-vml-lib.sh` 重打资产包 —— 示例是在**打包时**进 `vml_lib.zip` 的,
   光把文件放进 `Examples/` 不会自动出现在手机上。
6. 把这个表补一行。

**惯例**(两个游戏都照这个写,新增的也建议照做):

- 布局数值在 `main` 里算**一次**存起来,画和命中判定共用 —— 各算一遍就会出现
  「看着在键上、点下去没反应」。
- 每次输入后**先判"画面真的变了吗"再重画**:一帧要把整幅场景光栅化一遍(手机上几百毫秒),
  撞墙没动、结束后乱点这类情况就别重画。
- 长按连发用第二个定时器(`ui_timer_set(130, 1)`,用 tag 区分重力);`TOUCHUP` 时 kill 掉。
- 注释里写清**为什么**(哪条约束、哪次实测),不只写"做了什么"。

## 想在桌面看效果

桌面没有 500–599 那套 UI 号段,但仓库里的脚手架 `vmlhost`(`.scratch/vmlhost`)能无头跑:

```bash
# 脚本化触摸 + 重力节拍,并把每一帧走**和手机同一条渲染链**出成 PNG(可以直接看图验收)
dotnet run -c Release --project .scratch/vmlhost -- run Examples/c/tetris.c \
    --sim "t;t;87,671;297,639" --screen 395,578 --frames /tmp/out

vmlhost bench     # 量每帧的出图成本(这套"场景→DSL→PNG"路线每帧要多久)
vmlhost font      # 字体自检:挑中哪个字体、中英推进量、出样张
```

`--sim` 里每个 `x,y` 投一次触摸、`t` 投一次**重力节拍**(定时器消息);
`--screen W,H` 换可用绘图区(手机上实测约 395×578,不是屏幕尺寸);
`--frames` 出帧、`--trace` 打每一次 syscall(定位"卡在哪一条")。