An XNA game carries more than C# source: its behavior also depends on content processing, graphics assumptions, input devices and platform services. A successful migration begins with a playable reference and moves one small, complete slice into the new runtime.
This guide focuses on assessing an XNA 4.0 project for migration to MonoGame. MonoGame's XNA migration documentation describes compatibility and known differences. Projects from another XNA version need an additional assessment against that version's APIs. Download the migration inventory to record evidence as you work.
Recover a reproducible baseline
Locate the source revision, solution files, original assets, content project, third-party libraries and build instructions. Record the XNA version, target platform, compiler environment and any external services. If the original build still runs in an appropriate preserved environment, capture a short repeatable play session: menu, one level, pause, audio and save/load.
Keep screenshots and expected values with the source revision that produced them. A useful reference includes a known resolution, camera position, input sequence and save file. Frame counts or elapsed times need their measurement conditions attached. If you have only a binary, record that limitation and separate observed behavior from assumptions about its source.
Inventory rights to art, music, fonts, plugins and code before planning distribution on another platform. Preserve source assets where available. Rebuilding content from originals gives you more options than relying exclusively on compiled content artifacts.
Sort compatibility by subsystem
| Subsystem | First experiment | Evidence of progress |
|---|---|---|
| Game loop and state | Start the game and update one state | Predictable transition into a test scene |
| Graphics | Draw one sprite or model at a known position | Correct scale, color, ordering and alignment |
| Content | Rebuild and load one representative asset | Reproducible content build from source |
| Input | Move one object with the intended device | Correct mapping, focus and reconnect behavior |
| Audio | Play and stop one short effect | Expected volume, looping and lifecycle |
| Storage or online services | Trace each dependency | Explicit replacement or scoped removal plan |
MonoGame retains many XNA-compatible types and namespaces, which can reduce code changes. Its migration guide also identifies missing XNA areas including Microsoft.Xna.Framework.Storage, GamerServices and Net, and differences in shader compilation and graphics behavior. Audit actual uses of those APIs before estimating a port. A successful compile covers only the APIs the compiler can resolve.
Port a vertical slice
Choose the smallest path that exercises the real game: launch, load one level, move the player, trigger a sound, pause and return to a menu. Create a new project using the current official setup for your chosen MonoGame target and record the exact tool versions. Bring in source incrementally, rebuilding content through the target's documented pipeline.
Resolve compile failures by subsystem. Keep a short compatibility log: source location, original behavior, replacement, test and remaining uncertainty. A missing service may require a product decision, such as choosing a new save location or redesigning a multiplayer feature, rather than a direct method substitution.
Keep the original project recoverable while the slice develops. Avoid changing gameplay rules at the same time as runtime adaptation; the baseline is easier to compare when the intended game behavior remains stable.
Investigate visual differences systematically
Begin with an unambiguous scene: one sprite at integer coordinates, one known texture and a fixed camera. Compare resolution, viewport, scaling and sampling settings before changing artwork. If everything is shifted slightly, examine projection and pixel alignment.
The MonoGame migration guide specifically discusses XNA's DirectX 9-era half-pixel adjustment and differences with other graphics APIs. Apply a correction only after identifying what the original code already does and what the target expects. Adding a second compensating offset can create a new alignment error.
For shaders, retain original source and document the build path used for the target. Test a simple material before a complex effect. Separate a failure to compile from a shader that compiles but renders differently; those require different evidence.
Accept behavior on the intended target
Replay the same small session on the original reference and migrated build. Compare movement, collisions, UI transitions, audio and saved state. Test a resize, focus loss and the intended controllers. Verify that a packaged build starts on a clean test environment with its required content, instead of relying on files accidentally present in the development directory.
Mark differences as accepted design changes, defects or unresolved investigations. Record who accepted them and why. Keep distribution work behind a clear milestone: a reproducible build, the agreed slice working on the target, and an explicit list of unsupported features.
The migration inventory is complete when another developer can reproduce the reference, build the slice and understand what remains. This guide supplies a planning and acceptance method; it does not claim to have compiled your project. For a compact demonstration of input, state and elapsed time, the browser game-loop exercise makes those responsibilities visible without a platform migration.