从源码构建奶蛙桌宠 v2.0.1
=====================

普通使用者直接运行随包的 NaiwaPet.exe 即可，不需要构建工具。
项目为 C / Win32 原生程序，使用 Windows 自带的系统 DLL，
不使用 Electron、WebView 或 .NET。
v2.0.1 的可选截止时间使用 Windows 系统日期时间公共控件：
链接参数增加 -lcomctl32，manifest 声明 Common Controls v6。
该 DLL 为系统组件，不需要随包安装额外运行库。

已使用的工具链
--------------
Zig 0.17.0，Windows x64 官方便携包：
https://ziglang.org/download/0.17.0/zig-x86_64-windows-0.17.0.zip

文件大小：100268137 字节
SHA-256：
b5663f69581dcf391293fbf16c06cb80d81d806545ce618b4d0bab7f0eb8c428
官方校验来源：https://ziglang.org/download/index.json

编译器不随用户压缩包分发。
可使用已有 zig.exe 的完整路径，无需安装到系统或修改 PATH。

Windows 构建
------------
以下命令在 cmd.exe 中运行。进入本 BUILD.txt 所在的 source 目录，
把 ZIG 设置为本机已有编译器的实际完整路径：

  set "ZIG=C:\tools\zig\zig.exe"
  scripts\build.cmd

输出：
  dist\NaiwaPet.exe

脚本使用 -target x86_64-windows-gnu 和 Windows GUI 子系统。
默认编译缓存位于 source\build\zig-cache。
完整参数以 scripts\build.cmd 为准。

Linux 环境如已有对应 Zig 0.17.0 工具链，也可交叉编译：
  ZIG=/absolute/path/to/zig sh scripts/build.sh

该方式不代表已经在 Linux 上验证 Windows GUI 交互。

素材重建（可选）
----------------
预生成的 assets/sprite.bgra、assets/sprite-fixed.png、assets/pet.ico
和 src/animations.h 已提供，编译主程序无需 Python 或图像库。

只有重建素材或运行 Python 素材／包验证时才需要 Python 3 与 Pillow：
  python scripts\prepare_assets.py

脚本完全离线：保留并校验原始 WebP，对已确认的局部 alpha 缺陷
作确定性修复，生成无损 PNG、预乘 BGRA、图标和修复记录。
上游动画行、帧数与时间配置保持不变。
修复范围见上一级目录的 ASSET-FIXES.txt。

无窗口测试
----------
在 source 目录运行；以下测试程序不启动桌宠 GUI：

  if not exist build mkdir build
  "%ZIG%" cc -std=c11 -O2 -Wall -Wextra tests\test_core.c -o build\test_core.exe
  build\test_core.exe

  "%ZIG%" cc -target x86_64-windows-gnu -std=c11 -O2 -Wall -Wextra tests\test_todo_store.c -o build\test_todo_store.exe
  if not exist build\todo-fixtures mkdir build\todo-fixtures
  build\test_todo_store.exe "%CD%\build\todo-fixtures"

待办测试必须显式提供已存在的测试目录。
它使用测试夹具，不解析或写入真实个人 AppData 待办文件。
持久化测试包含可选截止时间、草稿日期、旧版数据兼容与无效日期保护。

待办列表的离屏布局／像素检查（只在内存 DC 绘制，不打开窗口）：

  "%ZIG%" cc -target x86_64-windows-gnu -municode -O2 -Wall -Wextra tests\test_todo_layout.c -luser32 -lgdi32 -lshell32 -lcomctl32 -o build\test_todo_layout.exe
  if not exist build\layout-previews mkdir build\layout-previews
  build\test_todo_layout.exe "%CD%\build\layout-previews"

圆角矢量图标的离屏绘制检查（输出目录需已存在）：

  "%ZIG%" cc -target x86_64-windows-gnu -std=c11 -O2 -Wall -Wextra -Werror tests\test_icons.c -luser32 -lgdi32 -o build\test_icons.exe
  build\test_icons.exe build

该测试只创建内存 GDI 表面，输出 build\icon-sheet.bmp；
不打开桌面窗口，也不读取个人数据。

素材回归与已编译 EXE 检查：
  python tests\test_asset_repairs.py
  python tests\verify_package.py

verify_package.py 优先读取 dist\NaiwaPet.exe；没有本地构建时读取随包的主程序。

不创建窗口的 GDI 绘制检查：
  "%ZIG%" cc -target x86_64-windows-gnu -std=c11 -O2 -Wall -Wextra -Wno-unused-function tests\render_panel.c -luser32 -lgdi32 -lshell32 -o build\render_panel.exe
  build\render_panel.exe build
  "%ZIG%" cc -target x86_64-windows-gnu -std=c11 -O2 -Wall -Wextra tests\test_render.c -luser32 -lgdi32 -lshell32 -o build\test_render.exe
  build\test_render.exe assets\sprite.bgra build\render-preview.bmp
实际通过情况和未验证的真实交互范围以 TEST-REPORT.txt 为准；
不要仅凭构建成功推断 GUI 正常。

目录
----
src/       Win32 主窗口、物理状态机、圆角面板及本地待办代码
assets/    保留的原始素材、修复派生文件和预生成资源
scripts/   离线构建与素材准备
tests/     行为、持久化、素材、PE 资源及辅助渲染检查
dist/      本地构建输出
build/     本地缓存、测试程序和测试夹具

