跳到正文
Bullet Hero
文档
本页内容
开发者关卡作者

安装

如何把SDK接入.NET或Unity项目，并确认它能读取你的关卡

SDK的代码位于github.com/bullet-hero/sdk，许可证为MIT

.NET

BulletHero.SDK包尚未发布到nuget.org。请从源码构建：

git clone https://github.com/bullet-hero/sdk.git
cd sdk
dotnet build -c Release BH.SDK.csproj   # bin~/Release/BH.SDK.dll and BH.SDK.xml
dotnet pack  -c Release BH.SDK.csproj   # bin~/Release/BulletHero.SDK.<version>.nupkg

然后二选一接入：

  • 从本地文件夹引用.nupkg：dotnet add package BulletHero.SDK --source <folder>。三个依赖会随它一起到位
  • 直接引用BH.SDK.dll。这时需要自己添加下面三个包：引用DLL不会带上它的依赖

依赖全部来自NuGet：

包版本用途
Newtonsoft.Json13.0.3JSON
BouncyCastle.Cryptography2.7.0为带密码的关卡提供OpenPGP
SharpZipLib1.4.2tar和zip（gzip来自BCL）

构建细节

  • 程序集名为BH.SDK.dll，XML文档随附在旁边
  • 目标框架是netstandard2.1，语言是C# 9。这正是Unity项目编译时使用的版本，所以同一份源码在Unity内外都能构建
  • 输出文件夹是bin~和obj~。加波浪号是因为Unity不导入名称以波浪号结尾的文件夹

Unity

游戏以git submodule的方式接入SDK：

git submodule init
git submodule add -f https://github.com/bullet-hero/sdk.git Assets/Plugins/BH.SDK

移除用git rm -r -f Assets/Plugins/BH.SDK

Unity项目需要自己提供：

  • Newtonsoft.Json，通过com.unity.nuget.newtonsoft-json包
  • 来自NuGet的BouncyCastle.Cryptography和SharpZipLib（游戏用NuGetForUnity安装它们）
  • Player Settings中的脚本宏BHSDK_UNITY。没有它，UnityIntegration会走不依赖引擎的分支
  • 放在SDK根目录的BH.SDK.Roslyn.dll。Unity只把分析器应用到它所在文件夹的程序集以及引用该程序集的程序集。挪到别处后，它什么也不分析

仓库根目录有一个package.json，名称为com.vertoker.bullet-hero-sdk，最低Unity版本为6000.0。因此Package Manager也能通过git URL添加SDK。开发者不使用也不介绍这种方式

检查：ConsoleSmoke示例

Samples~/ConsoleSmoke是一个net8.0控制台应用。它引用构建好的BH.SDK.dll，和第三方工具的做法完全一样。该应用读取一个关卡文件夹，输出名称、物体数量和代。然后让关卡经JSON和.blob各往返一次

dotnet build -c Release Samples~/ConsoleSmoke/ConsoleSmoke.csproj
dotnet Samples~/ConsoleSmoke/bin~/Release/net8.0/ConsoleSmoke.dll <level folder>
退出码含义
0全部一致
1参数错误
2找不到level.*或metadata.*
3往返结果不一致
4文件比当前SDK新

在游戏内置关卡new-zero-demo上的输出（用SDK 1.0.0录制）：

BH.SDK 1.0.0, model generation 1
name:       New zero demo
objects:    782
generation: 1 (Blob)
round trip Json: equal (1505078 bytes)
round trip Blob: equal (680706 bytes)
exit 0

下一步：关卡格式

SDK的组成

部分是什么是否需要Unity
BH.SDK核心：模型、序列化、版本、规则、校验、归档包、发布、生成器、Afterbeat互通否
UnityIntegration一个薄层，其中每个文件在有无Unity时都能编译（#if BHSDK_UNITY），例如Cat日志器否：在Unity之外它直接编译进核心
UnityExtensions到Unity类型的转换、2D变换、化身移动是，无条件
BH.SDK.Roslyn分析器和源码生成器。它为每个标有[GenerateModel]的模型编写Equals、复制、JSON与.blob编解码器以及校验遍历在编译期运行

模型文件只包含成员和构造函数。所有重复的部分都由生成器编写。所以不会在七个生成的方法体中的某一个里漏掉成员

为什么是独立的库

  • 关卡比游戏活得久。关卡是一个由开放格式文件组成的文件夹（JSON、tar.gz、zip、OpenPGP）。读取它们的代码也是开源的。即使写出关卡的游戏不在了，关卡依然可读
  • 与其他节奏游戏互通。与Afterbeat（原名Project Arrhythmia）之间的双向转换已经在SDK中。更多：Afterbeat互通
  • 修复更快。格式的缺陷从外部就能看到。任何读过代码的人都能报告它或提交修复
  • 第三方工具。转换器、校验器、关卡生成器或模组使用与游戏相同的模型。没有人需要从文件逆向还原它们
  • 服务器。核心不依赖Unity，以netstandard2.1构建。所以服务器能在同样的模型上执行与客户端相同的检查