empire-core 0.58.0

A fully typed Python client for Goodgame Empire.

EmpireCore lets Python code play Goodgame Empire the way the game's own client does. Log in, read your account and castles, react to incoming attacks and other events as they happen, send armies and spies, and run several accounts side by side.

Why EmpireCore

• Fully typed. Every request and reply is a pydantic model with readable field names, so your editor completes them and your type checker checks them.
• Behaves like the real game client. Logins, requests and their checks follow the game's own client code, so the server sees what it expects.
• Live state and events. A background thread keeps your account's state current. Register callbacks, or stream events with asyncio.
• Built to keep running. keep_session logs back in after a dropped connection, and AccountPool shares several logged-in accounts across threads.

What it covers

Install

uv add empire-core        # or: pip install empire-core

Python 3.10 or newer.

For an interactive console on a live client, with completion and a live view of every socket frame, install the console extra and run empire-console (Linux and macOS; untested on Windows):

pip install 'empire-core[console]'
empire-console                    # asks for the username and password; --zone for another world

Quick start

import time

from empire_core import EmpireClient, Movement


def warn(attack: Movement) -> None:
    print(f"Attack from {attack.source_player_name}, "
          f"landing in {attack.time_remaining}s")


with EmpireClient(
    username="you", password="...", keep_session=True
) as client:
    client.login()

    for castle in client.castle.get_all():
        res = client.castle.get_resources(castle.castle_id)
        print(f"{castle.castle_name}: {res.wood:,} wood, "
              f"{res.stone:,} stone, {res.food:,} food")

    client.state.on_incoming_attack(warn)
    time.sleep(3600)

Documentation: https://eschnitzler.github.io/EmpireCore/, with a guide for each part of the game and the full API reference.

Contributing

Contributions are welcome; see CONTRIBUTING.md. Bugs and feature requests are best filed as issues.

Contact

• Email: colossusdynamis@gmail.com
• Discord: colossus1

_{MIT licensed. Not affiliated with Goodgame Studios. For educational purposes only; use responsibly.}