# PyTTD - Python OpenTTD Client Library
[](https://badge.fury.io/py/pyttd)
[](https://pypi.org/project/pyttd/)
[](https://opensource.org/licenses/MIT)
A Python client library for connecting to [OpenTTD](https://www.openttd.org/) servers. Create AI bots, manage companies, and interact with OpenTTD games programmatically with **real-time data** and **without admin port**.
## Features
todo
## Installation
### From PyPI (Recommended)
```bash
pip install pyttd
```
### From Source
```bash
git clone https://github.com/mssc89/pyttd.git
cd pyttd
pip install -e .
```
## Quick Start
```python
from pyttd import OpenTTDClient
# Connect to OpenTTD server
client = OpenTTDClient("127.0.0.1", 3979, player_name="MyBot")
client.connect()
# Get real-time game information
game_info = client.get_game_info()
print(f"Game Year: {game_info['current_year']}")
print(f"Companies: {game_info['companies']}/{game_info['companies_max']}")
print(f"Clients: {game_info['clients']}/{game_info['clients_max']}")
# Company management
if client.get_our_company():
finances = client.get_company_finances()
print(f"Money: £{finances['money']:,}")
print(f"Loan: £{finances['loan']:,}")
# Take a loan and send a status message
client.increase_loan(50000)
client.send_chat("Bot taking loan for expansion!")
# Clean disconnect
client.disconnect()
```
## Real-Time Data Features
PyTTD provides real-time data that matches what other players see in the OpenTTD GUI:
```python
from pyttd import OpenTTDClient
client = OpenTTDClient()
client.connect()
# Real-time game state
game_info = client.get_game_info()
print(f"Current Game Year: {game_info['current_year']}") # e.g., 1964
print(f"Game Started: {game_info['start_year']}") # e.g., 1950
print(f"Companies Active: {game_info['companies']}") # e.g., 8/15
print(f"Players Online: {game_info['clients']}") # e.g., 12/25
# Company information
companies = client.get_companies()
for company_id, company in companies.items():
print(f"Company {company_id}: {company['name']}")
# Financial analysis
finances = client.get_company_finances()
performance = client.get_company_performance()
print(f"Net Worth: £{finances['net_worth']:,}")
print(f"Company Value: £{performance['company_value']:,}")
```
## Examples
### Data Monitor
```bash
python examples/data_display.py
```
Displays all available real-time game state information in a clean, organized format.
### Chat Bot
```bash
python examples/chat_bot.py
```
Basic example showing connection, company creation, and chat interaction.
### Company Manager
```bash
python examples/manager_bot.py
```
Demonstrates company management features and financial tracking.
### Financial Manager
```bash
python examples/finance_bot.py
```
Interactive financial management with chat-based commands.
## API Reference
### OpenTTDClient
The main client class for connecting to OpenTTD servers.
```python
client = OpenTTDClient(
server="127.0.0.1", # Server IP address
port=3979, # Server port
player_name="MyBot", # Your bot's name
company_name="MyCompany" # Company name (auto-created)
)
```
#### Connection Methods
- `client.connect()` - Connect to server and join game
- `client.disconnect()` - Clean disconnect from server
- `client.is_connected()` - Check connection status
#### Game Information
- `client.get_game_info()` - Complete game state information
- `client.get_map_info()` - Map size and terrain data
- `client.get_economic_status()` - Economic indicators
#### Company Management
- `client.get_companies()` - List all companies
- `client.get_our_company()` - Our company information
- `client.get_company_finances()` - Financial data
- `client.get_company_performance()` - Performance metrics
#### Financial Operations
- `client.increase_loan(amount)` - Increase company loan
- `client.decrease_loan(amount)` - Decrease company loan
- `client.give_money(amount, company)` - Transfer money
- `client.can_afford(amount)` - Check affordability
#### Company Customization
- `client.rename_company(name)` - Change company name
- `client.rename_president(name)` - Change manager name
- `client.set_company_colour(scheme, primary, colour)` - Change colors
#### Communication
- `client.send_chat(message)` - Send public chat message
- `client.send_chat_to_company(message, company_id)` - Company chat
- `client.broadcast_status()` - Broadcast bot status
#### Vehicle Management
- `client.get_vehicles()` - List all vehicles
- `client.get_our_vehicles()` - Our company's vehicles
- `client.get_vehicle_statistics()` - Vehicle performance data
## Requirements
- **Python**: 3.11 or higher
- **OpenTTD Server**: Tested with 14.1
## Development
### Setting up Development Environment
```bash
git clone https://github.com/mssc89/pyttd.git
cd pyttd
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Code formatting
black pyttd/
flake8 pyttd/
# Type checking
mypy pyttd/
```
## Protocol Implementation
PyTTD implements OpenTTD's complete network protocol including:
- **CLIENT_JOIN** and **CLIENT_GAME_INFO** packets for connection
- **SERVER_GAME_INFO** parsing for real-time data synchronization
- **CLIENT_COMMAND** for all game operations (construction, management, etc.)
- **SERVER_FRAME** handling for game synchronization
- **CLIENT_CHAT** and **SERVER_CHAT** for communication
The library automatically handles:
- Map downloading and decompression
- Game state synchronization
- Command validation and encoding
- Network packet parsing and generation
- Connection management and error handling
## Support
- **GitHub Issues**: [Report bugs or request features](https://github.com/mssc89/pyttd/issues)
- **Documentation**: [Full API documentation](https://github.com/mssc89/pyttd#readme)
- **Examples**: [Comprehensive examples](https://github.com/mssc89/pyttd/tree/main/examples)
Raw data
{
"_id": null,
"home_page": "https://github.com/mssc89/pyttd",
"name": "pyttd",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "openttd, transport, tycoon, simulation, game, ai, bot, client, network, protocol, multiplayer, automation",
"author": "mssc89",
"author_email": "mssc89 <pyttd@example.com>",
"download_url": "https://files.pythonhosted.org/packages/0d/bb/15346b8ce7cdd48e2ed080ca1299ce71a3c632218157cba85c191d9c697e/pyttd-1.0.0.tar.gz",
"platform": null,
"description": "# PyTTD - Python OpenTTD Client Library\n\n[](https://badge.fury.io/py/pyttd)\n[](https://pypi.org/project/pyttd/)\n[](https://opensource.org/licenses/MIT)\n\nA Python client library for connecting to [OpenTTD](https://www.openttd.org/) servers. Create AI bots, manage companies, and interact with OpenTTD games programmatically with **real-time data** and **without admin port**.\n\n## Features\n\ntodo\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install pyttd\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/mssc89/pyttd.git\ncd pyttd\npip install -e .\n```\n\n## Quick Start\n\n```python\nfrom pyttd import OpenTTDClient\n\n# Connect to OpenTTD server\nclient = OpenTTDClient(\"127.0.0.1\", 3979, player_name=\"MyBot\")\nclient.connect()\n\n# Get real-time game information\ngame_info = client.get_game_info()\nprint(f\"Game Year: {game_info['current_year']}\")\nprint(f\"Companies: {game_info['companies']}/{game_info['companies_max']}\")\nprint(f\"Clients: {game_info['clients']}/{game_info['clients_max']}\")\n\n# Company management\nif client.get_our_company():\n finances = client.get_company_finances()\n print(f\"Money: \u00a3{finances['money']:,}\")\n print(f\"Loan: \u00a3{finances['loan']:,}\")\n \n # Take a loan and send a status message\n client.increase_loan(50000)\n client.send_chat(\"Bot taking loan for expansion!\")\n\n# Clean disconnect\nclient.disconnect()\n```\n\n## Real-Time Data Features\n\nPyTTD provides real-time data that matches what other players see in the OpenTTD GUI:\n\n```python\nfrom pyttd import OpenTTDClient\n\nclient = OpenTTDClient()\nclient.connect()\n\n# Real-time game state\ngame_info = client.get_game_info()\nprint(f\"Current Game Year: {game_info['current_year']}\") # e.g., 1964\nprint(f\"Game Started: {game_info['start_year']}\") # e.g., 1950\nprint(f\"Companies Active: {game_info['companies']}\") # e.g., 8/15\nprint(f\"Players Online: {game_info['clients']}\") # e.g., 12/25\n\n# Company information\ncompanies = client.get_companies()\nfor company_id, company in companies.items():\n print(f\"Company {company_id}: {company['name']}\")\n \n# Financial analysis \nfinances = client.get_company_finances()\nperformance = client.get_company_performance()\nprint(f\"Net Worth: \u00a3{finances['net_worth']:,}\")\nprint(f\"Company Value: \u00a3{performance['company_value']:,}\")\n```\n\n## Examples\n\n### Data Monitor\n```bash\npython examples/data_display.py\n```\nDisplays all available real-time game state information in a clean, organized format.\n\n### Chat Bot\n```bash\npython examples/chat_bot.py \n```\nBasic example showing connection, company creation, and chat interaction.\n\n### Company Manager\n```bash\npython examples/manager_bot.py\n```\nDemonstrates company management features and financial tracking.\n\n### Financial Manager\n```bash\npython examples/finance_bot.py\n```\nInteractive financial management with chat-based commands.\n\n## API Reference\n\n### OpenTTDClient\n\nThe main client class for connecting to OpenTTD servers.\n\n```python\nclient = OpenTTDClient(\n server=\"127.0.0.1\", # Server IP address\n port=3979, # Server port \n player_name=\"MyBot\", # Your bot's name\n company_name=\"MyCompany\" # Company name (auto-created)\n)\n```\n\n#### Connection Methods\n- `client.connect()` - Connect to server and join game\n- `client.disconnect()` - Clean disconnect from server\n- `client.is_connected()` - Check connection status\n\n#### Game Information\n- `client.get_game_info()` - Complete game state information\n- `client.get_map_info()` - Map size and terrain data \n- `client.get_economic_status()` - Economic indicators\n\n#### Company Management\n- `client.get_companies()` - List all companies\n- `client.get_our_company()` - Our company information\n- `client.get_company_finances()` - Financial data\n- `client.get_company_performance()` - Performance metrics\n\n#### Financial Operations\n- `client.increase_loan(amount)` - Increase company loan\n- `client.decrease_loan(amount)` - Decrease company loan \n- `client.give_money(amount, company)` - Transfer money\n- `client.can_afford(amount)` - Check affordability\n\n#### Company Customization\n- `client.rename_company(name)` - Change company name\n- `client.rename_president(name)` - Change manager name\n- `client.set_company_colour(scheme, primary, colour)` - Change colors\n\n#### Communication\n- `client.send_chat(message)` - Send public chat message\n- `client.send_chat_to_company(message, company_id)` - Company chat\n- `client.broadcast_status()` - Broadcast bot status\n\n#### Vehicle Management\n- `client.get_vehicles()` - List all vehicles\n- `client.get_our_vehicles()` - Our company's vehicles\n- `client.get_vehicle_statistics()` - Vehicle performance data\n\n## Requirements\n\n- **Python**: 3.11 or higher\n- **OpenTTD Server**: Tested with 14.1\n\n## Development\n\n### Setting up Development Environment\n\n```bash\ngit clone https://github.com/mssc89/pyttd.git\ncd pyttd\n\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Code formatting\nblack pyttd/\nflake8 pyttd/\n\n# Type checking\nmypy pyttd/\n```\n\n## Protocol Implementation\n\nPyTTD implements OpenTTD's complete network protocol including:\n\n- **CLIENT_JOIN** and **CLIENT_GAME_INFO** packets for connection\n- **SERVER_GAME_INFO** parsing for real-time data synchronization \n- **CLIENT_COMMAND** for all game operations (construction, management, etc.)\n- **SERVER_FRAME** handling for game synchronization\n- **CLIENT_CHAT** and **SERVER_CHAT** for communication\n\nThe library automatically handles:\n- Map downloading and decompression\n- Game state synchronization \n- Command validation and encoding\n- Network packet parsing and generation\n- Connection management and error handling\n\n## Support\n\n- **GitHub Issues**: [Report bugs or request features](https://github.com/mssc89/pyttd/issues)\n- **Documentation**: [Full API documentation](https://github.com/mssc89/pyttd#readme)\n- **Examples**: [Comprehensive examples](https://github.com/mssc89/pyttd/tree/main/examples)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "OpenTTD Client Library",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/mssc89/pyttd/issues",
"Documentation": "https://github.com/mssc89/pyttd#readme",
"Homepage": "https://github.com/mssc89/pyttd",
"Source Code": "https://github.com/mssc89/pyttd"
},
"split_keywords": [
"openttd",
" transport",
" tycoon",
" simulation",
" game",
" ai",
" bot",
" client",
" network",
" protocol",
" multiplayer",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "45466a8a01893106c5317934a6a3b16709846756100c119e6fbae0e9060c094a",
"md5": "d83c3b1b579802cd77156e15935c2a7f",
"sha256": "ee88b43a1ebabf631df4459f608658ac3a445d414db2dff6dacc340956c0b90a"
},
"downloads": -1,
"filename": "pyttd-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d83c3b1b579802cd77156e15935c2a7f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 28044,
"upload_time": "2025-08-13T17:24:26",
"upload_time_iso_8601": "2025-08-13T17:24:26.568396Z",
"url": "https://files.pythonhosted.org/packages/45/46/6a8a01893106c5317934a6a3b16709846756100c119e6fbae0e9060c094a/pyttd-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0dbb15346b8ce7cdd48e2ed080ca1299ce71a3c632218157cba85c191d9c697e",
"md5": "86025039ae9db07bb555c24db59c696b",
"sha256": "bb6a189ffaf90791be67773f9b30cb7db966e85ec04593c2f2f174a5fa4b5f08"
},
"downloads": -1,
"filename": "pyttd-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "86025039ae9db07bb555c24db59c696b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 40751,
"upload_time": "2025-08-13T17:24:27",
"upload_time_iso_8601": "2025-08-13T17:24:27.623881Z",
"url": "https://files.pythonhosted.org/packages/0d/bb/15346b8ce7cdd48e2ed080ca1299ce71a3c632218157cba85c191d9c697e/pyttd-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-13 17:24:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mssc89",
"github_project": "pyttd",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyttd"
}
JSON
