# XTOpenSudoku **Repository Path**: ZYFDroid/XTOpenSudoku ## Basic Information - **Project Name**: XTOpenSudoku - **Description**: 阅星曈(XTEink X4 Pro)上的数独小程序:Lua + 随工程分发的 xtui 框架,只做触摸、只做竖屏(480×800)。 内置 9000 道题的离线题库(qqwing 预生成,每题唯一解,且保证纯逻辑可解、不需要猜),操作方式参考安卓平台 的 OpenSudoku。 - **Primary Language**: Unknown - **License**: GPL-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-13 - **Last Updated**: 2026-11-06 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # XTOpenSudoku 阅星曈(XTEink **X4 Pro**)上的数独小程序:**API 2.17 + XTUIKit v3**(原生 `ctx.ui` 界面库), **只做触摸、只做竖屏**(480×800)。内置 9000 道题的离线题库(qqwing 预生成,每题唯一解, 且保证纯逻辑可解、不需要猜),操作方式参考安卓平台的 OpenSudoku。 > 仓库已从旧的 0.8 框架迁移到 **API 2.17 / XTUIKit v3**。旧版是「自绘控件树」, > 新版是「原生界面库 + 一层持久控件包装」;`domain/xtui/` 已整体替换, > 业务层 `domain/sudoku/` 保留了题库、存档与棋盘逻辑。迁移记录见 > [`ideas_and_exps`](ideas_and_exps) 与根目录的验收命令。 --- ## 0. 先看结论:怎么跑、怎么验收 ```powershell # 1) 图形界面(人工点一点;状态落在 extra.tools\out\user_manual_run_state) .\RunProject.bat # 2) 无界面自检 + 基线(Agent 首选;退出码 0、断言 0 失败) $exe = "extra.tools\XTEinkAppEmulator.exe" New-Item -ItemType Directory -Force extra.tools\out | Out-Null & $exe --selftest . --out extra.tools\out\run --state-dir extra.tools\out\state ` --baseline extra.tools\out\baseline.json # 3) 主界面截图 & $exe --uishot extra.tools\out\ui.png . --state-dir extra.tools\out\state # 4) 按真实交互走(首页 → 难度 → 棋盘 → 填数 / 撤销 / 更多菜单) & $exe --selftest . --out extra.tools\out\keys --state-dir extra.tools\out\state-keys ` --sendkeys "t:240,494,_300,t:240,406,_500,t:35,111,_250,t:384,40,_250,t:448,40,_300,t:368,104,_400" ` --sendkeys-log ``` 工程目录参数一律给**归档根** `.`(本文件所在目录)。给 `project-files\` 也能载入, 但模拟器只从归档根解析 `assets\xic\`,素材会静默找不到。 基线首次运行是**建立**,之后是**比对**。比基线时要用干净的空 `--state-dir`: 基线里的帧哈希会跟着存档内容变,拿上一轮探针留下的存档去比会假报回归。 --- ## 1. 环境与目录 | 需要 | 用途 | | --- | --- | | Windows + PowerShell 7 | 跑模拟器 / 脚本 | | `extra.tools\XTEinkAppEmulator.exe` | API 2.17 离线模拟器(**不在版本库里**,见下) | | Python 3 | `tools\build_single.py`(可选的发布快照) | | JDK 17+ | 只有重新生成题库时才需要 | | 在线 XTApp Studio | 组装素材、题库、入口,出真机包 | ```text XTOpenSudoku\ ├── project-files\ ★ 真正的“工程根”(交给 Studio 的源码) │ ├── manifest.json api 2.17 / entry / data_files / preload_assets / 图标 │ ├── index.lua 薄入口:7 个宿主回调转发给 WindowManager │ ├── domain\sudoku\ 业务:9 个 Activity + 棋盘 + 题库 + 存档 + 教程 + 素材 key │ ├── domain\xtui\ XTUIKit v3(26 个 .lua;来自同版本框架仓库) │ ├── data\*.tsv 90 个题库分片(**不入库**,见第 3 节) │ ├── docs\xtui.md 框架 API 文档(v3) │ ├── docs\IDE_SETUP.md 编辑器配置 │ └── defs\*.d.lua LuaLS 类型定义(编辑器用,不参与运行) ├── assets\xic\ 59 张运行时 XIC(27 张棋局 + 32 张教程整页) ├── tools\ │ ├── build_single.py 打平出可整份粘贴的 index.lua(可选) │ ├── png_to_xic.py 教程 PNG → 1bpp XIC │ ├── qqwing_bank_gen\ 题库生成器(Java + qqwing,GPL-2.0-or-later) │ └── png_crop.py / png_ink_rows.py 帧图小工具 ├── ideas_and_exps\ 需求、题库方案、历轮优化记录 ├── extra.docs\ API 2.17 文档(随归档分发,git 忽略) ├── extra.tools\ 模拟器与自检产物(随归档分发,git 忽略) ├── RunProject.bat / PackProject.bat 双击即用 ├── LICENSE / LICENSING.md / LICENSES\ / REUSE.toml └── AGENTS.md 工程说明与验收清单 ``` --- ## 2. 模拟器从哪来 离线模拟器**不在版本库里**(单文件约 9.4 MB,每次刷新都是整块新二进制)。 把它放进 `extra.tools\`,文件名必须完全一致: ```text extra.tools\XTEinkAppEmulator.exe ``` - 新版是 **API 2.17** 模拟器;0.8 的包会被拒绝载入。 - 运行会在同目录产生 `logs\`、`state\`、`crash.log`,`extra.tools\` 整目录被 `.gitignore` 忽略。 - 没有它时,用模拟器仓库的 `XTEinkAppEmulator\XTEinkAppEmulator\bin\Debug\XTEinkAppEmulator.exe`。 --- ## 3. 题库(克隆后必须现场生成) 题库**不入库**(`project-files\data\.gitignore` 里是 `*.tsv`)。生成器在 `tools\qqwing_bank_gen\`:Java 版 qqwing + 分片生成器,参数确定、产物可复现。 ```powershell cd tools\qqwing_bank_gen pwsh -File build_bank_jar.ps1 # 编出 qqwing-bank.jar(JDK 17+) java -jar qqwing-bank.jar # 默认 3 档 × 30 片 × 100 题 → .\data\(12 线程约 2m40s) java -jar qqwing-bank.jar --verify # 重推难度档位 + 暴力枚举验唯一解 cd ..\.. Copy-Item tools\qqwing_bank_gen\data\*.tsv project-files\data\ -Force ``` - 一行 = `PS`:81 个题面字符 + TAB + 81 个解字符,空格写 `.`,行尾 LF; 每行 164 字节、每片 16400 字节。 - 档位与文件名是**故意错位**的:简单 → `easy_*`、中等 → `normal_*`、困难 → `hard_*` (对应 qqwing 的 simple / easy / intermediate)。 - 每个分片都要在 `manifest.json` 的 `data_files` 里登记(`name` 扩展名与 `format` 一致), 否则运行时 `ctx.package:read` 返回 `not_found`。 运行时读题走 **`ctx.package:read(name)`**(API 2.17 的包内数据文件接口), 不再使用 0.8 的 `ctx.data:read_text`。 --- ## 4. 素材:新 XIC、旧图标与原生 API `assets\xic\` 目前 **59 张**: | 类别 | key | 格式 | 说明 | | --- | --- | --- | --- | | 棋盘底图 | `boardimage` | 1bpp + alpha | 464×464,透明底 + 黑格线 | | 预填网点 | `mask_prefill` | 1bpp + alpha | 50×50,约 20% | | 大数字 | `bignum_1..9` | 1bpp + alpha | 48×48 | | 小数字 / 角标 | `smallnum_0..9` | 1bpp + alpha | 16×16 | | 标题图 | `title` | 1bpp + alpha | **351×245**(旧 logo 尺寸,转成新格式) | | 标题栏图标 | `ic_back_w24` / `ic_undo_w24` / `ic_more_w24` | 旧版 1bpp(无 alpha) | 24×24,白底黑字形,继续用旧版即可 | | 应用图标 | `ic_launcher` / `ic_banner` | 旧版 1bpp | `ic_launcher` **88×88**(点对点);`ic_banner` 200×150;manifest 的 `app_icon_s/l` | | 教程整页 | `tutorial_1..32` | 1bpp(无 alpha) | 464×640,由 `tools\png_to_xic.py` 生成;按需加载 | 要点: - **新版 XIC 的透明由 alpha 平面表达**,不再需要任何 `_matte`;`g:image` 的 `color = 0/15` 仍只对 1bpp 图有效,用来把黑字反白。 - **数字/棋盘/标题/预填网点**都已转成新格式;**图标继续用旧版**(白底图标画在白底按钮上,不需要 alpha)。 - 活跃数字的高亮**不用素材**:大数字底下铺 48×48 实心黑、小标记槽位铺 16×16 实心黑,再把字画白。`mask_hl` / `mask_pen_hl` 已删除。 - 旧版 `disablemask_w50` 已删除:置灰/禁用外观改用原生 `g:pattern`(白点)与 原生 `enabled = false`,不再需要这张网点图。 - 标题图 `title` 用旧版 351×245,而不是上一轮的 480×335:它和旧版面(标题 y=77、 按钮从 y=370 开始)逐像素对得上。 - 应用图标按 **88×88 点对点**作图:宿主只在这个尺寸 1:1 显示,其它尺寸会缩放, 像素化效果会糊。当前 `ic_launcher` 由 100×100 用 `tools\xic_crop.py` 居中裁出 (992 字节,1bpp、无 alpha);`ic_banner` 200×150 正好是 `app_icon_l` 的建议尺寸。 - 图片一律按**原尺寸**画,不做缩放(电子纸上缩放一张要 350–450 ms)。 - 常驻素材增删时三处一起改:`assets\xic\` 的 xic 集合、`NumberAssets.PRELOAD`、 `manifest.json` 的 `preload_assets`。`ic_launcher` / `ic_banner` 只作应用图标, `tutorial_1..32` 按需加载,两者都不在 `preload_assets` 里。 - 教程整页是纯黑白、全不透明,1bpp 无 alpha;PNG 源图在 `rendertutorial\output\`, 改图后重跑 `python tools\png_to_xic.py`。32 页与 `TutorialData.CHAPTERS` 一一对应。 --- ## 5. 在在线 Studio 组装与发布 API 2.x 的 **`require` 是运行时真实加载**,不再有 0.8 的“导出前静态打平”硬性要求。 两种上线方式都成立: ### 5a. 多文件工程直接上传(推荐日常) 1. 把 `project-files\` 的源码、`assets\xic\` 的 59 张 xic、`project-files\data\` 的 90 个 tsv 传到在线项目; 2. 粘 `project-files\manifest.json`(`entry` = `index.lua`,`api` = `2.17`); 3. 在线跑校验 / 试运行 / 打包。打包脚本数应为工程里的 `.lua` 数(框架 + 业务), 不再要求是 1。 ### 5b. 打平成单入口(可选发布快照) ```powershell .\PackProject.bat # = python tools\build_single.py # 产物:tools\output\index.lua + flattened-entry.map.json + flatten-report.json ``` 把 `tools\output\index.lua` **整份**粘进在线入口即可。该脚本会先核对 `manifest.json` 的 `version` 与 `AboutActivity.VERSION` 是否一致(不一致直接失败), 再默认清整行注释(行号不变)并移除测试块;产物最前面固定有两条 `-- [header-message]`(项目地址 + GPL-2.0-or-later 许可),清注释也不会清掉。 产物在 `.gitignore` 的 `/tools/output/` 里,**不要提交、不要手改**。这不是 2.x 的日常 运行前提,只是让“上线字节 = 本地验收字节”更容易钉死。 > `manifest.json` 的 `app_id` 是应用身份:本地是 `qqwing_sudoku-2f06554d`。 > 新建在线项目时以在线项目为准,别把本地这份盖上去。 --- ## 6. 当前状态 - 框架:**XTUIKit v3 / 0.7.x**,API 2.17,单层 `WindowManager + Activity`, 原生 `Row/Column/Grid/Stack`、`Button/Label/Image/Region`;完成态用系统原生 `ctx.dialog`。 - 九屏:首页 / 难度 / 游戏 / 无尽模式出题 / 关于 / 游戏设置 / 教程目录 / 教程查看 / 数独生成性能测试。 首页四行:继续游戏(无存档时原生 disabled)/ 开始新游戏 / 左「数独教程」右「游戏设置」/ 退出游戏;关于入口在「游戏设置」里,同页还有默认开启的「禁用全刷」开关 (关闭后系统会插入自动全刷,残影更少但游戏略被打断),以及「关于」下面的「性能测试」。 首页返回键直接退出应用,不弹系统退出确认;其它屏仍按 Activity 栈返回。完成一局不另开 Activity: 游戏页标题改成「谜题:难度,已完成,用时 MM:SS」,隐藏撤销 / 更多,并用原生 confirm 询问「回到主页 / 查看棋盘」;该状态下棋盘与数字面板锁定。 - 教程:32 张 464×640 整页图,目录按 7 个主题分章;查看页图片 1:1 显示, 底部「上一页 / 下一页」连续翻全部 32 页,跨章时标题自动更新。 - 难度页第四颗按钮是「无尽模式」:点击后进 `EndlessActivity` 现场生成(nano 生成 + `guess_check` 判定,直到不需要猜测);成功直接进游戏,标题里的难度是「无尽」。 生成期间只有「正在生成谜题」和一条视觉用进度条(30% 起步,每尝试一次 +10%,最高 90%);每次尝试各占一个 tick。5 次尝试都不合适则显示「生成器未能在 5 次尝试内生成 合适的谜题」、进度条归零,底部左右排列「取消并返回」和「重新生成」。完成后把 `ctx.state.sudokuEndlessSolved` +1;这颗按钮右上角显示的是**已解决的无尽模式题数**, 其它三档仍是剩余题量。 - 设置页「关于本应用」下面的「性能测试」:50 轮 nano 生成 + `guess_check` 判定, 显示进度条与每轮/生成/判定的最小、最大、平均用时和成功率;返回键取消并直接退出, 不保存结果。 - 棋盘:一个 464×464 的 `Region` 自绘 81 格;触摸命中由原生 `region` 提供。 活跃数字的高亮是实心黑块 + 白字(不使用 mask 素材)。 - 存档:沿用 0.8 的 `ctx.state.sudokuState` / `sudokuFillMode` 字段,老存档可直接继续; 另在完成一局时记 `quizBank`,无尽模式记 `sudokuEndlessSolved`。首页「继续游戏」在 没有存档时是原生 disabled;第二行「开始新游戏」始终可点。 - 异常退出(锁屏销毁 VM 等,`onDestroy(exiting=true)`)会写 `sudokuResumePending`, 下次进首页自动继续;菜单的「保存并退出」不写该标记。 - 验收: - `--selftest` + 基线:**117 通过 / 0 失败**; - LuaLS `--check`:**0 问题**; - 上一轮人工全流程走查:**测试通过**(继续游戏 / 新局完成 / 菜单 / 一键填草稿 / 保存并退出 / 锁屏后继续 / 返回键 / 视觉与旧版一致); - 教程探针:PNG→XIC 32 张逐像素回读一致;`--sendkeys` 走通 首页 → 教程目录 → 第 5 章 → 下一页 → 返回,并截图确认第 1 / 15 / 20 / 32 页、 首末页按钮禁用、跨章标题与设置/关于入口。 - 设置页探针:默认开启的「禁用全刷」、关闭后落盘为 `sudokuDisableFullRefresh=false`;`--sendkeys` 截图确认开关、说明、关于与性能测试入口。 - 无尽模式探针:`--sendkeys` 走通「开始新游戏 → 无尽模式 → 出题成功 → 游戏」, 标题为「谜题:无尽」;填完整盘后 `sudokuEndlessSolved` 落盘为 1,难度页第四颗 badge 显示 1;失败页用覆盖判定结果的 override 探针确认「取消并返回 / 重新生成」可点。 --- ## 7. 注意事项 1. **`app_id` 发布后不能改**;改了就是另一个应用,旧存档/旧文件不会跟过去。 2. `manifest.json` 的 `data_files[].max_bytes` 正好卡在 16400;改题库格式/行尾要同步改。 3. **产物不许写进 `project-files\`**:自检/截图产物统一落 `extra.tools\out\`, 打平产物落 `tools\output\`(两者都已被忽略)。 4. 模拟器 exe 文件名必须叫 `XTEinkAppEmulator.exe`,工程目录参数一律给归档根 `.`。 5. `requires` 含 `ui` / `dialog` / `pointer`:本应用只做 X4 Pro 触摸版,X4 Classic 不满足。 6. 锁屏/休眠会销毁 Lua VM;恢复靠 `onDestroy(exiting)` + `ctx.state`,不要依赖模块级变量。 --- ## 许可 **主许可:GPL-2.0-or-later**。应用本体(Lua 源码、素材、文档、本工程自有工具)与 `tools\qqwing_bank_gen\` 都按 **GNU GPL v2 或更高版本**分发,正文见 `LICENSE` 与 `LICENSES\GPL-2.0-or-later.txt`。 **项目自有内容的唯一例外**:随工程分发的 **XTUIKit v3** 框架(`project-files\domain\xtui\`, 以及它的框架文档/类型定义 `docs\xtui.md`、`defs\xtui.d.lua`、`defs\README.md`、`docs\IDE_SETUP.md`) 来自上游框架项目,保持 **MIT**,不随本应用改成 GPL。第三方组件(qqwing、思源黑体) 仍按各自的许可,见 LICENSING.md。 逐目录的范围表、第三方组件与理由见 **[LICENSING.md](LICENSING.md)**。 新增文件请照邻居带两行 SPDX 头;不能带注释的(图片 / `.xic` / JSON / `.bat`)往 `REUSE.toml` 里加一条。