Initialized openttd-client repo

README.md

@@ -0,0 +1,74 @@
+# 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)