ModernOverlay is a Windows-only overlay library for modern .NET. It replaces the useful parts of the GameOverlay.NET library stack with a new Vortice + Direct2D/DirectWrite/WIC + Win32 implementation.

This package is not a drop-in GameOverlay.NET replacement, but feature-wise is heavily inspired by the library from Michel. The API intentionally uses new names, explicit lifetimes, safer target tracking, and first-class diagnostics.

Preview Status

This repository currently targets net11.0-windows on a .NET 11 preview SDK. APIs, package layout, backend registration, and packaging metadata may change before .NET 11 GA.

Package-facing caveats for the MVP/alpha release:

1. The common ModernOverlay package bundles the Direct2D backend assembly for the preview one-package path. ModernOverlay.Direct2D is still also emitted as a separate backend package.
2. ModernOverlay.Integration.Experimental is source-only for alpha and should not be published until there is a real authorized experimental provider.
3. TransparencyMode.UpdateLayeredWindow and TransparencyMode.DirectComposition are request modes that currently fall back to the DWM/color-key Direct2D HWND path with diagnostics. True CPU-copy layered alpha and DirectComposition/DXGI per-pixel alpha remain future backend work.
4. The release bar is a hobbyist project aiming to be useful, buildable, sample-backed, and caveated.

Changelog

Version	Highlights
1.1 preview	Adds the ModernOverlay.UI package with retained interactive controls, layout panels, popups, floating windows, text editing, selective click-through regions, themes, and interface-only layout persistence.
1.0	Establishes the core overlay window lifecycle, Direct2D drawing backend, target tracking, input modes, diagnostics, cooperative IPC, samples, and release validation tooling.

Quick Start

Install the ModernOverlay.NET package. The package includes the Direct2D backend assembly for the common path, and the core facade auto-discovers ModernOverlay.Direct2D when the assembly is present.

Package install:

dotnet add package ModernOverlay.NET

Minimal overlay:

using ModernOverlay;
using ModernOverlay.Drawing;
using ModernOverlay.Windows;

await using OverlayWindow overlay = await OverlayWindow.CreateAsync(new OverlayWindowOptions
{
    Bounds = WindowBounds.FromPixels(100, 100, 640, 360),
    InputMode = OverlayInputMode.ClickThrough,
    ZOrder = OverlayZOrder.TopMost,
    FrameRateLimit = FrameRateLimit.Fixed(60),
});

using SolidBrushHandle white = overlay.Resources.CreateSolidBrush(ColorRgba.White);
using FontHandle font = overlay.Resources.CreateFont(new FontOptions("Segoe UI", 18));

overlay.Render += frame =>
{
    frame.Clear(ColorRgba.Transparent);
    frame.Draw.Text("Hello overlay", font, white, new PointF(24, 24));
};

await overlay.RunAsync();

Drawing coordinates are DIPs. WindowBounds represents physical pixels unless constructed through the DIP helpers.

Read more: quick start, A/B development testing, installation, DPI and multi-monitor.

Features

Feature	What is available now	Read more
Overlay window lifecycle	Borderless Win32 popup overlays with async create/run/dispose, manual recreation, show/hide, pause/resume, and owner-thread dispatch.	window modes, device recreation
Drawing	Immediate-mode clear, lines, rectangles, rounded rectangles, circles, ellipses, triangles, geometry paths, text, images, clips, transforms, and overlay helpers like boxes, corner boxes, crosshairs, and arrows.	drawing primitives, resource lifetime
Target tracking	Follow HWNDs, process ids/names, titles, class names, foreground windows, or custom providers; track whole-window, client-area, or custom bounds.	target tracking, troubleshooting
Input modes	Click-through overlays by default, optional interactive mode with pointer, keyboard, and text events, plus selective click-through input regions for mixed pass-through/interactive surfaces.	window modes, interactive UI
Retained UI	ModernOverlay.UI retained controls with layout panels, routed input, focus, text editing, popups, floating windows, tabs, color/range controls, theme customization, diagnostics, and interface-only layout persistence.	interactive UI, samples
Transparency	Usable DWM/color-key transparency for the Direct2D HWND backend, with diagnostic fallback events for reserved backend modes.	transparency validation, DirectComposition note
DPI and monitors	Per Monitor V2 awareness, physical-pixel window bounds, DIP drawing coordinates, DPI conversion helpers, negative-coordinate monitor support, and display-default frame pacing.	DPI and multi-monitor
Diagnostics	EventSource diagnostics, Microsoft.Extensions.Logging bridge, frame stats, target stats, native failure tracking, resource leak reports, and a diagnostics sample.	troubleshooting, performance guide
Cooperative IPC	Optional owned-host command protocol over named pipes, reusable remote resources, command patches, payload limits, command tokens, current-user/custom pipe ACLs, and bounded multi-client handling.	integration boundary
Performance evidence	BenchmarkDotNet harness, dry-run gate, local non-dry baselines for current classes, and a performance regression template.	performance guide, baseline

Performance Snapshot

The current local baseline was captured on Windows 10 IoT Enterprise LTSC 10.0.19044, AMD Ryzen 9 9950X3D, NVIDIA RTX 3080, .NET SDK 11.0.100-preview.4.26230.115, and BenchmarkDotNet 0.15.8 with the in-process emit toolchain. Treat these as same-machine comparison numbers, not cross-hardware guarantees.

Area	Benchmark	Mean	Allocation
Draw dispatch	Clear	2.6127 ns	0 B
Draw dispatch	DrawLine	0.2866 ns	0 B
Draw dispatch	FillRectangle	0.2765 ns	0 B
Direct2D render	ClearAndPresent	4,564.535 us	565 B
Direct2D render	DrawPrimitiveBatchAndPresent	4,450.942 us	552 B
Direct2D render	ResizeRenderTarget	3.539 us	404 B
Overlay lifecycle	CreateAndDisposeHiddenOverlay	138.9 ms	14.22 KB
Target tracking	QueryWindowBoundsByHwnd	18.9079 ns	0 B
Target tracking	FindTargetByProcessId	75,583.1546 ns	184 B

Read more: performance guide, local baseline, benchmarks index.

License

ModernOverlay is licensed under the MIT License.

Minimal Examples

Track an existing window by title:

var target = WindowTarget.ByTitle("Notepad")
    .WithBoundsMode(TargetBoundsMode.ClientArea);

await using OverlayWindow overlay = await OverlayWindow.CreateAsync(new OverlayWindowOptions
{
    Target = target,
    ZOrder = OverlayZOrder.FollowTarget,
    InputMode = OverlayInputMode.ClickThrough,
});

Draw common overlay markers:

overlay.Render += frame =>
{
    frame.Clear(ColorRgba.Transparent);
    frame.Draw.CornerBox(new RectF(40, 40, 160, 90), white, cornerLength: 18, strokeWidth: 2);
    frame.Draw.Crosshair(new PointF(320, 180), size: 14, white, strokeWidth: 2);
};

Use cooperative IPC from an owned process:

var client = new NamedPipeOverlayCommandClient("modern-overlay-demo", commandToken: "local-token");
await client.SendAsync(OverlayCommandMessage.Update(
[
    OverlayDrawCommand.Clear(ColorRgba.Transparent),
    OverlayDrawCommand.TextRun("owned host", new PointF(24, 24), ColorRgba.White),
]));

Read more: target tracking, drawing primitives, integration boundary.

Samples

Read more: samples index.

Quick launcher:

tools\Start-ModernOverlaySample.ps1 Basic
tools\Start-ModernOverlaySample.ps1 -List
tools\New-ModernOverlayPlayground.ps1 -From Basic -Name Basic-A

Sample	Purpose
samples/BasicOverlay	Minimal render loop and drawing setup.
samples/StickyTargetOverlay / samples/StickyWindowOverlay	Target tracking against an owned test window.
samples/InputModeOverlay / samples/InteractiveOverlay	Click-through versus interactive input behavior.
samples/ShapesOverlay / samples/GeometryOverlay	Shape, helper, and geometry drawing.
samples/ImageOverlay / samples/ImageAndTextOverlay	Image and text rendering.
samples/TextLayoutOverlay	Reusable text layouts.
samples/DiagnosticsOverlay	Frame, resource, target, and native diagnostics.
samples/ShowcaseOverlay	Screenshot-oriented primitive gallery with live developer metrics.
samples/HotkeyOverlay	Overlay hotkey handling.
samples/TransparencyValidationOverlay	Manual transparency validation.
samples/IpcOverlayDemo and samples/SampleOwnedHost	Cooperative named-pipe command protocol.

Documentation

Read more: docs index.

1. Start here: quick start, A/B development testing, installation, GameOverlay.NET mapping.
2. Core usage: window modes, target tracking, DPI and multi-monitor, drawing primitives, resource lifetime.
3. Runtime behavior: device recreation, troubleshooting, performance guide.
4. Integration and boundaries: integration boundary, transparency validation, capture-backed overlay spike, DirectComposition decision note.
5. Release/project status: task list, modernization spec, feature completeness, next action points, implementation history, development notes, public API and package review, release validation checklist, release publishing.

Project Layout

1. src: package/project responsibilities and source entry points.
2. samples: runnable capability demos.
3. tests: test areas and common commands.
4. benchmarks: BenchmarkDotNet classes and dry-run command.
5. tools: release validation command gate.

A personal note on AI usage from myself

The project has served as a learning experience for myself in using AI Agents "the correct way", in particular Codex. I wanted to implement some of the ideas I previously had as (bad) PoCs in other projects and try to make them feature complete; without sacrificing all of my free time completing it. All of the code has gone through numerous levels of review and quality assurance, from analysis breakdowns to task handling, milestone defintions to full implementations and the automated testing. With that being said, pretty much 99.9% of the project has been made using Codex with GPT 5.5 (high) and reviewed by Junie, Claude Sonnet 4.6 and GPT 5.4 in loop until relative agreement.

I've tried to keep most of the intermediate documentation from the AI's available in the repo, not only so that others can get inspired and try to use agents in a similar way, but also for myself to look back at the state of Agentic AI from May 2025 in the future.