pyttd


Namepyttd JSON
Version 1.3.0 PyPI version JSON
download
home_pagehttps://github.com/mssc89/pyttd
SummaryOpenTTD Client Library
upload_time2025-08-20 22:32:24
maintainerNone
docs_urlNone
authormssc89
requires_python>=3.11
licenseMIT
keywords openttd transport tycoon simulation game ai bot client network protocol multiplayer automation
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # PyTTD - Python OpenTTD Client Library

[![PyPI version](https://img.shields.io/pypi/v/pyttd.svg)](https://pypi.org/project/pyttd/)
[![Python versions](https://img.shields.io/pypi/pyversions/pyttd.svg)](https://pypi.org/project/pyttd/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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            | ![Done](https://img.shields.io/badge/status-done-brightgreen)            | -                                       |
| Commands                        | ![Done](https://img.shields.io/badge/status-done-brightgreen)            | Might have missed something             |
| Game state                      | ![Done](https://img.shields.io/badge/status-done-brightgreen)            | Might have missed something             |
| Save file parsing               | ![In Progress](https://img.shields.io/badge/status-in%20progress-yellow) | Game data and companies work            |
| High level functions            | ![In Progress](https://img.shields.io/badge/status-in%20progress-yellow) | 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[![PyPI version](https://img.shields.io/pypi/v/pyttd.svg)](https://pypi.org/project/pyttd/)\n[![Python versions](https://img.shields.io/pypi/pyversions/pyttd.svg)](https://pypi.org/project/pyttd/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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            | ![Done](https://img.shields.io/badge/status-done-brightgreen)            | -                                       |\n| Commands                        | ![Done](https://img.shields.io/badge/status-done-brightgreen)            | Might have missed something             |\n| Game state                      | ![Done](https://img.shields.io/badge/status-done-brightgreen)            | Might have missed something             |\n| Save file parsing               | ![In Progress](https://img.shields.io/badge/status-in%20progress-yellow) | Game data and companies work            |\n| High level functions            | ![In Progress](https://img.shields.io/badge/status-in%20progress-yellow) | 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"
}
        
Elapsed time: 1.40863s