empire-core 0.2.0

Asynchronous Python framework for Goodgame Empire

EmpireCore

Modern async Python library for Goodgame Empire automation

Features • Installation • Quick Start • Examples • Documentation

---

⚠️ Work in Progress

This library is under active development. APIs may change, and some features are incomplete or untested. Use at your own risk.

---

Features

Category	Capabilities
Connection	WebSocket, auto-reconnect, login cooldown handling
State Tracking	Player, castles, resources, buildings, units, movements
Actions	Attacks, transports, recruiting, building, with response validation
Automation	Task loops, multi-account, target finder, map scanner
CLI	Account status, login testing, state summary

Installation

This project uses uv for blazing-fast dependency management.

git clone https://github.com/eschnitzler/EmpireCore.git
cd EmpireCore

# Install dependencies and create venv automatically
uv sync

Traditional Installation (Pip)

python3 -m venv .venv
source .venv/bin/activate
pip install .

Configuration

Create an accounts.json file in the root directory. You can use the provided template:

cp accounts.json.template accounts.json

Then edit accounts.json with your credentials. This file is git-ignored to keep your credentials safe.

Quick Start

import asyncio
from empire_core import accounts

async def main():
    # Load default account from accounts.json
    account = accounts.get_default()
    if not account:
        print("Please configure accounts.json first!")
        return

    # Create client directly from account object
    client = account.get_client()
    
    await client.login()
    await client.get_detailed_castle_info()
    
    player = client.state.local_player
    print(f"{player.name} | Level {player.level} | {player.gold} gold")
    
    await client.close()

asyncio.run(main())

CLI Tool

The library includes a CLI for quick operations:

# Check configured accounts
uv run empire status

# Test login and show player stats
uv run empire login

Running Examples & Tests

# Run the demo
uv run examples/demo.py

# Run unit tests
uv run pytest

Development

We use ruff for linting and mypy for type checking.

# Setup pre-commit hooks
uv run pre-commit install

# Run all checks manually
uv run pre-commit run --all-files

---

_{For educational purposes only. Use responsibly.}