Tutorial 171: Start a New C# Game with the CNA.NET Template

CNA Tutorials · CNA snapshot b0e97bb1

ℹ

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-cs-template’s README (revision 008c3b1) and were not re-run for this page.

Which starting point?

You have	Start here
A new C# game	This tutorial: `cna-cs-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-cs-samples

1. Install the template and create a game

dotnet new install /path/to/cna-cs-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_CS_ROOT=/path/to/cna-cs
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, SDL_RENDERER (2D fallback) and HEADLESS renderers, and the same source running 600 frames on FNA.

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.