本文へスキップ
Bullet Hero
ドキュメント
このページの内容
開発者レベル作者

インストール

SDKはnuget.orgのBulletHero.SDKパッケージとして入手するか、ソースからビルドします。Unityにはgit submoduleとして組み込み、ConsoleSmokeサンプルで手元のレベルが読めることを確認できます

SDKのコードはgithub.com/bullet-hero/sdkにあります。ライセンスはMITです

.NET

BulletHero.SDKパッケージはnuget.orgで公開されています：dotnet add package BulletHero.SDK。3つの依存パッケージも一緒に入ります。ソースからビルドする場合は次のとおりです：

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>。3つの依存パッケージも一緒に入ります
  • BH.SDK.dllを直接。この場合、下の3つのパッケージは自分で追加します。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

ゲームはSDKをgit submoduleとして組み込んでいます：

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プロジェクト側で用意するもの：

  • com.unity.nuget.newtonsoft-jsonパッケージ経由のNewtonsoft.Json
  • NuGetからのBouncyCastle.CryptographyとSharpZipLib（ゲームはNuGetForUnityでインストールしています）
  • Player SettingsのスクリプトシンボルBHSDK_UNITY。これがないと、UnityIntegrationはエンジンを使わない分岐を選びます
  • SDKのルートにあるBH.SDK.Roslyn.dll。Unityはアナライザーを、それが置かれたフォルダーのアセンブリと、そのアセンブリを参照するアセンブリにだけ適用します。別の場所に移すと何も解析しません

リポジトリのルートには、名前がcom.vertoker.bullet-hero-sdk、Unityの最小バージョンが6000.0のpackage.jsonがあります。そのため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引数が正しくない
2level.*またはmetadata.*が見つからない
3往復変換の結果が一致しなかった
4ファイルがこのSDKより新しい

ゲームの組み込みレベルnew-zero-demoでの出力（sv 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コア：モデル、シリアライズ、バージョン、ルール、検証、アーカイブ、公開、ジェネレーターいいえ
UnityIntegrationすべてのファイルがUnityありでもなしでもコンパイルされる薄い層（#if BHSDK_UNITY）。たとえばCatロガーいいえ：Unityの外ではコアに直接コンパイルされる
UnityExtensionsUnityの型への変換、2Dトランスフォーム、アバターの移動はい、常に
BH.SDK.Roslynアナライザーとソースジェネレーター。[GenerateModel]の付いたモデルごとに、Equals、コピー、JSONと.blobのコーデック、検証の走査を書き出すコンパイル時に動作

モデルのファイルには、フィールドとコンストラクターだけが書かれています。繰り返しになる部分はすべてジェネレーターが書きます。そのため、生成される7つの本体のどれかでフィールドを書き忘れることがありません

独立したライブラリにした理由

  • レベルはゲームより長く残ります。レベルはオープンなフォーマット（JSON、tar.gz、zip、OpenPGP）のファイルが入ったフォルダーです。それを読むコードもオープンです。書き出したゲームがなくなっても、レベルは読めるまま残ります
  • 他のリズムゲームとの連携。フォーマットが公開されているので、他のゲームとの相互変換ツールをそれに基づいて書けます
  • 素早い修正。フォーマットの欠陥は外から見えます。コードを読んだ人なら誰でも、報告したり修正を送ったりできます
  • サードパーティーのツール。コンバーター、バリデーター、レベルジェネレーター、MODは、ゲームと同じモデルで動きます。ファイルからモデルを再構築する必要はありません
  • サーバー。コアはUnityなしでnetstandard2.1としてビルドされます。そのため、サーバーはクライアントと同じモデルに対して同じチェックを実行します