Contributions

We welcome contributions to the TrackMania RL project. Whether you’re fixing bugs, improving documentation, or implementing new features, your contributions are valuable.

This is a personal fork of the original Linesight project, but contributions are encouraged to help improve the codebase and make it more accessible for RL experimentation.

Getting Started

Before Contributing:

  1. Fork the repository

  2. Set up your development environment (see Dev FAQ)

  3. Open an issue to discuss your proposed changes

  4. Create a feature branch for your work

Development Setup:

# Clone your fork
git clone https://github.com/ArtyomZemlyak/rulka.git
cd rulka

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e ".[dev,doc]"

Coding Guidelines

Code Style:

  • Use Ruff for formatting and linting:

ruff format .
ruff check .

  • Follow existing code patterns and structure

  • Add docstrings to new functions and classes

  • Keep configuration in the YAML schema and default file

Commits:

  • Write clear, descriptive commit messages

  • Break changes into logical, self-contained commits

  • Reference related issues in commit messages

Testing:

  • Test changes before committing

  • Verify configuration loads: python -c "from config_files.config_loader import load_config; load_config('config_files/rl/config_default.yaml')"

  • For algorithmic changes, provide multiple training runs demonstrating improvements

Documentation

When contributing, please update relevant documentation:

  • Add docstrings to new code

  • Update RST files in docs/source/ for user-facing changes (see online docs)

  • Update config_files/README.md for configuration changes

  • Update CHANGELOG.md for notable changes

Building Documentation:

cd docs
pip install -e ".[doc]"
make html

Contribution opportunities

We list below improvements that can likely be made to the project.

Documentation

General documentation improvements for users or developers.

Respawns

All rollouts start from the beginning of a track. On challenging or high-risk tracks, the agent’s memory buffer may contain limited transitions for the end of the track, which makes it difficult for the agent to learn evenly across all sections of the track.

This is likely a difficult contribution as it involves modifications in several parts of the repository at once (rollouts & statistics tracking). It is yet unclear how to best resolve this issue.

One step further in difficulty, one might refactor the agent-environment interactions to follow the Gymnasium API.

Linux performance

On Linux, the game runs much slower than windows. You can see this if you display FPS by pressing - then open the console with ` and type “set speed 50”. Your FPS should reduce by orders of magnitude. We suspect this is some kind of bottleneck in wineserver but we do not know.

Game reboot

We observe that game instances slow down over time. As a mitigation, we have implemented code to restart the game instances every config.game_reboot_interval.

  • There is a rare issue where a worker will crash when restarting the game instance.

  • config.game_camera_number allows training an agent in cam 1/2/3. There is an issue where the cam change may not happen after a worker restarts the game instance. Due to this bug it is advised to train with game_camera_number 2 (the default cam).

Neural network architecture

We have performed limited tests to improve neural network architecture. There are opportunities to improve the neural network’s vision head (currently DQN-style, could test IMPALA-style or other architectures). There are also opportunities to improve the virtual checkpoints inputs (currently a basic Dense architecture which does not benefit from the known sequential structure of virtual checkpoints).

One may also try out largely different neural network architectures and/or input features.

Reinforcement learning algorithm

This project implements a modified version of the IQN algorithm. One may also try to implement any other compatible reinforcement learning algorithm.

“inputs_to_gbx” script

We use a script scripts/tools/video_stuff/inputs_to_gbx.py to convert a batch of xxxx.inputs files into corresponding xxxx.Replay.Gbx files. It works on Agade’s computer but not on pb4’s computer. The script was put together hastily, we would welcome an improved version.

Methods to train on varied & diverse tracks

  • Hide useless visual features (flags, track decor, …) with z-buffer masking (done with ReShade with TMI1.4, but screenshots are now made BEFORE ReShade shaders are applied in TMI2)

  • Replace game textures with normal maps or depth maps (done with ReShade with TMI1.4, but screenshots are now made BEFORE ReShade shaders are applied in TMI2)

  • Implement raycasting

  • Implement an automatic track generator, such that the AI can train on an infinite number of maps. As a start, one may restrict this to flat “map5-style” tracks.

  • anything else…

Guidelines

  • Before you start working on a contribution, please open an issue to discuss your proposed changes with the project maintainers. This will help avoid duplicate work and ensure that your contribution aligns with the project’s goals.

  • Please include a brief description of your changes in the pull request description. This will help us review your changes more quickly and efficiently.

  • All code contributions must be formatted with ruff check --select I --fix . ; ruff format .. This will ensure that your code is consistent with the project’s style guidelines and easy to read.

  • Contributions should be broken down into meaningful, self-contained chunks. Please avoid combining unrelated changes, such as refactoring and algorithmic improvements, in the same pull request. This will make it easier to review and test your changes.

  • For contributions that involve algorithmic changes, we expect contributors to provide multiple runs that demonstrate both the absence of performance regressions and the presence of the expected improvements.