Skip to content

Asset compiler: load from .sdbuild manifests instead of walking the csproj graph#3219

Merged
xen2 merged 11 commits into
stride3d:masterfrom
xen2:feature/sdbuild
Jun 17, 2026
Merged

Asset compiler: load from .sdbuild manifests instead of walking the csproj graph#3219
xen2 merged 11 commits into
stride3d:masterfrom
xen2:feature/sdbuild

Conversation

@xen2

@xen2 xen2 commented Jun 14, 2026

Copy link
Copy Markdown
Member

PR Details

The asset compiler used to rediscover which assemblies and assets to load by re-walking the csproj/ProjectReference graph on every run and guessing from implicit conventions.

Now every project emits a small .sdbuild manifest at build time (into obj/) describing exactly what the compiler needs (package, asset items, assemblies, referenced manifests, lock file) and the compiler reads that instead of evaluating MSBuild.

NuGet packages declare their asset types in their packed sdpkg.

Highlights

  • ~9× faster in-tree asset compile, ~40% for consumers (Stride.Graphics.Tests ~14.5s → ~1.6s; a consumer game ~4.1s → ~2.4s). Evaluation moves into the build, where it's incremental.
  • Unambiguous semantics — a missing assembly is now always a real error, not "broken or just unnecessary?". No first-TFM-ordering accident, no loading unrelated graph assemblies.
  • One declaration in csproj, <StrideAssetAssembly> which means "this assembly's types appear in assets", the single authoring surface. On by default for game/code projects; the generation and pack targets both consume it.
  • Mobile/cross-platform builds no longer fragile: non-host TFMs reference their host-TFM sibling manifest; no path guessing, no on-demand graphics-API build. Validated on Android.
  • New analyzer STRDIAG011 warns at compile time when an IProjectAsset type's extension isn't declared, instead of silently dropping its assets. ≤5 ms/compilation.
  • CItests/enduser/Stride.Packaging.Tests (Windows + Linux) packs a real plugin and consumes it via a true PackageReference.

What this unlocks

  • First-class third-party asset plugins over NuGet: a package ships asset types and they load because it declares them (AssetAssemblies), proven load-bearing by the packaging test. Previously only worked by accident for engine packages the compiler force-registers.
  • Plugins can add their own project-source asset extensions; the extension list is now a transitive, plugin-extensible property (+ the analyzer guard) rather than a hardcoded engine edit.
  • Sub-process / isolated asset builds with no live csproj graph required, CI suites no longer each re-evaluate the engine project graph.
  • Foundation for editor plugin surfaces and metadata-only editor loading. sdpkg is now the declared place a package describes its surface.

Types of changes

  • Docs change / refactoring / dependency upgrade
  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)

Checklist

  • My change requires a change to the documentation.
  • I have added tests to cover my changes.
  • All new and existing tests passed.
  • I have built and run the editor to try this change out.

@xen2 xen2 force-pushed the feature/sdbuild branch 3 times, most recently from 27e419e to 232ec3a Compare June 15, 2026 09:13
@xen2

xen2 commented Jun 15, 2026

Copy link
Copy Markdown
Member Author

/ci e2e

@stride-chatops

stride-chatops Bot commented Jun 15, 2026

Copy link
Copy Markdown

@xen2/ci dispatched:

⚠️ This PR modifies workflow YAML used by /ci, but the bot runs master's version:

Land workflow changes on master first if you need them tested.

@stride-chatops

Copy link
Copy Markdown

@VaclavElias

VaclavElias commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

I wonder if your updates allow using this feature https://learn.microsoft.com/en-us/dotnet/core/sdk/file-based-apps for some small examples.

I tried most recent stride build a few days ago with our community toolkit but obviously it doesn't work because the project is created somewhere in the temp folder and the asset compiler paths are not aware of such scenario. I can create a separate issue for that but maybe this is really low priorirty.

@xen2

xen2 commented Jun 16, 2026

Copy link
Copy Markdown
Member Author

/ci e2e

@stride-chatops

stride-chatops Bot commented Jun 16, 2026

Copy link
Copy Markdown

@xen2/ci dispatched:

⚠️ This PR modifies workflow YAML used by /ci, but the bot runs master's version:

Land workflow changes on master first if you need them tested.

@stride-chatops

Copy link
Copy Markdown

@xen2 xen2 force-pushed the feature/sdbuild branch 2 times, most recently from 4735df1 to 9b90fd7 Compare June 16, 2026 09:16
@Kryptos-FR

Copy link
Copy Markdown
Member

I wonder if your updates allow using this feature https://learn.microsoft.com/en-us/dotnet/core/sdk/file-based-apps for some small examples.

I tried most recent stride build a few days ago with our community toolkit but obviously it doesn't work because the project is created somewhere in the temp folder and the asset compiler paths are not aware of such scenario. I can create a separate issue for that but maybe this is really low priorirty.

I also think it is low priority but it's nice to track it as an issue.

@xen2 xen2 force-pushed the feature/sdbuild branch from 9b90fd7 to 3375c6e Compare June 16, 2026 10:29
xen2 added 4 commits June 17, 2026 10:17
…-in)

Manifest mode (--package-manifest / StrideAssetBuildManifestMode) loads the
session from the .sdbuild chain instead of walking csproj files: chases
referenced manifests, reads sdpkg-carrying NuGet packages from the lock file
directly, loads and registers exactly the declared AssetAssemblies, and takes
project assets from the manifest. No MSBuild evaluation, no reference-graph
loading. Verified functionally equivalent to the legacy walk on a NuGet-consumer
game (identical asset URL set; byte diffs are inherent skybox nondeterminism).
@xen2 xen2 force-pushed the feature/sdbuild branch from 3375c6e to f8c818a Compare June 17, 2026 02:14
xen2 added 7 commits June 17, 2026 11:27
…ed host assembly

pack-assets writes the host-loadable assembly (lib/<host-tfm>/<name>.dll) into the
packed sdpkg's AssetAssemblies; the manifest-mode consumer prefers those over the
lock file's runtime assemblies (falling back when a package predates the member).
Engine runtime asset packages declare StrideAssetAssembly=true so their packed
sdpkgs carry the entry. Validated: pack-assets + the pack target emit the entry for
Stride.Engine, and the consumer honors it (engine packages also stay robust via the
compiler's own assembly closure).
…w to test-enduser

Harness moves from samples/Tests/; fixtures+baselines into Fixtures/ subdir. Rename test-samples-screenshots workflow -> test-enduser (file, display name, repository_dispatch event, chatops suite key samples->enduser). Repoint runtime paths, baselines workflow, chatops map/help, CONTRIBUTING, and docs.
The build path now loads only from the .sdbuild chain. Drops the
StrideAssetBuildManifestMode toggle and the shadow validator; legacy
csproj graph-load stays for the editor and pack modes.
An IProjectAsset type whose [AssetDescription] extension is missing from StrideProjectAssetExtensions would silently drop its assets from the build; warn at compile time. Skips .cs and generator assets.
The name was a relic of the era when 'in solution = user project, from package = read-only system'. It actually means 'not backed by an editable in-solution SolutionProject' (a restored dependency, or any package in manifest mode), i.e. read-only. Pure rename; no behavior change. Also drops a now-redundant duplicate check.
Package -> PackageFile (matches its sibling ProjectFile, and stops shadowing the Package class). ProjectAssetsFile -> NuGetLockFile (it's the project.assets.json lock file; the old name was one letter off from ProjectAssets, the .sdsl item list, which is unrelated). Regenerated format, no migration.
@xen2 xen2 force-pushed the feature/sdbuild branch from f8c818a to d91f0d6 Compare June 17, 2026 02:28
@xen2 xen2 merged commit 7962964 into stride3d:master Jun 17, 2026
45 of 47 checks passed
@xen2 xen2 deleted the feature/sdbuild branch June 17, 2026 03:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants