Class Package

Namespace

Stride.Core.Assets

Assembly

Stride.Core.Assets.dll

A package managing assets.

[DataContract("Package")]
[AssetDescription(".sdpkg")]
[AssetFormatVersion("Assets", "3.1.0.0", "0.0.0.4")]
[AssetUpgrader("Assets", "0.0.0.4", "3.1.0.0", typeof(Package.MovePackageInsideProject))]
public sealed class Package : IFileSynchronizable, IAssetFinder

Inheritance

object

Package

Implements

IFileSynchronizable

IAssetFinder

Extension Methods

PackageExtensions.FindAsset(Package, IReference)

PackageExtensions.FindDependencies(Package, bool)

UnsafeUtilities.As<T>(object?)

Constructors

Package()

Initializes a new instance of the Package class.

public Package()

Fields

PackageFileExtension

The file extension used for Package.

public const string PackageFileExtension = ".sdpkg"

Field Value

string

Properties

AssetAssemblies

The former name of HostAssemblies.

[Obsolete("Use HostAssemblies.")]
public List<AssetAssembly> AssetAssemblies { get; }

Property Value

List<AssetAssembly>

AssetFolders

Gets the asset directories to lookup.

[DataMember(40, DataMemberMode.Assign)]
public AssetFolderCollection AssetFolders { get; set; }

Property Value

AssetFolderCollection

The asset directories.

AssetNamespace

Asset URL namespace: unset = the package name (the default), any other value = that custom prefix. Packed sdpkgs store the resolved name.

[DataMember(106)]
public string? AssetNamespace { get; set; }

Property Value

string

Assets

Gets the assets stored in this package.

public PackageAssetCollection Assets { get; }

Property Value

PackageAssetCollection

The assets.

AuthoredName

The authored name from the package file, when the session renamed Meta.Name to the csproj-derived identity; saving writes this name back so the file keeps its authored identity.

public string? AuthoredName { get; set; }

Property Value

string

Bundles

Gets the bundles defined for this package.

[DataMember(80)]
public BundleCollection Bundles { get; }

Property Value

BundleCollection

The bundles.

CompanionPackages

Packages a host loads on this package's behalf (StrideCompanionProject and StrideCompanionPackage items).

[DataMember(107)]
public List<CompanionPackage> CompanionPackages { get; }

Property Value

List<CompanionPackage>

Container

public PackageContainer Container { get; }

Property Value

PackageContainer

ExplicitFolders

Gets or sets the list of folders that are explicitly created but contains no assets.

[DataMember(70)]
public List<UDirectory> ExplicitFolders { get; }

Property Value

List<UDirectory>

FullPath

Gets the path to the package file. May be null if the package was not loaded or saved.

public UFile FullPath { get; set; }

Property Value

UFile

The package path.

HostAssemblies

Assemblies (relative to this package) whose types appear in assets: the asset compiler and the editor load exactly these.

[DataMember(105)]
[DataAlias("AssetAssemblies")]
public List<AssetAssembly> HostAssemblies { get; }

Property Value

List<AssetAssembly>

IsDirty

Gets or sets a value indicating whether this instance has been modified since last saving.

public bool IsDirty { get; set; }

Property Value

bool

true if this instance is dirty; otherwise, false.

IsImplicitProject

public bool IsImplicitProject { get; }

Property Value

bool

IsReadOnly

Gets a value indicating whether this package is read-only: a restored dependency (or otherwise not backed by an editable in-solution SolutionProject), so it is never edited or saved.

public bool IsReadOnly { get; }

Property Value

bool

Kind

What this package carries (StridePackageKind): a companion package states it, so a host can check it took what the declaring package announced. Packed sdpkgs and build manifests carry it; an authored sdpkg does not.

[DataMember(104)]
public PackageKind Kind { get; set; }

Property Value

PackageKind

LoadDependencyNames

The names of the packages this one binds to when its assembly loads: its dependencies, without the companions a host loads on its behalf, since a companion references this package and not the other way round.

public IEnumerable<string> LoadDependencyNames { get; }

Property Value

IEnumerable<string>

LoadedAssemblies

Gets the list of assemblies loaded by this package.

public List<PackageLoadedAssembly> LoadedAssemblies { get; }

Property Value

List<PackageLoadedAssembly>

The loaded assemblies.

Meta

Gets or sets the metadata associated with this package.

[DataMember(10)]
public PackageMeta Meta { get; set; }

Property Value

PackageMeta

The meta.

OutputGroupDirectories

Gets the output group directories.

[DataMember(50, DataMemberMode.Assign)]
public Dictionary<string, UDirectory> OutputGroupDirectories { get; set; }

Property Value

Dictionary<string, UDirectory>

The output group directories.

ResourceFolders

Gets the resource directories to lookup.

[DataMember(45, DataMemberMode.Assign)]
public List<UDirectory> ResourceFolders { get; set; }

Property Value

List<UDirectory>

The resource directories.

RootAssets

Asset references that needs to be compiled even if not directly or indirectly referenced (useful for explicit code references).

[DataMember(100)]
public RootAssetCollection RootAssets { get; }

Property Value

RootAssetCollection

RootDirectory

Gets the top directory of this package on the local disk.

public UDirectory? RootDirectory { get; }

Property Value

UDirectory

The top directory.

RootNamespace

public string? RootNamespace { get; }

Property Value

string

SerializedVersion

Gets or sets the version number for this asset, used internally when migrating assets.

[DataMember(-8000, DataMemberMode.Assign)]
[DataStyle(DataStyle.Compact)]
[Display(null, null, Browsable = false)]
public Dictionary<string, PackageVersion>? SerializedVersion { get; set; }

Property Value

Dictionary<string, PackageVersion>

The version.

Session

Gets the session.

public PackageSession? Session { get; }

Property Value

PackageSession

The session.

Exceptions

InvalidOperationException

Cannot attach a package to more than one session

State

public PackageState State { get; set; }

Property Value

PackageState

TemplateFolders

Gets the template folders.

[DataMember(90)]
public List<TemplateFolder> TemplateFolders { get; }

Property Value

List<TemplateFolder>

The template folders.

Templates

Gets the loaded templates from the TemplateFolders

public List<TemplateDescription> Templates { get; }

Property Value

List<TemplateDescription>

The templates.

TemporaryAssets

Gets the temporary assets list loaded from disk before they are going into Assets.

public List<AssetItem> TemporaryAssets { get; }

Property Value

List<AssetItem>

The temporary assets.

Toolkit

The UI toolkit an Editor package's views are written for (StrideEditorToolkit, e.g. Wpf); null for a toolkit-neutral package. Packed sdpkgs and build manifests carry it; an authored sdpkg does not.

[DataMember(108)]
public string? Toolkit { get; set; }

Property Value

string

UserSettings

Gets the package user settings. Usually stored in a .user file alongside the package. Lazily loaded on first time.

public PackageUserSettings UserSettings { get; }

Property Value

PackageUserSettings

The package user settings.

Methods

AddExistingProject(UFile)

Adds an existing project to this package.

public LoggerResult AddExistingProject(UFile pathToMsproj)

Parameters

pathToMsproj UFile

The path to msproj.

Returns

LoggerResult

LoggerResult.

AddExistingProject(UFile, LoggerResult)

Adds an existing project to this package.

public void AddExistingProject(UFile pathToMsproj, LoggerResult logger)

Parameters

pathToMsproj UFile

The path to msproj.

logger LoggerResult

The logger.

Clone()

Deep clone this package.

public Package Clone()

Returns

Package

The package cloned.

FindAsset(AssetId)

Finds an asset by its identifier.

public AssetItem? FindAsset(AssetId assetId)

Parameters

assetId AssetId

The identifier of the asset.

Returns

AssetItem

The corresponding AssetItem if found; otherwise, null.

Remarks

Looks for the asset amongst the current package and its dependencies.

FindAsset(UFile)

Finds an asset by its location.

public AssetItem? FindAsset(UFile location)

Parameters

location UFile

The location of the asset.

Returns

AssetItem

The corresponding AssetItem if found; otherwise, null.

Remarks

Looks for the asset amongst the current package and its dependencies.

FindAssetFromProxyObject(object?)

Finds an asset from a proxy object.

public AssetItem? FindAssetFromProxyObject(object? proxyObject)

Parameters

proxyObject object

The proxy object which is represent the targeted asset.

Returns

AssetItem

The corresponding AssetItem if found; otherwise, null.

Remarks

Looks for the asset amongst the current package and its dependencies.

FindAssetsInProject(string, out string?)

public static List<(UFile FilePath, UFile? Link)> FindAssetsInProject(string projectFullPath, out string? nameSpace)

Parameters

projectFullPath string

nameSpace string

Returns

List<(UFile FilePath, UFile Link)>

GetDefaultAssetFolder()

public UDirectory GetDefaultAssetFolder()

Returns

UDirectory

GetPackageIdFromFile(string)

Gets the package identifier from file.

public static Guid GetPackageIdFromFile(string filePath)

Parameters

filePath string

The file path.

Returns

Guid

Guid.

Exceptions

ArgumentNullException

log or filePath

ListAssetFiles(Package, bool, bool, bool)

public static List<PackageLoadingAssetFile> ListAssetFiles(Package package, bool listAssetsInMsbuild, bool listUnregisteredAssets, bool listAssetsOfUnknownType = false)

Parameters

package Package

listAssetsInMsbuild bool

listUnregisteredAssets bool

Every .sd* file is an asset file, whatever its type (packing).

listAssetsOfUnknownType bool

Also list .sd* files starting with a Yaml type tag whose type is not loaded.

Returns

List<PackageLoadingAssetFile>

Load(ILogger, string, PackageLoadParameters?)

Loads only the package description but not assets or plugins.

public static Package? Load(ILogger log, string filePath, PackageLoadParameters? loadParametersArg = null)

Parameters

log ILogger

The log to receive error messages.

filePath string

The file path.

loadParametersArg PackageLoadParameters

The load parameters argument.

Returns

Package

A package.

Exceptions

ArgumentNullException

log or filePath

LoadProject(ILogger, string)

public static PackageContainer LoadProject(ILogger log, string filePath)

Parameters

log ILogger

filePath string

Returns

PackageContainer

LoadTemporaryAssets(ILogger, List<PackageLoadingAssetFile>?, bool, Func<PackageLoadingAssetFile, bool>?, CancellationToken, bool)

Refreshes this package from the disk by loading or reloading all assets.

public void LoadTemporaryAssets(ILogger log, List<PackageLoadingAssetFile>? assetFiles = null, bool listAssetsInMsbuild = true, Func<PackageLoadingAssetFile, bool>? filterFunc = null, CancellationToken cancellationToken = default, bool listAssetsOfUnknownType = false)

Parameters

log ILogger

The log.

assetFiles List<PackageLoadingAssetFile>

The asset files (loaded from ListAssetFiles(Package, bool, bool, bool) if null).

listAssetsInMsbuild bool

Specifies if we need to evaluate MSBuild files for assets.

filterFunc Func<PackageLoadingAssetFile, bool>

A function that will filter assets loading

cancellationToken CancellationToken

The cancellation token.

listAssetsOfUnknownType bool

Exceptions

InvalidOperationException

Package RootDirectory is null or Package RootDirectory [{0}] does not exist.ToFormat(RootDirectory)

SaveSingleAsset(AssetItem, ILogger)

public static bool SaveSingleAsset(AssetItem asset, ILogger log)

Parameters

asset AssetItem

log ILogger

Returns

bool

SetCompanionDeclarations(AssetBuildManifest, string)

Applies a build manifest's kind, toolkit and companions; a companion of the same kind and name is completed, others are added.

public void SetCompanionDeclarations(AssetBuildManifest manifest, string manifestDirectory)

Parameters

manifest AssetBuildManifest

manifestDirectory string

SetPackagePath(UFile, bool)

Sets the package path.

public void SetPackagePath(UFile newPath, bool copyAssets = true)

Parameters

newPath UFile

The new path.

copyAssets bool

if set to true assets will be copied relatively to the new location.

UpdateAssemblyReferences(ILogger, PackageLoadParameters?)

Loads the assembly references that were not loaded before.

public void UpdateAssemblyReferences(ILogger log, PackageLoadParameters? loadParametersArg = null)

Parameters

log ILogger

The log.

loadParametersArg PackageLoadParameters

The load parameters argument.

ValidateAssets(bool, bool, ILogger)

public void ValidateAssets(bool alwaysGenerateNewAssetId, bool removeUnloadableObjects, ILogger log)

Parameters

alwaysGenerateNewAssetId bool

removeUnloadableObjects bool

log ILogger

Events

AssetDirtyChanged

Occurs when an asset dirty changed occurred.

public event DirtyFlagChangedDelegate<AssetItem> AssetDirtyChanged

Event Type

DirtyFlagChangedDelegate<AssetItem>

PackageDirtyChanged

Occurs when package dirty changed occurred.

public event DirtyFlagChangedDelegate<Package> PackageDirtyChanged

Event Type

DirtyFlagChangedDelegate<Package>