# 2dog

> 2dog runs Godot inside .NET: export your C# game to the browser, test it with xUnit, and embed the engine in any .NET application - while keeping your scenes, scripts, and Godot workflow.

2dog is a free & open-source (MIT) toolkit that inverts Godot's ownership
model: instead of the Godot editor exporting your game, a plain .NET
application hosts the engine (libgodot) as a library. Your scenes, scripts,
and GodotSharp C# API stay exactly as they are - you gain `dotnet run`,
`dotnet publish` to desktop and browser (WebAssembly), real-engine xUnit
tests, and embedding in any .NET app.
Current version: 4.7.2.82 (Godot 4.7.2).
NuGet packages: `2dog` (CLI tool + templates) - https://www.nuget.org/packages/2dog/,
`2dog.engine` (the library), `2dog.xunit` (test collections).
Source: https://github.com/outfox/2dog

Every page below is also served as raw Markdown: replace `.html` with `.md`
(the URLs below already point at the Markdown versions). The entire site is
also available concatenated at https://2dog.dev/llms-full.txt.

## Start Here

- [Getting Started](https://2dog.dev/getting-started.md): Embed a new or existing Godot C# project in a .NET application: install the .NET 10 SDK, scaffold hosts with 2dog new or 2dog add, and run your game with dotnet run.
- [Core Concepts](https://2dog.dev/concepts.md): How 2dog inverts Godot ownership: your .NET host owns the process and drives embedded libgodot, with GodotSharp API access, the main loop, resource paths, and the single-instance rule.
- [Project Layout](https://2dog.dev/project-layout.md): The recommended 2dog layout: the directory containing project.godot is the .NET solution root, with small nested host projects for desktop, browser, and tests that Godot ignores.

## Build and Ship

- [Adding 2dog to Existing Projects](https://2dog.dev/add.md): The 2dog add command adds .NET hosts to an existing Godot project in place - usage, commands, options, what gets generated, safety, and requirements.
- [Creating a New Project](https://2dog.dev/templates.md): Scaffold a complete 2dog project with 2dog new or dotnet new: pick desktop, web, and test hosts, then run your Godot C# game straight from the .NET CLI.

## Hosts

- [What's a Host?](https://2dog.dev/hosts/index.md): A host is a small .NET program that owns the process, starts embedded Godot, and drives its frame loop - an overview of the hosts 2dog generates and how they relate.
- [Generic Host](https://2dog.dev/hosts/generic.md): The generic 2dog console host starts Godot, runs your main scene, and gives ordinary .NET code control of the frame loop.
- [Avalonia Host](https://2dog.dev/hosts/avalonia.md): A cross-platform host that composites the Godot viewport inside an Avalonia window via the 2dog.avalonia package - Avalonia controls render on top of the running game.
- [Browser Host](https://2dog.dev/hosts/web.md): The 2dog browser host packages a Godot C# game as a static WebAssembly site; learn its runtime model, configuration, performance controls, and limitations.
- [WebXR Host](https://2dog.dev/hosts/webxr.md): The WebXR host adds a prewired WebXR Layers polyfill to the browser host for browser-based VR and AR.
- [Blazor Host](https://2dog.dev/hosts/blazor.md): The Blazor host embeds the Godot viewport in a Blazor Web App page: an ASP.NET Core server serves a Blazor WebAssembly client that runs Godot inside the .NET runtime Blazor already booted, so Razor code calls Godot directly.
- [WinForms Host](https://2dog.dev/hosts/winforms.md): A Windows-only host that embeds the Godot engine inside a WinForms window, with a pause button driving the instance - how to add it and how it works.
- [WinUI 3 Host](https://2dog.dev/hosts/winui.md): A Windows-only host that embeds the Godot engine inside a WinUI 3 (Windows App SDK) window and pumps frames from the XAML dispatcher - how to add it and how it works.
- [xUnit Host](https://2dog.dev/hosts/xunit.md): The 2dog test host: xUnit owns the process, so a fixture owns the Godot engine lifetime - test anatomy, project differences, and single-instance safety.

## API Reference

- [API Reference](https://2dog.dev/api-reference.md): Overview of the deliberately small 2dog API: twodog.Engine, Godot.GodotInstance, the twodog.Testing fixtures, xUnit collections, and object lifetimes at a glance.
- [twodog.Engine](https://2dog.dev/api/engine.md): API reference for twodog.Engine, which configures, starts, and owns one embedded Godot instance: constructor, properties, Start, Run, Dispose, and common Godot arguments.
- [Godot.GodotInstance](https://2dog.dev/api/godot-instance.md): API reference for Godot.GodotInstance, the handle returned by Engine.Start(): Iteration, IsStarted, focus and pause control, and disposal.
- [Godot.GodotSharp](https://2dog.dev/api/godotsharp.md): API stub for GodotSharp, which 2dog exposes.
- [twodog.Testing.FixtureBase](https://2dog.dev/api/fixture-base.md): API reference for FixtureBase, the abstract base class for test fixtures that own a Godot instance - constructor, properties, disposal, and custom xUnit collections.
- [twodog.Testing.Fixture](https://2dog.dev/api/fixture.md): API reference for Fixture, the test fixture that starts Godot with rendering enabled - used through RenderingCollection in xUnit tests.
- [twodog.Testing.HeadlessFixture](https://2dog.dev/api/headless-fixture.md): API reference for HeadlessFixture, the test fixture that starts Godot with --headless - used through HeadlessCollection in xUnit tests.
- [twodog.Testing.Xunit.RenderingCollection](https://2dog.dev/api/rendering-collection.md): API reference for RenderingCollection, the non-parallel xUnit collection that shares one rendering Fixture across test classes.
- [twodog.Testing.Xunit.HeadlessCollection](https://2dog.dev/api/headless-collection.md): API reference for HeadlessCollection, the non-parallel xUnit collection backed by one shared HeadlessFixture.
- [twodog.fixture.AssemblyPreloader](https://2dog.dev/api/assembly-preloader.md): API reference for AssemblyPreloader, which preloads game assemblies into the default AssemblyLoadContext before Godot starts.

## Develop and Configure

- [dnx 2dog](https://2dog.dev/dnx-2dog.md): Reference for the 2dog command-line tool: installation, commands, host flags, global and output options, exit codes, version pinning.
- [2dog new](https://2dog.dev/cli/new.md): Reference for 2dog new: create a Godot project with 2dog hosts - arguments, host flags, options, examples.
- [2dog add](https://2dog.dev/cli/add.md): Reference for 2dog add: add .NET hosts to an existing Godot project in place - arguments, host flags, options, examples.
- [2dog doctor](https://2dog.dev/cli/doctor.md): Reference for 2dog doctor: check a 2dog project and the machine, apply fixes, explain build failures - options, exit codes, every check id.
- [2dog update](https://2dog.dev/cli/update.md): Reference for 2dog update: bring a project's 2dog packages to the running tool's versions - arguments, options, examples.
- [2dog pack](https://2dog.dev/cli/pack.md): Reference for 2dog pack list: list an exported .pck's contents by size, without an engine or project.
- [2dog version](https://2dog.dev/cli/version.md): Reference for 2dog version: print the tool version and every package a scaffold references, checked against nuget.org.
- [2dog help](https://2dog.dev/cli/help.md): Reference for 2dog help: show the tool's usage, or the help for one verb.
- [Resource Import](https://2dog.dev/import-tool.md): How 2dog imports Godot resources automatically during MSBuild: incremental imports driven by GodotProjectDir, the twodog.import helper, and troubleshooting.
- [Testing with xUnit](https://2dog.dev/testing.md): Run xUnit tests against a real Godot engine with 2dog.xunit: installation, rendering and headless fixtures, shared collections, and writing and running tests.
- [Build Variants](https://2dog.dev/build-configurations.md): Choosing between the debug, release, and editor native Godot variants in 2dog, and how the Debug, Release, and Editor .NET configurations map onto them.
- [MSBuild Configuration](https://2dog.dev/configuration.md): 2dog MSBuild properties for host projects: GodotProjectDir, TwoDogVariant, duplicate Godot analyzer removal, package versioning, and the GodotSharp directory.

## Known Issues

- [Known Issues](https://2dog.dev/known-issues/index.md): Current 2dog limitations and their workarounds: one Godot instance per load context, xUnit discovery crashes with Godot types, GD.Print visibility in tests, and spaced project names breaking publish.
- [Single Godot Instance](https://2dog.dev/known-issues/single-instance.md): Only one Godot instance may run per assembly load context in 2dog; sequential restart is supported and isolated concurrent hosting is experimental.
- [xUnit Test Discovery Crash](https://2dog.dev/known-issues/xunit-discovery.md): Godot values in xUnit MemberData can crash the test host during discovery - the affected Godot types and the workarounds.
- [GD.Print in Tests](https://2dog.dev/known-issues/gd-print-output.md): Why GD.Print output is hidden during dotnet test, how to make it visible, and why ITestOutputHelper is the recommended pattern.

## Optional

- [FAQ](https://2dog.dev/faq.md): Frequently asked questions about 2dog: how it differs from godot-dotnet, whether it replaces GodotSharp, and why the tool and engine ship as separate packages.
- [Doctor and Update](https://2dog.dev/doctor.md): 2dog doctor checks a project and the machine, applies safe fixes, and explains build failures; 2dog update brings the 2dog packages to the tool's versions.
- [Troubleshooting](https://2dog.dev/troubleshooting.md): What the 2dog tool's exit codes, notes and errors mean, how it behaves in CI and pipes, and where to look when a restore or build fails.
- [Spaced Project Names](https://2dog.dev/known-issues/spaced-project-names.md): Whitespace in the game project's .NET name makes dotnet publish silently drop its NuGet dependencies from 2dog hosts - an upstream .NET SDK bug 2dog guards against.