Programmable automation client for Terraria servers.
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 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.
pip3 install terrex- 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
A basic bot that connects to a server and reacts to chat messages:
import asyncio
from terrex import Terrex
from terrex.event.filter import NewMessage
from terrex.event.types import ChatEvent
async def main() -> None:
async with Terrex("127.0.0.1", 7777) as client:
@client.on(NewMessage())
async def on_chat(event: ChatEvent) -> None:
print(event.text)
if "stop" in event.text.lower():
await client.stop()
await client.run_until_disconnected()
if __name__ == "__main__":
asyncio.run(main())More examples are available in the examples/ directory.
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.
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
Terrex is based on a fork of the original TerraBot project by Alexander Freeman (MIT licensed) (now archived and unmaintained). The codebase has been refactored, extended and re-architected for modern Python workflows.
- stable protocol layer
- multi-agent orchestration
- scripting behaviors (FSM / behavior trees)
- performance scaling
- cleaner API surface