Squirrel Script Core Engine
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- ROADMAP.md
- license.txt
- info.nut (Referenced via README development versioning)
- .github/workflows/rolling-release.yml (Referenced via README build process)
The Squirrel Script Core Engine serves as the fundamental execution logic for Trans AI, an automated opponent for OpenTTD. It is responsible for processing game states and making strategic decisions to transport cargo, passengers, and mail across various transport modes including air, road, rail, and sea. The engine operates within the OpenTTD NoAI framework, utilizing specific Nut script files (such as info.nut) to define its identity and behavioral parameters to the game engine.
The core logic is designed around the "Cargo Concept," a strategy that prioritizes many-to-one delivery patterns to optimize industry logistics. It integrates with external AI libraries to handle complex operations like list management and string manipulation, allowing the engine to focus on pathfinding, vehicle management, and infrastructure maintenance.
Sources: README.md:3-8, README.md:14-17, ROADMAP.md:38-41
Transportation Systems Architecture
The engine manages four primary transportation modules, each with specific logic for route generation and vehicle selection. These modules are evaluated based on game settings, such as infrastructure maintenance costs.
Route Management Logic
The engine implements different strategies for each transport type:
- Air Route: Logic for town-to-town passenger transport using airports, airplanes, and helicopters.
- Road/Tram Route: Dual-purpose logic handling both passengers (buses/trams) and freight cargoes (trucks/freight trams).
- Marine Route: specialized pathfinding using buoys to find proper water routes for ships.
- Rail Route: Complex logic supporting raw cargo transport between industries, with support for double-track layouts.
The following flowchart illustrates the high-level decision flow for route initialization:
The engine scans available towns and industries to determine which transport module to invoke based on available vehicle types and distance.
Sources: ROADMAP.md:4-36, ROADMAP.md:52-54, README.md:3-6
Integration and Dependencies
The Squirrel Script engine does not function in isolation; it relies on a standardized set of NoAI libraries to perform basic data structure operations.
| Library | Purpose |
|---|---|
| AI Library - Common | Core utility functions for OpenTTD AI interaction. |
| AI Library - List | Handling of industry, town, and vehicle lists. |
| AI Library - String | Parsing and formatting of in-game text and names. |
The engine's versioning is handled through a rolling release model (YYMMDD format), which is reflected in the info.nut file. For development environments, the version is set to a future date to ensure the local script overrides the versions downloaded from the 'Bananas' content service.
Sources: README.md:46-52, README.md:54-61
Special Features and Logic Modules
Cargo Concept (Many-to-One)
The core engine implements a "Cargo Concept" where it attempts to use a single industry as the primary destination for cargo types. This simplifies the transport network and mimics high-efficiency player strategies. Currently, this is heavily implemented in Rail routes, with ongoing rework for Road and Marine routes.
Corporate Management Logic
The engine includes logic for financial and corporate growth beyond simple transport:
- Mergers: The AI can detect and accept merger offers from other companies.
- Profitability Recovery: Logic is being developed to turn negative income acquisitions into profitable ventures to avoid bankruptcy.
The sequence above shows the interaction between the core AI, the supporting libraries, and the OpenTTD game engine during a typical execution cycle.
Sources: ROADMAP.md:38-50, README.md:6-10
Infrastructure Maintenance and Configuration
The engine adapts its behavior based on the infrastructure_maintenance setting. If activated, the AI prioritizes more cost-effective builds, particularly affecting the expansion of the Air Route module.
Build and Deployment
The engine's deployment is managed via GitHub Actions, which automates the packaging of Squirrel scripts into .tar files compatible with the OpenTTD ai directory.
Sources: ROADMAP.md:52-54, README.md:63-65
Conclusion
The Squirrel Script Core Engine for Trans AI provides a multi-modal transportation logic framework. By leveraging the Cargo Concept and modular route management, it provides a competitive environment for OpenTTD players while maintaining flexibility through the use of standardized AI libraries and automated CI/CD pipelines.