Migrating from MonoGame / XNA

Porting a C# XNA 4.0 or MonoGame game to CNA (C++23)

Overview

CNA is a C++23 reimplementation of Microsoft XNA 4.0, with SDL3 as its windowing platform layer (it reaches Windows, X11, Wayland and macOS through SDL’s own video drivers). Its API is intentionally faithful to XNA: the same namespace hierarchy, the same class names, the same method names. For a developer coming from MonoGame or XNA the conceptual model is identical — Game, SpriteBatch, ContentManager, GraphicsDevice, BasicEffect — all exist and behave as expected.

The differences are almost entirely syntactic: C++ does not have garbage collection, properties, delegates, or using-disposal blocks. Each of these maps cleanly to a C++ equivalent. Once you have internalised the mechanical substitutions in this guide, most XNA code ports line-by-line.

1. Namespace mapping

XNA uses dot-separated C# namespaces; CNA uses the identical names with :: separators. The using directive works the same way.

2. C++ vs C# quick reference

The table below covers the most common syntactic substitutions you will encounter during a port.

3. Game class migration

The Game subclass is the entry point for any XNA game. The lifecycle methods — Initialize, LoadContent, Update, and Draw — exist identically in CNA (they are protected virtual; Update takes GameTime& and Draw takes const GameTime&). The differences are C++ syntax: override comes after the signature, member variables are declared with their types (no implicit nullability), and resources are owned by std::unique_ptr or held by value rather than being garbage-collected. Two behavioural points matter when you port timing-sensitive code: with the default fixed time step the first Update sees an elapsed time of zero (XNA's clock; a variable step gets the time since the loop started), and a Game registers the built-in XNB readers for you. See Game Loop.

public class MyGame : Game
{
    GraphicsDeviceManager graphics;
    SpriteBatch spriteBatch;
    Texture2D playerTexture;

    public MyGame()
    {
        graphics =
          new GraphicsDeviceManager(this);
        Content.RootDirectory = "Content";
    }

    protected override void LoadContent()
    {
        spriteBatch =
          new SpriteBatch(GraphicsDevice);
        playerTexture =
          Content.Load<Texture2D>("player");
    }

    protected override void Update(
        GameTime gameTime)
    {
        if (GamePad.GetState(
              PlayerIndex.One).Buttons.Back
            == ButtonState.Pressed)
            Exit();
        base.Update(gameTime);
    }

    protected override void Draw(
        GameTime gameTime)
    {
        GraphicsDevice.Clear(Color.Black);
        spriteBatch.Begin();
        spriteBatch.Draw(
            playerTexture,
            new Vector2(100, 100),
            Color.White);
        spriteBatch.End();
        base.Draw(gameTime);
    }
}

class MyGame final : public Game
{
    GraphicsDeviceManager graphics;
    std::unique_ptr<SpriteBatch> spriteBatch;
    std::optional<Texture2D> playerTexture;

public:
    MyGame()
        : graphics(this)
    {
        getContentProperty()
          .setRootDirectoryProperty("Content");
    }

protected:
    void LoadContent() override
    {
        spriteBatch =
          std::make_unique<SpriteBatch>(
            getGraphicsDeviceProperty());
        playerTexture.emplace(
          getContentProperty()
            .Load<Texture2D>("player"));
    }

    void Update(
        GameTime& gameTime) override
    {
        if (GamePad::GetState(
              PlayerIndex::One)
            .getButtonsProperty().getBackProperty()
            == ButtonState::Pressed)
            Exit();
        Game::Update(gameTime);
    }

    void Draw(
        const GameTime& gameTime) override
    {
        getGraphicsDeviceProperty()
          .Clear(Color::Black);
        spriteBatch->Begin();
        spriteBatch->Draw(
            *playerTexture,
            Vector2(100, 100),
            Color::White);
        spriteBatch->End();
        Game::Draw(gameTime);
    }
};

4. Memory management

XNA relies on the .NET garbage collector: objects are allocated with new and reclaimed automatically. C++ has no garbage collector; you manage object lifetimes explicitly. CNA follows standard modern C++ ownership conventions:

• std::unique_ptr<T> — single-owner resource. Use this for game components, renderers, and anything your Game class owns exclusively. The resource is released automatically when the owning pointer goes out of scope or is reset.
• std::shared_ptr<T> — shared ownership, for objects that several owners really do share. Content assets are not the usual case: ContentManager::Load<T> returns each asset (Texture2D, SoundEffect, SpriteFont, Model) by value, and the GPU state behind a texture is shared-owned, so a copy you hold stays valid even after the manager unloads. Keep assets as value or std::optional members; types without a default constructor (SpriteFont, Video) need std::optional or a unique_ptr.
• Stack allocation — use for temporaries such as Vector2, Color, Rectangle, and GameTime. These are small value types and incur no heap allocation.
• ContentManager::Unload() — releases all assets currently held by the content manager's cache. Call this when transitioning between scenes to free GPU and CPU memory. Copies you already hold remain valid.
• Game components — add drawable/updatable components to the getComponentsProperty() collection (identical to XNA; a std::shared_ptr overload keeps the component alive for you), or hold them as std::unique_ptr members on your Game subclass.

The key rule: if you would write new Foo(...) in C#, write std::make_unique<Foo>(...) in C++ and store the result in a std::unique_ptr<Foo> member. The destructor will run automatically when your game object is destroyed.

5. Content pipeline

XNA and MonoGame pre-compile source assets into .xnb binary files. CNA reads XNB directly. Its 61 built-in readers (60 in a build without native 128-bit integer support) cover primitives, math, textures, fonts, audio, video, stock and compiled effects, and models, with LZX and shared-resource resolution, and ContentManager can migrate asset by asset between XNB, CNA's own .cnb container and supported loose formats. New in this snapshot: CNA can also write content at build time with the cna-content tool (.xnb or .cnb output, including .fbx, .x, .spritefont and XNA .contentproj inputs), so a project no longer has to keep MGCB or the XNA pipeline around just to produce assets. It is not an MGCB replacement: there is no .mgcb route.

For a typical 2D game the migration is straightforward: copy your existing content directory across, and the Load<T> calls are identical apart from the accessor spelling and the by-value result. Where you would rather drop the pre-compilation step entirely, place PNG and WAV files in the content directory instead and point getContentProperty().setRootDirectoryProperty() at it (a Game's content root already defaults to "Content").

6. Audio

CNA implements the main XNA audio API in the Microsoft::Xna::Framework::Audio namespace. The common classes work as expected:

• SoundEffect — loads a WAV file (or a compiled .xnb) and plays it as a fire-and-forget sound. API identical to XNA; Load<SoundEffect> returns it by value and CreateInstance() returns the instance by value.
• SoundEffectInstance — a controllable instance of a SoundEffect: pause, resume, loop, and volume control all work through setVolumeProperty, setPitchProperty, setPanProperty and setIsLoopedProperty. As in XNA, Apply3D after Play() on a pan-mode instance throws InvalidOperationException.
• MediaPlayer / Song — background music playback. API identical to XNA.

The XACT subsystem (AudioEngine, SoundBank, WaveBank, Cue) is a real parser and player rather than a facade, with FACT-shaped volume/RPC behavior and 3D calculations, playing through the SDL3 or ALSA audio implementation (the Null choice compiles it without audible output). Important caveats: only the first PlayWave per track is honoured; XMA/WMA wave-bank entries log and return a null sound rather than throwing; reverb is a no-op; and the XNB SoundEffectReader has different failure behavior. SoundEffect and MediaPlayer remain simpler alternatives.

7. Known gaps and limitations

8. Code examples

Full Game class

The following pair shows a minimal but complete game loop: window setup, content loading, update, and draw.

public class MyGame : Game
{
    GraphicsDeviceManager _graphics;
    SpriteBatch _spriteBatch;
    Texture2D _background;

    public MyGame()
    {
        _graphics =
          new GraphicsDeviceManager(this);
        _graphics
          .PreferredBackBufferWidth = 1280;
        _graphics
          .PreferredBackBufferHeight = 720;
        Content.RootDirectory = "Content";
        IsMouseVisible = true;
    }

    protected override void LoadContent()
    {
        _spriteBatch =
          new SpriteBatch(GraphicsDevice);
        _background =
          Content.Load<Texture2D>("bg");
    }

    protected override void Update(
        GameTime gt)
    {
        if (Keyboard.GetState()
            .IsKeyDown(Keys.Escape))
            Exit();
        base.Update(gt);
    }

    protected override void Draw(
        GameTime gt)
    {
        GraphicsDevice.Clear(
            Color.CornflowerBlue);
        _spriteBatch.Begin();
        _spriteBatch.Draw(
            _background,
            Vector2.Zero,
            Color.White);
        _spriteBatch.End();
        base.Draw(gt);
    }
}

class MyGame final : public Game
{
    GraphicsDeviceManager _graphics;
    std::unique_ptr<SpriteBatch> _spriteBatch;
    std::optional<Texture2D> _background;

public:
    MyGame() : _graphics(this)
    {
        _graphics
          .setPreferredBackBufferWidthProperty(1280);
        _graphics
          .setPreferredBackBufferHeightProperty(720);
        getContentProperty()
          .setRootDirectoryProperty("Content");
        setIsMouseVisibleProperty(true);
    }

protected:
    void LoadContent() override
    {
        _spriteBatch =
          std::make_unique<SpriteBatch>(
            getGraphicsDeviceProperty());
        _background.emplace(
          getContentProperty()
            .Load<Texture2D>("bg"));
    }

    void Update(GameTime& gt) override
    {
        if (Keyboard::GetState()
            .IsKeyDown(Keys::Escape))
            Exit();
        Game::Update(gt);
    }

    void Draw(const GameTime& gt) override
    {
        getGraphicsDeviceProperty().Clear(
            Color::CornflowerBlue);
        _spriteBatch->Begin();
        _spriteBatch->Draw(
            *_background,
            Vector2::Zero,
            Color::White);
        _spriteBatch->End();
        Game::Draw(gt);
    }
};

SpriteBatch draw

spriteBatch.Begin(
    SpriteSortMode.Deferred,
    BlendState.AlphaBlend);

spriteBatch.Draw(
    texture,
    new Rectangle(10, 10, 64, 64),
    Color.White);

spriteBatch.DrawString(
    font,
    "Hello, World!",
    new Vector2(200, 100),
    Color.Yellow);

spriteBatch.End();

spriteBatch->Begin(
    SpriteSortMode::Deferred,
    BlendState::AlphaBlend);

spriteBatch->Draw(
    texture,          // a const Texture2D& (or *ptr)
    Rectangle(10, 10, 64, 64),
    Color::White);

spriteBatch->DrawString(
    font,             // a const SpriteFont&
    "Hello, World!",
    Vector2(200, 100),
    Color::Yellow);

spriteBatch->End();

ContentManager load

// Load a texture
Texture2D tex =
    Content.Load<Texture2D>("sprites/hero");

// Load a sound
SoundEffect boom =
    Content.Load<SoundEffect>("sfx/boom");

// Load a font
SpriteFont font =
    Content.Load<SpriteFont>("fonts/ui");

// Unload all assets
Content.Unload();

// Load a texture (PNG loaded directly);
// Load<T> returns the asset by value
Texture2D tex =
    getContentProperty()
      .Load<Texture2D>("sprites/hero");

// Load a sound (WAV as a loose file)
SoundEffect boom =
    getContentProperty()
      .Load<SoundEffect>("sfx/boom");

// Load a font (.cnj descriptor or .xnb)
SpriteFont font =
    getContentProperty()
      .Load<SpriteFont>("fonts/ui");

// Unload all assets (copies you
// hold stay valid)
getContentProperty().Unload();