Tutorial 171: Start a New C# Game with the CNA.NET Template
What you’ll learn: how to create a new C# CNA game with dotnet new cna-game and run its shared source on the desktop, in the browser and on Android.
Status: the template and CNA.NET are beta and source-first. The template is installed from a local checkout, not from a package feed. Commands follow cna-dotnet-template’s README (read at revision 008c3b1, before the repository was renamed from cna-cs-template) and were not re-run for this page. CNA’s early-October Apple campaign also ran the template’s development and package modes on a physical Mac mini M4, against the CNA revision of that time.
Which starting point?
| You have | Start here |
|---|---|
| A new C# game | This tutorial: cna-dotnet-template |
| An existing XNA, FNA or MonoGame game | Tutorial 170 and the migration guide: a thin SDK-style wrapper plus CNA.XnaCompat |
| A question about how an XNA API behaves on CNA | The reference programs in cna-dotnet-samples |
1. Install the template and create a game
dotnet new install /path/to/cna-dotnet-template
dotnet new cna-game --name MyGame
cd MyGame
The template (short name cna-game) generates one shared game source — HelloGame.cs and Program.cs, written against Microsoft.Xna.Framework — and three projects: a desktop project (net8.0), Platforms/Browser (a Microsoft.NET.Sdk.WebAssembly project, net11.0) and Platforms/Android (net11.0-android, API 24 or later). The sample game covers the lifecycle, device management, window resizing, keyboard, mouse and gamepad, a texture loaded from Content/logo.png, SpriteBatch and a rotating BasicEffect cube, with a 2D fallback when the renderer has no 3D pipeline. By default (consumerMode=Development) the projects reference a CNA.NET source checkout.
2. Run it on the desktop
export CNA_DOTNET_ROOT=/path/to/cna-dotnet
CNA_NATIVE_LIBRARY=/path/to/cna/build/modules/c-api/libcna_c_api.so dotnet run
dotnet run -- --smoke-test # 60 frames, then exit
dotnet run -- --stability-test # 600 frames, then exit
Build the native library first, as in Tutorial 170. The template README records 60 and 600 frames on Linux with the OPENGLES3, SOFTWARE and HEADLESS renderers among others, and the same source running 600 frames on FNA. On macOS point CNA_NATIVE_LIBRARY at libcna_c_api.dylib instead, built from the same pinned CNA commit as on Linux.
3. Run it in the browser
dotnet publish Platforms/Browser -c Release
cd Platforms/Browser/bin/Release/net11.0/publish/wwwroot && python3 -m http.server 8080
This needs .NET 11 with the wasm-tools workload and the WebAssembly build of CNA’s C ABI, staged by CNA.NET’s Linux-only Build-BrowserNative.sh. The template’s browser head is single-threaded; a game that starts its own threads needs the threaded build described in the migration guide. CNA.NET’s browser qualification so far is headless Chromium.
4. Run it on Android
dotnet build Platforms/Android -c Release -t:Install
This needs .NET 11 with the android workload and the Android build of CNA’s C ABI (CNA.NET’s Build-AndroidNative.sh). The default runtime identifier is android-x64, the x86_64 emulator on which CNA.NET was qualified; ARM packages build, but have not been run on a physical device.
One source, several engines
The desktop project builds the same game source against CNA, FNA, MonoGame or Kni with -p:Engine=…; only a small EngineDiagnostics.cs asks which one is running. The multi-language 3D demo takes the idea further: the same small 3D game written in C++ against CNA’s C++ API, in C against the C ABI, and in C# as one source file that builds against CNA.NET or FNA.