# Hercules Pyloaded – Hinweise für Claude

Python-Neubau des PHP-Browsergames Hercules. Die Altversionen liegen unverändert daneben
(`../v001-warpman`, `../v002-hercules-reload`, `../v003-hercules-rereload`) und dienen nur als
Quelle für Spielideen und Balancing-Werte; Code wird nicht übernommen.

Konzept: https://claude.ai/code/artifact/745bf02e-46d7-4087-9f78-d941c55997f1 (Claude Doc,
mit den Docs-Werkzeugen lesen). Vor größeren Änderungen an Spielregeln dort nachsehen.

## Befehle

uv ist nicht im PATH, daher immer `python -m uv run …`:

- Tests: `python -m uv run pytest`
- Lint/Format: `python -m uv run ruff check` / `python -m uv run ruff format`
- Typen: `python -m uv run mypy`
- Server: `python -m uv run python manage.py runserver`

## Architekturregeln

- `src/engine/` ist reines Python ohne Django-Import, `mypy --strict`, jede Formel hat Tests.
- Views rufen Services auf; Services laden Daten, rufen die Engine, schreiben in einer Transaktion.
- Erweiterbarkeit ist eine harte Anforderung: neue Rohstoffe, Gebäude, Forschungen, Rumpfe und
  Bauteile nur über Daten (`data/*.yaml`), nie über neue Spalten oder Code. Keine Spalte pro
  Rohstoff oder Gebäude; Verweise nur über stabile Text-Schlüssel (`titan`, `zentrale`).
- Wirkungen von Gebäuden und Forschung laufen über das Effekt-System; neuer Code nur für eine
  neue Effekt-Art.
- Wachstum exponentiell, Parameter pro Eintrag in den Stammdaten.
- Zeitgesteuertes über die Event-Queue (`run_worker`); Rohstoffe werden beim Lesen hochgerechnet.
- Einstellungen nur über Umgebungsvariablen (`src/config/settings.py`, `.env.example`).

## Sprache

Oberfläche, Kommentare, Docstrings und Commit-Nachrichten auf Deutsch. Code-Bezeichner
(Klassen, Funktionen, Variablen) auf Englisch.

## Repository

Gitea: https://git.pertl-ing.de/ (privat). Push nur nach Freigabe durch den User.