包构建手册
本手册将介绍如何构建一个bpm包,您需要将您的资源打包成bpm可识别的格式,我们才能将其并入bpm数据库
由于目前Ballance的资源出产特别少,基本上都是开发组代为制作,但是如果您掌握了打包方法,您可以为我们节省下不少时间并将其投入到bpm的进一步完善中。
阅读此手册可能存在一定技术困难或困惑,这是正常的,因为对于一位可能只是打打游戏的玩家,突然让其接触特别严谨以及未知的东西,确实会令其困惑。
什么是包
如果你用过Linux,那么大概率会了解到包管理器,如apt,yum之类的。包管理器管理的就是包。同样的bpm管理的也是包,只不过它管理的是ballance的包,并且提供了一些普通包管理器没有的选项来专门为Ballance服务。
如果你对上面所述并不熟悉,那么打个比方,bpm是一个家电服务商,你可以通过它为你的家(Ballance)安装各种电器(包),而且这个家电服务商很智能,能了解你家可以带动多大的电器并及时调整电器之间的关系(包冲突与依赖管理)
包通常分为两部分,即这个包的本体,以及其附加的各类属性,例如,这个包可以与哪些包配合使用,或者与哪些包冲突而不能一起使用。
包的本体
对于bpm所管理的包的本体部分,主要由两部分组成,资源文件 与 安装脚本。将资源文件与安装脚本打包进一个zip文件之后,便成为bpm可以识别的包的本体了。
同时,有些包比较特殊,例如地图文件,它必定只有一个地图NMO文件,对于某些包,它可能只存在一个ScriptBody.cs
用于执行脚本,这些包,如果将其打包,则会比较浪费,因此bpm也为这些只有一个文件的包提供了直接传输的功能,即无需打包,直接并入数据库。
资源文件
资源文件是当前包需要为游戏配置的内容,对于map类型的包来说,这个文件就是地图nmo文件,对于Ballance Mod Loader来说,这个文件就是游戏核心修改文件以及各类配置文件。
脚本文件
脚本文件是bpm包的核心文件。因为bpm会在安装,配置,检测,删除包的时候调用脚本文件,提供必要的参数,并由脚本文件自行做一些操作,来使得包被正确安装。bpm是不会操作资源文件的,一切对资源文件的操作都由脚本文件代为执行,同时这也赋予了包制作者极大的权利。bpm无法管控这些,所以请各位包制作者参考后面的脚本建议来编写bpm包,以达到统一的效果。
bpm 脚本使用C#作为脚本语言,使用 Roslyn 编译脚本并执行。您必须按照ScriptTemplate.cs
的格式来书写相关代码。事实上,您所书写的代码,最终都会被附加到此项目的ScriptBody.cs
中然后进行编译,如果想要了解您到底可以使用哪些函数与库,您可以参阅ScriptBody.cs
ScriptTemplate.cs
是我们提供给您编写脚本的模板,一切脚本均需在此模板上进行修改
脚本函数简介与参数解析
安装脚本共有4个函数,分别是Install,Deploy,Remove和Help。分别对应安装,部署,移除,帮助。
通用参数gamePath
和currentPath
分别代表游戏目录与当前脚本的执行目录(存放有相关资源文件)。gamePath
和currentPath
的最后字符都是是不带slash的(Project-z23
及其之前的版本的参数类型与此不同)
通用参数i18n
表示bpm希望您以何种语言提供错误信息或传递文本,您不必必须支持i18n,bpm传输此参数的时候会使用I18N.cs
内部的语言标识。
通用委托getConfig
和setConfig
用以执行读取或写入当前包的设置的工作。
脚本建议
- bpm支持多种类型的包,有mod这种可以直接部署在游戏里的包,也有map这种需要让玩家自行决定安装到何处的包。正是由于我们给了玩家这种选择,所以对于map这种需要部署的包,在安装的时候不应去修改游戏关卡文件,而应当在部署的时候,将自身携带的资源文件覆盖到游戏文件上。
- 建议使用脚本示例中提供的脚本并加以稍许修改来达到最大的同一化。
内部脚本
内部脚本,指的是我们将安装脚本直接内置在了bpm中并一起编译了出来。其主要目的是为了防止一个脚本模板早期书写错误导致最终需要对几百个包的脚本进行全部修改的尴尬情况。
对于Map
,Sky
,Texture
,SoundEffect
,BGM
,我们有内置脚本的部署。
使用内部脚本的包无需拥有Setup.cs
,关于如何启用内置脚本,请参考后文的 包的附加属性 章节
如何打包
请至少确保安装脚本被单独置于zip包下,而不是zip包中某个文件夹下,否则bpm会找不到安装脚本而报错。例如:正确示例:xxx.zip/Setup.cs
错误示例:xxx.zip/xxxFolder/Setup.cs
如果是单文件包,则可以跳过此章节,无需做任何操作。
Windows
如果你使用Windows(这或许是大多数人的情况),请选中你需要安装的文件,然后右键选择发送到-Zip压缩包即可。
非Windows
如果你并不使用Windows,或者并不想用Windows自带的压缩,请手动以zip格式创建压缩包,不要添加任何多余选项(例如:密码,分卷,固实等),以防止解包失败。
包的附加属性
在Project-sakura
之后,bpm将包的各类附加属性并入了package.db
并由数据库代为管理,取消了原有的json
式的附加属性。请前往数据库指南中查询package.db
中表version
的相关字段含义
bpm内部实现说明
- 下载时,包被下载到
cache/download
,并永久驻留作为本地缓存。 - 安装时,包被解包(如果是单文件包则是复制)到
cache/decompress
,执行脚本后,cache/decompress
下所有文件被移动到cache/installed/xxx
下,xxx代表当前包的名字 - 部署时,从
cache/install/xxx
执行脚本 - 删除时,从
cache/install/xxx
执行脚本,执行完毕后,删除文件夹cache/install/xxx