BlizzCrafter.MonoGame.AssetService 1.0.0-preview.2

MonoGame.AssetService

MonoGame.AssetService provides the manifest contract, manifest builder support, and runtime asset loading for MonoGame projects.

Packages:

• MonoGame.AssetService: manifest model and runtime loading API
• MonoGame.AssetService.Builder: manifest generation for content build projects

Basic usage

Build-time manifest generation

Add MonoGame.AssetService.Builder to your content builder project and write the manifest after a successful build:

using Microsoft.Xna.Framework.Content.Pipeline;
using Microsoft.Xna.Framework.Content.Pipeline.Processors;
using MonoGame.AssetService.Builder;
using MonoGame.Framework.Content.Pipeline.Builder;
using System.Reflection;

var contentCollectionArgs = new ContentBuilderParams()
{
    Mode = ContentBuilderMode.Builder,
    SourceDirectory = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../Assets")),
    WorkingDirectory = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../")),
    OutputDirectory = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../bin")),
    IntermediateDirectory = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../obj")),
    Platform = TargetPlatform.DesktopGL
};

Assembly.Load("MonoGame.AssetService.Builder"); // 3.8.5-develop.13 fix

var builder = new Builder();

if (args is not null && args.Length > 0)
{
    builder.Run(args);
}
else
{
    builder.Run(contentCollectionArgs);
}

if (builder.FailedToBuild == 0)
{
    builder.WriteAssetManifest();
}

return builder.FailedToBuild > 0 ? -1 : 0;

public class Builder : ContentBuilder
{
    public override IContentCollection GetContentCollection()
    {
        var contentCollection = new ContentCollection();

        contentCollection.Include<WildcardRule>("Engine/Effects/*.fx");
        contentCollection.Include<WildcardRule>("Engine/Fonts/*.spritefont");

        contentCollection.IncludeCopy<WildcardRule>("Game/GUI/*.json");
        contentCollection.Include<WildcardRule>("Game/GUI/*.png");
        contentCollection.Include<WildcardRule>("*.spritegroup", new SpriteGroupImporter(), new SpriteGroupProcessor());

        return contentCollection;
    }

    // Writes the actual asset manifest
    public void WriteAssetManifest()
    {
        var writer = new AssetManifestWriter();
        writer.Write(Parameters, GetContentCollection(), Logger);
    }
}

The manifest is written to:

• Content/__asset-manifest.v1.json

Using the AssetService

using Microsoft.Xna.Framework.Content;
using MonoGame.AssetService;

var assetService = Content.CreateAssetService();

var effect = assetService.Load<Effect>("Engine/Effects/Water");
string guiJson = assetService.ReadText("Game/GUI/Theme/system_style");

Manifest format

The manifest contains entries like this:

{
  "assetPath": "Demo/Misc",
  "kind": "Container",
  "alias": "Demo.Misc",
  "qualifiedAlias": "Demo.Misc",
  "sourcePath": "Demo/Misc.spritegroup",
  "outputPath": "Demo/Misc"
},
{
  "assetPath": "Demo/Misc/Player",
  "kind": "Item",
  "alias": "Player",
  "qualifiedAlias": "Demo.Misc.Player",
  "containerPath": "Demo/Misc",
  "itemKey": "Player",
  "sourcePath": "Demo/Misc.spritegroup",
  "outputPath": "Demo/Misc"
},
{
  "assetPath": "Engine/Effects/Disabled",
  "kind": "Build",
  "sourcePath": "Engine/Effects/Disabled.fx",
  "outputPath": "Engine/Effects/Disabled"
},
{
  "assetPath": "Demo/GUI/DefaultTheme/Styles/horizontal_line",
  "kind": "Copy",
  "sourcePath": "Demo/GUI/DefaultTheme/Styles/horizontal_line.json",
  "outputPath": "Demo/GUI/DefaultTheme/Styles/horizontal_line.json"
}

How identifiers are resolved

Load<T>(string assetPath) is the standard entry point.

The supplied string is resolved in this order:

• qualified alias, for example Demo.Misc.Player
• canonical asset path, for example Engine/Effects/Water
• unqualified alias when it is unique

This allows runtime code to stay on a single loading API while manifest-backed aliases and canonical asset paths both remain supported.

Copied assets

Copied assets are accessed through file-oriented APIs:

using var stream = assetService.OpenStream("Game/GUI/Theme/system_style");
string json = assetService.ReadText("Game/GUI/Theme/system_style");
string fullPath = assetService.GetPhysicalPath("Game/GUI/Theme/system_style");

Advanced customization

Advanced scenarios can still provide custom asset resolvers or container resolvers through AssetServiceOptions, but the default user path is:

assetService.Load<T>("...")

Use custom resolvers only when your project introduces runtime asset types that need specialized loading beyond standard built content and copied files.

NuGet packages publish matching .snupkg symbol packages for debugging.