DEV Community

Cover image for Run Unity3D as a First‑Class Service with .NET Aspire (Aspire.Unity experimental)
Dutchskull
Dutchskull

Posted on • Edited on

Run Unity3D as a First‑Class Service with .NET Aspire (Aspire.Unity experimental)

#gamedev #tooling #dotnet #aspire

.NET Aspire is a cloud‑native application model for composing APIs, databases, and background workers into a single distributed AppHost. Aspire.Unity (experimental) integrates Unity3D into that model so your Unity project starts, stops, and receives Aspire configuration as part of the same AppHost lifecycle — treating Unity like any other service in your topology.

Repo: https://github.com/Dutchskull/Aspire.Unity3D

Why bring Unity into Aspire?

  • Run Unity as a service alongside APIs, workers, and databases.
  • Start and stop Unity automatically with your AppHost.
  • Pass Aspire configuration and environment variables into the Unity runtime at startup.
  • Use Unity for live data visualization, server-driven simulation, automated play‑mode tests, or developer tooling integrated into your distributed app.

Quick install

  1. Add the NuGet package to your AppHost project: 
dotnet add package Dutchskull.Aspire.Unity
Enter fullscreen mode Exit fullscreen mode
  1. In Unity Package Manager add the Git packages:
  2. https://github.com/Dutchskull/Unity.Configuration.git?path=/Unity.Configuration/Packages/Unity.Configuration
  3. https://github.com/Dutchskull/Aspire.Unity3D.git?path=/AspireIntegration/Packages/AspireIntegration

Minimal example

Add one line to your AppHost to register a Unity project:

var unity = builder.AddUnityProject("game", "..\\..\\AspireIntegration", 1);
Enter fullscreen mode Exit fullscreen mode

This:

  • Registers a Unity project named "game".
  • Uses the relative path "..\..\AspireIntegration".
  • Starts Unity at the default URL http://127.0.0.1:54021.
  • Opens the scene at index 1 and starts Play mode.

Advanced usage

Two overloads let you choose scene by index or name and customize URL, port, and Unity install root:

public static IResourceBuilder<UnityProjectResource> AddUnityProject(
    this IDistributedApplicationBuilder builder,
    string name,
    string projectPath,
    int? sceneIndex = null,
    string url = "http://127.0.0.1",
    int port = 54021,
    string? customUnityInstallRoot = null) {...}

public static IResourceBuilder<UnityProjectResource> AddUnityProject(
    this IDistributedApplicationBuilder builder,
    string name,
    string projectPath,
    string? sceneName = null,
    string url = "http://127.0.0.1",
    int port = 54021,
    string? customUnityInstallRoot = null) {...}
Enter fullscreen mode Exit fullscreen mode

Example with all arguments:

var unity = builder.AddUnityProject(
    name: "game",
    projectPath: "..\\..\\AspireIntegration",
    url: "http://localhost",
    port: 55000,
    customUnityInstallRoot: "E:\\Unity"
);
Enter fullscreen mode Exit fullscreen mode

Configuration: Aspire config inside Unity

Aspire.Unity exposes Aspire configuration directly to the Unity runtime via the Unity-side ConfigProvider static object:

ConfigProvider.Configuration
Enter fullscreen mode Exit fullscreen mode

What this enables:

  • Environment variables, appsettings, secrets and other Aspire configuration sources are available inside Unity at startup.
  • Inject API base URLs, feature flags, or credentials into Unity without hardcoding.
  • Drive scene logic, simulation parameters, and runtime behavior from Aspire configuration.
  • Support multiple environments (development, staging, production) transparently for Unity.

Tip: Use ConfigProvider.Configuration to read typed settings or feature flags in Awake/Start so your scene boots with the correct runtime values.

Example scenarios

  • Real‑time dashboards: Visualize telemetry from Aspire APIs inside Unity scenes.
  • Server‑driven simulation: Aspire coordinates runs; Unity executes simulations and reports results back.
  • CI play‑mode tests: Launch Unity in AppHost to run automated tests as part of your pipeline.
  • Developer tooling: Expose an interactive scene preview or visualization service for local development.

Roadmap

Planned improvements include:

  • Integrating with Open-telemetry

Try it

This project is experimental but already useful for prototyping Aspire + Unity workflows. I’d love to hear how you’d combine Aspire and Unity — visualization, simulations, CI testing, or developer tooling?

Top comments (0)