Metadata-Version: 2.4
Name: terrex
Version: 2.0.0
Summary: Programmable automation client for Terraria servers
Author-email: Maksim Stashkevich <makstashkevich@gmail.com>
License-Expression: MIT
Keywords: terraria,automation,bots,agents,protocol,api
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy
Provides-Extra: dev
Requires-Dist: check-manifest; extra == "dev"
Provides-Extra: test
Requires-Dist: coverage; extra == "test"
Dynamic: license-file

# Terrex

Programmable automation client for Terraria servers.

[![PyPI version](https://badge.fury.io/py/terrex.svg)](https://badge.fury.io/py/terrex)

![Terrex logo](https://raw.githubusercontent.com/makstashkevich/terrex/master/assets/logo.jpg)

---

## What is Terrex?

Terrex is a Python framework for building programmable Terraria agents (bots).

It provides a clean event-driven API for connecting to servers, reacting to world state,
parsing packets and executing scripted behaviors.

Originally inspired by an archived [TerraBot](https://github.com/flammified/terrabot) project by Alexander Freeman (MIT licensed) (inactive for ~10 years),  
Terrex is a modernized, extended and actively developed fork focused on:

* automation
* simulation
* protocol control
* scalable multi-agent systems

Think of it as a runtime for Terraria agents — not just a bot.

---

## Installation

```bash
pip3 install terrex
````

---

## Core Features

* Connect to Terraria servers as a client
* Full chat interaction
* Event-driven packet handling
* Live world & player state parsing
* Item & tile updates tracking
* Programmatic movement (teleport + control layer)
* Extensible event system for custom logic

---

## Minimal Example

A basic bot that connects to a server and reacts to chat messages:

```python
from terrex import Terrex
from terrex.events import Events

bot = Terrex("127.0.0.1")
events = bot.get_event_manager()

@events.on_event(Events.Chat)
def on_chat(event_id, message):
    print(message)

    if "stop" in message.lower():
        bot.stop()

bot.start()

while bot.client.running:
    pass
```

More examples are available in the `examples/` directory.

---

## Project Philosophy

Terrex is built as an automation engine — not a cheat client.

Primary use cases include:

* programmable agents
* server testing & simulation
* AI experiments
* scripted behaviors
* world interaction automation

Anything else is simply an emergent property.

---

## Contributing

Terrex is under active development and contributions are welcome.

Current high-priority areas:

* NPC packet parsing
* Item interactions & drops
* Player synchronization packets
* Tile placement & world modification
* Movement & physics layer

Packet documentation reference:
[https://github.com/MakStashkevich/terrex/blob/master/docs/packets.md](https://github.com/MakStashkevich/terrex/blob/master/docs/packets.md)

---

## Origins

Terrex is based on a fork of the original [TerraBot](https://github.com/flammified/terrabot) project by Alexander Freeman (MIT licensed) (now archived and unmaintained).
The codebase has been refactored, extended and re-architected for modern Python workflows.

---

## Roadmap (high level)

* stable protocol layer
* multi-agent orchestration
* scripting behaviors (FSM / behavior trees)
* performance scaling
* cleaner API surface
