Installation¶

Get Brine2D up and running in minutes with .NET 10 and your favorite IDE.

Overview¶

Brine2D is a single package for .NET 10:

Brine2D - Core engine, rendering, input, audio, ECS - everything you need

Optional packages: - Brine2D.Build - Compile-time asset path generation (auto-generates typed Assets class from your assets folder)

Prerequisites¶

Required¶

.NET 10 SDK - Download here
IDE - Visual Studio 2022+, VS Code, or Rider

Optional¶

Git - For cloning samples

Verify .NET 10¶

Check your .NET version:

dotnet --version

Expected output:

10.0.xxx

If you see 9.x or earlier, download .NET 10 SDK.

Quick Install¶

Option 1: New Project (Recommended)¶

Create a new game from scratch:

dotnet new console -n MyGame
cd MyGame
dotnet add package Brine2D

Project structure:

MyGame/
├── MyGame.csproj
├── Program.cs
└── assets/          (create this folder)
    ├── images/
    ├── audio/
    └── fonts/

Option 2: Add to Existing Project¶

Add Brine2D to an existing .NET 10 project:

cd YourExistingProject
dotnet add package Brine2D

Option 3: Manual .csproj Edit¶

Edit your .csproj file directly:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Brine2D" Version="x.x.x" />
  </ItemGroup>

  <!-- Copy assets to output -->
  <ItemGroup>
    <None Update="assets\**\*">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
  </ItemGroup>
</Project>

Optional: Brine2D.Build¶

For compile-time asset path generation:

dotnet add package Brine2D.Build

This auto-generates a strongly-typed Assets class from your assets/ folder, giving you IntelliSense and compile-time safety for asset paths. See the Brine2D.Build README for details.

Verify Installation¶

After installing, create a minimal Program.cs:

using Brine2D.Core;
using Brine2D.Engine;
using Brine2D.Hosting;
using Brine2D.Input;

var builder = GameApplication.CreateBuilder(args);

builder.Configure(options =>
{
    options.Window.Title = "Test Game";
    options.Window.Width = 800;
    options.Window.Height = 600;
});

builder.AddScene<TestScene>();

await using var game = builder.Build();
await game.RunAsync<TestScene>();

public class TestScene : Scene
{
    private readonly IGameContext _gameContext;

    public TestScene(IGameContext gameContext)
    {
        _gameContext = gameContext;
    }

    protected override void OnRender(GameTime gameTime)
    {
        Renderer.DrawText("Brine2D works!", 100, 100, Color.White);
    }

    protected override void OnUpdate(GameTime gameTime)
    {
        if (Input.IsKeyPressed(Key.Escape))
            _gameContext.RequestExit();
    }
}

Run it:

dotnet run

You should see a window with "Brine2D works!" displayed.

Platform Setup¶

Windows¶

Brine2D works out of the box on Windows. No additional setup needed.

Linux¶

Install SDL3 development packages:

# Ubuntu/Debian
sudo apt install libsdl3-dev

# Fedora
sudo dnf install SDL3-devel

macOS¶

Install SDL3 via Homebrew:

brew install sdl3

Troubleshooting¶

Problem: Package not found¶

Symptom:

error NU1102: Unable to find package Brine2D

Solutions:

Check NuGet sources:
```
dotnet nuget list source
```

Ensure nuget.org is enabled:

dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org

Problem: Assets not found at runtime¶

Symptom:

FileNotFoundException: Could not find file 'assets/player.png'

Solution:

Check file location:
Assets must be relative to executable location
Default: bin/Debug/net10.0/
Copy assets to output:

<ItemGroup>
  <None Update="assets\**\*">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>

Use forward slashes (cross-platform):

// :white_check_mark: Works on all platforms
"assets/images/player.png"

// :x: Windows only
"assets\\images\\player.png"

Best Practices¶

DO¶

Copy assets to output directory

<None Update="assets\**\*">
  <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</None>

Use .gitignore for build artifacts
```
bin/
obj/
.vs/
*.user
```

Use centralized asset folders

assets/
├── images/
├── audio/
└── fonts/

DON'T¶

Don't hard-code absolute asset paths

// :x: Bad
var texture = await _assets.GetOrLoadTextureAsync("C:\\MyGame\\assets\\player.png");

// :white_check_mark: Good
var texture = await _assets.GetOrLoadTextureAsync("assets/images/player.png");

Summary¶

Package	Purpose	Required?
Brine2D	Core engine (rendering, input, audio, ECS, scenes)	Yes
Brine2D.Build	Compile-time asset path generation	Optional

Minimum requirements: - .NET 10 SDK - Brine2D package - IDE (VS 2022+, VS Code, or Rider)

Platform notes: - Windows: Works out of the box - Linux: Requires SDL3 dev packages - macOS: Requires Homebrew SDL3

Next Steps¶

Now that Brine2D is installed, let's create your first game!

Quick Start - Create your first scene in 5 minutes
Your First Game - Build a complete game
Project Structure - Organize your project
Configuration - Configure your game

Quick Reference¶

# Create new project
dotnet new console -n MyGame
cd MyGame
dotnet add package Brine2D
dotnet run

<!-- Minimal .csproj -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Brine2D" Version="x.x.x" />
  </ItemGroup>

  <ItemGroup>
    <None Update="assets\**\*">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
  </ItemGroup>
</Project>

Ready to create your first game? Head to Quick Start!