TrackMania Procedural Map Generator

An experimental toolset to programmatically and procedurally generate playable maps for TrackMania 2020.

About The Project

This project was born out of a challenge: could a TrackMania map be generated entirely from code, without ever opening the in-game editor?

My initial goal was to generate a modern TrackMania 2020 .Gbx file directly, but the complexity of the format proved difficult. The breakthrough came from a different approach:

1. Generate a map for an older, better-understood game (TrackMania Nations Forever).
2. Convert that older map into the modern TrackMania 2020 format using a community-made tool.

This repository contains the scripts to do just that. It includes a Python script that can parse a simple .txt file defining a track's layout, and a procedural generator that creates a random, multi-level "tower" style map. This is currently an alpha version, a proof-of-concept that shows this unique map creation pipeline is possible.

Features

• Procedural Map Generation: Run gen_map.py to create a new, randomized tower-style track layout (my_track_layout.txt).
• Text-Based Map Definition: The core engine reads a simple BlockName X Y Z Rotation format from a text file.
• Automated Build Pipeline: The build.py script automates the entire process:
  1. Generates the random map layout.
  2. Builds the TMNF .Gbx map file.
  3. Converts the map to the TM2020 format.
  4. Moves the final map into your user directory, ready to play.

Getting Started

Follow these steps to set up and run the project.

Prerequisites

1. Python 3.x
2. Required Python libraries: pygbx and lzo.

   pip install pygbx lzo

3. NationsConverterCLI: This project relies on this essential tool to convert the maps. Download the latest release from its GitHub repository.

Installation & Usage

1. Clone the repository:

   git clone https://github.com/TheMaster1127/programmatically-making-a-trackmania-map
   cd programmatically-making-a-trackmania-map

2. Install the prerequisites as described above.

3. IMPORTANT: Configure Paths Before running, you must update the hardcoded paths in the scripts to match your system.

   • In build.py, update these variables:

     CONVERTER_EXE = r"C:\path\to\your\NationsConverterCLI.exe"
     CONVERTER_OUTPUT_DIR = r"C:\path\to\your\NationsConverterCLI\Output"
     FINAL_MAPS_DIR = r"C:\Users\YourUser\Documents\Trackmania\Maps\My Maps" 

   • In gen_map.py, update this variable at the bottom of the file:

     baseDir = "C:\\path\\to\\your\\project\\folder\\"

4. Run the Build Script: Execute the main build script from your terminal. It will handle everything automatically.

   python build.py

   If successful, a new, playable map will appear in the FINAL_MAPS_DIR you specified.

Current State & Future Plans

This project is currently in an alpha stage. It is fully functional as a proof-of-concept but is not yet user-friendly.

Current Limitations:

• Paths and map generation parameters (like the tower height) are hardcoded directly in the Python scripts.
• The random map generator only produces one style of track.

Future Goals:

• Implement a config.json or .ini file to manage paths and settings easily.
• Expand the procedural generator to create different styles of maps (e.g., circuits, downhill).
• Add more user-configurable options for map generation (e.g., set_tower_height(x)).

Special Thanks & Acknowledgements

This project would not have been possible without the foundational work of others in the TrackMania community. A huge thank you to the creators of these essential tools:

• donadigo/tmtracknn: For the initial Python scripts that provided the base for understanding and manipulating TMNF .Gbx files.
• BigBang1112/nations-converter: For the incredible converter tool that makes this entire project viable for modern TrackMania.

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for more details.