模板

你可以通过运行以下命令，从模板生成一个新项目：

npm create pixi-vn@latest

交互式演示

如何使用模板

如果你正在阅读本页，说明你可能已经有了一个由模板生成的项目。 以下小节将引导你完成让它启动运行所需的最初几步。

初始设置

用你的 IDE 打开项目文件夹。 下面的示例使用的是 Visual Studio Code。

项目打开后，VS Code 会自动提示以下几件事：

• 安装推荐的扩展 — 会出现一条通知，要求你安装工作区推荐的扩展。 强烈建议你接受安装。 如果没有出现该通知，你也可以在扩展面板中通过筛选 推荐的扩展 来手动安装它们。
• 运行启动任务 — VS Code 可能会提示你运行已配置好的启动任务，用来安装所有项目依赖。 如果你更喜欢手动操作，可以运行：

npm install

运行项目

该模板包含一组为 VS Code 预先配置好的启动配置。 如果你不熟悉它们：启动配置是一些快捷方式，用来告诉 VS Code 如何启动你的项目（并可选地附加调试器），这样你就不需要每次都在终端中输入命令。 你可以从运行和调试面板（左侧边栏中的播放按钮图标，或按 F5）访问它们。 在面板顶部的下拉列表中选择你想要的配置，然后按绿色的播放按钮。

以下配置可供使用：

• Debug Game：这是你在开发过程中最常使用的配置——每次保存文件时，浏览器都会自动刷新。 请注意，在此模式下动画可能不够流畅，资源加载速度也可能比最终发布的版本慢。
• Debug Game Preview：它能更贴近地模拟游戏发布后的实际表现：动画流畅，加载时间真实，并启用了各项优化。 在发布之前，如果你想确认一切看起来和感觉都正确，可以使用此配置。
• Run as Desktop App (Dev)：它会编译 Rust/Tauri 后端，并以原生桌面窗口的形式启动游戏。 如果你的模板不面向桌面或移动平台，则不会出现此配置。

自定义样式

该模板的界面（UI）完全基于 shadcn/ui 构建，这意味着你可以自定义颜色主题，而无需修改任何组件代码。

打开 shadcn/ui 主题构建器，按你的喜好调整颜色，然后导航到页面的复制部分，复制生成的 CSS 命令。 在你的项目根目录下运行该命令：

npx shadcn@latest add <paste-the-generated-command-here>

应用之后，建议重新格式化源文件：

npm run format

关于更多自定义内容——字体、全局样式等——请参阅 样式与字体。

项目结构

模板屏幕

该模板附带一组预先构建好的屏幕，涵盖了视觉小说的基本组成部分。 每个屏幕都是一个 React 组件，并连接到由 TanStack Router 管理的路由。

• 主菜单（/）— 玩家启动游戏时看到的第一个屏幕。 它提供了开始新游戏、继续已保存的游戏，以及打开设置的入口。
• 叙事屏幕（/game/narration）— 展示故事的核心游玩屏幕。 它渲染对话、角色立绘、背景和选项。
• 设置——设置面板没有自己专属的路由。 相反，它使用 Search Params 将自身覆盖显示在当前活动的任何屏幕之上。 这种方式让 URL 保持简洁，同时仍允许玩家在游戏中的任何位置打开设置，并在设置的各个板块（音频、显示、语言等） 之间导航，而不会丢失自己原来所在的位置。
• • 导航屏幕（/game/navigation）— 仅限 Point & Click（点击式冒险）。 它让玩家在房间之间导航，并执行当前位置可用的各种操作。
• 地图屏幕（/game/map）— 仅限 Point & Click（点击式冒险）。 它显示地图，并让玩家从一个位置移动到另一个位置。 它还支持管理多个地图。