EmueraBA

介绍

EmueraBA 启动器是由 EmueraEE+EM 启动器修改而来，目前保持使用 .NET Framework 4.8 平台构建。

启动器的默认标题改为 EmueraBA，并更改了启动器的默认图标。

图形库更换为 SkiaSharp，画面显示与图像绘制的相关功能已全面改用SkiaSharp，描画インターフェース (图形绘制接口) 配置项已被移除。
请参阅 GETRESOURCEEXT 中的 使用例 部分以了解支持的图像格式。

支持读取和播放 GIF 、WEBP 动态图像，只需像静态图像那样在resources资源文件中定义，然后在ERB脚本中以同样的方式打印显示即可。
可以使用 SETANIMETIMER 指令来刷新画面以获得流畅的播放效果。

实现了自动识别字符范围功能，已能正确识别中、日、韩、英、Emoji字符并计算长度，内部で使用する東アジア言語 (内部使用的东亚语言) 配置项已被移除。

在 显示设置 界面中新增 タブ文字幅 (制表符宽度) 配置项，该配置项可调整 制表符(\t) 在文本中的字符长度，默认值为 8。
制表符会根据之前的文本的字符长度来自动调整自身的字符长度，例如制表符之前有文本 111，则当前制表符会占据5个字符长度。

新增用户定义变量关键字 RESIZE ，该关键字用于标记需要重设数组大小的变量。关于该关键字的更多使用事项请参阅 ARRAYRESIZE。

支持截图功能，可通过菜单栏中的 帮助 → 截图按钮 来将当前的画面保存为文件，或通过新增的 GSNAPSHOT 指令来获取当前画面的图像数据。

resources 文件夹支持读取字体文件，只需像 font 文件夹那样直接将字体文件放入即可。

RANDDATA 数组的长度不再限制，可在 csv/VariableSize.CSV 文件中修改。

模组功能

新增了模组读取机制，并在启动器菜单栏中新增了一个 模组列表 会话窗口，可在此查看、开关模组以及调整模组加载顺序。

添加模组的方法如下：

在游戏主目录下新建 mod 文件夹，该文件夹即为模组主目录。
在 mod 文件夹下新建一个模组文件夹，文件夹名称不限，例如 MyMod。
在 MyMod 文件夹下新建名为 _mod.csv 的模组标识文件，并根据下述表格中的属性填写内容：

属性	描述
ID	该模组的唯一标识。若该标识为空或是与其他模组重名，则模组不会被识别。请确保ID名称符合函数命名规范，且制定后不建议二次修改。
Name	该模组的显示名称。
Authors	该模组的作者名称。
Cover	该模组的显示封面。若要读取模组内的图像，可填写 `{0}` 作为模组所在路径，例如 `{0}resources/cover.png`
Description	该模组的显示简介，可换行续写。请确保Description属性写在其他属性之后。

文件路径与示例内容：mod/MyMod/_mod.csv
ID,MyMod
Name,我的mod v1.0
Authors,Tom & Jerry
Cover,{0}resources/cover.png
Description,我的mod的简介
我的mod的简介1
我的mod的简介2

接下来，您可以在模组文件夹中添加如下资源文件：

创建 csv 文件夹以添加预设文件：.csv Chara*.csv VarExt*.csv。
创建 erb 文件夹以添加脚本文件：.erb .erh .erd。
创建 resources 文件夹以添加以下资源：
- 图像资源：.csv .png .jpg 等，请参阅 GETRESOURCEEXT 中的 使用例 部分以了解支持的图像格式。
- 音频资源：.csv .ogg .m4a 等，请参阅 GETRESOURCEEXT 中的 使用例 部分以了解支持的音频格式。
- Spine资源：.csv .atlas .skel .json。
- 字体资源：.ttf .otf。
- 插件资源：.csv .dll。
创建 text 文件夹以添加多语言资源：.json。
创建 font 文件夹以添加字体资源：.ttf .otf。

模组内的文件与游戏主目录下的文件并无区别，文件名称不限，但需要注意模组之间的内容重复问题：

预设文件：.csv Chara*.csv VarExt*.csv
- 出现任何内容重复的情况时，同模组内会选择最先的内容并发出警告，不同模组之间会选择后排模组的内容并发出警告。
脚本文件：.erb .erh .erd
- 出现任何内容重复的情况时，同模组内会选择最先的内容并发出警告，不同模组之间会选择后排模组的内容并发出警告。
图像资源、音频资源、Spine资源
- 出现资源名称重复的情况时，同模组内会选择最先的内容并发出警告，不同模组之间会选择后排模组的内容。
字体资源
- 出现字体正式名称重复的情况时，同模组内会选择最先的内容，不同模组之间会选择后排模组的内容。
多语言资源
- 出现键名路径完全相同的情况时，同模组内会选择最后的内容，不同模组之间会选择后排模组的内容。
插件资源
- 出现扩展方法名称重复的情况时，同模组内会选择最先的内容并发出警告，不同模组之间会选择后排模组的内容。

多语言功能

多语言功能可以方便创作者整理游戏中的文本以进行本地化翻译，之后在游戏运行时启动器会自动整合可用和优先的语言内容，以快速呈现多语言文本。

添加多语言文本的方法如下。我们将以添加 简体中文 语言作为示例：

在游戏主目录下新建 text 文件夹，该文件夹即为多语言主目录。
在 text 文件夹下新建一个区域语言文件夹，文件夹名称需参考 区域性语言 文档中的 语言标签(Language tag)。
- 通过查询上述文档可得知 Chinese (Simplified) 的区域名称为 zh-CN，该名称将作为文件夹名称。
- 文件夹名称不分大小写，且不分 下划线(_) 与 减号(-)，但建议统一改为大写和 下划线(_)，例如 ZH_CN。
在 ZH_CN 文件夹下新建任意 json 格式的文件，并在文件中填入如下示例内容：

文件路径与示例内容：text/ZH_CN/text.json
{
  //这是一条注释。

  "键名": "内容",
  "START_GAME": "开始游戏",
  "ITEM": "物品",
  "ITEM":
  {
    "APPLE":
    {
      "NAME": "苹果",
      "DESC": "一种水果",
    },
    //注意：请避免键名中包含换行符(\n)，例如 BA\nNANA 是不合规的键名，这是因为启动器在整合语言内容时利用了该字符。
    "BANANA":
    {
      "NAME": "香蕉",
      "DESC":
      [
        "大香蕉，一条大香蕉",
        "你的感觉真的很奇妙",
      ],
    },
  },
}

至此，我们已成功添加了 简体中文 的多语言文本，接下来我们需要在设置中启用该语言：

打开启动器并进入 模组列表，可以看到窗口左下角的 多语言列表 里多了 中文 的选项，请将该选项双击启用，并点击 保存 按钮。
- 若您已添加了多个不同的语言，您可使用鼠标拖动已启用的语言以调整语言的呈现顺序，列表顶部的优先级最高。
- 此外，在 模组列表 中，如果模组之间出现键名路径重复的情况，则优先采用后排模组的文本内容。
- 每次改动 多语言列表 后只有重启程序才能重置语言文本缓存，以及重置所有被重构为常量字符串的代码。

最后，在代码中使用 TEXT 与 TEXTLIST 指令来获取多语言文本，调用时只需按照json文件中自行设定的键名路径来输入键名即可：

LOCALS '= TEXT("start_game")		; 获取文本“开始游戏”，输入的键名无需区分大小写
PRINTSL TEXT("ITEM")			; 打印“物品”
PRINTSL TEXT("ITEM", "APPLE", "DESC")	; 打印“一种水果”

TEXTLIST LOCALS, "ITEM", "APPLE", "DESC"
PRINTSL LOCALS:0			; 打印“一种水果”
TEXTLIST LOCALS, "ITEM", "BANANA", "DESC"
PRINTSL LOCALS:0			; 打印“大香蕉，一条大香蕉”
PRINTSL LOCALS:1			; 打印“你的感觉真的很奇妙”

音频功能

音频组件更换为 CSCore ，并在启动器菜单栏中新增了一个 音频 会话窗口，可在此调整各项音量与功能。

可以如图像资源那样，在 resources 文件夹下放置音频文件、创建csv文件并定义Audio资源以支持更多自定义的音频效果。

Audio资源的csv文件填写格式与示例内容
; Audio名称,音频文件名,音量(100),起始时间(00:00:00),播放时长(音频文件的总时长)
MyMusic,MyMusic.ogg
MyMusic1,MyMusic1.m4a,100
MyMusic2,MyMusic2.wav,80,00:01:30
MyMusic3,MyMusic3.mp3,70,00:01:30,15000

csv文件中的 起始时间 和 播放时长 属性可接收 TimeSpan 或 ms(毫秒) 值，TimeSpan 的书写格式请参阅 TimeSpan.TryParse 文档中的示例部分。

请参阅 音频相关 指令以了解更多关于音频的功能。
请参阅 GETRESOURCEEXT 中的 使用例 部分以了解支持的音频格式。

Spine动画功能

添加了对 Spine 运行时 的支持，可读取Spine动画文件并通过 SkiaSharp 来渲染绘制画面。

目前支持以下版本的Spine运行时：
- 3.8.xx
- 4.2.xx

添加Spine资源的方法与添加图像资源类似，请将Spine资源文件放置在 resources 文件夹下并创建csv文件，在csv文件中填写如下内容：

Spine资源的csv文件填写格式与示例内容
; Spine资源名称,atlas文件,skel文件或json文件
aris_spine, aris.atlas, aris.skel

之后可在代码中使用 SPINECREATE、CBGSETSPINE 等指令加载并显示Spine动画到屏幕画面上。

SPINE相关指令的使用示例：
; 设置动画刷新间隔，单位为毫秒
SETANIMETIMER 1000 / 60

; 创建一个Spine动画到自行指定的ID中
SPINECREATE 0, "aris_spine"

; 设置Spine动画的缩放比例为50%
SPINESETSCALE 0, 50

; 为Spine动画设置ANIM
SPINESETANIM 0, 0, "IDLE_01", 1
SPINESETANIM 0, 1, "00", 1

; 将指定的Spine动画显示到屏幕画面上
CBGSETSPINE 0, 0, 0, 1

请参阅 SPINE相关 指令以了解更多关于Spine动画的功能。

插件功能

EmueraBA支持读取外部的动态链接库文件(*.dll)，可在不修改启动器本身的情况下添加扩展方法并在游戏脚本中调用，以满足更多功能需求和改善运行性能。

构建插件的流程如下：

请先执行 EmueraBA启动器的构建流程，完成EmueraBA启动器的开发环境部署。
在已克隆的EmueraBA仓库中找到并打开 Emuera.sln 解决方案，在Visual Studio的解决方案资源管理器中找到 PluginExample 项目，打开项目中的 PluginEntry.cs 文件。
插件中必须包含一个公共静态的 PluginEntry 类，该类即为插件的初始化入口。
在 PluginEntry 类中声明以下内容，为启动器添加新功能：

声明一个公共静态的 void RegisterFunctionMethod(Dictionary<string, FunctionMethod> methodList) 函数以添加扩展方法。
- 可通过参阅以下文件来大致了解继承自 FunctionMethod 的实现类的写法，以在 PluginEntry.cs 文件中编写自定义的扩展方法：
  - Emuera\GameData\Function\Creator.cs
  - Emuera\GameData\Function\Creator.Method.cs 系列文件

在Visual Studio的界面左上角找到解决方案配置，若配置为 Debug，则将其切换至 Release。
对 PluginExample 项目点击 鼠标右键 → 属性，在 应用程序 菜单页中将 程序集名称 和 程序集信息… 的默认名称更改为属于你的插件名称。
对 PluginExample 项目点击 鼠标右键 → 重新生成，生成的DLL文件可在 PluginExample\bin\Release 文件夹中找到。

把插件添加到游戏本体的流程如下：

与添加图像资源的方式类似，只需将生成的DLL文件放置在 resources 文件夹下并创建csv文件，在csv文件中填写如下内容即可。
注意在csv文件中只需填写包含 PluginEntry 类的DLL文件，其他附带的DLL文件无需填写。

插件资源的csv文件填写格式与示例内容
; DLL文件名
MyPlugin.dll
MyOtherPlugin.dll

新增扩展变量类型

列表

列表的声明格式为 #LIST(S) <变量名>

声明该变量时支持与 GLOBAL、SAVEDATA、CHARADATA、DYNAMIC、REF 关键字同时定义。
与 SAVEDATA 关键字定义时需要将 バイナリデータライターのバージョン (二进制存档写入器版本) 配置项更改为 1809 及以上。

请参阅 列表相关 指令以了解更多功能。

使用例
#LIST MY_LIST			; 声明一个值为`整数`类型、名称为 `MY_LIST` 的列表变量

LISTADD MY_LIST, 10		; 向 MY_LIST 中添加一个值为 10 的元素
PRINTVL MY_LIST:0		; 打印 MY_LIST 的 0 号元素，打印结果为 "10"

哈希列表

哈希列表的声明格式为 #HASHLIST(S) <变量名>

请参阅 哈希列表相关 指令以了解更多功能。

使用例
#HASHLISTS MY_HASHLIST			; 声明一个值为`字符串`类型、名称为 `MY_HASHLIST` 的哈希列表变量

HASHLISTADD MY_HASHLIST, "TEXT"		; 向 MY_HASHLIST 中添加一个值为 "TEXT" 的元素
PRINTVL HASHLISTHAS(MY_HASHLIST, "TEXT"); 打印 MY_HASHLIST 对值 "TEXT" 的查找结果，打印结果为 "1"

字典

字典的声明格式为 #DICT_<I|S><I|S> <变量名>
如果声明的键类型为 整数，则支持使用ERD键词功能。

声明该变量时支持与 CONST、GLOBAL、SAVEDATA、CHARADATA、DYNAMIC、REF、HARDCHECK 关键字同时定义。
与 SAVEDATA 关键字定义时需要将 バイナリデータライターのバージョン (二进制存档写入器版本) 配置项更改为 1809 及以上。

请参阅 字典相关 指令以了解更多功能。

使用例
#DICT_IS MY_DICT		; 声明一个键为`整数`类型、值为`字符串`类型、名称为 `MY_DICT` 的字典变量

MY_DICT:6 '= "TEXT"		; 向 MY_DICT 中写入一个键为 6、值为 "TEXT" 的元素
PRINTSL MY_DICT:6		; 打印 MY_DICT 中的键为 6 的值，打印结果为 "TEXT"

数组型字典

数组型字典的声明格式为 #DICT(S)_DIM(S) <变量名>(, 数组长度 = 1)
如果声明的主键类型为 整数，则支持使用ERD键词功能。
变量的第二维数组下标默认支持使用ERD键词功能。

声明该变量时支持与 GLOBAL、SAVEDATA、CHARADATA、DYNAMIC、REF、HARDCHECK 关键字同时定义。
与 SAVEDATA 关键字定义时需要将 バイナリデータライターのバージョン (二进制存档写入器版本) 配置项更改为 1809 及以上。

请参阅 字典集合相关 指令以了解更多功能。

使用例
#DICTS_DIM MY_DICTDIM, 10		; 声明一个主键为`字符串`类型、值为`整数`类型、名称为 `MY_DICTDIM` 的数组型字典变量，该变量所创建的每个数组的长度为 `10`

DICTITEMCREATE MY_DICTDIM, "NEW"	; 在 MY_DICTDIM 中创建一个名称为 "NEW" 的数组
MY_DICTDIM:"NEW":0 = 20			; 将 MY_DICTDIM 中的 "NEW" 数组的 0 号元素赋值为 20
PRINTVL MY_DICTDIM:"NEW":0		; 打印 MY_DICTDIM 中的 "NEW" 数组的 0 号元素，打印结果为 "20"

列表型字典

列表型字典的声明格式为 #DICT(S)_LIST(S) <变量名>
如果声明的主键类型为 整数，则支持使用ERD键词功能。

请参阅 列表相关、字典集合相关 指令以了解更多功能。

使用例
#DICTS_LIST MY_DICTLIST			; 声明一个主键为`字符串`类型、值为`整数`类型、名称为 `MY_DICTLIST` 的列表型字典变量

DICTITEMCREATE MY_DICTLIST, "NEW"	; 在 MY_DICTLIST 中创建一个名称为 "NEW" 的列表
LISTADD MY_DICTLIST:"NEW", 20		; 向 MY_DICTLIST 中的 "NEW" 列表添加一个值为 20 的元素
PRINTVL MY_DICTLIST:"NEW":0		; 打印 MY_DICTLIST 中的 "NEW" 列表的 0 号元素，打印结果为 "20"

哈希列表型字典

哈希列表型字典的声明格式为 #DICT(S)_HASHLIST(S) <变量名>
如果声明的主键类型为 整数，则支持使用ERD键词功能。

请参阅 哈希列表相关、字典集合相关 指令以了解更多功能。

使用例
#DICTS_HASHLIST MY_DICTHASHLIST			; 声明一个主键为`字符串`类型、值为`整数`类型、名称为 `MY_DICTHASHLIST` 的哈希列表型字典变量

DICTITEMCREATE MY_DICTHASHLIST, "NEW"		; 在 MY_DICTHASHLIST 中创建一个名称为 "NEW" 的哈希列表
HASHLISTADD MY_DICTHASHLIST:"NEW", 20		; 向 MY_DICTHASHLIST 中的 "NEW" 哈希列表添加一个值为 20 的元素
PRINTVL HASHLISTHAS(MY_DICTHASHLIST:"NEW", 20)	; 打印 MY_DICTHASHLIST 中的 "NEW" 哈希列表对值 20 的查找结果，打印结果为 "1"

字典型字典

字典型字典的声明格式为 #DICT(S)_DICT_<I|S><I|S> <变量名>
如果声明的主键类型为 整数，则支持使用ERD键词功能。
如果声明的次键类型为 整数，则支持使用ERD键词功能。

请参阅 字典相关、字典集合相关 指令以了解更多功能。

使用例
#DICTS_DICT_IS MY_DICTDICT		; 声明一个主键为`字符串`类型、次键为`整数`类型、值为`字符串`类型、名称为 `MY_DICTDICT` 的字典型字典变量

DICTITEMCREATE MY_DICTDICT, "NEW"	; 在 MY_DICTDICT 中创建一个名称为 "NEW" 的字典
MY_DICTDICT:"NEW":8 '= "TEXT"		; 向 MY_DICTDICT 中的 "NEW" 字典写入一个键为 8、值为 "TEXT" 的元素
PRINTSL MY_DICTDICT:"NEW":8		; 打印 MY_DICTDICT 中的 "NEW" 字典中的键为 8 的元素，打印结果为 "TEXT"

语法、指令与程序的兼容性变动

解禁了 函数型宏定义 的相关功能，尚未完全测试该功能的可靠性。

ERD键词功能的相关改动：

省略键词索引值时，系统会为该键词自动分配一个尚未使用的索引值。
警告：带 SAVEDATA 声明的变量不建议省略索引值，以避免游戏存档数据错乱。
填写已存在的键词名称作为索引值时，将会直接引用该键词的索引值。

ERD键词功能示例：erb/example.erd
1,能量饮料	; "能量饮料"的索引值被分配为1
,酒		; "酒"的索引值被自动分配为0，因为索引值0未被占用
酒,Wine		; "Wine"的索引值将引用自"酒"，即为0
果汁,ジュース	; "ジュース"的索引值将引用自后续的"果汁"，即为2
,果汁		; "果汁"的索引值被自动分配为2，因为索引值0和1已被占用

FORM语法的相关改动：

使用内插变量时，不再需要根据其变量类型区分花括号({STR})与百分比号(%STR%)。
新增对齐关键字 CENTER，可使文本在指定的字符长度内居中对齐。例如 {"确认", 6, CENTER} 将会格式化为 " 确认 "。
可以传入数值表达式作为对齐参数，例如 {"确认", 6, 1 + 1} 将会格式化为 " 确认 "。
具体的数值及含义如下：
- 0 = 左对齐，相当于 LEFT 关键字。
- 1 = 右对齐，相当于 RIGHT 关键字。
- 2 = 居中对齐，相当于 CENTER 关键字。

HTML语法的相关改动：

div 标签的 bcolor 属性更名为 bdcolor (borderColor)，以避免与其他标签中的 bcolor (backgroundColor)属性混淆。
div 标签的 bdcolor 属性的输入值格式改为 'color' 单颜色值，不再接收四角颜色值。
div 标签的 border 属性的输入值格式改为 'thick' 单数值，不再接收四角数值。
div 标签的 margin 属性的效果改为向外扩张，不再向内挤压。

角色型二维数组支持省略第1参数（当 キャラクタ変数の引数を補完しない (不自动补完角色变量的参数) 配置项未启用时）。

FOR-NEXT 与 REPEAT-REND 控制语句的临时缓存会随函数一同进出堆栈。

__FILE__ 变量获取的文件路径的反斜杠 \\ 替换为正斜杠 /。

REPLACE 指令的其中一种参数格式已被分离为独立指令 REPLACEBYARRAY。

下列指令现已支持处理Emoji字符🎉，这些指令在处理Emoji字符时会通过计算显示宽度得出大致的字符长度。
例如 😀 的字符长度为2，👨‍👩‍👧‍👦 的字符长度为4。

SUBSTRING 指令处理边缘字符的逻辑已变更。如果文本的选定位置处在长字符的中间，则后退到该字符的起始位置。
也就是说，卡在起始位置的字符会被计入，卡在末尾位置的字符会被无视。

ERDNAME 省略第3参数时将会查找数组最后一维的下标键词。

INPUTMOUSEKEY 指令会额外变更 RESULTS:0 和 RESULT:3 的值。

GCREATE、GCREATEFROMFILE、GLOAD 指令在创建图像前会释放已创建的图像，即无需在创建前调用 GDISPOSE 指令。

GCREATEFROMFILE 指令的第2参数必须确保是从主目录开始的相对路径，且第3参数已被移除。

GDASHSTYLE 指令的线帽效果已变更。

GDRAWTEXT 指令仅返回 RESULT:0，其他返回值已失效。

GDRAWGWITHMASK 的绘制结果受 alpha值和 blue值影响。

由于图形库的更换，GDRAWG、GDRAWSPRITE 指令的颜色矩阵的使用方式已变更，具体请参阅 GSETCOLORMATRIX 指令中的说明。

SETANIMETIMER 指令在 TINPUT 或者 INPUTMOUSEKEY 之类的计时等待的情况下仍会继续刷新动画。

SPRITECREATE、SPRITEANIMECREATE 指令在创建Sprite前会释放已创建的非内置Sprite，即无需在创建前调用 SPRITEDISPOSE 指令。如果已存在同名的内置Sprite则会创建失败。

SPRITEDISPOSEALL 指令不再具备移除内置Sprite的功能，且能够释放所有内置Sprite所引用的图像。

PLAYBGM、PLAYSOUND 指令的第1参数仅支持输入Audio名称。若要通过音频文件路径来播放，请先使用 AUDIOCREATEFROMFILE 指令来创建Audio。
关于如何添加内置Audio资源，请参阅 音频功能 部分。

SETBGMVOLUME 指令只会变更当前正在播放的背景音乐的音量，不再影响全局音量。

SETSOUNDVOLUME 指令已被弃用，不再有任何效果。

ENUMFILES 指令获取的文件路径的反斜杠 \\ 替换为正斜杠 /。

通过菜单栏中的 タイトルに戻る 按钮返回标题画面时将会额外清空如下内容：

清空所有CBG图像，包括CBGBUTTON、CBGBMAP等，效果与 CBGCLEAR 指令相同。
清空所有运行时创建的Sprite，释放所有Sprite所引用的图像，效果与 SPRITEDISPOSEALL 指令相同。
清空所有运行时创建的Spine动画，释放所有Spine动画所引用的图像，效果与 SPINEDISPOSEALL 指令相同。
清空所有运行时创建的Audio并释放音频缓存，效果与 AUDIODISPOSEALL 指令相同。

emuera.log 游戏日志和 console.log 调试日志使用 UTF-8-BOM 编码保存。

watchlist.csv 变量监视列表使用 UTF-8-BOM 编码保存和读取。

关闭调试窗口时不再自动保存变量监视列表。

介绍​

模组功能​

多语言功能​

音频功能​

Spine动画功能​

插件功能​

新增扩展变量类型​

列表​

哈希列表​

字典​

数组型字典​

列表型字典​

哈希列表型字典​

字典型字典​

语法、指令与程序的兼容性变动​

介绍