Skip to content
Bullet Hero
Documentation
On this page
Developer

Contributing to the SDK

Report SDK problems in the issues of the bullet-hero/sdk repository, and send code changes there as pull requests. The contributor rules live in the same repository, next to the code

The repository is bullet-hero/sdk, the default branch is master

Where to report

What aboutWhere
the SDK and its codebullet-hero/sdk/issues
the game: players' bugs and requestsbullet-hero/releases/issues
the documentation textbullet-hero/docs

Where the rules are

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

FileWhat is in it
README.mddependencies, level packages, building the DLL and the package, the check sample
AGENTS.mdthe mental model, a folder index and the conventions of the whole library
AGENTS.md in every folderthe local rules of that folder, for example Serialization, Validations, Publishing
Docs/VERSIONING.mdversion axes, generations, migration and refusal
Docs/IDENTIFIERS.mdhow the model addresses entities: 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, newest on top

Build and tests

dotnet build -c Release BH.SDK.csproj
dotnet test Tests/BH.SDK.Tests.csproj
dotnet pack -c Release BH.SDK.csproj
  • here the same sources that Unity compiles are built without Unity. A file that breaks the engine-independence contract breaks this build
  • the output goes to bin~ and obj~
  • the pack command only creates a .nupkg. Publishing to nuget.org is done by the repository's release workflow when an sv tag is pushed
Caution

The analyzers and the model generator ship as a prebuilt BH.SDK.Roslyn.dll in the SDK root. After editing anything in Roslyn/, rebuild it and copy it over. Otherwise the old generator keeps running, even though 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 menu item Tools > BH.SDK.Roslyn > Build Analyzer does the same

Invariants worth knowing in advance

  • the core does not reference a single UnityEngine type. Code that needs the engine goes into UnityExtensions/ or into UnityIntegration/ behind #if BHSDK_UNITY with an engine-free branch
  • the code works the same with files and with in-memory data and uses only the asynchrony from the BCL
  • 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 field takes its key from Names.cs
  • any model change 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 if one of them moved alone