EmpireCore
A fully typed Python client for Goodgame Empire
Documentation · Getting started · Guides · API reference · Changelog
EmpireCore logs in to Goodgame Empire the way the game's own client does, then gives you typed services for your castles, army, commanders, alliance, mail, spies and the world map. Every request and reply is a pydantic model written against the game client's code, every failure is a typed exception, and a background thread keeps a thread-safe picture of your account current while your code runs.
What you get
- Services for the whole game:
client.alliance,castle,army,attack,commanders,equipment,skills,spy,map,movements,messages,player,defense,rankingandevents. - Typed end to end: pydantic v2 models with snake_case fields over the wire
keys, and a
py.typedmarker so your type checker sees them. - Honest failures: one
EmpireErrorbase, no leaked pydantic or socket errors, and no empty list that secretly means "the request failed". - Live, thread-safe state with callbacks for incoming attacks, arrivals and recalls.
- Wave filling from nothing but a target's coordinates, the way the game's "Fill waves" button does it.
- Fast map scans and an account pool for running many accounts.
Install
uv add empire-core # or: pip install empire-core
Python 3.10 or newer.
Quick start
from empire_core import EmpireClient, Kingdom, MapItemType
with EmpireClient(username="your_user", password="your_pass") as client:
client.login()
for castle in client.castle.get_all():
print(f"{castle.castle_name} at ({castle.x}, {castle.y})")
scan = client.map.scan_kingdom(Kingdom.GREEN, item_types=[MapItemType.CASTLE])
print(f"{len(scan.items)} castles, {len(scan.failed_chunks)} chunks failed")
client.state.on_incoming_attack(lambda m: print("incoming from", m.source_player_name))
The getting started guide covers choosing a server, login tokens, reading state and handling errors.
Highlights
- Checked against the game client. Requests follow the client's own command objects, key order included; models cite the client class and line they mirror; and the command ids are checked weekly against the live client.
- Live-verified where the code can't tell. Where the client's code cannot settle what the server does, the library goes by what a live server did and says so, and the docs mark what is still unknown.
- Fast scans. Map requests go out back to back, as the client sends them: a live scan of 289 chunks ran at about 17 requests a second without a refusal. Re-scanning only the chunks that held anything takes roughly a third fewer requests.
Documentation
Everything else lives at https://eschnitzler.github.io/EmpireCore/: a
guide for each part of the game, diagrams of the login and request flow, and an
API reference generated from the source with every model's fields, wire keys
and descriptions. Runnable scripts are in
examples/.
Contributing
Contributions are welcome. See CONTRIBUTING.md for adding protocol commands and services, the model conventions and the tests.
git clone https://github.com/eschnitzler/EmpireCore.git
cd EmpireCore
uv sync --extra dev
uv run pytest
Contact
- 📧 Email: colossusdynamis@gmail.com
- 💬 Discord:
colossus1
Bugs and feature requests are best filed as issues.
MIT licensed. Not affiliated with Goodgame Studios. For educational purposes only; use responsibly.
1 maintainer
Metadata
1 maintainer
Release files for empire-core 0.42.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.42.0.tar.gz | 979.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| empire_core-0.42.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.5 MB
Release files / empire_core-0.42.0.tar.gz
| Download URL | empire_core-0.42.0.tar.gz |
|---|---|
| Size | 979.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d51e2d2110bc08a1df9200009c3216dd90c209f8b99227b1fb512af72a7cc997
|
|
BLAKE2b-256 checksum How to use checksums |
e8e9356bf3919f4c11043656ec6b521576c9769c8fb6e049edb7807b2d696403
|
| 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 Sep 30, 2026.
Transparency logRelease files / empire_core-0.42.0-py3-none-any.whl
| Download URL | empire_core-0.42.0-py3-none-any.whl |
|---|---|
| Size | 520.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5f9daa0ef3a601e0e4b22e8b9f9c2a20cb60740c7186160898e2e545b8860dfa
|
|
BLAKE2b-256 checksum How to use checksums |
af2697c51d4459e710bf988d50e792a00bac8e8f0b5f5f4a9d60ae68da4c7a3d
|
| 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 Sep 30, 2026.
Transparency log
