CargoDist API Support
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
CargoDist (Cargo Distribution) is a planned enhancement for the Trans AI project intended to support the advanced cargo routing mechanics available in OpenTTD. While Trans AI currently focuses on a "one type of industry as a cargo destination" strategy (the Cargo Concept), the CargoDist feature aims to integrate with the OpenTTD API to handle more complex, multi-destination cargo flows.
Sources: README.md:3-5, ROADMAP.md:44
The scope of this feature involves utilizing available OpenTTD game mode APIs to allow the AI to function effectively in environments where cargo has specific destinations. This is categorized as a "Special Feature" in the project's development path, intended to complement existing transport capabilities across air, road, marine, and rail routes.
Sources: ROADMAP.md:33-44
Implementation Status
CargoDist support is currently listed as a planned feature in the project roadmap. It is part of the broader objective to evolve Trans AI from simple industry-to-industry transport to a system that understands and interacts with OpenTTD's internal distribution algorithms.
Roadmap Integration
The development of CargoDist support is tracked under the "Special Feature" section of the project roadmap.
| Feature Component | Status | Description |
|---|---|---|
| CargoDist Game Mode | Planned | Support CargoDist using available API |
| Cargo Concept (Many-to-one) | In Progress | Reworking road/marine routes for better destination handling |
Sources: ROADMAP.md:35-44
Architecture and Design Goals
The architecture for CargoDist support is designed to be built upon the existing multi-modal transport framework of Trans AI. The AI currently utilizes specific libraries and strategies to manage different transport routes.
Logical Data Flow
The following diagram illustrates how CargoDist support is intended to interface with the existing Trans AI logic and the OpenTTD game engine.
The diagram shows the conceptual flow where the AI queries the OpenTTD API to receive distribution data from the CargoDist kernel, which then informs the Route Manager's decisions.
Sources: README.md:3-8, ROADMAP.md:44
Dependencies for API Support
To interact with complex game mechanics like CargoDist, Trans AI relies on standard AI libraries. These must be present in the ../ai/library folder.
- AI Library - Common: Basic framework for AI operations.
- AI Library - List: Used for managing collections of stations, industries, or cargo types.
- AI Library - String: Essential for parsing and handling names/identifiers within the API.
Sources: README.md:37-41
Planned Interaction with Transport Routes
CargoDist support will eventually influence how the AI manages its various transportation sub-systems. The current roadmap indicates that different routes have varying levels of readiness for complex cargo handling.
Route Compatibility
| Route Type | Current Strategy | CargoDist Impact |
|---|---|---|
| Air Route | Town-to-town passenger transport. | Multi-airport passenger routing. |
| Road Route | Town-to-town (Bus) & Industry-to-Industry (Truck). | Cargo destination awareness for freights. |
| Marine Route | Town-to-town & Industry-to-town via buoys. | Complex sea-lane distribution. |
| Rail Route | Raw cargo industry-to-industry. | Chain-link industry distribution. |
Sources: ROADMAP.md:3-32
Technical Configuration
The AI identifies itself to the game engine and manages its versioning to ensure the most recent API features are available during development.
Versioning and API Priority
Trans AI uses a rolling release model (YYMMDD). In the info.nut file (the main metadata file for OpenTTD AIs), the version is set to a future date during local development to ensure the engine prioritizes the developer's local changes over official releases when testing new API implementations like CargoDist.
Sources: README.md:48-52
Summary
CargoDist API Support represents a significant milestone in the Trans AI roadmap. By moving from a "Many-to-one" cargo concept to full distribution support, the AI will be able to compete effectively in modern OpenTTD games where cargo has specific, non-negotiable destinations. This feature will leverage the standard AI libraries and the existing multi-modal transport infrastructure to provide a more realistic and efficient transport network.
Sources: ROADMAP.md:35-44, README.md:3-8