Qt Quick

The Qt Quick host uses 2dog.qt and Qt Bridge for C# to show Godot inside a QML scene. QML items placed over the GodotView render on top of the game, including translucent items.

(QML on top, Godot underneath, C# all the way down)

Experimental

Qt Bridge for C# is pre-release software. The Qt Quick host is tested on Windows; Linux and macOS builds are untested.

Use It

Qt Bridge compiles native code during the build. Install these tools first:

• CMake
• Ninja
• A C++ toolchain. On Windows, use Visual Studio with the Desktop development with C++ workload.

See the Qt Bridge requirements for details.

Run these commands from your Godot project directory:

dnx 2dog add --qt
dotnet run --project MyGame.qt

The Qt Bridge package for Windows x64 includes Qt. On Linux and macOS, install Qt 6 first. Then pass its prefix, which is the directory that contains lib/cmake/Qt6/Qt6Config.cmake:

dotnet run --project MyGame.qt -p:QtDir=/path/to/qt6

Customize It

A QtGodotSession owns the engine. Create it in Main before you load QML. Dispose it after the QML engine exits:

using Qt.Quick;
using twodog;

using var session = new QtGodotSession("MyGame", args: args);
Qml.LoadFromRootModule("Main");
Qml.WaitForExit();

The TwoDog QML module provides GodotView, which shows the game and forwards input:

import QtQuick
import TwoDog

Window {
    width: 1280
    height: 720
    visible: true

    GodotView { anchors.fill: parent; focus: true }
}

Qt Bridge runs Main on its own thread, while Qt's GUI thread pumps the engine once per Qt Quick frame. The session's Started, FrameAdvanced, ActiveModeChanged and Stopped events run on the GUI thread. C# methods that QML calls also run on the GUI thread. Both can use the Godot API directly, for example through session.Engine.Tree. See C# and QML to learn how to expose C# types to QML.

See the showcase host for a pause button, time-scale slider, and FPS display.

Rendering and Lifecycle

On Windows, Qt Quick's default Direct3D 11 backend shares a GPU texture with the engine, with no copy through the CPU. Other platforms and graphics backends use CPU readback, which is also the automatic fallback. Set PresentationMode to force either.

The engine starts when the first GodotView renders, and it stops when the application quits. When Godot quits, the application also quits. Only one GodotView can show the engine at a time.

While the window is minimized or hidden, the engine continues to run at a background rate but does not render, like a standalone Godot game. This happens only while Qt's event loop runs. To pause it instead, set IsPaused from a QML handler for Qt.application.state or the window's visibility.

GodotView forwards mouse, wheel and keyboard input. Physical keycodes assume a US keyboard layout. IME composition is not supported. Captured mouse modes hide the cursor but do not confine it.

Publish It

Qt Bridge deploys Qt next to the app during the build. dotnet publish is not tested for the Qt Quick host yet. Native AOT is unsupported, because Qt Bridge loads the app through the .NET host.

See Qt Quick Configuration for build settings.

Licensing

Qt Bridge for C# and Qt are available under the LGPL-3.0 or a commercial license, and Qt Bridge is pre-release software. 2dog.qt ships no Qt code; like the rest of 2dog, it is MIT licensed.

An app that ships Qt and Qt Bridge binaries must meet their license obligations. Under the LGPL, you must:

• Include the license texts and notices.
• Make the corresponding Qt source available.
• Let users replace the LGPL libraries.

Qt Bridge compiles its generated native host from LGPL sources, so keep that host rebuildable. This is not legal advice. Check the Qt Bridge repository and Qt's licensing terms for your case.

Requirements

• Qt Bridge for C# (QtGroup.Qt.Bridge.CSharp.<rid>) and the Qt 6 version it requires.
• CMake, Ninja and a C++ toolchain.
• Windows x64, Linux x64 or macOS arm64.