快速上手
先决条件
Naninovel 是 Unity 游戏引擎 的扩展，因此强烈建议在开始使用 Naninovel 之前至少 学习使用 Unity 的基础知识。
如果您不打算在 Naninovel 之外实现自定义游戏玩法，可以跳过与场景相关的说明；场景会由 Naninovel 自动处理。
视频指南
如果您更喜欢通过视频学习，可以观看下面的教程，内容与本快速上手指南相对应。
创建 Unity 项目
创建项目时，建议选择基于通用渲染管线（URP）的 Universal 2D 或 Universal 3D 模板。旧版内置渲染管线（BiRP）也能使用，但 Unity 已不再积极维护，预计今后会弃用。不建议使用高清渲染管线（HDRP）：虽然通常能运行，但部分渲染功能可能无法直接兼容。
选择 2D 还是 3D 取决于您正在构建的游戏风格。对于大多数标准视觉小说，我们建议选择 2D，这样图像将默认作为精灵资产导入，您无需手动调整导入设置。您可以稍后在 项目设置 中更改编辑器行为模式。
创建新项目后，Unity 会自动添加一个示例场景，其中包含“Main Camera”，以及模板自带的其他游戏对象；具体包含哪些对象取决于所选模板。
Naninovel 不依赖于场景；因此，我们建议从场景中删除这些对象，以防止不必要的性能开销或与 Naninovel 系统的冲突。您也可以删除示例场景本身，但建议在项目中至少保留一个场景，以便某些编辑器功能正常工作。
优化编辑器
注意
此步骤为可选项，并非使用 Naninovel 的必要条件。其目的仅在于提高 Unity 编辑器的性能。如果您不确定项目需要哪些包或模块，请跳过此步骤。
请打开并检查 Unity 项目根目录下“Packages”文件夹中的 manifest.json 文件，它列出了已安装的包和模块。您可能并不需要所有这些包和模块，但每一个都可能拖慢编辑器。以下是 Naninovel 所需的依赖项；请考虑删除不需要的其他项：
com.unity.modules.audio
com.unity.modules.video
com.unity.modules.imgui
com.unity.modules.animation
com.unity.modules.particlesystem
com.unity.modules.imageconversion
com.unity.render-pipelines.universal
com.unity.inputsystem
com.unity.uguiVCS 设置
如果您正在使用版本控制系统，例如 Git，请考虑忽略以下路径，以避免产生不必要的变更：
# 自动生成的临时 Unity 资产。
/Assets/NaninovelData/Transient*
# 外部工具生成的临时文件。
/Assets/NaninovelData/.nani/Transient*请注意，Assets/NaninovelData 是一个自动生成的文件夹。最初创建后，您可以将其重命名或移动到“Assets”下的任何文件夹（Naninovel 仍然能够找到它）。如果您这样做，上述忽略路径必须相应更新。
示例
Git 忽略配置可以参考 示例项目 中的 .gitignore。该项目为了便于整理，将“NaninovelData”文件夹重命名为“Naninovel”，并移到 Assets/Settings 下。您也可以在自己的项目中按同样的方式移动这个文件夹。
安装 Naninovel
发布流
Naninovel 通过 3 个发布流分发：preview（预览版）、stable（稳定版）和 final（最终版）。
preview 流紧跟最新开发进展，更新最频繁，包含所有最新功能。不过，它偶尔也会引入破坏性更改或错误。如果项目还处于开发初期，或需要其他版本尚未提供的特定功能，请选择此流。
stable 流是折衷方案：它只接收错误修复，没有最新功能，但也没有任何破坏性更改。在大多数情况下建议使用。
final 流经过的测试最充分，稳定性最高，但版本也最旧，且不在 技术支持 范围内。仅在项目已发布且无法升级时，才应继续使用最终版本。
stable 流同时发布在 GitHub 和 Unity 的 Asset Store 上（不过 Asset Store 上的发布不如 GitHub 频繁），而 preview 和 final 流仅在 GitHub 上提供。
从 Asset Store 安装
安装 Naninovel 最简单的方法是通过 Unity Package Manager（UPM）的“My Assets”选项卡。打开 Package Manager 窗口，找到 Naninovel，然后单击“Install”。
有关使用 UPM 的更多信息，请参阅 Unity 文档。
从 GitHub 安装
preview 和 stable 流中的最新 Naninovel 版本通过 Naninovel GitHub 存储库分发。要访问存储库，请 注册您的 Naninovel 许可证 并按照仪表板上的说明指定您的 GitHub 用户。
获得存储库的访问权限后，请通过 Unity 的 Package Manager 将 https://github.com/naninovel/upm.git#X.X 添加为 Git 包，其中 X.X 是您想要安装的发布版本，例如：
https://github.com/naninovel/upm.git#1.22您可以在 发布页面 上找到所有可用的版本及其 Git URI。
如果您希望持续使用 preview 流的最新版本，或在 stable 流的补丁推送到 GitHub 存储库后立即获取，这种安装方式会很方便。在 Package Manager 窗口中单击“Update”，即可将已安装的包更新到最新提交。
提示
如果在安装包时遇到错误，请确保您已使用账户仪表板中指定的 GitHub 用户通过身份验证。在 Windows 上进行身份验证的最简单方法是使用 GitHub Desktop 登录。在 macOS 和 Linux 上，请改用 GCM。有关 更多信息，请参阅 Unity 指南。
从归档安装
您也可以从 下载归档 获取安装包。如果需要某个已不再通过 Asset Store 分发的最终版本，可以使用这种方式。归档收录了各个旧版本的最终发布包，覆盖从 1.14 到当前稳定版本的范围。
只需将下载的 .unitypackage 文件拖放到 Unity 编辑器窗口中，然后单击“Import”即可安装该包。有关安装本地包的更多信息，请参阅 Unity 文档。
核心概念
在深入了解 Naninovel 之前，让我们快速了解一下它的一些核心概念。
其中一个基本概念是 Actor（演出元素），后面的指南会反复提到它。Actor 是一种实体，由标识符（ID）、外观、空间（场景）中的位置等参数来描述。
Actor 是一个抽象概念，实际存在的是以下几种具体类型，它们各自带有不同的附加参数：
| Actor 类型 | 附加参数 | 描述 |
|---|---|---|
| 角色 | 朝向 | 代表场景中的角色。 |
| 背景 | 无 | 代表场景中的背景；默认放置在角色 Actor 后面。 |
| 文本打印机 | 文本、作者 ID、显示进度 | 随着时间的推移逐渐显示（打印）文本消息。 |
| 选项处理程序 | 选项 | 允许玩家选择可用的选项之一。 |
设想一个典型的视觉小说画面：背景前方显示着一个角色。用 Naninovel 的术语来描述，就是下面这样：
假设您想改变角色“Kohaku”的情绪或姿势，并且已经准备了多张角色纹理（图像），分别描绘不同的状态。在 Naninovel 中，这些纹理称为 Actor 的外观（appearance）。要切换角色的显示状态，就需要更改该角色 Actor 的外观。同样，要让“MainBackground”显示其他内容，也需要更改该背景 Actor 的外观。
Actor 及其参数通过 剧本脚本 中指定的命令来控制。
另一个广泛使用的概念是 用户界面（UI）。玩家使用 UI 与 Actor 和游戏的其余部分进行交互。这包括各种菜单（标题、存档/读档、设置等）和控制面板（切换自动播放模式、跳过文本等）。默认情况下，UI 元素显示在 Actor 之上。
文本打印机和选项处理程序既是 Actor，也是 UI 元素。它们具备 Actor 的特性，可以通过剧本脚本控制，同时也是玩家与游戏交互的界面。
如果您熟悉编程，可以阅读 引擎架构，从软件工程的角度了解 Naninovel 的设计。
第一步
初次安装 Naninovel 时，会在 Assets/Scenario 文件夹中自动生成几个示例脚本，并自动打开 故事编辑器 选项卡。单击故事编辑器顶部的“Play”按钮进入播放模式。
Unity 编辑器将进入播放模式并显示默认标题 UI。同时，Title 剧本脚本将在故事编辑器中打开，表明它当前正在播放。
不妨试用故事编辑器的各项功能，并尝试编辑脚本，更改会实时应用。示例脚本中的注释简要说明了旁边的命令，可以一并阅读。在标题 UI 中单击“NEW GAME”，即可进入包含更多示例的 Entry 脚本。
添加剧本脚本
熟悉基本流程后，接下来就开始为游戏添加实际内容。在 Naninovel 中，驱动故事的核心资产称为剧本脚本（scenario script）。
目前已有两个自动生成的脚本，下面来学习如何添加新脚本。故事编辑器 也能管理脚本，不过入门阶段我们先按 Unity 的标准流程操作；故事编辑器的具体操作方式可以参阅它的专用指南。
首先，单击“Stop”按钮退出播放模式。一般来说，添加或删除资产、调整项目设置等所有项目级修改，都应在退出 Unity 播放模式后进行。
打开与示例脚本一起自动生成的 Assets/Scenario 文件夹。这就是剧本根目录（scenario root），所有 Naninovel 剧本脚本都存放在这里。在该文件夹内右键单击，选择 Create -> Naninovel -> Scenario Script，创建新的剧本脚本 Test.nani。
注意
剧本脚本（以及其他资产）可以放在项目中的任意文件夹，整理方式和命名也由您决定。不过，所有剧本脚本必须归于 Unity 项目内同一个根目录。只要满足这一点，就可以在该目录下按需创建任意数量、任意层级的子文件夹来整理脚本。
警告
Unity 以特殊方式处理名为“Resources”的文件夹：存储在此类文件夹下的资产被强制包含在构建中，这可能会导致 性能问题。最重要的是，除非指南特别要求，否则切勿将任何内容存储在 Resources/Naninovel 文件夹下，因为这可能会导致各种冲突和未定义的行为。
剧本脚本是扩展名为 .nani 的文本文件。您可以在其中使用 Naninovel 的编剧语言 NaniScript 来控制场景中发生的事情。脚本文件可以用任意文本或代码编辑器打开和编辑，例如 Microsoft Word 或 VS Code。
故事编辑器 写入剧本文件的同样是 NaniScript，因此可以与代码编辑器交替使用。下文会以代码编辑器为例展示脚本片段，但在故事编辑器中也能完成相同的步骤：在行类型下拉列表中从 @ 开始输入，即可看到匹配的命令。
请打开创建的 Test.nani 脚本并添加以下行：
你好，世界！— 执行时，此行将打印“你好，世界！”。
接下来，打开 Entry.nani 脚本并将最后的 @title 命令替换为：
@goto Test— 此命令会转到新建的 Test.nani 脚本继续播放，而不是返回标题菜单。
进入播放模式，开始新游戏，并一直玩到打印出“你好，世界！”。尝试在游戏进行时编辑脚本——更改将立即应用。
添加角色
打开刚才添加剧本脚本时使用的菜单，这次选择 Create -> Naninovel -> Actor Record -> Character，创建一个保存新角色 Actor 配置的角色记录（character record）资产。将这个记录资产命名为 K。使用 K 这样的简短标识符，是因为剧本脚本中会反复用到它，可以省去每次输入全名的麻烦。实际向玩家显示的名称“Kohaku”，则可以在记录资产的 Display Name 中设置。
角色的标识符和显示名称都可以自行选择。需要注意的是，ID 不能包含空白字符或特殊字符，而显示名称可以包含空白字符和任意特殊字符。
提示
您会在我们的配置菜单中找到许多选项。与其他 Unity 菜单一样，大多数控件都有相关的工具提示来解释它们的作用。要查看工具提示，请将鼠标悬停在控件上并稍等片刻——说明将出现在光标下方。
现在，让我们为 Actor 选择实现。Naninovel 中的角色可以基于常规或切片精灵、Live2D 或 Spine 动画模型、3D 网格以及许多其他类型的资产；您也可以添加自己的实现。在本教程中，我们将使用基于 2D 纹理资产（图像）的精灵实现。
最后，为角色分配外观。将纹理拖放到角色记录所在的文件夹中，选中这些纹理，再单击检查器标题栏下方的 Naninovel 图标，选择 Characters -> K。
修改剧本脚本以使用 @char 命令显示添加的角色：
@char K
你好，世界！角色会显示在屏幕中央。未指定外观时，会自动选择名为“Default”的外观。要指定其他外观，请在角色 ID 后加上一个点，再接上外观名称，如下所示：
@char K.Happy
你好，世界！只要已为角色“K”添加了名为“Happy”的外观，现在就会显示相应的精灵，而不是默认精灵。
现在，在文本前加上角色 ID 和冒号，即可将显示的文本与该角色关联：
@char K.Happy
K: 你好，世界！还可以把角色的外观设置与要显示的文本合写在一行，减少输入：
K.Happy: 你好，世界！要隐藏角色，请使用 @hide 命令，后跟 Actor ID：
@hide K添加背景
与角色类似，背景在 Naninovel 中可以用多种方式表示：精灵、视频、场景等；也可以自定义实现。
背景 Actor 可以有多个，彼此独立。不过，典型的视觉小说通常只使用一个背景 Actor，通过切换外观来更换背景。为了简化这种常见操作，@back 命令默认控制 ID 为 MainBackground 的背景 Actor：
@back Road— 该命令将使 MainBackground Actor 过渡到 Road 外观。
创建背景 Actor 记录和分配外观精灵的方式与角色类似：
- 创建一个文件夹来存储背景，例如
Assets/Backgrounds - 右键单击该文件夹并选择
Create -> Naninovel -> Actor Record -> Background以创建MainBackground记录 - 在检查器中查看该记录并选择实现，例如
SpriteBackground - 分配外观资源
在背景外观之间切换时，默认使用交叉淡入淡出 过渡效果。要更改效果，请在外观名称后指定过渡类型：
@back Road
@back Ruins.RadialBlur这将使用“RadialBlur”过渡效果从“Road”过渡到“Ruins”。
要引用除主背景以外的背景（例如，如果您希望将多个背景叠加在一起），请指定该 Actor 的 ID。例如，假设除主背景外还存在一个 ID 为 Flower 的背景 Actor，则以下命令会将其外观更改为“Bloomed”，然后更改为“Withered”：
@back Bloomed id:Flower
@back Withered id:Flower使用相同的 @hide 命令隐藏背景：
@hide Flower添加音频
要向 Naninovel 注册 BGM（背景音乐）或 SFX（音效）音频资源，先选中音频剪辑资产，再打开之前注册角色和背景资源时使用的检查器菜单，这次选择“BGM”或“SFX”。
要将注册的音频资源作为背景音乐播放，请使用 @bgm 命令：
@bgm CloudNine切换音乐音轨时会自动应用交叉淡入淡出效果。音乐默认循环播放，是否循环、音量大小以及淡入淡出的持续时间，都可以通过命令参数调整。
相比之下，音效默认不会循环播放。使用 @sfx 命令播放它们：
@sfx Explosion要停止正在播放的 BGM 或 SFX，请分别使用 @stopBgm 和 @stopSfx 命令：
@stopBgm CloudNine
@stopSfx Explosion管理资源
您可以在项目设置窗口的 Naninovel 选项卡下查看所有已注册的资源，以及 Actor 和其他引擎选项；使用 Naninovel -> Configuration 编辑器菜单可快速访问配置。
您可以自由更改资源路径（默认情况下它们与资产名称相同），这有助于组织资源。注册的路径是您在剧本脚本中引用资源时实际使用的路径。例如，将音效 Explosion 的路径更改为 Battle/Explosion 后，请使用新路径来播放它：
@sfx Battle/Explosion添加或修改资源后，故事编辑器和 VS Code 扩展都会自动同步这些更改，并更新相关列表。
提示
考虑安装 Unity 的 Addressables 包，以完全掌控资产在最终构建中的组织和打包方式——Naninovel 将自动与该包集成。
对话模式
尽管 Naninovel 主要设计为构建视觉小说的基础，但它也可以用作任何类型游戏的嵌入式对话或过场动画系统。
您可以手动配置引擎，使其适合这种嵌入式用途，也可以使用专门的“Minimal Mode”（最小模式）开关。该开关会自动修改配置，移除大多数内置 UI，并禁用部分功能，将引擎精简到最低限度。
通过 Naninovel -> Set Up Minimal Mode Unity 编辑器菜单启用最小模式。
警告
最小模式设置过程将修改引擎的默认配置和资源，并且更改无法自动撤消。仅当您开始一个新项目，并打算将 Naninovel 用作嵌入式对话系统而不是视觉小说引擎时，才启用该模式。
指南的“高级”部分详细介绍了如何通过 C# 将引擎集成到现有代码库中。这里先演示一种无需编写代码的简单对话交互：玩家将鼠标移到可交互对象上，单击后开始对话。请在空场景中添加以下对象：
- 一个带有
Event / Event System组件的对象- 将
Naninovel/Resources/Naninovel/Input/DefaultControls分配为Actions Asset
- 将
- 一个带有
Event / Physics Raycaster组件的摄像机对象 - 一个将充当对话触发器的立方体
- 删除附加到立方体的默认碰撞体组件
右键单击立方体，选择 Naninovel -> Dialogue，即可为它自动设置对话触发器。随后在检查器中查看新建的子对象 Dialogue，并为其分配要播放的剧本脚本资产。
接下来，在 Dialogue/Trigger 对象上设置触发条件：
- 将
Collide With和Raycast From设置为“None” - 将
Perform Input设置为 Naninovel 输入操作资产中的UI/Click操作 - 启用
Hover With Pointer
进入播放模式并将鼠标悬停在立方体上——当鼠标光标位于其上方时，提示将做出反应。左键单击以开始对话。要退出对话，请使用 @exitDialogue 命令。
Trigger Events 组件提供了许多选项，只需调整这些选项，就能设置大多数常见的交互方式。例如，在第一人称视角下从一定距离注视对象、在横向卷轴视角下发生碰撞，或在第三人称视角下将指针悬停在对象上后按键。各选项的具体作用可以查看对应的工具提示。
演示示例
Naninovel 包包含两个基本示例：
- Visual Novel — 一个具有多条路线的基本视觉小说模板，演示了占位符 Actor、各种命令、普通变量和元变量、可自定义角色名称以及其他传统 VN 机制的使用。
- Dialogue System — 一个 3D 横向卷轴场景，其中 Naninovel 用作嵌入式对话系统，展示了临时打印机、气泡选项处理程序、与 Cinemachine 的集成以及其他常见用法。
这两个示例都可以通过 Unity Package Manager 导入：选择 Naninovel 包，打开“Samples”选项卡，再单击相应示例的“Import”按钮。
更多高级用法可以参考 示例项目。其中包含许多针对特定用途的示例，例如 Live2D 和 Spine 角色、自定义 Actor 着色器、交互式地图、视频 Actor、日历和库存自定义 UI 等。