LuaSTGPlus

# 资产子系统

在 LSTGPlus 中，资产的最小组织单位为池。

默认的，在 Legacy API 中，预定义了两个池供使用：全局池和关卡池。

通过 API，可以选择卸载某个资产池中所有资产，或者选择在哪个资产池中加载资产（详见 Legacy API 章节）。

资产具有不同的类型，每种类型具有单独的名字空间，具体下述。

# 规则

# 资产加载规则

资产加载可以通过一系列内建的 API 完成（详见 Legacy API 章节）。

资产原始文件将通过 VFS 打开，为了方便使用和保持兼容性，我们约定：

  • 如果资产文件路径以./开头，将会从 API 调用方脚本所在路径为相对路径搜索并打开资产文件
  • 其他情况，始终认为资产是从相对于 VFS 中以/assets/为根路径进行寻址的

例如：

-- script/test.lua
LoadTexture('1', './1.png')  -- /assets/script/1.png
LoadTexture('2', '/2.png')  -- /assets/2.png
LoadTexture('3', '3.png')  -- /assets/3.png

# 资产使用规则

当一个资产被使用时，LuaSTGPlus 会先从关卡池寻找资产并加载使用。如果关卡池中没有找到对应名称的资产，则从全局池进行查找。

# 错误处理

为了和异步加载及热更新机制兼容，LuaSTGPlus 将不会在资产不存在的情况下终止流程。

如果发现渲染效果不符合预期等情况，需要开发者及时关注控制台中的报错，以检查资产是否正确加载。

TODO

检查资产是否成功加载的能力尚未暴露在 API 中。

# 资产类型

LuaSTGPlus 中定义了如下资产类型：

枚举值 描述
1 纹理
2 精灵
3 动画序列
4 背景音乐
5 音效
6 粒子效果
7 纹理化字体（亦称为美术字）
8 TTF矢量字体（亦称为程序字）
9 Shader 效果

# 纹理

LuaSTGPlus 支持下述纹理格式：

  • JPEG
  • PNG
  • TGA
  • BMP
  • PSD

需要注意每种格式有其支持限制，详见stb_image (opens new window)。

内部使用上，所有纹理都会被转换为 RGBA32 格式，并被视作 SRGB 色彩空间输入。

此外，我们支持指定纹理的 PPU，以便根据需要调整纹理精度。

TODO

指定 PPU 的功能尚未暴露在 API 中。

# RenderTarget

LuaSTGPlus 还可以创建一类特殊的纹理，即 RenderTarget，简称 RT。

RT 可以像普通纹理一样被使用，但更主要的是 RT 可以被用作渲染画面的输出。

LuaSTGPlus 目前总是自适应地将 RT 设置为渲染输出分辨率，即总是保持和屏幕大小一致。我们可能在未来版本中增加对自定义 RT 大小的支持。

WARNING

你不能在一次渲染中同时将 RT 作为渲染输出和绘图用的纹理，这会引发未定义的行为。

# 精灵

LuaSTGPlus 的精灵附带碰撞盒大小定义。

详见Legacy API 文档。

# 动画序列

LuaSTGPlus 的动画序列附带碰撞盒大小定义。

详见Legacy API 文档。

# 背景音乐

背景音乐将以流的形式进行加载，即在运行时进行解码和格式转换。

当前支持下述类型的音频文件（下同）：

  • wav
  • aiff
  • au
  • voc
  • flac
  • ogg/vorbis
  • raw
  • shn
  • mp3

详见音频子系统。

# 音效

音效将在加载时整个解码为 PCM 数据，因此会占用更多的内存空间。

详见音频子系统。

# 粒子效果

为保证兼容性，粒子效果沿用HGE引擎的粒子效果文件格式和相关逻辑。

当前所有的粒子均在 CPU 侧进行模拟。

此外，为了保证兼容性，默认情况下粒子的发射方向总是与发射器方向相反。

# 纹理化字体

为保证兼容性，纹理化字体沿用HGE引擎所定义的纹理字体格式。

相比较HGE默认的格式，我们允许用户定义以UTF-8编码描述的单个码点，以便对中文进行支持。

# TTF矢量字体

LuaSTGPlus 使用 FreeType 光栅化矢量字体，因此可以支持 TrueType 和 OpenType 格式定义的字体。

此外我们允许创建FontCollection以便提供字体fallback的能力。

TODO

创建 FontCollection 的能力尚未暴露在 API 中。

# Shader 效果

从 LuaSTGPlus v2 开始，我们引入了基于 Lua 驱动和定义的 Shader 效果文件格式。

这一格式参考了 FX 的实现，并采用 HLSL 作为基本的语法，配合 Lua 完成效果文件的包装。

详见渲染子系统。

# 高级特性

# 异步加载

LuaSTGPlus 提供异步资产加载的能力。

当启用异步加载时：

  • 资产将会在额外的若干个工作线程加载
  • 当资产未加载时进行使用
    • 对于纹理资产和引用自纹理资产的其他资产类型，会采用内部的占位纹理替代
    • 对于其他资产，将会产生报错

如果平台不支持多线程，则资产只能在主线程上分时间片逐个加载。

TODO

检查资产是否完成加载的能力尚未暴露在 API 中。

# 资产热更新

当运行在开发模式、且没有关闭相关功能的情况下，LuaSTGPlus 可以提供资产热更新的功能。

LuaSTGPlus 会在帧更新间隔逐一检查资产是否发生更改。当发生更改时，LuaSTGPlus 会重新触发异步/同步资产加载过程，覆盖原有老的数据。

这一过程原则上对上层逻辑无感知。

← 渲染子系统 →