kovagoadi
2eea541158
Editing (game port, OpenTTDClient): a core of JGRPP's scheduled dispatch DoCommands — set_scheduled_dispatch (enable/disable), add/remove schedule, add/remove/clear slots, and set duration/start date. Adds the command IDs to protocol.py. Viewing (admin, OpenTTDAdminClient.get_dispatch): the GameScript API has no dispatch support, so a new server patch (docker/patches/0002-*) adds read-only GSOrder.GetScheduledDispatch* / IsScheduledDispatchEnabled getters, an AdminBridge GameScript get_dispatch handler exposes them, and get_dispatch() returns the live schedules and slots (mirrors get_timetable). Note: set_dispatch_start_date values are normalised by the engine relative to current game time, so they read back offset from the requested value. Includes unit + e2e tests, a demo in main.py, and protocol/timetable docs. The AdminBridge GameScript and the patched OpenTTD-patches clone live outside this repo; the 0002 patch file is the durable source for the latter. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
85 lines
4.2 KiB
Markdown
85 lines
4.2 KiB
Markdown
# 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.
|
|
- **Order Editing:** Add and remove a vehicle's orders (`add_order()` inserts a "go to station" stop, `remove_order()` deletes one) via real game-protocol commands.
|
|
- **Scheduled Dispatch (JGRPP):** Edit a vehicle's dispatch schedules and departure slots over the game port (`add_dispatch_schedule()`, `add_dispatch_slot()`, `set_dispatch_duration()`, `set_scheduled_dispatch()`, and more), and read them back authoritatively with `OpenTTDAdminClient.get_dispatch()` (via a patched GameScript API + the AdminBridge GS).
|
|
- **Authoritative Timetable Reads:** `OpenTTDAdminClient.get_timetable()` fetches the real, current timetable of any vehicle from the running game (via a patched GameScript API + the AdminBridge GS) — no company join needed, works for timetables set before connecting.
|
|
- **Station Listing:** Enumerate stations via the Admin GameScript channel with `list_stations()`.
|
|
- **Station Cargo Snapshots:** `OpenTTDAdminClient.get_station()` returns a station's live per-cargo state from the running game — both the **real-time** amount waiting and the **planned** flow through the cargodist link graph — over the AdminBridge GS (stock GameScript API, no server patch needed).
|
|
- **Cargo Flow Breakdown:** `OpenTTDAdminClient.get_station_cargo()` breaks one cargo type down by **source station** and **next hop** (routing destination) for both waiting (real-time) and planned amounts, with optional `from_station`/`via_station` filters.
|
|
|
|
## 🛠 Setup
|
|
|
|
### Prerequisites
|
|
- Python 3.11+
|
|
- A running OpenTTD server (preferably JGRPP)
|
|
|
|
### Installation
|
|
1. Create and activate a virtual environment:
|
|
```bash
|
|
python3 -m venv venv
|
|
source venv/bin/activate # Linux/macOS
|
|
```
|
|
2. Install dependencies:
|
|
```bash
|
|
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".
|
|
|
|
```bash
|
|
python3 main.py [Username] [CompanyID]
|
|
```
|
|
|
|
Example:
|
|
```bash
|
|
python3 main.py MyBot 0
|
|
```
|
|
|
|
### Module Integration
|
|
You can use the `openttd` package in your own projects:
|
|
|
|
```python
|
|
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:
|
|
```bash
|
|
pytest -m "not e2e"
|
|
```
|
|
For detailed instructions on E2E testing and coverage reports, see the [Testing Guide](file:///home/kovagoadi/openttd-client/docs/TESTING.md).
|
|
|
|
## 📜 Documentation
|
|
- [Architecture & Design](docs/ARCHITECTURE.md)
|
|
- [Protocol Internals (PAKE/Encryption)](docs/PROTOCOL.md)
|
|
- [Vehicle Timetables Usage Guide](docs/TIMETABLES.md)
|
|
- [Contributor Guide](docs/CONTRIBUTING.md)
|