这里集中回答 LetsGal Studio 使用过程中最常遇到的问题。遇到异常时，先保存项目并查看错误提示；涉及素材、构建或协作时，不要直接删除项目文件来尝试修复。
第一次使用先看
LetsGal Studio 是什么？
LetsGal Studio 是面向 Galgame 和视觉小说的可视化创作工具。它把剧本、角色立绘、场景、声音、分支、变量、演出、游戏界面和构建发布放在同一个项目中管理。
不写代码也可以完成一部常规视觉小说；需要背包、养成、地图、小游戏或特殊界面时，可以通过 TypeScript、React 和 Studio SDK 开发扩展。
不写代码能做到什么？
| 能力 | 可以完成的内容 |
|---|
| 剧本 | 对白、旁白、选项分支、条件判断、变量、章节和 Fragment |
| 角色与场景 | 普通、序列帧、Spine 与 Live2D 立绘，立绘皮肤、距离与位置，多层场景和视差 |
| 演出 | 镜头、粒子、声音、视频、幕布、浮动文字和时间线动画 |
| 游戏界面 | 标题、存读档、设置、历史、鉴赏、对话框、HUD 和剧情面板 |
| 工作流 | 剧本导入、实时预览、调试、项目历史、云端分享和多人协作 |
| 发布 | macOS、Windows，以及测试版 Web 构建 |
写代码以后还能扩展到什么程度？
程序扩展可以提供 React UI、自定义剧本方法、章节调度策略、设置、存档字段和系统界面，也可以使用 Canvas 或 WebGL 制作小游戏及特殊渲染。
扩展能够读取和控制剧情变量、角色、场景、声音、镜头、存档和界面，因此可以实现背包、好感度、任务、地图选点、日程、战斗面板、解谜和小游戏等系统。扩展入口见扩展是什么。
Studio 的能力边界在哪里？
- 核心定位是视觉小说：常规文字冒险和 2D 演出是内置能力；复杂 3D 世界、物理模拟、大型实时动作游戏不属于内置工作流。
- 可视化 UI 不是网页导入器：它适合用编辑器搭建游戏界面，但不能把任意网站、HTML 包或外部程序一键嵌入。
- 小游戏需要适配或开发：有 React、TypeScript、Canvas 或 WebGL 源码时可以改造成扩展；只有 EXE 或其他引擎成品时，通常需要重写交互层。
- Web 构建仍是测试版：浏览器不支持
ctx.native.node，桌面原生扩展不能直接用于 Web；构建产物也不提供资源加密。
- 移动端尚未提供正式构建：当前发布目标以 macOS、Windows 和测试版 Web 为主。
- Studio 不替代素材工具：图片、立绘、音乐、视频、字体和配音仍需自行制作或合法取得授权。
- 项目历史不备份素材文件：它可以恢复剧本和配置，不能找回已经删除的图片、音频或视频。
- 实时协作只同步增量：首次加入前仍需通过云端分享或其他方式取得完整项目。
我应该选择哪种制作方式？
| 目标 | 推荐方式 |
|---|
| 制作常规 Galgame | 可视化剧本 Block + 内置界面 |
| 修改标题页、菜单或 HUD | 可视化 UI |
| 制作复杂动态界面 | 可视化 UI + TypeScript 控制器 |
| 制作小游戏、Canvas 或 WebGL 内容 | 程序扩展 UI |
| 接入已有网页或外部小游戏 | 取得源码后适配为扩展，不建议直接嵌入成品 |
| 发布浏览器版本 | Web 测试版构建，并避开 Node 原生能力 |
| 多人共同编辑 | 先分享完整项目，再开启实时协作 |
安装与工作区
macOS 提示应用“已损坏”，怎么办？
确认安装包来自 LetsGal Studio 官网，然后在终端执行：
xattr -dr com.apple.quarantine "/Applications/LetsGal Studio.app"
工作区和项目有什么区别？
工作区是保存多个项目的文件夹，每个项目是其中一个独立子目录。不要把某个具体项目目录再次选成工作区，否则项目列表和文件层级容易混乱。
需要更换工作区时到 Studio 设置中修改。移动项目前先关闭 Studio，再整体移动项目文件夹，不要只移动其中的章节或资源目录。
为什么不能把 Studio 安装目录设为工作区？
安装目录会在应用更新或重新安装时被替换，不适合保存项目。v1.9.8 起 Studio 会阻止选择自身安装目录，避免更新时误删项目；请另选“文档”或其它专门的创作目录。
素材与资源
为什么素材已经在磁盘上，Studio 仍提示缺失？
项目保存的是素材相对路径。在系统文件管理器中移动、重命名或删除文件后，原引用不会自动跟随。
请重新导入文件、恢复原路径，或删除对应引用。可以在资源总览中检查缺失引用及其使用位置。
为什么拖入图片后没有自动出现在剧本里？
导入素材只会把文件加入资源库，或创建角色、场景等实体，不会自动插入剧情 Block。导入后仍需在剧本目标位置添加 Scene、Show Character、Video 等对应 Block。
删除的图片或音频能通过项目历史恢复吗？
不能。项目历史恢复剧本、角色、场景、界面、变量和项目配置，不保存图片、音频、视频等素材文件内容。
素材文件应使用 Time Machine、Windows 文件历史、Git LFS 或其他备份工具保护。详见项目历史。
视频已经导入，为什么预览黑屏？
先确认视频使用受支持的编码。文件扩展名相同不代表内部编码一定兼容；必要时转换为常见的 MP4/H.264 后重新导入。更多检查方法见视频素材常见问题。
Live2D 为什么能导入但不能预览或构建？
Studio 不内置 Live2D Cubism Core。请在 设置 → 第三方授权 → Live2D Cubism 安装本人从官方合法取得的 Cubism SDK for Web；换电脑构建时也需要在新电脑重新安装。详细要求见动态图像与动态立绘。
多个扩展怎样共用道具或图鉴数据？
把静态资料建立为项目数据集合，再分别绑定到扩展声明的数据依赖。数据表属于项目，不会因为卸载某个扩展而删除；扩展开发者可通过 ctx.database访问自己的绑定。
剧本编辑
怎样插入新的 Block？
在空白旁白块按 Tab 打开菜单，再选择对白、场景、声音、条件、变量或演出 Block。连续对白内部也可以按 Tab 调整角色显示名、距离与位置、表情和皮肤。
所有内置 Block 可从Block 总览继续查看。
为什么 Ren’Py 风格代码行不能直接修改某些参数？
代码模式支持直接编辑对白和常用剧本语句。场景、镜头、声音、分支等复杂 Block 在文本行里可能只显示只读摘要。
选中对应行后使用属性检查器，或切回卡片视图修改完整参数。详见Ren’Py 风格代码编辑器。
导入图片或扫描 PDF 时为什么提示需要 OCR？
剧本导入只会把本地提取出的文字交给文本模型，不会直接把图片或二进制 PDF 发给模型。扫描件没有文字层时，请先使用 OCR 工具转换成可复制文本或带文字层的 PDF，再重新导入。
场景切换时角色或旧画面没有按预期清除，怎么办？
Scene Block 负责切换背景，但复杂换场可能还需要移除角色、销毁场景或使用幕布遮挡多个操作。
规则图素材缺失会导致剧情卡住吗？
不会。规则图为空或加载失败时，场景转场会安全退化为随机溶解。自定义规则图需要作为“规则图”素材导入；也可以直接选择 Studio 提供的内置规则图。
可视化 UI 与小游戏
怎么制作可视化 UI？
可视化 UI 适合制作标题页、菜单、HUD、弹窗、任务面板和简单剧情交互，不需要先写 React 代码。
基本流程：
- 进入“个性化 → 项目设置”。
- 在左侧扩展树中新建或选择一个本地扩展。
- 展开扩展下的“界面”，点击新增并输入界面名称。
- 在设计视图中添加文字、图片、按钮、列表、表单或智能组件。
- 使用右侧检查器调整位置、尺寸、锚点、样式、数据绑定和点击动作。
- 到动画视图配置入场、退场和页面动画。
- 切换到预览视图，实际测试按钮、变量、数据和关闭流程。
只做排版和内置动作时，不需要初始化扩展程序。需要复杂计算、动态生成内容或调用外部服务时，可以再为扩展初始化程序，并通过 TypeScript 控制现有界面。
完整教程见可视化界面编辑器，元素、数据和动画分别见界面元素、界面数据与动作和界面动画。
怎么制作一个标题画面？
最快的方式是修改项目自带的标题画面：
- 进入“个性化 → 项目设置”。
- 在扩展树中展开“默认游戏壳 → 界面”。
- 选择“标题画面”并进入编辑器。第一次修改时，Studio 会为当前项目创建可编辑副本。
- 更换背景图、Logo 和标题文字，再调整按钮的位置、字体、颜色和动画。
- 切换到预览视图，依次测试新游戏、继续、设置、鉴赏和退出。
- 回到剧本，在入口章节需要显示标题的位置插入一个“显示界面”Block，并选择标题画面。
创建或修改可视化界面，只是保存了这份界面本身。要让它在剧本运行到某个位置时真正出现，还需要插入“显示界面”Block。
在剧本中显示标题画面
- 打开项目的入口章节。
- 在开头的空白旁白块按 Tab。
- 选择“显示界面”。
- 在界面选择器中选择“系统插槽 → 标题画面”；如果没有使用系统插槽，也可以选择刚才创建的具体可视化界面。
- 标题画面通常设为“模态 + 顶+”，让剧本等待玩家点击开始、继续或其他入口。
推荐选择“系统插槽 → 标题画面”。这样以后更换标题画面的绑定目标，剧本中的 Block 会自动跟随，不需要重新选择界面。完整参数见显示 UI。
标题画面常用按钮及对应动作：
| 按钮 | 点击动作 |
|---|
| 开始游戏 | 开始新游戏 |
| 继续游戏 | 继续最近存档 |
| 读取存档 | 打开读档 |
| 设置 | 打开设置 |
| 历史记录 | 打开历史记录 |
| 鉴赏 | 打开鉴赏 |
| 退出 | 退出游戏 |
- 新建一个本地扩展，并在扩展下创建可视化界面。
- 按项目画布尺寸添加铺满画面的背景、Logo、按钮和装饰元素。
- 为按钮配置上表中的系统动作。
- 到“个性化 → 项目设置 → 游戏系统”。
- 把“标题画面”插槽绑定到新建的界面。
- 回到入口章节，插入“显示界面”Block，并选择“系统插槽 → 标题画面”。
- 从项目入口运行预览，检查首次启动、已有存档和返回标题三种状态。
优先使用“打开设置”“打开读档”等系统动作，不要让按钮写死某一份具体界面。以后替换设置或存读档界面时，标题画面会自动跟随新的系统绑定。
“恢复原始界面”会丢弃当前项目对默认标题画面的修改。进行大改前，可以把标题画面复制到自己的本地扩展中保留版本。
Studio 能直接插入外部制作的小游戏吗？
Studio 目前没有把任意 HTML 网页、独立 EXE 或其他引擎导出包直接嵌入剧情的通用导入按钮。外部小游戏能否使用，取决于你是否拥有源码，以及它能否适配 Studio 的运行环境。
- 已有 React、TypeScript、Canvas 或 WebGL 源码：可以改造成程序扩展 UI，通常是最合适的接入方式。
- 只有网页构建产物：不能保证直接嵌入；建议取得源码后改造成扩展，而不是依赖
iframe 或外部网页。
- 只有独立可执行程序：不适合作为游戏内 UI，也无法用于 Web 构建。桌面端即使通过原生能力启动外部程序，也会带来打包、权限、存档和跨平台问题。
- 来自其他游戏引擎的工程：通常需要重写交互层，或者把核心规则和素材迁移到 Studio 扩展中。
接入第三方小游戏前，还要确认代码、素材、字体、音乐和第三方库的许可证允许随作品分发。
能不能直接在 Studio 里开发小游戏？
可以。推荐使用“程序扩展 + 程序 UI”，通过 React、Canvas 或 WebGL 实现小游戏画面和交互，再使用 Studio SDK 连接剧情。
典型结构是：
- 新建本地扩展并初始化程序。
- 在扩展的
render() 中返回小游戏的 React 组件。
- 使用
ctx.variables、扩展存档 Schema 或项目变量保存分数、结果和进度。
- 使用角色、场景、音频和素材 API 读取项目内容。
- 在剧本中插入“显示 UI”Block，选择该扩展的程序 UI。
- 把界面设为“模态 + 顶+”，让剧情等待小游戏结束。
- 小游戏结束时写入结果并关闭 UI，剧本再根据变量进入成功或失败分支。
如果小游戏主要是按钮、文字、图片和简单状态切换，可以先用可视化 UI 搭建，再通过 ctx.visualUI补充逻辑；需要实时循环、碰撞、Canvas、WebGL 或复杂动画时，直接使用程序 UI 更合适。
开发入口见扩展是什么和开发流程。剧本打开方式见显示 UI，存档数据见存档 Schema。
小游戏如果需要同时发布到 Web，请使用浏览器兼容 API，不要依赖 ctx.native.node。桌面原生模块在 Web 构建中不可用。
预览与调试
预览为什么停在某个位置不再继续？
先查看调试面板的当前 OP 和日志。常见原因包括：
- Wait Block 正在等待时间或玩家点击；
- 分支正在等待玩家选择；
- 输入界面或自定义 UI 尚未关闭；
- 引用的 Fragment、变量、素材或扩展方法无效；
- 自定义扩展的异步方法没有结束。
可以从当前章节或指定位置重新运行，并参考运行与调试定位具体操作。
为什么预览清晰，但换一台设备后画面性能不同？
内部渲染倍率、默认帧率和特效质量都会影响 GPU 开销。高倍率、高帧率和高特效质量组合在低性能设备上可能不稳定。
到画面渲染设置检查渲染精度、倍率上限、图片采样、默认帧率和特效质量，并在目标设备上实际测试。
打包与 Web
构建为什么因为缺失素材而中断？
构建会扫描所有有效引用。只要剧本、角色、场景、界面或扩展配置仍引用不存在的文件，就不会生成一个内容残缺的游戏包。
根据错误信息列出的引用位置重新导入素材、恢复路径或删除引用，再重新构建。详见缺失素材会中断打包。
Web 构建完成后应该上传哪些文件？
保持以下同级目录结构整体部署：
dist/
├── web/
└── assets/
web 是页面，assets 是游戏资源。使用默认 ../assets/ 时不需要提前填写域名；只有把素材独立部署到 CDN 时，才需要填写完整资源地址并正确配置跨域。
完整说明见Web 测试版。
为什么不能直接双击 Web 构建里的 HTML 试玩？
浏览器通过 file:// 打开页面时会限制模块和资源请求。请使用构建完成后的“本地试玩 Web”，或通过本地 HTTP 服务访问 dist/web，不要直接双击 HTML 文件。
桌面版可用的扩展为什么在 Web 版失效？
浏览器不能调用 Node 原生模块。使用 ctx.native.node 的扩展只适用于桌面环境，不会在 Web 构建中运行。需要同时发布 Web 版时，应提供浏览器兼容实现或避免依赖原生能力。
当前构建产物会加密游戏资源吗？
不会。当前构建仍处于预览阶段，剧本和素材可能被直接查看，不应把构建产物当作资源加密或版权保护方案。
项目历史与协作
项目历史多久创建一次快照？
默认每 2 分钟检查一次，可以在“设置 → 系统”调整为 1–120 分钟。只有项目内容发生变化时才创建自动快照；删除、重命名、排序以及打开或关闭项目还可能创建里程碑。
输入协作邀请码后，为什么要求先导入项目？
邀请码只建立实时增量同步，不包含完整项目。请让发起者先通过云端分享发送项目，导入并打开同一个项目后，再输入 8 位邀请码加入。
协作时章节为什么变成只读？
同一章节同一时间只由取得编辑权的成员修改。其他成员正在编辑、当前正在申请编辑权或网络断开时，本机会显示只读原因。查看顶部成员状态和协作动态，等待编辑权释放或连接恢复。
为什么协作成员没有收到新增素材？
章节和项目配置会自动同步，图片、音频、视频等素材需要在协作面板手动点击“同步素材”。单个超过 20 MB 的文件会跳过，大文件请重新使用云端分享传递。
扩展与更新
分享项目后，对方还需要安装相同扩展吗？
项目启用扩展后，运行所需的项目发行物会跟随项目保存。正常复制或云端分享完整项目时，对方不需要另行安装原扩展；扩展源码不会包含在项目发行物中。
如果只是单独复制章节，扩展、素材或配置仍可能缺失。
为什么调用扩展方法时找不到某个方法？
确认扩展已经加入并启用。部分扩展方法还会根据项目设置按需显示；关闭对应能力后，它不会出现在新建候选中，但剧本里已经使用的方法仍会保留并正常执行。
Stable 和 Beta 更新通道有什么区别？
Stable 适合日常创作，Beta 用于提前体验尚未完全稳定的功能。切换通道不会修改项目内容，但 Beta 版本创建或升级的数据不一定适合旧版 Studio 打开。
更新设置和差分下载说明见Studio 设置 · 关于。
仍然无法解决
反馈问题时，建议同时准备：
- Studio 完整版本号和更新通道；
- 操作系统版本；
- 能稳定复现问题的步骤；
- 报错文字、构建日志或调试日志；
- 不包含敏感内容的截图；
- 问题是否只在某个项目、某个平台或某种构建目标出现。
先用项目副本复现问题。不要直接发送包含未公开剧本、账号令牌或商业素材的完整项目。 
