这是 Canvasia Engine 在“先原生化 Runtime，编辑器先保留网页技术”路线上的第一阶段预览。
当前目标不是一次性替换现有网页播放器，而是先把最核心的剧情播放主链迁到真正不依赖 HTML 的桌面运行时里。
- 背景切换
- 角色显示 / 隐藏
- 作者可调的自动说话者聚焦：关闭 / 柔和 / 电影感三档，可设置强度和切换速度；当前发言角色提亮并优先显示，其他可见立绘柔和退后，静态阅读方案会取消缩放动画
- 作者可调的自动对话镜头：柔和 / 电影感模式会随当前说话者的位置轻微横移和推近，旁白回到中性构图；视觉舒适度会降低或关闭运动，手写缩放 / 平移镜头卡按轴优先覆盖
- 道具、前景、遮罩与 Cut-in 舞台贴图的命名图层显示 / 移动 / 隐藏，支持前后层、位置、宽度、透明度、旋转、镜像、层级、时长与缓动
- 台词 / 旁白
- 台词 / 旁白句内节奏：支持作者插入短停顿、长停顿和局部慢速 / 快速 / 瞬间显示；玩家选择“瞬间显示”时会覆盖作者节奏，避免影响无障碍阅读
- 台词 / 旁白富文本：支持重点强调、轻声低语、安全自定义颜色和汉字注音，并可与句内停顿及局部语速组合；历史和存档摘要保留干净正文
- 经典 ADV、逐句累积并可手动换页的 NVL、电影字幕三种逐句文字呈现方式
- 选项，包括按好感度、道具、路线旗标等变量隐藏或锁定，锁定原因提示，以及全部条件未满足时的防卡死安全继续
- 跳转 / 条件分支 / 可复用子场景调用与自动返回（支持嵌套，并随存档恢复）
- 基础变量修改
- 作者可定义“跟随存档”与“跨周目记忆”变量；跨周目值独立保存，不会被新游戏、旧存档或剧情回退倒退，系统菜单支持二次确认后单独重置
- 玩家命名 / 问答 / 数字输入，以及台词、旁白、选项、锁定提示里的
{{变量ID}}动态正文；答案随存档与剧情回退状态保存 - BGM 精确起播、片头后循环、循环终点、同曲续播 / 重播、SFX 与语音播放
- 带场景缩略图的正式存档 / 快速存档；正式档可保护关键分支，旧存档没有图片或保护字段时仍可正常读取
- 系统菜单“数据保险箱”：一键把全部档位、续玩记录、资料馆解锁、跨周目记忆、玩家档案和体验设置写入项目专属
.canvasia-save；恢复前校验项目与 SHA-256、要求二次确认、自动建立安全点，任一记录失败会整组回滚 - 可视化存档 / 读档面板
- 标题页、选项、存档、设置、历史和资料馆的手柄导航与阅读快捷动作
- 基础系统菜单
- 主题 / 显示模式 / 一键阅读方案 / 文字速度 / 字号 / 文本框可见度 / 视觉舒适度 / 四路音量设置
- 角色 / 旁白独立语音混音，可叠加总语音与逐句音量、单独静音并持久保存，历史回听与语音回想同步生效
- 玩家自定义键位，可持久保存、自动交换冲突按键、一键恢复推荐键位，并保留关闭 / 帮助 / 存档等安全操作
- 玩家档案 / 自动续玩记录
- 原生标题页 / 主菜单入口
- 多馆标签页资料馆
- 章节回放 / 音乐鉴赏 / CG 回想
- 地点图鉴 / 角色图鉴 / 结局回放 / 成就馆
- CG / 地点 / 角色 / 旁白 / 关系 / 成就详情查看页
- 项目级正式存档位数量
- 项目级文本框样式基础同步
- 项目级成品 UI 皮肤颜色 / 标题资源同步
- 项目级 UI 九宫格绘制、存档卡片皮肤与按钮多状态贴图
- 项目级字体族 / 字体素材同步
- Runtime 资源预热清单读取：启动时缓存关键图片 / 短音频，后续素材按项目性能档位与实测单项耗时自适应分帧预热，诊断会显示平均耗时、峰值、慢项和当前帧预算，并确认 BGM / 视频流媒体路径
- 原生绘制变换缓存：背景、立绘、舞台贴图、九宫格 UI 与静态滤镜会复用已缩放 / 翻转 / 旋转表面；低配、标准、高画质档使用不同内存上限，并在运行诊断中显示命中率、估算占用和淘汰次数
- 可全文搜索并按角色 / 语音筛选的文本历史、历史语音回听、自动播放、已读快进，以及可恢复变量 / 舞台 / 音乐 / 视觉效果的逐步剧情回退
- 后台安全播放：窗口失焦或最小化时暂停剧情自动前进、打字机、限时选项、阻塞视频、转场和片尾，恢复后统一校正时间戳并从剩余进度继续；后台帧率会自动降到低频待机，避免无意义占用 CPU
- 按项目性能档位控制总量、遇到持续帧率压力会自动缩放粒子池的基础粒子表现
- 基础镜头 / 闪屏 / 淡入淡出 / 滤镜 / 景深演出
- Live2D / 3D 角色模型元数据预览桥
- 3D 场景交互预览桥
- 3D 模型 / 3D 场景资产结构、材质贴图槽、动画通道与依赖清单
- 视频卡片的影院式原生预览卡 / 可选 PyAV 音画同步内嵌播放 / OpenCV 画面兜底 / 系统播放器桥接兜底
- 真实时序片尾字幕：支持 4 至 180 秒滚动、深色 / 浅色 / 透明背景、作者控制是否可跳过、结束自动续接；静态视觉舒适模式会改为无滚动分页
- PyInstaller 独立 App 打包脚手架
原生 Runtime 已经可以承担第一版桌面预览和小型项目试玩导出；后续增强会按“先稳定主链，再补高级演出”的顺序推进：
| 模块 | 当前状态 | 后续增强方向 |
|---|---|---|
| 剧情主链 | 已支持背景、角色、台词、玩家输入、正文变量、条件隐藏 / 锁定选项、可暂停并随存档恢复的限时自动选择、跳转、条件、跟随存档 / 跨周目变量与可嵌套子场景调用 / 返回 | 持续对齐网页 Runtime 的高级演出边角场景 |
| 存档与系统菜单 | 已支持带本机场景缩略图的正式存档 / 快速存档、重要档位防误覆盖、旧存档兼容、带项目绑定与完整性校验的数据保险箱、恢复前安全点和失败整组回滚，以及主题、显示模式、一键阅读方案、文字速度、文字大小、文本框透明度、视觉舒适度、四路音量、角色 / 旁白语音混音、自定义按键和动态操作帮助 | 增加更多辅助功能和项目级菜单扩展 |
| 阅读体验 | 已支持项目字体族、项目字体素材、ADV / NVL / 电影字幕逐句呈现、句内停顿与局部语速、强调 / 低语 / 颜色 / 汉字注音、真实滚动 / 静态分页片尾、文本历史、语音回听、自动播放语音等待、持久化已读快进、逐步剧情回退、后台安全暂停、清屏隐藏和截图 | 后续补更多可访问性选项、触控映射和阅读偏好预设 |
| 语音驱动演技 | 已根据解码后的真实语音 PCM 包络驱动当前发言立绘的克制起伏，支持关闭 / 柔和 / 电影感、强度、灵敏度以及静态阅读自动停用，并保留无分析数据时的平滑兜底 | 后续由 Live2D / 3D 渲染后端消费 mouthOpen 参数，实现模型嘴型和更细表情联动 |
| 输入设备 | 已支持键盘、鼠标和手柄；键盘可由玩家持久化改键并安全处理冲突，手柄可使用摇杆 / 十字键导航、确认 / 返回，并快捷打开历史、系统菜单、回退、自动播放和已读快进 | 后续补手柄自定义映射、震动反馈和更多设备实机档案 |
| 资源预热与绘制缓存 | 已读取导出包 runtime_preload_manifest.json，并按项目 performanceProfile 套用标准、网页轻量、低配 / 移动端、高画质 PC 四档预热策略；报告会根据首屏体积、总预热体积、流媒体数量和条目数量给出推荐档位；关键资源启动预热，高画质档会提前准备 early 资源，非关键资源继续通过后台队列准备；每项预热会记录耗时和结果，保留有界慢项清单，并按平均 / 峰值成本自动降低或恢复每帧工作量；失败项不会误记为路线缓存；背景、立绘、舞台贴图、九宫格 UI、静态滤镜和完整对话框底板使用有界 LRU 表面缓存，避免每帧重复重采样或重建阴影 / 圆角 / 边框；运行诊断显示预热耗时、帧预算、缓存命中率、合成耗时、峰值、内存估算、淘汰和超预算绕过 |
后续补更多设备实机内存采样和素材类型 |
| 项目 UI 皮肤 | 已在 Pygame 中绘制基础颜色、标题资源、面板九宫格、存档卡片、按钮多状态贴图，以及作者可调的说话者聚焦和自动对话镜头；编辑器可用 .canvasia-ui-kit.json 整包迁移配置与依赖素材，导入时重绑为项目内 ID，原生 Runtime 直接消费导入后的项目配置 |
后续补更多控件级绑定和可复用部件预设；UI Kit 文件解析与安全写入继续由编辑器负责，避免在成品 Runtime 重复一套导入器 |
| 资料馆 / 回想馆 | 已支持章节、音乐、CG、地点、角色、结局、成就及详情页 | 增加高级筛选、排序、专属转场和更多馆内互动 |
| 粒子与镜头 | 已支持基础粒子、四档粒子总量预算、持续帧率压力下的粒子池自动降档 / 恢复、手写缩放 / 平移、自动说话者镜头、闪屏、淡入淡出、滤镜和景深；手写镜头按轴覆盖自动镜头 | 补齐组合层、更多物理参数和复杂粒子表现 |
| 3D 模型 / 场景 | 已支持 3D 角色模型元数据桥、3D 场景交互预览桥、glTF 结构统计、材质贴图槽探针、动画通道探针、依赖检查和引用位置清单 | 后续接真实 3D 渲染后端、材质预览视窗、动画选择器和场景碰撞 / 镜头轨道 |
| 视频卡片 | 已支持影院式原生预览卡、可选 PyAV/FFmpeg 音画同步内嵌播放、OpenCV 画面兜底、剪辑区间停止和系统播放器桥接兜底 | 继续补时间轴裁切 UI、更多编码实机矩阵和平台原生播放器方案 |
- Python 3.10+
pygame-ce
安装命令：
python3 -m pip install -r requirements.txt如果是在编辑器导出的原生 Runtime 包里运行，依赖文件会被改名为：
python3 -m pip install -r requirements-native-runtime.txtpython3 runtime_player.py --validate-bundle .
python3 runtime_player.py --describe-runtime-preload .
python3 runtime_player.py --describe-runtime-preload-markdown .
python3 runtime_player.py --performance-budget-report .--describe-runtime-preload 会输出适合自动化读取的 JSON；--describe-runtime-preload-markdown 会输出适合人工复查的 Markdown。两者都会检查预热清单、缺失素材、当前性能档位、推荐性能档位、critical 首屏资源体积和整体预热队列体积，适合在发布前定位“打开游戏第一下卡顿”的风险。
--performance-budget-report 会输出作品规模和素材体积预算报告，适合检查包体是否过大、单个素材是否过重、剧情场景是否需要拆分。
如果是在源码仓库里验证原生 Runtime 的真实 Pygame 绘制链，可以回到仓库根目录运行：
./run_native_runtime_smoke.sh这条命令会创建 .native_runtime_smoke_venv 隔离环境、安装 pygame-ce，并使用 dummy 音频/视频驱动运行 tests/test_native_runtime_render_smoke.py。macOS 也可以双击 run_native_runtime_smoke.command，Windows 可运行 run_native_runtime_smoke.cmd。
不启动窗口，集中运行导出包结构、发布前自检、VN 基础质感、标题页、正式存档面板、存档/设置/资料馆/玩家档案、粒子、演出、视频桥接和视频内嵌画面探针：
python3 runtime_player.py --doctor .这条命令会输出 JSON 总报告。涉及存档和设置写入的检查会使用临时用户目录，不会覆盖玩家或创作者机器上的真实存档。
不启动窗口，在 --doctor 的基础上输出更接近发版决策的 Release Candidate 报告。报告会汇总阻塞项、警告项、三系统打包矩阵、视频后端策略、商业发布缺口和下一步建议：
python3 runtime_player.py --release-candidate-report .导出包也会自动附带一份 native-runtime-release-candidate-report.json。如果想重新生成报告，可以直接运行随包脚本：
- macOS：双击
检查原生Runtime发布候选.command - Linux：运行
./check_native_runtime_release_candidate.sh - Windows：双击
check_native_runtime_release_candidate.bat
如果只想输入短命令，也可以使用：
python3 runtime_player.py --rc-report .报告中的 status 含义：
preview_ready：可进入桌面 Preview RC 的三系统实机打包阶段。preview_ready_with_warnings：主链可进入 Preview RC，但仍有发布警告需要在 Release notes 或实机点测中处理。preview_ready_with_optional_failures：Preview 主链不阻塞，但存在非核心能力失败。blocked：存在 Preview 阻塞项，应先修复再打包。
编辑器导出的完整原生 Runtime 包会额外附带：
native-runtime-release-control-report.md：给人工验收看的总控报告，汇总发布自检、RC 状态、3D 风险摘要、发布门禁和下一步处理顺序。native-runtime-release-control-report.json：给自动化脚本或 CI 读取的同一份结论，字段包含qualityGate、releaseCheck、releaseCandidate、asset3d、vnBaselineQuality、performanceBudget和nextSteps。native-runtime-vn-baseline-quality.md/native-runtime-vn-baseline-quality.json：检查视觉小说基础体验是否像完整作品，覆盖立绘兜底、背景覆盖、BGM 进入点、选项、空文本、占位素材和轻量演出润色。native-runtime-performance-budget.md/native-runtime-performance-budget.json：检查包体、已引用素材体积、图片/音频/视频预算、单个过大素材、剧情规模和未使用素材，帮助发布前压缩和拆分资源。
这些报告会在导出包生成时自动写入。若需要重新计算底层检查，可以先运行 --release-check、--doctor、--release-candidate-report、--describe-3d-assets 和 --performance-budget-report，再重新从编辑器导出一版包。
也可以直接在导出的原生 Runtime 包里刷新总控报告：
python3 runtime_player.py --write-release-control-reports .或分别输出到终端：
python3 runtime_player.py --release-control-json .
python3 runtime_player.py --release-control-report .
python3 runtime_player.py --vn-baseline-quality-report .
python3 runtime_player.py --performance-budget-report .随包脚本会自动调用同一条刷新命令：
- macOS：双击
生成原生Runtime发布总控报告.command - Linux：运行
./generate_native_runtime_release_control.sh - Windows：双击
generate_native_runtime_release_control.bat
编辑器导出的完整原生 Runtime 包会额外附带：
native-runtime-release-acceptance.md：面向发布前人工点测的清单，包含自动检查结果、VN 基础质感、性能预算、macOS / Windows / Linux 三系统验收项，以及启动、读档、音画、回想馆、成品分发等逐项确认框。native-runtime-release-acceptance.json：同一份清单的机器可读版本，可供 CI、发布脚本或外部工具读取。
这份清单会在导出包生成时自动写入。建议在正式分享或发布前打开 Markdown 版本，按目标系统完成最后一轮人工点测。
重新生成验收清单：
python3 runtime_player.py --write-acceptance-reports .或分别输出到终端：
python3 runtime_player.py --acceptance-check .
python3 runtime_player.py --acceptance-report .随包脚本：
- macOS：双击
生成原生Runtime发布验收清单.command - Linux：运行
./generate_native_runtime_acceptance_checklist.sh - Windows：双击
generate_native_runtime_acceptance_checklist.bat
编辑器导出的完整原生 Runtime 包会附带：
native-runtime-file-integrity.json：核心文件 SHA-256 清单，覆盖game_data.json、Runtime 脚本、启动脚本、requirements、素材和export_manifest.json。native-runtime-file-integrity.md：同一份清单的人类可读摘要，包含文件数量、总大小、最大文件和校验命令。
这份清单默认不包含可重新生成的诊断报告、完整性报告本身、缓存目录和本机 App 构建输出，避免刷新报告或打包 App 后造成误报。
验证当前包：
python3 runtime_player.py --verify-file-integrity .重新生成完整性清单：
python3 runtime_player.py --write-file-integrity-reports .随包脚本：
- macOS：双击
校验原生Runtime文件完整性.command - Linux：运行
./verify_native_runtime_file_integrity.sh - Windows：双击
verify_native_runtime_file_integrity.bat
如果下载页面同时提供 .zip.sha256 或 .zip.checksum.json，可以先用它们校验压缩包本身；解压后再运行上面的包内完整性校验，能覆盖“下载损坏”和“解压后文件缺失/被改动”两层风险。
如果同时提供 .zip.verify.command、.zip.verify.sh 或 .zip.verify.bat，下载者可以把脚本和 zip 放在同一目录，直接运行对应系统脚本完成压缩包 SHA-256 校验。
如果下载页面提供 .zip.release-artifacts.md 或 .zip.release-artifacts.json，它们是维护者生成的发布附件索引：里面会列出这次 Release 建议上传的 zip、校验文件、机器可读索引，以及解压后应查看的包内报告。
如果下载页面提供 .zip.release-notes.md，它是维护者可直接复制到 GitHub Release 正文的发布说明草稿，通常会包含主包、SHA-256、三系统一键校验脚本和包内完整性校验步骤。
不启动窗口，输出 3D 模型和 3D 场景的发布前资产清单：
python3 runtime_player.py --describe-3d-assets .导出包会自动附带一份 native-runtime-3d-asset-report.json。这份报告会列出：
- 资产类型、导出路径、是否被角色或剧情场景引用
- glTF 节点、网格、primitive、材质、贴图槽、动画通道、相机、灯光数量
.glb / .vrm二进制容器的文件头、声明长度、JSON chunk 和 BIN chunk 状态- 顶点、三角面、draw call、材质、贴图和动画通道的静态性能预算估算
- 材质里的基础色、法线、遮蔽、自发光、金属/粗糙度贴图槽是否能解析到图片
- 动画名称、通道数量、采样器数量、目标节点和 transform 路径
- scene、node、mesh、material、texture、skin、animation 等 glTF 内部索引是否断链
.gltf外部bin / 图片 / 贴图依赖是否缺失或越界fbx / obj等建议转换格式的提示- 每个问题对应的修复建议
如果项目包含 3D 场景或 3D 角色模型，建议在打包 App 前先看这份清单，再运行 --doctor 和 --release-candidate-report。
导出包还会自动附带 native-runtime-3d-asset-summary.md。它和 JSON 清单内容一致，但排版更适合人直接阅读、复制到 Issue，或作为 Release notes 的资产检查摘要。也可以手动重新生成：
python3 runtime_player.py --describe-3d-assets-markdown .编辑器导出的完整原生 Runtime 包还会附带 native-runtime-3d-risk-digest.json。这份文件是给发布页和自动化工具读取的精简风险摘要，会把性能预算、GLB/VRM 容器、内部引用、贴图槽和依赖风险浓缩成少量指标与优先问题，并保留 assetId、导出路径和引用位置预览，方便编辑器把风险直接定位回素材库。
不启动窗口，输出发布前诊断报告。这个检查会覆盖入口场景、缺失素材、素材格式风险、大文件风险、存档位数量、成品 UI 皮肤素材引用等：
python3 runtime_player.py --release-check .原生 Runtime 默认保留“影院式预览卡 + 系统播放器桥接”兜底；安装可选视频依赖后，会优先尝试 PyAV/FFmpeg 音画同步内嵌播放。如果 PyAV 不可用、音频解码失败或目标编码不兼容，会继续回落到 OpenCV 窗口内画面播放，再回落到系统播放器桥接。
查看当前机器的视频后端能力：
python3 runtime_player.py --describe-video-backends .如果想检查当前导出包是否能生成窗口内视频帧并支持内嵌画面播放，可以运行：
python3 runtime_player.py --probe-video-preview .如果想启用窗口内音画同步播放和 OpenCV 画面兜底，可以额外安装可选依赖：
python3 -m pip install -r requirements-native-runtime-video.txt安装后，视频卡片可按 V 优先在窗口内进行 PyAV 音画同步播放 / 暂停，按 O 调用系统播放器兜底；如果 PyAV 打不开，会自动尝试 OpenCV 画面播放，再回落到默认桥接方案。--probe-video-preview 会输出每个视频的探针状态，方便发布前确认是缺依赖、缺 pygame、文件缺失还是编码无法读取。
这条路线目前仍是商业化候选实现：PyAV 路径已经负责解码音频缓冲并按播放时钟驱动画面帧，OpenCV 负责无音频画面兜底；正式发布前仍需要在目标 macOS / Windows / Linux 机器上做 OP / ED / PV 编码兼容性实机验证。
python3 runtime_player.py game_data.json如果你下载的是已经打包好的 Native Runtime Preview zip，先解压，再按平台启动：
- macOS：优先打开
.app；如果系统提示未签名，可右键选择“打开”并确认来源是官方 Release 页面。 - Windows：打开解压目录里的
.exe；如果 SmartScreen 提示未知发布者，先用随包.sha256、.checksum.json或.verify.bat校验压缩包。 - Linux：运行解压目录里的可执行文件；如果没有执行权限，先给启动文件加执行权限。
如果你下载的是编辑器导出的源码式 Runtime 包，还没有打成 App，可以用随包脚本启动：
- macOS：双击
启动原生Runtime预览.command - Linux：运行
./run_native_runtime_preview.sh - Windows：双击
run_native_runtime_preview.bat
导出的原生 Runtime 包已经包含 PyInstaller 打包入口。创作者在目标系统上执行对应脚本，就可以把 runtime_player.py + game_data.json + 素材 打进 native_app_dist/，同时生成 native_app_package_manifest.json 和一个用于上传到 Release 的 Preview zip：
- macOS：双击
打包原生Runtime应用.command - Linux：运行
./build_native_runtime_app.sh - Windows：双击
build_native_runtime_app.bat
也可以手动执行：
python3 -m pip install -r requirements.txt -r requirements-build.txt
python3 build_native_runtime_app.py --mode onedir .打包清单会记录发布前自检、视频后端状态和视频内嵌画面探针结果，方便排查目标系统上的视频/素材问题。 清单也会记录 3D 资产 JSON 清单与 Markdown 摘要的状态，方便确认打包前后 3D 模型、场景、材质贴图槽和动画通道检查结果没有丢失。
在编辑器导出的原生 Runtime 包中，对应命令是：
python3 -m pip install -r requirements-native-runtime.txt -r requirements-native-runtime-build.txt
python3 build_native_runtime_app.py --mode onedir .打包脚本默认会先运行 python3 runtime_player.py --release-check .。如果自检发现错误，会先停止打包，避免把明显缺素材或入口错误的版本发出去。
如果想生成单文件可执行程序：
python3 build_native_runtime_app.py --mode onefile .如果想覆盖应用名和 macOS Bundle Identifier：
python3 build_native_runtime_app.py --mode onedir --app-name YourGame --bundle-id com.canvasia.yourgame .macOS 的 onedir 模式会在 native_app_dist/ 下生成 .app 和一个同名运行目录。优先把 .app 作为本机测试对象；正式分发前再做签名、公证和完整点测。
PyInstaller 通常需要在目标系统本机打包，不建议期待从 macOS 直接交叉编译 Windows / Linux：
- macOS：生成
.app，未签名/未公证时可作为 Preview 下载测试，正式公开分发需要 Developer ID 签名和 notarization。 - Windows：在 Windows 上运行
build_native_runtime_app.bat，会生成.exe或 onedir 目录；未签名时 SmartScreen 可能提示未知发布者。 - Linux：在 Linux 上运行
./build_native_runtime_app.sh，会生成 Linux 可执行目录；后续可继续封装 AppImage、deb/rpm 或 Flatpak。
手机端不走 PyInstaller，当前不能直接由这个脚本生成 Android APK 或 iOS IPA。可行路线分三档：
- 近期可试：继续使用网页 Runtime / WebView 包装，先验证手机触控、横竖屏、音频策略和存档。
- 中期路线：做独立 Android Runtime，把
game_data.json映射到 Kivy / Python-for-Android 或 Godot 这类移动壳。 - 长期路线：做 iOS / Android 双端原生 Runtime，共用项目格式，但渲染、音频、存档和商店发布链要单独实现。
因此手机端现在应标记为实验规划，不建议和桌面原生 Runtime 混在同一个发布承诺里。
Runtime 启动失败时，会在用户目录写入错误日志：
~/.canvasia-engine/native-runtime-logs/
随包会提供 native-runtime-crash-feedback.md 模板。玩家或测试者遇到打不开、闪退、黑屏时，可以在解压后的原生 Runtime 包目录运行：
python3 runtime_player.py --write-crash-feedback-reports .这会把最近的本机崩溃日志整理成 native-runtime-crash-feedback.md / .json。默认报告只包含摘要和已脱敏路径；需要深度排查时，再单独附上日志目录里的原始 .log 文件。
打包脚本不会替你做平台签名、公证或杀毒误报处理；正式公开发布前，仍建议在对应系统上做一次完整人工点测。
当前已经支持：
F5：快速存档F8 / F9：读入快速存档F6：打开正式存档面板- 正式存档面板内按
P：保护 / 取消保护当前档位；保护后仍可读取，但不能覆盖 F7：打开读档面板F11：切换窗口 / 全屏F1 / Tab：打开系统菜单F2 / ?：打开操作帮助H：打开文本历史- 历史面板内
/：输入台词 / 角色 / 场景关键词；F：切换角色；V：只看有语音；R：重听选中语音；C：清除筛选 A：开启 / 关闭自动播放S：开启 / 关闭已读快进PageUp：回到上一个剧情停顿点，并恢复当时的变量、背景、立绘、BGM、粒子和视觉效果F12 / P：保存当前画面截图- 鼠标左键：推进文本 / 确认
- 鼠标右键：打开系统菜单；弹窗内右键返回 / 关闭
- 鼠标中键 /
U：隐藏或恢复界面，便于清屏查看 CG / 背景 - 鼠标滚轮上：打开或滚动文本历史
- 鼠标滚轮下：推进当前文本；历史面板内向下滚动
- 手柄左摇杆 / 十字键：移动标题页、选项、存档、设置、历史和资料馆中的选择
- 手柄
A / ×：确认；B / ○：返回，阅读中按下会打开系统菜单 - 手柄
X / □：文本历史；Y / △ / Menu：系统菜单 - 手柄
LB / L1：剧情回退；RB / R1：自动播放；View：已读快进 - 系统菜单里的
体验设置：主题 / 显示模式 / 一键阅读方案 / 视觉舒适度 / 文字速度 / 文字大小 / 文本框透明度 / 自动播放语音等待 / 四路音量
视觉舒适度提供 原始演出 / 柔和模式 / 静态模式 三档。柔和模式会降低震动、闪屏与转场幅度；静态模式会直接跳过短暂震动、闪屏和转场动画，但仍保留演出结束后的背景、角色位置与黑场状态。
一键阅读方案提供 原作演出 / 舒适阅读 / 大字阅读 / 静态阅读 四档，会联动文字速度、字号、文本框可见度和视觉舒适度。玩家继续修改任一细项后，当前方案会显示为 自定义组合，不会覆盖作品数据。
- 系统菜单里的
玩家档案：本地游玩次数、累计时长、续玩次数 - 系统菜单里的
续玩记录：读取或清除自动续玩位置 - 系统菜单里的
资料馆：支持章节 / 音乐 / CG / 地点 / 角色 / 结局 / 成就标签切换 - 资料馆里
← / →：切换馆页 Ctrl + 1 / 2 / 3：写入前 3 个正式存档位Ctrl + Shift + 1 / 2 / 3：读入前 3 个正式存档位Esc：关闭面板 / 退出预览
维护或写教程时，可以直接导出 Runtime 当前内置的完整操作清单，避免 README、帮助层和实际快捷键长期不同步：
python3 runtime_player.py --describe-controls存档文件会写到用户目录下：
~/.canvasia-engine/native-runtime-saves/
存档画面缩略图会独立写入：
~/.canvasia-engine/native-runtime-save-thumbnails/
存档 JSON 只保存受限的缩略图键名，不写入本机绝对路径。缩略图写入失败不会让进度保存失败；没有缩略图的旧存档会继续使用文字摘要卡片显示。
正式存档、自动续玩、跨周目记忆、玩家设置和资料馆进度都通过同一套安全存储层写入：新内容会先完整落盘，再以原子替换更新主文件，并保留上一份有效的 .bak 恢复副本。主文件缺失、截断或不是预期 JSON 结构时，Runtime 会自动读取恢复副本、修复主文件，并在标题页状态栏提示玩家重新确认和保存。主动清除续玩记录时会同时清除恢复副本，不会让旧进度意外复活。
系统菜单中的“数据保险箱”会把上述玩家数据另存为项目专属 .canvasia-save：
~/.canvasia-engine/native-runtime-vault/<project-id>/
保险箱不会打包素材或本机绝对路径，只保存白名单中的六类 JSON 玩家数据。恢复时会重新读取文件并验证格式版本、项目 ID 和 SHA-256；第一次确认只进入 5 秒待确认状态，第二次确认前会先创建 before-restore 安全点。跨文件恢复中任一写入失败，Runtime 会尝试把已经写入的记录全部还原。
玩家档案和续玩记录也会写到用户目录下：
~/.canvasia-engine/native-runtime-profiles/
~/.canvasia-engine/native-runtime-autoresume/
截图会保存到：
~/.canvasia-engine/native-runtime-screenshots/
原生 Runtime 会优先读取项目 gameUiConfig.fontAssetId 指向的字体素材，支持 ttf / otf / ttc。如果项目没有绑定字体素材，或字体加载失败，会按 fontFamily、fontStyle 和系统字体候选链回退，不会因为缺字体直接退出。
文本历史会记录已经展示过的台词 / 旁白 / 视频卡片说明 / 片尾字幕说明，可搜索台词、角色或场景，并按角色或是否带语音筛选。如果历史条目绑定了语音，可在历史面板里选中条目后按 R 回听；语音素材缺失时会给出状态提示。筛选只改变历史视图，不会改动当前剧情位置或存档。自动播放会在当前文本完全显示后按设置间隔推进，也可设置为等待语音播放结束后再计时；已读快进会读取本机已保存的已读文本记录，遇到未读文本、选项或视频卡片会停下。
已读记录会写入 Runtime 进度文件，并带有文本内容摘要；如果创作者后续修改了同一位置的台词，Runtime 会把它视为新文本，避免快进误跳过新内容。
快速存档、正式存档和自动续玩会保存最近的历史文本快照，读档后仍能打开历史面板查看存档点之前的文本。
剧情回退使用独立的内存时间线，最多保留最近 120 个停顿点；重复停在同一状态时会自动去重。读档或重新开始会建立新的回退起点，不会意外跨越存档边界恢复旧路线。
不启动窗口，只验证存档写入和读回：
python3 runtime_player.py --exercise-save-load .不启动窗口，输出当前项目的正式存档分页摘要：
python3 runtime_player.py --describe-save-dialog .不启动窗口，输出原生标题页的菜单、Logo、续玩与存档摘要：
python3 runtime_player.py --describe-title-screen .不启动窗口，验证主题 / 显示模式 / 文字速度 / 音量设置的写入与读回：
python3 runtime_player.py --exercise-settings .不启动窗口，验证章节 / 音乐 / CG / 地点 / 角色 / 结局资料馆进度的写入与读回：
python3 runtime_player.py --exercise-archives .不启动窗口，验证当前项目里的粒子卡能否生成原生 Runtime 可播放条目：
python3 runtime_player.py --exercise-particles .不启动窗口，验证镜头 / 闪屏 / 淡入淡出 / 滤镜 / 景深这类演出卡能否被原生 Runtime 规范化：
python3 runtime_player.py --exercise-visual-effects .原生 Runtime Preview 会优先尝试可选 PyAV/FFmpeg 音画同步内嵌播放，并保留 OpenCV 画面播放和系统默认视频播放器作为兼容性兜底。这个命令可检查导出包里有哪些视频、是否存在、被哪些视频卡引用，以及当前系统是否能唤起默认播放器：
python3 runtime_player.py --describe-video-bridge .如果项目依赖 OP / ED / PV，正式发布前仍建议同时导出网页包或 NW.js 桌面包实机确认，或在目标系统安装可选视频依赖后完整点测一次。
不启动窗口，验证玩家档案和自动续玩记录的写入、读回与清除：
python3 runtime_player.py --exercise-profile .