Bricks: NuGet package dependencies (restore, lock file, editor loading) #313

Current State

Bricks declare NuGet dependencies in a nuget map in package.json. Generated game projects already turn that map into PackageReference items (CsProjectGenerator.AddBrickPackages). The editor, however, cannot load a precast brick assembly that depends on a package it doesn't already reference itself. BrickAssemblies.Load only loads the DLLs in Precast~/lib into the default load context; nothing probes package folders.

Bricks work around this by copying third-party DLLs into Precast~/lib from their csproj:

• org.mass4.turian.ui copies Guinevere.dll and Guinevere.Styling.dll from its references. It depends on MASS4.Guinevere 6.*, a floating version. SkiaSharp is in its nuget map, and the editor loads it only because the editor references SkiaSharp itself.
• org.mass4.turian.physics.bepu (Physics: backend, rigid bodies and collision #64) copies BepuPhysics.dll and BepuUtilities.dll and has no nuget map.

Hand-listed DLL copies are a stopgap. If user bricks can't depend on NuGet packages, the brick ecosystem fails. The missing piece is tooling (restore plus probe-path wiring), not a .NET constraint.

Goal

A brick's nuget map is the single source of truth for its package dependencies. The editor restores the map, loads the packages, and resolves version conflicts between bricks; game export ships the resolved packages. Builds are reproducible through a lock file.

Design decisions

1. Restore: one generated stub project merges the nuget maps of all loaded bricks, and dotnet restore restores it. Use one stub for all bricks, not one per brick, so there is one lock file and the conflict policy has a single place to live. dotnet restore is preferred over in-process NuGet.Protocol, which would add a dependency to the editor.
2. Hermetic cache: dotnet restore writes to ~/.nuget/packages by default. Next to the stub project, generate a NuGet.config with <config><add key="globalPackagesFolder" value="Library/NuGet" /></config>, or set NUGET_PACKAGES for the restore process, so packages live in the project's cache. Pick the exact folder (Library/NuGet or .Cache/NuGet) to match the existing project layout.
3. Lock file: generate with RestorePackagesWithLockFile=true. Restores during editor load and in CI use --locked-mode, so a committed packages.lock.json is authoritative.
4. No floating versions: reject floating versions (2.5.*, 6.*) in brick nuget maps, or resolve them at restore time and write the pin back. Floating versions combined with a lock file is how drift creeps in. Migrate the UI brick's 6.* Guinevere reference.
5. Version unification across bricks:
   • Within a major version, the highest requested version wins.
   • Different major versions are a hard error that names both bricks and both versions.
   • Ordering follows NuGet's SemVer 2.0 rules, prerelease labels included: 2.5.0-beta.33 is above 2.5.0-beta.9, and a release is above its prereleases. Compare with NuGetVersion, never with string >.
6. Editor loading:
   • Emit a .deps.json beside each precast brick assembly; the stub restore already produces the data.
   • Load each brick through an AssemblyDependencyResolver, which gives the transitive closure and per-context version selection.
   • A Resolving handler is only a fallback.
   • Every brick's resolver must see the unified restore's result, so two bricks never load two versions of one package.
7. Precast~/lib commit policy:
   • Keep Precast~/lib copies as a generated artifact (restore, then copy), never a hand-maintained list.
   • First-party bricks commit the generated copy, so a fresh clone loads offline and CI needs no restore for editor-only paths.
   • Add a drift test that restores from the map and compares against the committed DLLs by assembly and package version, not file hash, so build noise doesn't cause false failures. Run it alongside BrickVerifier.
8. Scope: pure managed packages only. Packages with native assets, or transitive native assets, are out of scope and need extra handling later. Brick READMEs must not promise them.

Tasks

• Generate the merged stub project (all loaded bricks' nuget maps), its NuGet.config with a project-local globalPackagesFolder, and RestorePackagesWithLockFile.
• Run dotnet restore when bricks load and when they are installed or changed; use --locked-mode when a lock file exists. Report restore failures in the Output panel and the CLI.
• Unify versions across bricks: highest within a major, a hard error across majors, NuGet SemVer prerelease ordering (NuGetVersion).
• Reject floating versions in nuget maps, or pin them on restore.
• Load precast brick assemblies through AssemblyDependencyResolver with a generated .deps.json; keep a Resolving fallback.
• Generate Precast~/lib third-party copies from the nuget map (restore, then copy), replacing the hand-listed copies in the UI and physics bricks' csproj files.
• Add a drift test: restore the map and compare the committed Precast~/lib DLLs by version.
• Migrate org.mass4.turian.ui: pin Guinevere and move it into the nuget map.
• Migrate org.mass4.turian.physics.bepu: add "nuget": { "BepuPhysics": "2.5.0-beta.33", "BepuUtilities": "2.5.0-beta.33" }.
• Game export: confirm resolved packages are copied through the existing PackageReference path, and that server builds still leave out client-only bricks' packages.
• Docs: a brick authoring section on NuGet dependencies, covering the lock file, the version policy, and the pure-managed limit.

Acceptance Criteria

• A brick that depends only on a NuGet package, with no DLLs in Precast~/lib, loads in the Studio and the CLI, and its types work in play mode.
• Two bricks asking for X 1.2.0 and X 1.4.0 both load 1.4.0. Asking for X 1.x and X 2.x fails with an error naming both bricks.
• 2.5.0-beta.33 is chosen over 2.5.0-beta.9.
• A committed packages.lock.json is enforced: a change to a nuget map without updating the lock fails in locked mode.
• A fresh clone opens offline with the first-party bricks.
• The drift test fails when a nuget map and the committed Precast~/lib disagree.
• The UI and physics bricks no longer hand-list DLL copies.
• Exported games run with brick packages; server builds stay free of client-only packages.

Related

• Physics: backend, rigid bodies and collision #64 (physics backend; the Bepu brick currently vendors its DLLs)
• Brick manifest platform allow-list and per-platform NuGet (Bricks: platform allow-list and per-platform NuGet in brick manifests #248)