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_sessionlogs back in after a dropped connection, andAccountPoolshares several logged-in accounts across threads.
What it covers
| Service | What it does |
|---|---|
client.castle |
Castles, buildings, resources, horses, tax, sending goods and troops |
client.army |
Units, recruitment and the hospital |
client.attack |
Sending attacks, attack presets, and filling waves like the game does |
client.commanders |
Commanders and castellans |
client.skills |
Generals, abilities and skill trees |
client.equipment |
The equipment inventory |
client.spy |
Spy missions, sabotage and spy reports |
client.map |
Kingdom scans and map lookups |
client.movements |
Army movements, recalls and incoming attacks |
client.alliance |
Chat, help requests, members and the treasury |
client.messages |
The mailbox, mail and battle reports |
client.defense |
Reading and setting castle defense |
client.rewards |
The free daily rewards |
client.player, ranking, events |
Players, highscores and events |
Install
uv add empire-core # or: pip install empire-core
Python 3.10 or newer.
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.
1 maintainer
Metadata
1 maintainer
Release files for empire-core 0.50.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| empire_core-0.50.0.tar.gz | 1.6 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| empire_core-0.50.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.4 MB
Release files / empire_core-0.50.0.tar.gz
| Download URL | empire_core-0.50.0.tar.gz |
|---|---|
| Size | 1.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4a112b33e2202cc4f984a8b3387d28970f7adc83758daaa089419baa69f2e4b6
|
|
BLAKE2b-256 checksum How to use checksums |
21db1d134342ec19d35ab8bc80ffcbd04ea25151745723bc8b25cb3efdae809f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.
Transparency logRelease files / empire_core-0.50.0-py3-none-any.whl
| Download URL | empire_core-0.50.0-py3-none-any.whl |
|---|---|
| Size | 807.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3b3cda3524d442f6eff20e4713171afd114e9881d29e9bc656f8cee4a65ccac0
|
|
BLAKE2b-256 checksum How to use checksums |
e5267fb5d183c76621cc18f97a7eb89a1423b57181860d16118721983a2f193a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.
Transparency log
