feat: Stride Gamebuilder as an alternative for .NET IOC startup

[Doprez]

PR Details

This PR adds the ability to completely customize the startup of a users game by using dependency injection.

This is a rethinking of my original work to try and make it at least a minimal breaking change so that GameStudio and existing projects can be upgraded gradually. This is not feature complete but I would like to build the new windowing API based on this structure assuming this is approved as a valid change.

I also took some small inspiration from how Avalonia decided on their own startup structure so there are some very small similarities.

Why didn't I use existing AppBuilders/HostBuilders?

I did look into this with the original starting point being based on #1841 but without changing the core Stride libraries it wasn't as useful out of the box. I did still abstract over the IServiceCollection in order to allow us to migrate over to that system in the future or allow users to add dependencies that exist in .NET already. The other issue with the IServiceCollection is that you can not add services at runtime like you can with Strides IServiceRegistry which would have been a major breaking change throughout everything.

What about existing classes inheriting or using Game?

This should be working exactly as it does today apart from how content and GameContext is loaded in the project and this is currently the main thing that could break projects if merged in. Thankfully most functionality was internal already so this shouldn't be an issue for 99% of users.

Why make the GameWindow public?

Honestly just looking for some feedback here but making it public allows users to properly set up the GameContext if they decide to use it with the new startup. This is not concrete as well since assuming this gets approved I would be changing how the GraphicsDevice sees the GameWindow as purely a position and size rather than a whole object.

Why not fully use the IOC PR like #1841

This is a less breaking change and allows the underlying code to be modified without the users noticing. My PR is meant to be the path of least resistance.

Example Startup code

Extensions that are used in the default Game class for a generic Stride games to run:

public static class GameBuildExtensions
{
    public static IGameBuilder UseDefaultGameSystems(this IGameBuilder gameBuilder)
    {
        var services = gameBuilder.Game.Services;

        var scriptSystem = new ScriptSystem(services);
        var sceneSystem = new SceneSystem(services);
        var audioSystem = new AudioSystem(services);
        var gameFontSystem = new GameFontSystem(services);
        var spriteAnimationSystem = new SpriteAnimationSystem(services);
        var debugTextSystem = new DebugTextSystem(services);
        var gameProfilingSystem = new GameProfilingSystem(services);
        var inputSystem = new InputSystem(services);
        var effectSystem = new EffectSystem(services);
        // registers itself as a service
        var streamingManager = new StreamingManager(services);

        gameBuilder
            .AddGameSystem(scriptSystem)
            .AddGameSystem(sceneSystem)
            .AddGameSystem(audioSystem)
            .AddGameSystem(gameFontSystem)
            .AddGameSystem(spriteAnimationSystem)
            .AddGameSystem(debugTextSystem)
            .AddGameSystem(gameProfilingSystem)
            .AddGameSystem(inputSystem)
            .AddGameSystem(effectSystem)
            .AddGameSystem(streamingManager);

        // add services
        gameBuilder
            .AddService(scriptSystem)
            .AddService(sceneSystem)
            .AddService(spriteAnimationSystem)
            .AddService(debugTextSystem)
            .AddService(gameProfilingSystem)
            .AddService(inputSystem)
            .AddService(effectSystem)
            .AddService(inputSystem.Manager)
            .AddService(audioSystem)
            .AddService<IAudioEngineProvider>(audioSystem)
            .AddService(gameFontSystem)
            .AddService(gameFontSystem.FontSystem)
            .AddService<IFontFactory>(gameFontSystem.FontSystem);

        return gameBuilder;
    }

    public static IGameBuilder UseDefaultGameSystemsDI(this IGameBuilder gameBuilder)
    {
        gameBuilder
            .AddService<ScriptSystem>()
            .AddService<SceneSystem>()
            .AddService<SpriteAnimationSystem>()
            .AddService<DebugTextSystem>()
            .AddService<GameProfilingSystem>()
            .AddService<EffectSystem>()
            .AddService<StreamingManager>()
            .AddService<IAudioEngineProvider, AudioSystem>()
            .AddService<GameFontSystem>()
            .AddService<FontSystem>();

        return gameBuilder;
    }
}

Actual Startup code with custom inputs and logger:

using Doprez.Stride.Input; // for SharpHookInputSource and HIDDeviceInputSource
using GameBuilderTest;
using Stride.Core.Diagnostics;
using Stride.Core.IO;
using Stride.Core.Serialization.Contents;
using Stride.Engine;
using Stride.Engine.Builder;
using Stride.Engine.Design;
using Stride.Games;
using Stride.Rendering;

var gameBuilder = GameBuilder.Create();

gameBuilder.UseDefaultGameSystemsDI()
    .UseStrideInput()
    .UseStrideFontSystem()
    .UseDefaultDb()
    .UseDefaultContentManager()
    .SetGameContext(GameContextFactory.NewGameContextSDL()) // This allows users to still use the default context behaviour
    .AddStrideInputSource(new SharpHookInputSource()) // These are custom inputs I made
    .AddStrideInputSource(new HIDDeviceInputSource()) // These are custom inputs I made
    .AddLogListener(new ConsoleLogListener()); // Add loggers easily through here using Strides logging system not .NETs

var game = gameBuilder.Build();

var content = game.Services.GetService<IContentManager>();
var settings = content.Load<GameSettings>("GameSettings");

var sceneSystem = game.Services.GetService<SceneSystem>();
sceneSystem.InitialSceneUrl = settings.DefaultSceneUrl;
sceneSystem.InitialGraphicsCompositorUrl = settings.DefaultGraphicsCompositorUrl;

var fileProvider = game.Services.GetService<IDatabaseFileProviderService>().FileProvider;
game.Services.GetService<EffectSystem>()
    .CreateDefaultEffectCompiler(fileProvider);

game.Run();

Related Issue

Original runtime management change

#2404

This was my first attempt with the focus of only managing the GameWindow but quickly cascaded into a mess of breaking changes and turned into a mess of unmaintainable code. This went from "I want to change the window host" to "dear god everything is hard coded and broken after a single change"

---

Second attempt at startup changes

#2574

This was my better PR for the startup change but broke WAY too much to justify the cascading changes required to work with GameStudio.

---

modern IOC change

#1841

I really loved the idea of this one but it breaks so much with the core systems of Stride since they rely on Stride specific alternatives. For example Services and logs which would need to be updated throughout Strides libraries which is out of scope for my time.

In an ideal world I think this one is a good option but without more manpower/hours feels unrealistic for now.

---

Types of changes

• Docs change / refactoring / dependency upgrade
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist

• My change requires a change to the documentation.
• I have added tests to cover my changes.
• All new and existing tests passed.
• I have built and run the editor to try this change out.

[Kryptos-FR]

Should we create a future branch?

I feel like this too much of a change to fit into a minor release. By having a separate branch we could investigate further changes without setting anything into stone yet.

[VaclavElias]

I like this PR. future branch might work, or anything what would make this changes happen 🙂.

[Doprez]

I would be be happy with that. I am very hesitant to make some of these APIs public in a release since they were internal due to their unfinished state(specifically the windowing). My main goal of this PR was to get the other core contributors attention to see if there was anything absolutely atrocious that I did 😆

I think one of the benefits here would be for the GameStudio and how it instantiates the scene Game. It should be able to remove a lot of the cascading that exists once I get the windowing changes in.

[Kryptos-FR]

Is it correct?

[Doprez]

This is correct, the logic is now handled by the Game class (line 361) or through the GameBuilder with the AddStrideInputSource extension instead. I removed the line for clean up.

[VaclavElias]

@Doprez, do you want me to run a copilot review on this and see what it will spit out?

[Doprez]

@Doprez, do you want me to run a copilot review on this and see what it will spit out?

Sure, doesnt hurt to have some extra hints.

[Copilot]

Pull Request Overview

This PR introduces a customizable game startup using dependency injection to allow gradual upgrading of existing projects while exposing a new game windowing API. Key changes include refactoring GameBase and related classes to derive their GamePlatform from the GameContext, updating service registrations throughout, and adding a new GameBuilder for a streamlined startup process.

Reviewed Changes

Copilot reviewed 32 out of 32 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
sources/engine/Stride.Games/GameBase.cs	Refactored game platform and context handling, updated property access modifiers, and added helper methods for GameContext initialization.
sources/engine/Stride.Games/Desktop/GamePlatformDesktop.cs	Updated constructor to accept GameContext instead of GameBase.
sources/engine/Stride.Games/Android/GamePlatformAndroid.cs	Updated constructor to accept GameContext instead of GameBase.
sources/engine/Stride.Engine/Engine/Game.cs	Modified Game constructor and initialization to use provided or default GameContext.
sources/engine/Stride.Engine/Engine/Builder/*.cs	Added and updated game builder components to support DI and new service registrations.
sources/editor/*	Updated editor game startup code to integrate with the new startup and GameContext management.
sources/core/*	Updated service registration methods and file provider services to support context-based initialization.
sources/buildengine/*	Adjusted DatabaseFileProvider service to allow value updates.
sources/Directory.Packages.props	Added a new package reference for Microsoft.Extensions.Hosting.

Comments suppressed due to low confidence (1)

sources/engine/Stride.Engine/Engine/Builder/GameBuilder.cs:120

• [nitpick] Consider renaming 'dataBase' to a more descriptive and properly cased variable name such as 'databaseProvider' for clarity.

var dataBase = Game.Services.GetService<IDatabaseFileProviderService>();

[Copilot]

Pull Request Overview

Introduce a new dependency-injection–driven startup pipeline for Stride games, enabling full customization of game initialization while minimizing breaking changes.

• Refactored GameBase to use a GameContext, support swapping contexts at runtime, and expose essential members as protected.
• Added GameBuilder, MinimalGame, and extension methods to configure services, game systems, input sources, and logging via IServiceCollection.
• Extended ServiceRegistry and core interfaces to allow explicit service registration by type and made database file provider mutable.

Reviewed Changes

Copilot reviewed 32 out of 32 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
sources/engine/Stride.Games/GameBase.cs	Refactored startup flow to use GameContext, added SetGameContext/EnsureGameContextIsSet, and made key properties protected.
sources/engine/Stride.Games/Desktop/GamePlatformDesktop.cs	Updated constructor to accept GameContext instead of GameBase.
sources/engine/Stride.Games/Android/GamePlatformAndroid.cs	Updated constructor to accept GameContext instead of GameBase.
sources/engine/Stride.Engine/Stride.Engine.csproj	Added Microsoft.Extensions.Hosting package reference.
sources/engine/Stride.Engine/Engine/Game.cs	Modified Game constructor, default context, input source initialization, and removed direct casts for database provider.
sources/engine/Stride.Engine/Engine/Design/GameSettings.cs	Removed unused System and Stride.Graphics usings.
sources/engine/Stride.Engine/Engine/Builder/MinimalGame.cs	Introduced hosted minimal game class with DI and hosted service implementation.
sources/engine/Stride.Engine/Engine/Builder/IGameBuilder.cs	Defined IGameBuilder interface to expose builder state.
sources/engine/Stride.Engine/Engine/Builder/GameBuilderExtensions.cs	Provided extension methods to register systems, services, logging, input, DB, and content for a game.
sources/engine/Stride.Engine/Engine/Builder/GameBuilder.cs	Implemented the GameBuilder class with service wiring, system registration, context setup, and build logic.
sources/editor/Stride.Editor/Preview/PreviewGame.cs	Updated constructor to accept GameContext.
sources/editor/Stride.Editor/Preview/GameStudioPreviewService.cs	Passed GameContext into PreviewGame.
sources/editor/Stride.Editor/Engine/EmbeddedGame.cs	Updated EmbeddedGame constructor to accept GameContext.
sources/editor/Stride.Editor/EditorGame/Game/EditorServiceGame.cs	Added overload constructor accepting GameContext.
sources/editor/Stride.Assets.Presentation/AssetEditors/EntityHierarchyEditor/Game/EntityHierarchyEditorGame.cs	Updated constructor to forward GameContext.
sources/core/Stride.Core/ServiceRegistry.cs	Added AddService(object, Type) overload to trigger ServiceAdded event.
sources/core/Stride.Core/IServiceRegistry.cs	Declared new AddService(object, Type) interface member.
sources/core/Stride.Core.Serialization/IO/IDatabaseFileProviderService.cs	Made FileProvider setter public for mutable DB plumbing.
sources/buildengine/Stride.Core.BuildEngine.Common/MicrothreadLocalDatabases.cs	Implemented FileProvider setter on microthread-local provider.
sources/Directory.Packages.props	Pin Microsoft.Extensions.Hosting version.

Comments suppressed due to low confidence (4)

sources/engine/Stride.Engine/Engine/Game.cs:447

• The variables rawInputEnabled and context are not defined in this scope. You likely meant to reference the instance fields Context and a corresponding RawInputEnabled property. Rename and reference the correct fields or pass them into this method.

if (rawInputEnabled && context is GameContextWinforms gameContextWinforms)

sources/engine/Stride.Engine/Engine/Builder/GameBuilder.cs:18

• The collection initializer [] is invalid C#. Use a concrete constructor such as new Dictionary<Type, object>();.

public Dictionary<Type, object> InternalServices { get; internal set; } = [];

sources/engine/Stride.Engine/Engine/Builder/GameBuilder.cs:24

• The list initializer [] is invalid here. Replace with new List<LogListener>(); to correctly instantiate the collection.

public List<LogListener> LogListeners { get; internal set; } = [];

sources/engine/Stride.Engine/Engine/Builder/GameBuilder.cs:26

• Invalid list initializer []; use new List<IInputSource>(); to create the collection instance.

public List<IInputSource> InputSources { get; internal set; } = [];

[Copilot]

In the branch where Context is null and a non-null context is passed, you only set Context = context without wiring up GamePlatform events or registering services. Factor out the event hookup and service registration into a common helper so the first assignment is fully initialized.

[Doprez]

This is intentional. We are assuming that the user has set up their own GameContext properly. Although I do want to revisit GameContext in general later when we have a branch where things can break more.

This one could definitely be better but was a workaround to keep the same functionality of the current Game class.

[Arc-huangjingtong]

very nice！