2dog.engine 4.7.2.122

2dog.engine

Embed the Godot engine in your .NET applications.

2dog lets a standard .NET application host Godot and use the GodotSharp API.

Quick Start

Scaffold a host beside an existing project.godot:

dnx 2dog add

using twodog;

using var engine = new Engine("MyGodotApp", args: args);
engine.Start();

while (!engine.Iteration())
{
    // Your code runs here every frame.
}

Engine owns the instance; Start() returns a borrowed GodotInstance compatibility handle. Use RequestQuit(), Completion, and Exited for lifecycle control. Desktop disposal is synchronous; browser code awaits DisposeAsync(). After completion, create a new Engine to restart. Pump and access Godot from the thread that called Start(); do not iterate and dispose the same engine concurrently from different threads.

The generated host embeds its GodotProjectDir. The constructor uses that source directory during development and the adjacent .pck after publish.

To create a new project instead:

dnx 2dog new MyGodotApp

What's Included

• twodog.dll - engine hosting API
• 2dog.godotsharp - exact-pinned fork C# bindings and source generator
• GodotPlugins - script loading
• Automatic asset import - incremental import during build

Platform-specific native libraries are provided by transitive dependencies (2dog.win-x64, 2dog.linux-x64, 2dog.osx-arm64); the GodotTools assemblies used by the automatic import come from 2dog.tools.

Game and library bindings

2dog new, 2dog add, and 2dog update configure fork bindings in the game automatically. Existing Godot.NET.Sdk defaults and compatible stock dependencies are supported; no implicit-reference opt-out properties are required. Plain .NET libraries can reference 2dog.godotsharp directly, and 2dog.godotsharp.editor when they use editor APIs, at the engine's version.

Incompatible Godot versions and stale manual binding references still fail the build. See the binding package guide. Trimming compatibility of your own code remains a separate concern.

Intentionally unawaited tasks

Observe fire-and-forget operations so failures are reported immediately:

using twodog;

SaveAsync().Forget(); // Console.Error on desktop, browser console errors on web

Forget() supports Task, Task<T>, ValueTask, and ValueTask<T>; successful completion and cancellation stay quiet. It consumes value tasks, which must not be awaited or consumed again. Plain discarded tasks rely on the runtime's GC-delayed unobserved-exception event. See browser exception diagnostics for logging every thrown exception during debugging.

Simulating Test Input

twodog.Testing.FixtureBase.Input is shared by xUnit collections and NUnit fixtures. Input.Click(control) aims at a control through its viewport's input router, so foreground controls, clipping and input suppression still apply. PushToViewport(event, viewport) routes custom events locally; Send(event) uses Godot's input server, flushes buffered input and updates global polling state. Use these methods on the engine's owner thread. See Simulating Input for examples and routing limits.

Windows window lifecycle diagnostics

Set TWODOG_LIFECYCLE_LOG to a log file path before starting a windowed engine to record Windows activation/minimize/restore messages, Godot window signals and an independent frame-loop heartbeat. The trace appends to the file and flushes once per second, including while the owner thread is stalled. Unset the variable to disable tracing. See the windowed test instructions for a showcase reproduction command and the separate native window-state capture script.

Documentation

• Getting Started
• API Reference