kovagoadi
b33869334a
Timetables have no GameScript API surface, so this implements real DoCommands over the game port (ClientCommand/ServerCommand) instead of the Admin GameScript relay used for list_vehicles(): change_timetable(), autofill_timetable(), set_timetable_start(), and set_vehicle_on_time() send commands, while get_vehicle_timetable() reconstructs state purely by observing ServerCommand broadcasts, since no query command exists. Includes the custom varuint wire codec these commands require, a full usage guide (docs/TIMETABLES.md), and a worked demo in main.py. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
OpenTTD Python Client
A high-performance, Object-Oriented Python client for OpenTTD servers, specifically optimized for JGR Patch Pack (JGRPP). This client handles the modern secure handshake, including X25519 PAKE authentication and AEAD stream encryption.
🚀 Features
- Secure Authentication: Full implementation of X25519 PAKE (Password-Authenticated Key Exchange).
- Stream Encryption: Automatic XChaCha20-Poly1305 authenticated encryption for all game traffic.
- Modular Design: Separates low-level binary protocol handling from high-level game logic.
- State Management: Handles the full join sequence including Map download and synchronization.
- Comprehensive Testing: Robustly tested with unit, logic, and E2E tests (including 100% coverage for unit/logic tests).
- Vehicle Listing: Query vehicle data via the Admin GameScript channel with
list_vehicles(). - Vehicle Timetables: Read and modify a vehicle's timetable (
change_timetable(),autofill_timetable(),set_timetable_start(),set_vehicle_on_time(),get_vehicle_timetable()) via real game-protocol commands.
🛠 Setup
Prerequisites
- Python 3.11+
- A running OpenTTD server (preferably JGRPP)
Installation
- Create and activate a virtual environment:
python3 -m venv venv source venv/bin/activate # Linux/macOS - Install dependencies:
pip install openttd-protocol pymonocypher
📖 Usage
Running the default client
The main.py script is configured to join the local server and the company "Én transport".
python3 main.py [Username] [CompanyID]
Example:
python3 main.py MyBot 0
Module Integration
You can use the openttd package in your own projects:
from openttd import OpenTTDClient
client = OpenTTDClient(host="127.0.0.1", username="BotName")
await client.connect(server_password="asd")
await client.join_company(company_id=0, company_password="asd123")
await client.joined.wait()
# Your logic here...
📂 Project Structure
main.py: Main entry point and usage example.lib/openttd/: Core package containing the protocol and client logic.docs/: Extensive documentation on architecture, protocol, and contributing.tests/: Comprehensive test suite (Logic, Protocol, E2E).
🧪 Testing
We maintain high test coverage. To run normal (non-E2E) tests:
pytest -m "not e2e"
For detailed instructions on E2E testing and coverage reports, see the Testing Guide.