Brine2D.Build 1.0.0

Brine2D.Build

Status: Not yet published.
The package is complete and ready. It will be published alongside Brine2D 1.0 after cross-platform MSBuild validation (Windows/macOS/Linux, VS/Rider/CLI).
Track progress: github.com/CrazyPickleStudios/Brine2D

Optional MSBuild tooling for Brine2D.

Automatically generates a strongly-typed Assets class from your assets/ folder on every build. No content pipeline, no CLI tools, no .mgcb files. Add one PackageReference, drag files into your assets folder, and use them with full IntelliSense and compile-time safety.

Installation (when published)

dotnet add package Brine2D.Build

Or in your .csproj:

<PackageReference Include="Brine2D.Build" Version="1.0.0" />

That's it. The .targets file is imported automatically by NuGet. No further configuration required.

What Gets Generated

Given this folder structure:

assets/
  images/
    player.png
    background.png
    tileset.png
  audio/
    jump.wav
    hurt.wav
    music/
      theme.ogg
      battle.ogg
  fonts/
    ui.ttf
    mono.ttf

Brine2D.Build generates the following on every build (into obj/):

// <auto-generated>
// Generated by Brine2D.Build. Do not edit manually.
// Source: assets/
// Rebuilds automatically when files in that folder are added, removed, or renamed.
// </auto-generated>

namespace MyGame;

/// <summary>
/// Auto-generated path constants for every asset in assets/.
/// </summary>
public static partial class Assets
{
    /// <summary>Assets in audio/</summary>
    public static class Audio
    {
        /// <summary>assets/audio/jump.wav</summary>
        public const string Jump  = "assets/audio/jump.wav";

        /// <summary>assets/audio/hurt.wav</summary>
        public const string Hurt  = "assets/audio/hurt.wav";

        /// <summary>Assets in audio/music/</summary>
        public static class Music
        {
            /// <summary>assets/audio/music/battle.ogg</summary>
            public const string Battle = "assets/audio/music/battle.ogg";

            /// <summary>assets/audio/music/theme.ogg</summary>
            public const string Theme  = "assets/audio/music/theme.ogg";
        }
    }

    /// <summary>Assets in fonts/</summary>
    public static class Fonts
    {
        /// <summary>assets/fonts/mono.ttf</summary>
        /// <remarks>Fonts need a size: _assets.GetOrLoadFontAsync(Assets.Fonts.Mono, size: 16)</remarks>
        public const string Mono = "assets/fonts/mono.ttf";

        /// <summary>assets/fonts/ui.ttf</summary>
        /// <remarks>Fonts need a size: _assets.GetOrLoadFontAsync(Assets.Fonts.Ui, size: 16)</remarks>
        public const string Ui   = "assets/fonts/ui.ttf";
    }

    /// <summary>Assets in images/</summary>
    public static class Images
    {
        /// <summary>assets/images/background.png</summary>
        public const string Background = "assets/images/background.png";

        /// <summary>assets/images/player.png</summary>
        public const string Player     = "assets/images/player.png";

        /// <summary>assets/images/tileset.png</summary>
        public const string Tileset    = "assets/images/tileset.png";
    }
}

Usage

Use the generated constants directly with IAssetLoader, or as seeds for a typed AssetManifest:

Direct loading:

var tex  = await _assets.GetOrLoadTextureAsync(Assets.Images.Player);
var sfx  = await _assets.GetOrLoadSoundAsync(Assets.Audio.Jump);
var font = await _assets.GetOrLoadFontAsync(Assets.Fonts.Ui, size: 16);

Typed manifest (recommended for parallel load):

public class LevelAssets : AssetManifest
{
    public readonly AssetRef<ITexture>     Player  = Texture(Assets.Images.Player);
    public readonly AssetRef<ITexture>     Tileset = Texture(Assets.Images.Tileset, TextureScaleMode.Nearest);
    public readonly AssetRef<ISoundEffect> Jump    = Sound(Assets.Audio.Jump);
    public readonly AssetRef<IMusic>       Theme   = Music(Assets.Audio.Music.Theme);
    public readonly AssetRef<IFont>        HUD     = Font(Assets.Fonts.Ui, size: 20);
}

private readonly LevelAssets _manifest = new();

protected override async Task OnLoadAsync(CancellationToken ct)
{
    // All assets loaded in parallel. SceneManager updates loading screen progress
    // at its own waypoints; pass an IProgress<AssetLoadProgress> here for finer
    // reporting (e.g., updating a custom progress bar inside your scene logic).
    await _assets.PreloadAsync(_manifest, cancellationToken: ct);
}

protected override void OnEnter()
{
    // Implicit conversion; no .Value needed
    _player.Sprite.Texture = _manifest.Player;
    Audio.PlayMusic(_manifest.Theme);
}

Supported Asset Types

All other file types in the folder are silently ignored.

Configuration

All properties are optional. Override any of them in your .csproj:

<PropertyGroup>
  
  <Brine2DAssetsFolder>content</Brine2DAssetsFolder>

  
  <Brine2DAssetsNamespace>MyGame</Brine2DAssetsNamespace>

  
  <Brine2DAssetsClassName>GameAssets</Brine2DAssetsClassName>

  
  <Brine2DGenerateAssets>false</Brine2DGenerateAssets>
</PropertyGroup>

Incremental Builds

The generation target uses MSBuild Inputs/Outputs; it only runs when a file in your assets folder is newer than the generated .cs file.

The partial Keyword

The generated class is declared partial, which means you can extend it in your own code without conflict:

// Assets.cs, your file, alongside the generated one
public static partial class Assets
{
    // Anything declared here won't be overwritten on rebuild
    public static class Runtime
    {
        public static string LevelPath(int level) => $"assets/levels/level_{level:D2}.tmj";
    }
}

Without This Package

Brine2D.Build is entirely optional. You can write manifests by hand with full compile-time safety; the generated constants are just a convenience for larger projects:

// Works identically, no package required
public class LevelAssets : AssetManifest
{
    public readonly AssetRef<ITexture>     Player = Texture("assets/images/player.png");
    public readonly AssetRef<ISoundEffect> Jump   = Sound("assets/audio/jump.wav");
}

Requirements

• .NET 10 SDK
• Brine2D, the core engine package

License

MIT. See LICENSE.