# 嵌入 Lua
## 你会学到什么
- 在 Rust 宿主中注册 `pulse` 模块。
- 区分 `register` 和 `register_package_loader`。
- 理解示例为什么用 `include_str!("script.lua")`。
- 处理输出路径、采样路径和错误展示。
## 适合谁读
准备把 `mlua-pulse` 嵌入自己的 Rust 程序，或想理解每个示例 `main.rs` 的用户读本章。
## 前置知识
- [心智模型](../00-overview/mental-model.md)
- [Cargo 特性](features.md)
## 心智模型
Rust 宿主负责创建 Lua 环境、注册模块、加载脚本和展示错误。Lua 脚本负责音乐逻辑。这样最终用户可以改 `script.lua`，而宿主保持稳定。
`register_package_loader` 是大多数场景推荐入口，因为它让 Lua 可以自然写 `local pulse = require("pulse")`。`register` 返回模块表，适合你想手动放进 `globals` 或自定义沙箱。
## 最小可运行例子
```rust
fn main() -> mlua::Result<()> {
let lua = mlua::Lua::new();
mlua_pulse::register_package_loader(&lua)?;
lua.load(
r#"
local pulse = require("pulse")
local song = pulse.song():tempo(120)
assert(song ~= nil)
"#,
)
.exec()
}
```
示例目录通常这样写：
```rust
fn main() -> mlua::Result<()> {
let lua = mlua::Lua::new();
mlua_pulse::register_package_loader(&lua)?;
lua.load(include_str!("script.lua")).exec()
}
```
## 参数和边界
`mlua_pulse::register(&lua)` 返回 `mlua::Table`。你可以把它设到 globals：
```rust
let pulse = mlua_pulse::register(&lua)?;
lua.globals().set("pulse", pulse)?;
```
`mlua_pulse::register_package_loader(&lua)` 注册模块加载器，Lua 侧使用 `require("pulse")`。动态模块构建时，模块名同样是 `pulse`。
输出路径由 Lua 脚本传入，通常相对于运行时当前目录。项目示例从仓库根目录运行，并写入 `examples/<name>/output/` 或 `output/`。宿主程序如果改变当前目录，应明确传入绝对路径或先设置工作目录。
## 常见陷阱
不要在 Rust 侧吞掉 Lua 错误。导出失败、无效音名、无效效果、文件路径错误都应该展示给用户。
不要让 Lua 脚本依赖不确定的当前目录。示例可以简单使用相对路径，产品宿主应考虑把输出目录和采样目录作为配置。
不要在嵌入式构建和动态模块构建之间混用特性。嵌入式用 `vendored`（源码编译 Lua，符号静态链接进 rlib）；动态模块用 `module`（符号来自宿主 Lua），两者不要同时启用。切换 Lua 版本时只启用一个版本特性，例如 `lua54` 或 `luajit`。
## 进阶用法
宿主可以为 Lua 注入自己的辅助函数，例如路径解析、日志、进度回调或资产查找。音乐 API 仍由 `pulse` 提供，宿主 API 只补充环境能力。
如果最终用户不写 Lua，而是程序生成音乐，可以直接使用 [Rust 构造器](rust-builders.md)，绕过 Lua 脚本。
## 相关章节
- [Rust 构造器](rust-builders.md)
- [Cargo 特性](features.md)
- [错误处理](error-handling.md)
- [Rust API](../06-reference/rust-api.md)