# 资产子系统

在 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 会重新触发异步/同步资产加载过程,覆盖原有老的数据。

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