A fully typed Python client for Goodgame Empire.
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.
- Fast. One account scans the Green kingdom's roughly 8,900 castles in 15 to 17 seconds; split across 8 accounts, it takes 2.9 seconds.
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.player, ranking, events |
Players, highscores and events |
Install
uv add empire-core # or: pip install empire-core
Python 3.10 or newer. EmpireCore is pre-1.0, so a minor release may change the API; the changelog lists every change that does.
Quick start
from empire_core import EmpireClient, Kingdom, MapItemType
with EmpireClient(username="you", password="...") as client:
client.login()
castles = client.castle.get_all()
print(f"{len(castles)} castle(s)")
scan = client.map.scan_kingdom(Kingdom.GREEN, item_types=[MapItemType.CASTLE])
print(f"Green kingdom: {len(scan.items):,} castles")
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.46.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.46.0.tar.gz | 1.3 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| empire_core-0.46.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.9 MB
Release files / empire_core-0.46.0.tar.gz
| Download URL | empire_core-0.46.0.tar.gz |
|---|---|
| Size | 1.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
759c471e1b589c0a36c92efc9956bb0b76c7f5d625b7c70c326d61e9437f43e1
|
|
BLAKE2b-256 checksum How to use checksums |
fd5e50d958e547c1b60b8cd5a552641873583af9d49018ff47914e326b287cc4
|
| 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 5, 2026.
Transparency logRelease files / empire_core-0.46.0-py3-none-any.whl
| Download URL | empire_core-0.46.0-py3-none-any.whl |
|---|---|
| Size | 610.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ac616102a22371600295b1e485123ea16bd52ed2cc1fb897fb89b0c40bd2f68b
|
|
BLAKE2b-256 checksum How to use checksums |
9cff83e2a949ac2061f4c7cc5d93052d4238d5fab99ae74b502a99b8d9b5c922
|
| 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 5, 2026.
Transparency log
