# 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.
- **100% Test Coverage:** Robustly tested with unit, logic, and E2E tests.

## 🛠 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 100% test coverage. To run tests:
```bash
PYTHONPATH=lib pytest --cov=openttd tests/
```

## 📜 Documentation
- [Architecture & Design](docs/ARCHITECTURE.md)
- [Protocol Internals (PAKE/Encryption)](docs/PROTOCOL.md)
- [Contributor Guide](docs/CONTRIBUTING.md)