# courseplay/courseplay_fs25 architecture

> Architecture diagram of the GitHub repository courseplay/courseplay_fs25, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/courseplay/courseplay_fs25
- Repository: https://github.com/courseplay/courseplay_fs25

## Overview

##### Main Components
- Mod Core & Integration Layer:
- Mod’s entry point via “modDesc.xml”, which defines the mod for the game engine.
- That the integration with the game engine happens via specializations (in the “scripts/specializations” folder) and Lua scripts (such as Courseplay.lua).

- AI & Decision-Making Modules:
- AI directory, under “scripts/ai”, showing sub-components like controllers, jobs, tasks, strategies, and turns.
- Interdependencies such as task scheduling, vehicle behavior decision-making, and sensor input processing (from various controllers in “scripts/ai/controllers” and “scripts/ai/tasks”).

- Course Generation & Management:
- “courseGenerator” and “courseManager” directories. These are responsible for generating navigation courses, managing field layouts, and interfacing with user configurations.
- Components that deal with field layout calculations, headland generation, and genetic algorithms (notably in “scripts/courseGenerator/genetic”).

- GUI & User Interaction:
- Out the “scripts/gui” section including HUD elements (e.g., “scripts/gui/hud”) and in-game menu pages (“scripts/gui/pages”).
- This layer handles user feedback such as displaying course information, status texts, and interactive menus.

- Configuration & Data Files:
- “config” folder with XML configuration files that control settings like course generation parameters, vehicle behaviors, global settings, and translations.
- “translations” folder as part of supporting internationalization.

- Auxiliary Modules & Utilities:
- Supporting modules such as “scripts/pathfinder” (for route finding algorithms – A*, Dijkstra, ReedsShepp, etc.), “scripts/events” (event handling for in-game events) and “scripts/util” (helper utilities, logging, math functions).
- Testing and debugging components (found in “scripts/test” and “scripts/debug”) as separate but connected modules.

##### Relationships and Interactions
- From the configuration files to the core modules (e.g., settings in XML dictate how course generation proceeds).
- From the AI decision module to the physics and control modules (i.e., specializations and vehicle controllers).
- From the GUI layer to underlying course and AI logic – commands initiated by the user are processed and can trigger adjustments in the AI workflow.
- Communication between event triggers (scripts/events and scripts/trigger) and the corresponding AI tasks.

##### Architectural Patterns and Design Principles
- A modular layout where components such as course generation, AI management, and GUI display are independent modules with well-defined interfaces.
- Use of layered architecture: core game logic (course generation, AI, etc.), configuration/data layer, and presentation (GUI, HUD).
- That some parts follow specialized domain patterns (for example, the genetic algorithm in course generation and pathfinding algorithms in “scripts/pathfinder”).

##### Relevant Technologies, Frameworks, and Tools
- Scripting Language: The project is predominantly built in Lua.
- XML-based Configuration: Several XML files under “config” define game settings, translation, and HUD appearances.
- Version Control & CI/CD: The “.github” directory contains workflow configurations (e.g., linter, unit-tests, translation updates), indicating automated testing and continuous integration which could be shown as an external pipeline interacting with the codebase.

##### Detailed Representation
- Mod Loader and Core Initialization (modDesc.xml, Courseplay.lua)
- AI & Behavior Modules (with nested clusters for controllers, tasks, jobs, strategies)
- Course Generation (including genetic algorithms and field/course computation)
- GUI & HUD (display elements and interactive menus)
- Configuration/Data Management (XML settings, translations, image assets)
- Auxiliary Utilities (pathfinder, event system, debugging)
- Finally, include an indication of the supporting CI/CD pipeline – referencing the .github workflows that ensure code quality and updates.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Environment
    E["Farming Simulator Environment"]:::external

    %% Game Integration Layer
    subgraph "Game Integration Layer"
        A1["modDesc.xml"]:::integration
        A2["Courseplay.lua"]:::integration
        A3["Specializations"]:::integration
    end

    %% Core Logic Layer
    subgraph "Core Logic Layer"
        B1["AI & Decision-Making Modules"]:::ai
        B2["Course Generator"]:::generation
        B3["Genetic Algorithm"]:::generation
        B4["Course Manager"]:::generation
        subgraph "Auxiliary Modules & Utilities"
            B5a["Pathfinder"]:::auxiliary
            B5b["Event System"]:::auxiliary
            B5c["Utilities"]:::auxiliary
            B5d["Debug/Testing"]:::auxiliary
        end
    end

    %% Presentation & Configuration Layer
    subgraph "Presentation & Configuration Layer"
        C1["GUI & User Interaction"]:::gui
        C2["GUI Configurations"]:::gui
        C3["Config Files"]:::config
        C4["Translations"]:::config
    end

    %% CI/CD Pipeline
    D["CI/CD Pipeline"]:::cicd

    %% Connections - External to Integration
    E -->|"loads"| A1
    E -->|"loads"| A2
    E -->|"loads"| A3

    %% Integration Layer to Core Logic
    A1 -->|"initiates"| B1
    A2 -->|"initiates"| B1
    A3 -->|"enhances"| B1

    %% AI interactions with Course Management
    B1 -->|"triggers"| B2
    B1 -->|"updates"| B4
    B2 -->|"employs"| B3

    %% AI interacts with Auxiliary Modules
    B1 -->|"uses"| B5a
    B1 -->|"dispatches"| B5b
    B1 -->|"calls"| B5c
    B1 -->|"monitors"| B5d

    %% Configuration influences Core Logic and GUI
    C3 -->|"configures"| B1
    C3 -->|"configures"| B2
    C3 -->|"configures"| B4
    C4 -->|"localizes"| C1

    %% GUI interactions with Core Logic
    C1 -->|"commands"| B1
    C1 -->|"commands"| B2
    C1 -->|"commands"| B4
    C2 -->|"setsup"| C1

    %% CI/CD Pipeline feedback into key modules
    D ---|"validates"| A1
    D ---|"validates"| B1
    D ---|"validates"| B2
    D ---|"validates"| C3

    %% Styles
    classDef external fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef integration fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef ai fill:#87CEEB,stroke:#000,stroke-width:2px;
    classDef generation fill:#00CED1,stroke:#000,stroke-width:2px;
    classDef gui fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef config fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef auxiliary fill:#dda0dd,stroke:#000,stroke-width:2px;
    classDef cicd fill:#D3D3D3,stroke:#000,stroke-width:2px;

    %% Click Events
    click A1 "https://github.com/courseplay/courseplay_fs25/blob/main/modDesc.xml"
    click A2 "https://github.com/courseplay/courseplay_fs25/blob/main/Courseplay.lua"
    click A3 "https://github.com/courseplay/courseplay_fs25/tree/main/scripts/specializations/"
    click B1 "https://github.com/courseplay/courseplay_fs25/tree/main/scripts/ai/"
    click B2 "https://github.com/courseplay/courseplay_fs25/tree/main/scripts/courseGenerator/"
    click B3 "https://github.com/courseplay/courseplay_fs25/tree/main/scripts/courseGenerator/genetic"
    click B4 "https://github.com/courseplay/courseplay_fs25/tree/main/scripts/courseManager/"
    click C1 "https://github.com/courseplay/courseplay_fs25/tree/main/scripts/gui/"
    click C2 "https://github.com/courseplay/courseplay_fs25/tree/main/config/gui/"
    click C3 "https://github.com/courseplay/courseplay_fs25/tree/main/config/"
    click C4 "https://github.com/courseplay/courseplay_fs25/tree/main/translations/"
    click B5a "https://github.com/courseplay/courseplay_fs25/tree/main/scripts/pathfinder/"
    click B5b "https://github.com/courseplay/courseplay_fs25/tree/main/scripts/events/"
    click B5c "https://github.com/courseplay/courseplay_fs25/tree/main/scripts/util/"
    click B5d "https://github.com/courseplay/courseplay_fs25/tree/main/scripts/debug/"
```
