# PyTTD - Python OpenTTD Client Library
[](https://pypi.org/project/pyttd/)
[](https://pypi.org/project/pyttd/)
[](https://opensource.org/licenses/MIT)
Finally, a Python client library for connecting to [OpenTTD](https://www.openttd.org/) servers **as a player**, issuing **commands**, observing **game state** and **parsing maps**! Create bots, manage companies, and interact with OpenTTD games programmatically **with real-time data** and **without admin port access**.
## Features
| Feature | Status | Remarks
|---------------------------------|--------------------------------------------------------------------------|------------------------------------------
| Multiplayer protocol |  | - |
| Commands |  | Might have missed something |
| Game state |  | Might have missed something |
| Save file parsing |  | Game data and companies work |
| High level functions |  | Helpers for common high-level tasks |
## Requirements
- **Python**: 3.11 or higher
- **OpenTTD Server**: Tested with 14.1
## 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()
```
### Save File Parsing
PyTTD includes a save file parser module that can extract detailed game data from OpenTTD save files.
```python
from pyttd import load_save_file
# Parse a save file
game_data = load_save_file("path/to/savefile.sav")
# Access parsed data
print(f"Save version: {game_data['meta']['save_version']}")
print(f"Map size: {game_data['statistics']['map_size']}")
print(f"Companies: {game_data['statistics']['companies_count']}")
# Company information with financial data
for company in game_data['companies']:
print(f"{company['name']}: £{company['money']:,} (AI: {company['is_ai']})")
# Game date and economy
date = game_data['game']['date']['calendar_date']
print(f"Game date: {date['year']}-{date['month']}-{date['day']}")
economy = game_data['game']['economy']
print(f"Interest rate: {economy['interest_rate']}%")
```
## Examples
### Data Monitor
```bash
python examples/data_display.py
```
Displays all available real-time game state information.
### 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.
### Save File Parser
```bash
python examples/save_file_parser.py path/to/savefile.sav
```
Parse OpenTTD save files to extract game data including companies, map information, and economic data. All in a clean JSON file!
## 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()` - 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
#### Maps
TODO: describe it here
## 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/
```
## 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/51/00/37c18f8481629bfe2ba5becfe8187ca0f0c9ad2172e4bb110c53fc401b93/pyttd-1.3.0.tar.gz",
"platform": null,
"description": "# PyTTD - Python OpenTTD Client Library\n\n[](https://pypi.org/project/pyttd/)\n[](https://pypi.org/project/pyttd/)\n[](https://opensource.org/licenses/MIT)\n\nFinally, a Python client library for connecting to [OpenTTD](https://www.openttd.org/) servers **as a player**, issuing **commands**, observing **game state** and **parsing maps**! Create bots, manage companies, and interact with OpenTTD games programmatically **with real-time data** and **without admin port access**.\n\n## Features\n\n| Feature | Status | Remarks\n|---------------------------------|--------------------------------------------------------------------------|------------------------------------------\n| Multiplayer protocol |  | - |\n| Commands |  | Might have missed something |\n| Game state |  | Might have missed something |\n| Save file parsing |  | Game data and companies work |\n| High level functions |  | Helpers for common high-level tasks |\n\n## Requirements\n\n- **Python**: 3.11 or higher\n- **OpenTTD Server**: Tested with 14.1\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### Save File Parsing\n\nPyTTD includes a save file parser module that can extract detailed game data from OpenTTD save files.\n\n```python\nfrom pyttd import load_save_file\n\n# Parse a save file\ngame_data = load_save_file(\"path/to/savefile.sav\")\n\n# Access parsed data\nprint(f\"Save version: {game_data['meta']['save_version']}\")\nprint(f\"Map size: {game_data['statistics']['map_size']}\")\nprint(f\"Companies: {game_data['statistics']['companies_count']}\")\n\n# Company information with financial data\nfor company in game_data['companies']:\n print(f\"{company['name']}: \u00a3{company['money']:,} (AI: {company['is_ai']})\")\n \n# Game date and economy\ndate = game_data['game']['date']['calendar_date']\nprint(f\"Game date: {date['year']}-{date['month']}-{date['day']}\")\n\neconomy = game_data['game']['economy']\nprint(f\"Interest rate: {economy['interest_rate']}%\")\n```\n\n## Examples\n\n### Data Monitor\n```bash\npython examples/data_display.py\n```\nDisplays all available real-time game state information.\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### Save File Parser\n```bash\npython examples/save_file_parser.py path/to/savefile.sav\n```\nParse OpenTTD save files to extract game data including companies, map information, and economic data. All in a clean JSON file!\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()` - 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\n#### Maps\nTODO: describe it here\n\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## 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.3.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": "4012e8ccfae8ff6ce23350b20d0a52712bb35ed677c579c77e0ea2218910fe3a",
"md5": "bdda72f3c8fee45220d67f5f6a9f1ee0",
"sha256": "61ad048c477a64180b8298a6fdc4b68ce162110f83746b84c591e70f1c01c318"
},
"downloads": -1,
"filename": "pyttd-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bdda72f3c8fee45220d67f5f6a9f1ee0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 57915,
"upload_time": "2025-08-20T22:32:22",
"upload_time_iso_8601": "2025-08-20T22:32:22.896400Z",
"url": "https://files.pythonhosted.org/packages/40/12/e8ccfae8ff6ce23350b20d0a52712bb35ed677c579c77e0ea2218910fe3a/pyttd-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "510037c18f8481629bfe2ba5becfe8187ca0f0c9ad2172e4bb110c53fc401b93",
"md5": "1c2fc257359b4d4c4d32f6fa07690574",
"sha256": "986aea8ae2853df9ad20526e671bd4550a25097fb385e47732cc25ded3234f80"
},
"downloads": -1,
"filename": "pyttd-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "1c2fc257359b4d4c4d32f6fa07690574",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 73145,
"upload_time": "2025-08-20T22:32:24",
"upload_time_iso_8601": "2025-08-20T22:32:24.296969Z",
"url": "https://files.pythonhosted.org/packages/51/00/37c18f8481629bfe2ba5becfe8187ca0f0c9ad2172e4bb110c53fc401b93/pyttd-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-20 22:32:24",
"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
