FS25 Vehicle Sorter Development

Development guide for working with the FS25 Vehicle Sorter codebase - a Python desktop application that allows Farming Simulator 2025 players to reorder vehicles in their savegame by modifying the `vehicles.xml` file.

Project Overview

FS25 Vehicle Sorter is a Python desktop application that modifies the TAB-cycling order of vehicles in Farming Simulator 2025 by reordering elements in the savegame's `vehicles.xml` file.

Architecture

Project Structure

The project follows the modern Python src/ layout:

Core Components

**src/fs25_vehicle_sorter/main.py** - GUI application entry point using FreeSimpleGUI. Handles all UI events, vehicle selection, and movement operations. The main event loop processes user interactions and updates the vehicle list display.

**src/fs25_vehicle_sorter/vehicle_xml.py (VehiclesXml class)** - Core business logic for loading/saving savegames and manipulating vehicle order. This class:

**src/fs25_vehicle_sorter/model.py (Vehicle class)** - Simple data model representing a vehicle with properties:

FS25 Format Changes

FS25 significantly changed the vehicles.xml format from FS22:

**Key differences:**

**How it works:**

Development Workflow

This project uses [uv](https://docs.astral.sh/uv/) for Python version and dependency management.

Step 1: Install Dependencies

```bash

uv sync

```

Step 2: Run the Application

```bash

uv run python main.py

```

Step 3: Code Quality Checks

Run Ruff for linting and formatting:

```bash

Check for linting issues

uv run ruff check .

Auto-fix linting issues

uv run ruff check --fix .

Format code

uv run ruff format .

Run both fix and format

uv run ruff check --fix . && uv run ruff format .

```

Step 4: Pre-commit Hooks

Pre-commit hooks automatically run ruff before each commit:

```bash

Install the hooks (one-time setup)

uv run pre-commit install

Manually run hooks on all files

uv run pre-commit run --all-files

Skip hooks for a specific commit (not recommended)

git commit --no-verify

```

Step 5: Build Executable

Build a standalone executable using PyInstaller:

```bash

uv run pyinstaller --onefile --name "FS25 Vehicle Sorter" --windowed main.py

```

Important Implementation Details

**XML Element Ordering**: TAB order is determined by the order of `<vehicle>` elements in the XML file. When saving, reorder these elements to match the vehicles_list order (src/fs25_vehicle_sorter/vehicle_xml.py:50-53).

**Attachment Tracking**: Uses `uniqueId` references via `attachedVehicleUniqueId` attribute. These remain valid when reordering since uniqueId values are not modified.

**Backup Creation**: Always creates a timestamped backup before saving (src/fs25_vehicle_sorter/vehicle_xml.py:56-59).

**Reload After Save**: Always reload the savegame after saving (src/fs25_vehicle_sorter/vehicle_xml.py:65) to refresh the in-memory state.

**Package Structure**: Uses relative imports (e.g., `from .model import Vehicle`) within the src/fs25_vehicle_sorter directory.

Platform-specific Notes

The app detects the platform and sets default savegame locations:

Constraints