GBX.NET 2.0.5

There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package GBX.NET --version 2.0.5                
NuGet\Install-Package GBX.NET -Version 2.0.5                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="GBX.NET" Version="2.0.5" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add GBX.NET --version 2.0.5                
#r "nuget: GBX.NET, 2.0.5"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install GBX.NET as a Cake Addin
#addin nuget:?package=GBX.NET&version=2.0.5

// Install GBX.NET as a Cake Tool
#tool nuget:?package=GBX.NET&version=2.0.5                


NuGet Discord

A general purpose library for Gbx files - data from Nadeo games like Trackmania or Shootmania, written in C#/.NET. It supports high performance serialization and deserialization of 200+ Gbx classes.

For more details, see the main README.

Framework support

Due to the recently paced evolution of .NET, framework support has been limited only to a few ones compared to GBX.NET 1:

  • .NET 8
  • .NET 6
  • .NET Standard 2.0

You can still use GBX.NET 2 on the old .NET Framework, but the performance of the library could be degraded.


These examples expect you to have <ImplicitUsings>enable</ImplicitUsings>. If this does not work for you, add using System.Linq; at the top.

Map information

Additional package GBX.NET.LZO is required in this example.

using GBX.NET;
using GBX.NET.Engines.Game;
using GBX.NET.LZO;

Gbx.LZO = new MiniLZO();

var map = Gbx.ParseNode<CGameCtnChallenge>("Path/To/My.Map.Gbx");

foreach (var block in map.GetBlocks().GroupBy(x => x.Name))
    Console.WriteLine($"{block.Key}: {block.Count()}");

Map information from Gbx header

using GBX.NET;
using GBX.NET.Engines.Game;
using GBX.NET.LZO;

var map = Gbx.ParseHeaderNode<CGameCtnChallenge>("Path/To/My.Map.Gbx");


Header contains a lot less information than the full node.

Modify and save a map

using GBX.NET;
using GBX.NET.Engines.Game;
using GBX.NET.LZO;

Gbx.LZO = new MiniLZO();

var gbx = Gbx.Parse<CGameCtnChallenge>("Path/To/My.Map.Gbx");
var map = gbx.Node; // See Clarity section for more info

map.MapName = "My new map name";


The trick here is that the Gbx properties are saved in the gbx object variable (Gbx class).

If you were to go with ParseNode in this case, this would not work for TMF and older games, but it is still possible if you specify the Gbx parameters in the Save method:

map.Save("Path/To/MyNew.Map.Gbx", new()
    PackDescVersion = 2 // Latest known PackDesc version in TMF

For TMS or TMN ESWC, you would have to specify ClassIdRemapMode for example:

map.Save("Path/To/MyNew.Map.Gbx", new()
    ClassIdRemapMode = ClassIdRemapMode.Id2006
    PackDescVersion = 1

These save parameters depend on the game of choice, but since Trackmania 2, this does not matter.

Processing multiple Gbx types

Additional package GBX.NET.LZO is required in this example.

This example shows how you can retrieve ghost objects from multiple different types of Gbx:

using GBX.NET;
using GBX.NET.Engines.Game;
using GBX.NET.LZO;

Gbx.LZO = new MiniLZO();

var node = Gbx.ParseNode("Path/To/My.Gbx");

var ghost = node switch
    CGameCtnReplayRecord replay => replay.GetGhosts().FirstOrDefault(),
    CGameCtnMediaClip clip => clip.GetGhosts().FirstOrDefault(),
    CGameCtnGhost g => g,
    _ => null

if (ghost is null)
    Console.WriteLine("This Gbx file does not have any ghost.");
    Console.WriteLine("Time: {0}", ghost.RaceTime);

Using pattern matching with non-generic Parse methods is a safer approach (no exceptions on different Gbx types), but less trim-friendly.

Read a large amount of replay metadata quickly

In case you only need the most basic information about many of the most common Gbx files (maps, replays, items, ...), do not read the full Gbx file, but only the header part. It is a great performance benefit for disk scans.

using GBX.NET;
using GBX.NET.Engines.Game;

foreach (var filePath in Directory.EnumerateFiles("Path/To/My/Directory", "*.Replay.Gbx", SearchOption.AllDirectories))
    catch (Exception ex)
        Console.WriteLine($"Gbx exception occurred {Path.GetFileName(filePath)}: {ex}");

void DisplayBasicReplayInfo(string filePath)
    var nodeHeader = Gbx.ParseHeaderNode(filePath);

    if (nodeHeader is CGameCtnReplayRecord replay)
        Console.WriteLine($"{replay.MapInfo}: {replay.Time}");

File types

Some of the common types to start with (a lot more are supported):

Latest extension Class Can read Can write Other extension/s
Map.Gbx CGameCtnChallenge Yes Yes Challenge.Gbx
Replay.Gbx CGameCtnReplayRecord Yes No
Ghost.Gbx CGameCtnGhost Yes Yes
Clip.Gbx CGameCtnMediaClip Yes Yes
Item.Gbx CGameItemModel Yes Yes Block.Gbx
Mat.Gbx CPlugMaterialUserInst Yes Yes
Mesh.Gbx CPlugSolid2Model Yes Yes
Shape.Gbx CPlugSurface Yes Yes
Macroblock.Gbx CGameCtnMacroBlockInfo Yes Yes
LightMapCache.Gbx CHmsLightMapCache No No
SystemConfig.Gbx CSystemConfig Yes Yes
FidCache.Gbx CMwRefBuffer Yes Yes
Profile.Gbx CGamePlayerProfile Up to TMF Up to TMF
Scores.Gbx CGamePlayerScore Yes No

Supported games

Many essential Gbx files from many games are supported:

  • Trackmania (2020), April 2024 update
  • ManiaPlanet 4(.1), TM2/SM
  • Trackmania Turbo
  • ManiaPlanet 3, TM2/SM
  • ManiaPlanet 2, TM2/SM
  • ManiaPlanet 1, TM2
  • TrackMania Forever, Nations/United
  • Virtual Skipper 5
  • TrackMania United
  • TrackMania Nations ESWC
  • TrackMania Sunrise eXtreme
  • TrackMania Original
  • TrackMania Sunrise
  • TrackMania Power Up
  • TrackMania (1.0)


GBX.NET library (this package) is MIT Licensed.

However, if you would use GBX.NET.LZO package with it (which is usually required), you'd need to follow the GNU GPL v3 License. See License section on the main README for more details.

Special thanks

Without these people, this project wouldn't be what it is today (ordered by impact):

  • Stefan Baumann (Solux)
  • Melissa (Miss)
  • florenzius
  • Kim
  • tilman
  • schadocalex
  • James Romeril
  • frolad (Juice)
  • Mika Kuijpers (TheMrMiku)
  • donadigo

And many thanks to every bug reporter!

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (11)

Showing the top 5 NuGet packages that depend on GBX.NET:

Package Downloads

An LZO compression plugin for GBX.NET to allow de/serialization of compressed Gbx bodies. This official implementation uses lzo 2.10 from NativeSharpLzo and minilzo 2.06 port by zzattack.


A wrapper for better JSON serialization of GBX.NET nodes, useful for comparing data.


Provides extensions for image handling in GBX.NET (GDI+, Windows only).


A PAK file parser using the GBX.NET features.


Support for zlib compressed parts of Gbx, integrated with GBX.NET. This official implementation uses Iconic.Zlib.Netstandard.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
2.0.6-beta2 31 7/16/2024
2.0.6-beta1 53 7/16/2024
2.0.5 198 7/1/2024
2.0.4 259 6/12/2024
2.0.3 128 5/31/2024
2.0.3-beta1 118 5/30/2024
2.0.2 260 5/4/2024
2.0.1 158 4/29/2024
2.0.0 230 4/26/2024
2.0.0-rc1 188 4/23/2024
2.0.0-beta2 85 4/21/2024
2.0.0-beta1 187 4/20/2024
2.0.0-alpha3 73 4/18/2024
2.0.0-alpha2 146 4/14/2024
2.0.0-alpha1 119 4/12/2024
1.2.6 398 2/19/2024
1.2.5 419 12/31/2023
1.2.4 397 11/26/2023
1.2.3 242 11/24/2023
1.2.2 552 7/8/2023
1.2.1 637 6/7/2023
1.2.0 816 5/4/2023
1.2.0-beta2 103 4/30/2023
1.2.0-beta1 95 4/25/2023
1.1.3 510 2/1/2023
1.1.2 306 1/21/2023
1.1.1 485 12/30/2022
1.1.0 1,263 12/11/2022
1.1.0-alpha2 187 11/11/2022
1.1.0-alpha1 109 10/25/2022
1.0.1 744 9/10/2022
1.0.0 420 9/9/2022
0.16.6 453 8/24/2022
0.16.5 464 8/21/2022
0.16.4 458 8/19/2022
0.16.3 466 8/18/2022
0.16.2 731 8/11/2022
0.16.1 479 7/21/2022
0.16.0 1,250 7/16/2022
0.15.1 546 4/4/2022
0.15.0 965 2/23/2022
0.15.0-rc2 132 2/19/2022
0.15.0-rc 172 2/1/2022
0.14.3 352 12/19/2021
0.11.0 573 6/25/2021
0.8.0 433 1/29/2021