什么是Raven引擎

logo

Raven 是一款基于 Rust 语言开发的现代化视觉小说/文字冒险游戏引擎，专注于为开发者提供简洁高效的叙事工具链。凭借 Rust 的内存安全性与高性能特性，Raven 能够流畅运行于多平台，同时通过声明式脚本语法和模块化设计，大幅降低视觉小说的开发门槛。

这个文档是什么？

这份文档不是面对开发者的开发教程，而是源码编译手册，想研究和深度改造引擎的开发者可以阅读此文档 得到引擎改造思路和详尽的编译方法，同时可以了解引擎的架构

开源地址

https://github.com/e72uj/Raven

联络我们

🐧群:818497392

稳定性警告

⚠️ 注意：当前项目处于早期开发阶段，API 会有重大变更，不建议在生产环境中使用。

或者：

状态 Raven 引擎目前处于 Alpha 阶段，核心功能仍在开发中，存在不稳定因素。

系统要求

下面为作者的设备 配置为真实的调试和运行机器 芯片: M4 pro 内存: 24G 硬盘: 512G

开发环境配置

下面演示一下Raven开发环境配置的流程：

安装Rust

编译和运行Raven引擎需要使用rust，请访问官方进行数据

https://www.rust-lang.org/zh-CN/

拉取最新代码

使用GitKraken 或者是 GitHub Desktop 工具进行代码拉取。地址如下：

https://github.com/E72UJ/Raven.git

创建 crates 目录

drwxr-xr-x@ 13 furau  staff         416  6 10 11:42 assets
-rw-r--r--@  1 furau  staff      126301  5 18 18:29 Cargo.lock
-rw-r--r--@  1 furau  staff         995  5 18 18:04 Cargo.toml
drwxr-xr-x@  7 furau  staff         224  5 27 19:59 cli
drwxr-xr-x@  8 furau  staff         256  5 18 16:53 crates
-rw-r--r--@  1 furau  staff  1713670585  5 28 00:04 crates.zip
drwxr-xr-x@  6 furau  staff         192  6  2 05:39 demo
drwxr-xr-x@  8 furau  staff         256  6 11 17:59 docs
drwxr-xr-x@  9 furau  staff         288  6  7 08:54 examples
-rw-r--r--@  1 furau  staff       10172  5 14 14:02 LICENSE-APACHE.txt
-rw-r--r--@  1 furau  staff        1151  6  2 05:43 README.md
drwxr-xr-x@  3 furau  staff          96  5 15 08:19 src
drwxr-xr-x@  8 furau  staff         256  5 14 06:10 target

编译程序

编译依赖包

为方便国内开发者编译引擎，我们准备了一个 引擎所用依赖 的国内镜像版本。 其中包含许多编译中间文件。请选择性使用 压缩包基础需求结构如下。

bevy
bevy_flash
flash_runtime
swf_animation-main
swf_macro

地址

[https://www.123865.com/s/ADdHjv-Oxsd3](https://www.123912.com/s/bGVovd-Ewwtd?pwd=Rb1V# 提取码:Rb1V)

Windows 编译手册

Macos 编译手册

常用词汇表

基本概念

引擎架构

graph LR A[创作工具] -->|生成| B[YAML配置文件] C[资源文件] -->|路径引用| B B -->|输入| D[Rust渲染引擎] D -->|输出| E[视觉小说画面]

工作流程

目录结构

Rust 项目目录结构分析

Cargo.toml - Rust 项目的配置文件，定义了项目元数据、依赖关系和构建设置

Cargo.lock - 锁定文件，记录了精确的依赖版本，确保构建的可重现性

src/ - 主要的源代码目录，包含项目的核心代码

target/ - Cargo 构建输出目录，包含编译后的二进制文件、库文件等

项目组织结构

crates/ - 包含多个子 crate（Rust 包），表明这是一个工作空间（workspace）项目

crates.zip - crates 目录的压缩备份

cli/ - 命令行界面相关代码，独立的 CLI 工具模块

文档和示例

README.md - 项目说明文档

docs/ - 详细的项目文档

examples/ - 使用示例和演示代码

demo/ - 演示相关文件

资源文件

assets/ - 项目资源文件，如配置文件、数据文件等

images/ - 图片资源

许可证文件

LICENSE 和 LICENSE-APACHE.txt - 项目许可证文件，采用了 Apache 许可证

资产文件结构

const EMBEDDED_FONT_FIRA_MONO: &[u8] = include_bytes!("../../crates/assets/fonts/FiraMono-Medium.ttf");
const EMBEDDED_FONT_GENSEN_MARU: &[u8] = include_bytes!("../../crates/assets/fonts/GenSenMaruGothicTW-Bold.ttf");
const EMBEDDED_FONT_SOURCE_HAN: &[u8] = include_bytes!("../../crates/assets/fonts/SourceHanSansSC-Medium.otf");
const EMBEDDED_RAVEN_EXE: &[u8] = include_bytes!("../../crates/assets/Raven");
const EMBEDDED_PORTRAIT_ALICE: &[u8] = include_bytes!("../../crates/assets/portraits/alice.png");
const EMBEDDED_PORTRAIT_BOB: &[u8] = include_bytes!("../../crates/assets/portraits/bob.png");
const EMBEDDED_PORTRAIT_NARRATOR: &[u8] = include_bytes!("../../crates/assets/portraits/narrator.png");
const EMBEDDED_SVG_SCIHUB: &[u8] = include_bytes!("../../crates/assets/portraits/SciHub.svg");
const EMBEDDED_MAIN_YAML: &[u8] = include_bytes!("../../crates/assets/main.yaml");
const EMBEDDED_DIALOGUES_YAML: &[u8] = include_bytes!("../../crates/assets/dialogues.yaml");
const EMBEDDED_CHAR_HEROINE_DEFAULT: &[u8] = include_bytes!("../../crates/assets/characters/heroine/default.png");
const EMBEDDED_CHAR_PROTAGONIST_DEFAULT: &[u8] = include_bytes!("../../crates/assets/characters/protagonist/default.png");
const EMBEDDED_CHAR_VILLAIN_DEFAULT: &[u8] = include_bytes!("../../crates/assets/characters/villain/default.png");
const EMBEDDED_SVG_LONG: &[u8] = include_bytes!("../../crates/assets/characters/svg/long.svg");
const EMBEDDED_SWF_66: &[u8] = include_bytes!("../../crates/assets/swf/66.swf"); // 新增SWF资源
文件/文件夹描述
assets存放项目所需的资源文件,如图片、字体等
Cargo.tomlRust 项目的配置文件,定义了项目的名称、版本、依赖等信息
Cargo.lock记录了项目依赖的确切版本,确保项目在不同环境下都使用相同的依赖版本
cli命令行工具相关的源代码
crates存放项目发布到 crates.io 的压缩包
crates.zip项目的发布压缩包
demo项目的示例代码
docs项目的文档
examples存放项目的示例代码
LICENSE-APACHE.txt项目的 Apache 2.0 许可证
README.md项目的自述文件
src项目的源代码文件夹
targetRust 编译器生成的目标文件存放目录

DSL 设计

最后更新 2025/11/04 作者 furau

分层系统

默认层级结构

#![allow(unused)]
fn main() {
show alice happy          # 显示在 master 层
show alice happy at left   # 在指定位置显示
show bg school            # 背景层
show overlay ui_element   # UI层
}

多对象

每个层可以有多个对象，用标签区分

#![allow(unused)]
fn main() {
show alice happy as alice_main
show alice sad as alice_memory  # 同一角色的不同实例
}

替换机制

#![allow(unused)]
fn main() {
show alice happy     # Alice 显示为开心
show alice sad       # Alice 自动从开心切换到伤心（替换，不是叠加）
hide alice          # Alice 完全消失

show bg room        # 显示房间背景  
show bg school      # 背景自动从房间切换到学校
}

对象遮蔽

#![allow(unused)]
fn main() {
character Alice {
    name = "爱丽丝";
    sprite = "characters/protagonist/default.png";
}
character Alice {
    name = "摩西";
    sprite = "characters/protagonist/sad.png";
}
}

执行策略

核心分段策略

#![allow(unused)]
fn main() {
  scene 场景1 {
            // 连续执行的指令
            show character Alice
            show background Hello
            play_music "intro.mp3"
            
            // 自动暂停点 - 对话
            narrator "欢迎来到这个神奇的世界！"
            
            // 自动暂停点 - 角色对话  
            dialog Alice "你好，我是Alice！"
            dialog Alice "很高兴见到你！"
            
            // 连续执行的场景切换
            hide background Hello
            show background School
            set Alice emotion happy
            
            // 又一个暂停点
            dialog Alice "我们现在在学校了！"
            
            // 选择菜单 - 暂停点
            choice {
                option "探索学校" -> {
                    dialog Alice "好的，让我们一起探索！"
                    jump scene 探索场景
                }
                option "回家" -> {
                    dialog Alice "那么再见了！"
                    end_scene
                }
            }
        }
    };
}

常用命令

安装 rust

# Linux/macOS
export RUSTUP_DIST_SERVER=https://mirrors.ustc.edu.cn/rust-static
export RUSTUP_UPDATE_ROOT=https://mirrors.ustc.edu.cn/rust-static/rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Windows (PowerShell)
$env:RUSTUP_DIST_SERVER = "https://mirrors.ustc.edu.cn/rust-static"
$env:RUSTUP_UPDATE_ROOT = "https://mirrors.ustc.edu.cn/rust-static/rustup"
irm https://sh.rustup.rs -UseBasicParsing | iex

优化编译

cargo build --release

执行案例程序

cargo run --example goto

常用cargo 指令

| `cargo clean` | 清理项目的构建成果 |
| `cargo update` | 更新项目的依赖项 |
| `cargo add` | 添加新的依赖项 |
| `cargo remove` | 移除项目的依赖项 |

常用资源代码关键词

样式资源

stylesheet: Res<UiStyleSheet>,

交互区域

click_area

颜色值设定

BackgroundColor(Color::NONE)

函数

载入页面布局函数

setup_about_scene()

卸载关于页面函数

cleanup_all_about()

载入帮助页面函数

setup_help_scene()

常量值表

常用按钮组颜色

const NORMAL_BUTTON: Color = Color::srgba(0.1, 0.1, 0.1, 0.8);
const HOVERED_BUTTON: Color = Color::srgb(0.25, 0.25, 0.25);
const PRESSED_BUTTON: Color = Color::srgb(0.35, 0.75, 0.35);

参考资料

bevy 案例

https://bevy.org/examples/

bevy github 案例

https://github.com/bevyengine/bevy/tree/main/examples

bevy-flash

https://github.com/aojiaoxiaolinlin/bevy_flash

核心系统

Script Engine（脚本引擎） - 解析和执行游戏脚本的核心系统，负责处理对话、选择分支和游戏逻辑。

Dialogue System（对话系统） - 管理角色对话显示、文本渲染和语音播放的系统。

Save/Load System（存档系统） - 处理游戏进度保存和读取，包括变量状态、剧情进度和用户选择记录。

Choice System（选择系统） - 处理玩家选择分支，影响剧情走向和角色好感度的系统。

资源管理

Asset Pipeline（资源管道） - 将原始素材（图片、音频、文本）转换为游戏可用格式的工具链。

Texture Atlas（纹理图集） - 将多个小图片合并到一张大图中，优化内存使用和渲染性能。

Localization System（本地化系统） - 支持多语言文本、音频和图片资源的管理系统。

Resource Manager（资源管理器） - 统一管理游戏资源的加载、缓存和释放。

视觉效果

Live2D Integration（Live2D集成） - 支持2D角色动画的技术，让角色立绘具有动态表情和动作。

Transition Effects（转场效果） - 场景切换、立绘变化时的视觉过渡效果，如淡入淡出、滑动等。

Layer System（图层系统） - 管理背景、角色立绘、UI元素等不同层次的渲染顺序。

Sprite Animation（精灵动画） - 处理2D图像的帧动画和补间动画。

音频系统

Audio Mixing（音频混合） - 同时播放多个音频轨道（BGM、音效、语音）的技术。

Lip Sync（唇语同步） - 让角色口型动画与语音对白同步的技术。

Dynamic Music（动态音乐） - 根据剧情情绪或玩家选择自动切换背景音乐。

脚本和数据

Markup Language（标记语言） - 用于编写游戏脚本的特殊语法，如Ren'Py的脚本语言。

Flag System（标志系统） - 记录游戏状态和玩家选择的布尔变量系统。

Variable Management（变量管理） - 处理数值型游戏数据，如好感度、金钱、属性值等。

Event Trigger（事件触发器） - 根据特定条件自动执行剧情事件的机制。

用户界面

UI Framework（UI框架） - 构建游戏界面的基础架构，包括按钮、菜单、对话框等。

Auto Mode（自动模式） - 自动播放对话和剧情，无需玩家手动点击的功能。

Skip Function（跳过功能） - 快速跳过已读内容或整段剧情的机制。

Backlog System（回顾系统） - 让玩家查看之前对话内容的历史记录功能。

高级功能

Gallery System（画廊系统） - 解锁和查看CG图片、音乐、角色资料的收藏功能。

Achievement System（成就系统） - 记录玩家完成特定目标的奖励机制。

Route Management（路线管理） - 处理多条剧情线和多结局的分支管理系统。

Memory Optimization（内存优化） - 针对大量图片和音频资源的内存使用优化技术。