概述与前置知识

このコンテンツはまだ日本語訳がありません。

到目前为止，你已经了解了如何使用末语引擎的标准框架来编写视觉小说剧本。对于大多数创作者而言，这已经足够了。但如果你想进一步定制游戏的外观和体验——比如重新设计标题画面、更改对话框样式、添加新的 UI 界面、实现自定义的游戏机制——你就需要深入到框架层进行修改。

本章将帮助你理解标准框架的结构，并指导你如何在此基础上进行定制。

什么时候需要定制框架？

以下是一些常见的定制场景：

修改标题画面 — 更换背景图、按钮位置、添加动画效果
自定义对话框 — 改变文本框的外观、姓名框样式、按钮布局
调整设置界面 — 添加新的设置项、修改界面布局
创建新的页面 — 添加 CG 鉴赏、音乐鉴赏、制作人员名单等
自定义角色表现 — 修改角色立绘的切换动画、高亮效果
添加新的命令 — 在剧本中支持新的指令（如屏幕震动、天气效果等）
实现特殊交互 — 选择分支、小游戏、地图探索等

架构总览

末语引擎采用三层架构设计：

┌─────────────────────────────────────┐
│         React 框架层（你在这里）       │  ← TypeScript / React
│   页面、组件、状态管理、命令处理        │
├─────────────────────────────────────┤
│        QuickJS 运行时 + Kit SDK       │  ← JavaScript (受限环境)
│   渲染器、事件系统、引擎通信 API       │
├─────────────────────────────────────┤
│          Rust 引擎核心               │  ← Rust (wgpu + winit)
│   图形渲染、音频、资源管理、插件       │
└─────────────────────────────────────┘

定制框架意味着在最上层工作——你使用 TypeScript 和 React 编写代码，通过 @momoyu-ink/kit SDK 与引擎层交互。你不需要了解 Rust 或底层渲染细节。

前置知识

定制框架需要以下基础知识：

TypeScript

末语框架使用 TypeScript 编写。如果你只熟悉 JavaScript，TypeScript 的学习曲线很平滑——它只是在 JavaScript 基础上添加了类型注解。

React

框架使用 React 来构建用户界面。你需要理解：

组件（Component）：独立的 UI 单元，接受属性（props）、管理自己的状态
Hook：useState、useEffect、useCallback、useRef 等常用 Hook
JSX：在 JavaScript 中编写类似 HTML 的语法

如果你还不熟悉 React，建议先阅读：

React 官方中文教程

状态管理：Valtio

框架使用 Valtio 作为状态管理库。Valtio 采用”可变代理”的方式——你可以像修改普通对象一样修改状态，UI 会自动更新：

import { proxy, useSnapshot } from 'valtio';

// 创建状态
const state = proxy({ count: 0 });

// 在组件中使用
function Counter() {
  const snap = useSnapshot(state);  // 读取（只读快照）
  return (
    <text
      text={`Count: ${snap.count}`}
      onClick={() => { state.count++; }}  // 直接修改原始对象
    />
  );
}

Valtio 文档

标准框架 vs 从零开始

末语的 JavaScript SDK（@momoyu-ink/kit）提供了底层的渲染和通信能力。在此之上，标准框架（即你克隆的项目模板）提供了一整套开箱即用的功能：

标准框架提供的	从零开始需要自己实现
标题画面、设置界面、存档界面	所有页面和交互
完整的命令处理系统	剧本命令解析和执行
背景、角色、文本框的渲染和动画	所有视觉表现
页面路由和导航	页面管理
游戏状态管理	状态方案设计
存档/读档功能	存档系统对接

对于绝大多数项目，我们推荐基于标准框架进行定制，而非从零开始。标准框架经过了充分的测试，并且各模块之间已经做好了协调。你只需要修改需要调整的部分。

接下来，我们将从项目结构开始，逐步了解框架的每个部分。