---
description: Lua脚本环境
---

# 0.11

lua脚本环境模块可在程序运行时以热插拔的方式加载执行lua脚本编写的脚本化微应用程序。

## 术语约定

### 脚本化微应用

一个包含了lua脚本文件和图片、视频、音乐、模型等多种媒体文件打包而成的归档文件，可在加载运行后提供和主程序一致的交互体验。

### 根脚本

微应用程序至少需要包含一个名为root.lua的根脚本文件，微应用加载后，会执行root.lua，微应用的所有逻辑都从根脚本开始。

一个根脚本需要包含以下结构:

```lua
local function run()
    G_LOGGER:Info("lua root.Run ...")
    G_LOGGER:Info(G_SLOT_UI.name)
    G_LOGGER:Info(G_SLOT_WORLD.name)
end

local function update()
end

local function stop()
    G_LOGGER:Info("lua root.Stop ...")
end

local function handleEvent(_event, _data)
    G_LOGGER:Info(_event)
end

root = {
    Run = run,
    Update = update,
    Stop = stop,
    HandleEvent = handleEvent,
}
```

## 功能特性

### 运行时热插拔

模块可在运行时从外部插入微应用运行，同时可将微应用从运行时拔除。

### 全局导出

模块中已经导出了一些常用的可访问成员到lua空间，在lua代码中可以直接调用。

| 导出名                  | 类型                                     | 说明         |
| -------------------- | -------------------------------------- | ---------- |
| G\_LOGGER            | XTC.FMP.LIB.MVCS.Logger                | 日志的实例      |
| G\_SLOT\_UI          | UnityEngine.GameObject                 | UI挂载槽的实例   |
| G\_SLOT\_WORLD       | UnityEngine.GameObject                 | 3D世界挂载槽的实例 |
| G\_API\_PROXY        | XTC.FMP.MOD.LuaEnv.LIB.APIProxy        | API代理的实例   |
| G\_FONT\_MAIN        | UnityEngine.Font                       | 主要的字体      |
| G\_RUNNER\_COROUTINE | XTC.FMP.MOD.LuaEnv.LIB.CoroutineRunner | 协程的运行组件    |

## 配置说明

标准范例：

```xml
<?xml version="1.0" encoding="utf-8"?>
<MyConfig version="1.0">
    <!-- UI 
      visible: 预加载完成后是否显示
      slot: ui根节点在主Canvas中的挂载路径
    -->
    <UI visible="true" slot="[root]"/>
    <!-- World
      visible: 预加载完成后是否显示
      slot: world根节点的挂载路径
    -->
    <World visible="true" slot="[root]"/>
    <!-- 远程过程调用
      address: 地址
    -->
    <GRPC address="https://localhost:19000"/>
    <!-- 样式列表
      name: 名称
      StandardColor: 标准色，如未定义，lsa使用自己的颜色，如定义，lsa优先使用标准色
      StandardColor.primary: 主要色，RGBA的HEX值
      StandardColor.secondary: 次要色，RGBA的HEX值
      StandardColor.success: 成功色，RGBA的HEX值
      StandardColor.danger: 危险色，RGBA的HEX值
      StandardColor.warning: 警告色，RGBA的HEX值
      StandardColor.info: 主要颜色，RGBA的HEX值
      StandardColor.light: 亮色，RGBA的HEX值
      StandardColor.dark: 暗色，RGBA的HEX值
    -->
    <Styles>
        <Style name="default">
          <StandardColor primary="" secondary="" success="" danger="" warning="" info="" light="" dark=""/>
        </Style>
    </Styles>
    <!-- 预创建的实例列表
      uid: 实例的唯一ID
      style: 使用的样式名
      uiSlot: UI挂载的路径
      worldSlot: World挂载的路径
    -->
    <Instances>
        <Instance uid="default" style="default" uiSlot="" worldSlot=""/>
    </Instances>
    <!-- 预加载 -->
    <Preload>
        <!-- 消息订阅的主题
          message: 消息
          Parameter.key: 参数的键
          Parameter.value: 参数的值
          Parameter.type: 参数的类型，支持的类型为string,int,float,bool
        -->
        <Subjects>
            <Subject message="_/XTC/LuaEnv/Open">
                <Parameters>
                    <Parameter key="uid" value="default" type="string"/>
                    <Parameter key="source" value="assloud://" type="string"/>
                    <Parameter key="uri" value="XTC.LuaEnv/_resources/1.lsa#" type="string"/>
                    <Parameter key="delay" value="0" type="float"/>
                </Parameters>
            </Subject>
        </Subjects>
    </Preload>
</MyConfig>
```

## 消息订阅

TODO

## 依赖插件

* oelMVCS
* oelArchive
* NVorbis
* XLuaPlugin

## 模板列表

### Karaoke (卡拉OK)

* 可更改主题皮肤
* 可切换人声和伴唱两种模式
* 可控制播放进度
* 可控制音量大小

#### 文件结构

```
|- x.lsa
  |- root.lua                 // 根脚本
  |- app.lua                  // 应用逻辑脚本
  |- style.lua                // 主题样式脚本
  |- lrc.lua                  // 歌词脚本
  |- accompaniment.ogg        // 不带人声的伴奏的音频，建议为(44100Hz, 192kbps, stereo)
  |- music.ogg                // 带人声的音乐的音频，建议为(44100Hz, 192kbps, stereo)
  |- bg.jpg                   // 背景图片，拉伸显示
  |- frame.png                // 背景边框图片，九宫格显示
  |- cover.png                // 中央唱片图
  |- handle.png               // 进度条按钮图
  |- icon-accompaniment.png   // 伴奏按钮图
  |- icon-music.png           // 唱按钮图
  |- icon-pause.png           // 暂停按钮图
  |- icon-play.png            // 播放按钮图
  |- icon-volume.png          // 音量按钮图
  |- loading.png              // 加载图
  |- panel-volume.png         // 音量条背景图
```

#### 配置说明

* 修改样式

样式的修改可替换图片和修改style.lua中的值

* 更改歌词

将歌词格式的文本替换到lrc.lua中

### PhotoAlbum (相册)

* 可更改主题皮肤
* 可浏览图片预览
* 可缩放图片大小
* 可显示和关闭图片配文

#### 文件结构

```
|- x.lsa
  |- root.lua                 // 根脚本
  |- app.lua                  // 应用逻辑脚本
  |- unityUtilities.lua       // 通用工具脚本
  |- style.lua                // 主题样式脚本
  |- config.lua               // 配置脚本
  |- description_off.png      // 描述关闭按钮图片
  |- description_on.png       // 描述打开按钮图片
  |- handle.png               // 缩放条按钮图
  |- slider.png               // 缩放条背景图
  |- progress.png             // 加载进度背景图
  |- images                   // 图片文件夹
    |- img#1.jpg              // 第一张图片
    |- ...
```

#### 配置说明

* 修改样式

样式的修改可替换图片和修改style.lua中的值

* 更改图片

将图片放置到images文件夹中，并按 img#{n}.jpg方式命名，n从1开始。

修改完图片后更改config.lua中的图片数量值

```lua
local count = 4
```

同时添加图片的描述

```lua
description["img#1.jpg"]["en_US"] = "图片1的描述"
```

### ImagePresentation (图片演示)

* 可更改主题皮肤
* 可使用上一页和下一页进行翻页
* 可点击画面显示和关闭工具栏
* 工具栏可拖拽
* 可在工具栏中打开图片预览列表

#### 文件结构

```
|- x.lsa
  |- root.lua                 // 根脚本
  |- app.lua                  // 应用逻辑脚本
  |- config.lua               // 配置脚本
  |- unityUtilities.lua       // 通用工具脚本
  |- style.lua                // 主题样式脚本
  |- toolbar_drag.png         // 工具栏拖拽按钮图片
  |- toolbar_prev.png         // 工具栏上一页按钮图片
  |- toolbar_next.png         // 工具栏下一页按钮图片
  |- toolbar_list.png         // 工具栏列表按钮图片
  |- images                   // 图片文件夹
    |- img#1.jpg              // 第一张图片
    |- ...
```

#### 配置说明

* 修改样式

样式的修改可替换图片和修改style.lua中的值

* 更改图片

将图片放置到images文件夹中，并按 img#{n}.jpg方式命名，n从1开始。

修改完图片后更改config.lua中的图片数量值

```lua
local count = 4
```

### Recitation (朗诵)

* 可更改主题皮肤
* 可控制播放进度
* 可控制音量大小
* 滚动的文章显示

#### 文件结构

```
|- x.lsa
  |- root.lua                 // 根脚本
  |- app.lua                  // 应用逻辑脚本
  |- style.lua                // 主题样式脚本
  |- config.lua               // 配置脚本
  |- audio.ogg                // 朗诵音频，建议为(44100Hz, 192kbps, stereo)
  |- bg_landscape.jpg         // 横屏的背景图片，拉伸显示
  |- bg_portrait.jpg          // 竖屏的背景图片，拉伸显示
  |- frame.png                // 内容边框图片，九宫格显示，需搭配frame_border参数使用
  |- icon-pause.png           // 暂停按钮图
  |- icon-play.png            // 播放按钮图
  |- icon-volume.png          // 音量按钮图
  |- loading.png              // 加载图
  |- mask.png                 // 内容区域的遮罩图，九宫格显示，需搭配mask_border参数使用
  |- progress-bg.png          // 进度条背景图
  |- progress-fill.png        // 进度条填充图
  |- progress-handle.png      // 进度条按钮图
  |- toolbar-bg.png           // 工具栏背景图
  |- volume-bg.png            // 音量条背景图
  |- volume-handle.png        // 音量条按钮图
```

#### 配置说明

* 修改样式

样式的修改可替换图片和修改style.lua中的值

* 更改文字显示内容

修改config.lua中对应的值

## 更新日志

### Recitation/6.0.0

\[新增] 第一版

### 0.11.0

\[新增] 到处标准色到Lua环境

### ImagePresentation/6.0.0

\[新增] 第一版

### PhotoAlbum/6.0.0

\[新增] 第一版

### 0.10.0

\[更新] 将NLayer组件替换为NVorbis \[新增] 导出协程运行组件到lua运行时 \[更新] 音频读取使用流方式加快加载速度

### Karaoke/6.1.0

\[新增] 预加载完成后使用协程暂停1秒 \[更改] 使用ogg替换mp3

### 0.9.0

\[更新] 关闭时结束读取线程

### Karaoke/6.0.1

\[修正] 播放进度无法点击的问题 \[更新] 自动循环播放
