Skip to content
Bullet Hero
ENRU
Contributing to the SDK
On this page
Developer

Contributing to the SDK

Where to report problems, where the SDK's rules for contributors are written down, and how to build, test and pack it

The SDK is a separate repository: bullet-hero/sdk, with the default branch master. Changes to the SDK code arrive there as pull requests

Where to report

AboutWhere
the SDK and its codebullet-hero/sdk/issues
the game: bugs and requests from playersbullet-hero/releases/issues
the documentation textbullet-hero/docs

Where the rules are

The rules for contributors live in the SDK repository itself, next to the code they describe:

FileWhat it holds
README.mddependencies, level packages, building the DLL and the package, the smoke sample
CLAUDE.mdthe mental model, the index of folders and the conventions of the whole library
CLAUDE.md in each folderthe local rules of that folder, for example Serialization, Validations, Publishing
Docs/VERSIONING.mdthe version axes, generations, migration and refusal
Docs/IDENTIFIERS.mdhow a model addresses things: Guid, int, frame, field path
Licensing policy for user levels (on this site)the licensing policy for user content, edited together with TrustedSourceCatalog
Versions/README.mdhow to write a snapshot and a migrator
Generators/README.mdthe generator contract
Roslyn/README.mdthe analyzers and the model generator, how to rebuild them
UnityIntegration/README.mdthe dual-compilation contract
CHANGELOG.mdchanges by sv version, with an [Unreleased] section on top

Building and testing

dotnet build -c Release BH.SDK.csproj
dotnet test Tests/BH.SDK.Tests.csproj
dotnet pack -c Release BH.SDK.csproj
  • the same sources that Unity compiles build here without Unity. A file that breaks the engine-free contract fails this build
  • output goes to bin~ and obj~
  • the packing command only produces a .nupkg. Nothing is pushed to nuget.org from the repository
Caution

The analyzers and the model generator ship as a prebuilt BH.SDK.Roslyn.dll in the SDK root. After editing anything under Roslyn/, rebuild and copy it. Otherwise the old generator keeps running while the sources say otherwise

cd Roslyn
dotnet build BH.SDK.Roslyn.csproj -c Release
cp bin~/Release/BH.SDK.Roslyn.dll ../BH.SDK.Roslyn.dll
dotnet test Tests~/BH.SDK.Roslyn.Tests.csproj -c Release

Inside the Unity Editor the same is done by the menu item Tools > BH.SDK.Roslyn > Build Analyzer

Invariants worth knowing first

  • the core references no UnityEngine type. Code that needs the engine goes to UnityExtensions/, or to UnityIntegration/ behind #if BHSDK_UNITY with an engine-free branch
  • code works on files and on in-memory data alike, and uses only BCL async
  • netstandard2.1 and C# 9 are what the Unity project compiles with. They are not raised
  • a model is a [GenerateModel] public sealed partial class. Every serialized member takes its key from Names.cs
  • any change to the model is a new generation with a snapshot and a migrator. More - Versioning and migrations
  • the SDK version lives in three places: SdkVersion.cs, package.json and <Version> in BH.SDK.csproj. SdkVersionAgreementTests fails when one moves alone