Ein vollgrafisches Aufbauspiel im Anno-Stil, das sich jede Nacht von einer lokalen KI selbst weiterentwickelt — mit KI-Mitspielern auf der eigenen Weltkarte und asynchronem Online-Multiplayer über GitHub.
Die Spiel-Engine enthält keine einzige hartcodierte Spielmechanik-Instanz — jedes Gebäude, jede Ressource, jede Produktionskette und jedes Zeitalter kommt aus JSON-Content-Packs in data/content/. Nachts analysiert eine lokale KI (Gemma via llama.cpp) den aktuellen Spielstand und erweitert das Spiel eigenständig um neue Inhalte. Der Mensch behält dabei volle Transparenz und Kontrolle.
- Was das Spiel ist
- KI-Mitspieler
- Online-Multiplayer über GitHub
- Mobile & PWA
- Der weitere Zweck der lokalen KI
- Schnellstart
- Architektur
- Die nächtliche KI-Pipeline
- Menschliche Aufsicht & Sicherheit
- Data-driven Content & Grafik
- API
- Konfiguration
- Backup & Restore
- Entwicklung
- Projektstruktur
Idlevolution ist ein isometrisches Idle-/Aufbauspiel im Browser:
- Mehr-Insel-Weltkarte mit prozeduralem Terrain: Wasser, Sandküsten, Gras, Wald und Fels — mit Klippen, Küstenschaum und gemischtem Baumbestand. Die eigene Insel wächst beim Epochenaufstieg in den Ozean hinein.
- Baumodus mit Anno-artigen Platzierungsregeln: Minen brauchen Fels, Fischer brauchen Wasser, Holzfäller brauchen Wald in der Nähe. Grün/Rot-Vorschau, mehrfelder Grundrisse, Gebäude drehen (
R). - Prozedural gezeichnete Gebäude — jeder Typ hat eine eigene Silhouette (Haus, Sägewerk, Mine, Schmelze, Farm, Markt, Turm, Lager …), abgeleitet aus seiner Funktion.
- NPC-Siedler, die zwischen Wohnhaus und Arbeitsstätte pendeln und auf Straßen laufen.
- Straßen & Logistik: Wege bauen (Linksziehen) und abreißen (Rechtsziehen); Straßenanschluss steigert die Produktion.
- Wirtschaft: Produktionsketten (Holz → Bretter → Werkzeuge), Arbeiterzuweisung, Lagerkapazitäten, sichtbare Ketten- und Engpass-Anzeigen.
- Bevölkerungsstufen & Bedürfnisse: Jede Epoche hat eine Bevölkerungsstufe (Jäger & Sammler → Siedler → …) mit Güter-Bedürfnissen, die die Zufriedenheit und damit das Wachstum steuern.
- Schifffahrt & Handel: ⚓ Häfen bauen, Waren per Schiff zu Nachbarinseln schicken, Angebote am 🪙 Marktplatz einstellen und annehmen (mit Treuhand und Schiffs-Lieferung).
- Zeitalter-Fortschritt, Tag/Nacht-Zyklus, Minimap, Offline-Progression.
Und das Wichtigste: Der Inhalt wächst weiter, ohne dass jemand ihn programmiert.
Bis zu 4 zuschaltbare KI-Spieler besiedeln eigene Inseln auf derselben Weltkarte (🌍-Panel) und entwickeln sich in Echtzeit mit — über dieselbe Tick-Engine wie der Mensch:
- Stratege + Taktiker: Die lokale LLM plant einmal täglich Strategie, Bauplan und Persönlichkeit jedes KI-Spielers; ein deterministischer Executor setzt den Plan Tick für Tick um (Arbeiter zuweisen, Ketten bauen, Epochen aufsteigen).
- Nachbarn immer sichtbar: Kamera-Schwenk oder Klick im 🌍-Panel springt zur Insel; Rangliste nach Bevölkerung, Strategie und Chronik je Insel. Fremde Gebäude sind read-only.
- Handel: KI-Spieler bauen Häfen, nehmen faire Angebote an und stellen eigene ein — der Markt belebt sich von selbst.
- ⚔️ Krieg im Tagesrhythmus: Soldaten in der 🛡️ Kaserne ausbilden und tagsüber einen Raubzug erklären — die Schlacht schlägt sich beim nächtlichen KI-Lauf (fair gegenüber der Tageszug-KI). Der Sieger plündert Beute (max. 25 % je Vorrat), Inseln wechseln nie den Besitzer. Verteidigt wird mit Soldaten, 🗼 Wehrtürmen und Miliz; angegriffene KI schwört Vergeltung für die nächste Nacht.
Roadmap & Details: docs/roadmap-ki-spieler.md — alle 6 Stufen umgesetzt.
Asynchroner Multiplayer ohne eigenen Server — GitHub ist Speicher, Login und Prüf-Instanz. Community-Repo: idlevolution-online.
- Opt-in mit Disclaimer: Ohne „Mit GitHub verbinden" (Device Flow, kein Passwort im Spiel) und explizite Freigabe-Zustimmung („auf eigene Gefahr, keine Haftung") verlässt kein Byte den eigenen Rechner.
- Insel veröffentlichen: Die eigene Insel (Karte, Gebäude, Straßen) und die eigenen LLM-generierten Inhalte werden als Pull Request hochgeladen — IDs global genamespaced (
gh-<user>--…), Sprite-Farben eingefroren. Eine GitHub Action prüft jeden PR (Pfad-Schutz, Schema, Limits) und merged automatisch. Läuft nach der ersten Freigabe nächtlich mit. - Nachbarn besuchen: Fremde Inseln werden tokenlos synchronisiert, streng validiert, isoliert abgelegt und lassen sich read-only besuchen — inklusive der fremden, prozedural gezeichneten LLM-Gebäude in Originaloptik.
- ✨ Inhalte übernehmen: Die LLM-Baupläne eines Nachbarn lassen sich per Klick ins eigene Spiel importieren — sie werden ein normales, in der 🤖-Zentrale deaktivierbares Content-Pack. So wandern KI-Erfindungen von Welt zu Welt.
- 🌐 Online-Handel: Angebote im 🪙-Markt für andere Spieler veröffentlichen und fremde annehmen (⚖️ Fairness-Einschätzung nach Warenwert). Abwicklung asynchron über einen Treuhand-Handshake beim nächsten Sync beider Seiten — Doppel-Annahmen und Stornos werden sauber erstattet.
- 🚪 Offline gehen: entfernt die eigenen Daten jederzeit per Pull Request aus dem Community-Repo.
Konzept: docs/roadmap-multiplayer.md · Fortschritt: docs/multiplayer_roadmap.md.
Idlevolution ist am Smartphone spielbar (Querformat), ohne dass sich die Desktop-Optik ändert:
- Touch-Steuerung: Ein Finger schwenkt, zwei Finger zoomen (Pinch); Bauen per zentriertem Fadenkreuz mit ✓-Bestätigung, 🧹-Radiermodus statt Rechtsklick.
- Mobile-HUD: Bau-Dock unten, Menü-FABs, Panels als Bottom-Sheets, antippbare Ressourcen-Aufschlüsselung.
- Installierbar als PWA: Homescreen-Icon, Fullscreen im Querformat (Android-Install-Prompt braucht HTTPS).
Zum Testen am Desktop: ?mobile=1 an die URL hängen.
Ursprünglich war die lokale KI nur ein „Content-Generator". Mit den eingebauten Aufsichts- und Sicherheitswerkzeugen erfüllt sie ab jetzt eine erweiterte Rolle:
Die KI ist kein einmaliger Generator, sondern ein dauerhaft laufender, autonomer Designer. Jede Nacht:
- liest sie den echten Siedlungs-Status (Lücken, Engpässe, Terrain-Verteilung, Zufriedenheit, bisherige Ablehnungen),
- erfindet passende neue Ressourcen, Gebäude, Produktionsketten, Bevölkerungsstufen und ganze Zeitalter,
- und bestimmt dabei selbst deren Aussehen (über
meta.art) und deren Platzierungslogik (Terrain/Nachbarschaft) — vollständig data-driven, ohne dass die Engine das jeweilige Gebäude kennen muss.
Das Spiel ist damit nie „fertig". Es ist ein lebendiges System, das sich Woche für Woche in Richtungen entwickelt, die niemand vorher festgelegt hat.
Jeder Lauf wird protokolliert. Abgelehnte Pakete und ihre Gründe fließen in den nächsten Prompt zurück — die KI lernt aus ihren Fehlern und wiederholt sie seltener. Balancing-Grenzen, Erreichbarkeits- und Sandbox-Prüfungen wirken wie ein ständiger Lektor.
Der eigentliche, weiterreichende Zweck: Idlevolution demonstriert, wie ein lokales Sprachmodell ein reales, laufendes System offen und unbegrenzt weiterentwickeln kann — ohne die Kontrolle zu verlieren.
- Kein hartcodierter Inhalt → die KI hat echten Gestaltungsspielraum.
- Mehrstufige Sicherheitsprüfung → sie kann das System nicht kaputt machen (Struktur, Referenzen, Balancing, Soft-Lock-Wächter, 1000-Tick-Sandbox).
- Volle Transparenz → jeder Eingriff ist nachvollziehbar (KI-Protokoll, Chronik).
- Jederzeit rückholbar → einzelne Erweiterungen lassen sich per Klick zurückrollen, der Gesamtzustand per Backup wiederherstellen.
Die Rolle des Menschen verschiebt sich damit vom Autor zum Kurator: nicht mehr Inhalte schreiben, sondern die nächtliche Entwicklung sichten, gutheißen oder gelegentlich einen Ausreißer zurücknehmen. Idlevolution ist in diesem Sinne ein kleines, greifbares Modell für beaufsichtigte, autonome KI-getriebene Weiterentwicklung von Software.
Voraussetzungen: Docker + Docker Compose, sowie ein erreichbarer OpenAI-kompatibler LLM-Endpunkt (z. B. llama.cpp / llama-swap mit einem Gemma-Modell).
cp .env.example .env # Passwörter, AI_IMPORT_TOKEN und LLM_BASE_URL setzen
docker compose up -d --build
# → Spiel öffnen: http://localhost:8420KI-Generierung manuell auslösen (statt auf den nächtlichen Cron zu warten):
./scripts/generate-now.shDrei Container, klare Trennung von Code, dynamischem Zustand und Inhalt:
| Service | Aufgabe |
|---|---|
app |
Fastify-Backend (Node 20, ESM) + gebautes Svelte-4-UI. Lädt die Content-Packs, führt die Tick-Simulation aus, dient die API und persistiert den Spielstand in PostgreSQL. |
db |
PostgreSQL 16 — nur dynamischer Zustand (Bestände, platzierte Gebäude, Straßen, Epoche, Audit-Log). Content-Definitionen bleiben Dateien. |
ai-worker |
Cron-Scheduler (AI_CRON, Standard 03:00). Holt den Siedlungs-Status, ruft das LLM und reicht das Ergebnis über die API zum Import ein. |
- Stack: Fastify · PostgreSQL 16 · Svelte 4 + Tailwind 3 · Canvas-Rendering (kein WebGL nötig) · Node-Test-Runner.
- Datenfluss der Inhalte: ausschließlich Dateien →
applädt & merged sie →/api/content→ das UI rendert nur, was hier ankommt.
┌─────────────── ai-worker (Cron 03:00) ───────────────┐
│ │
GET /api/ai/export │ Siedlungs-Status ──► Prompt ──► gemma4-12b │
(Lücken, Raten, │ ▲ │ │
Zufriedenheit, │ │ JSON-Pack │
letzte Ablehnungen)│ │ │ │
└────────┼──────────────────────────────────┼─────────┘
│ ▼
│ POST /api/ai/import
Feedback-Schleife ────┘ │
▼
Hot-Reload ◄── Datei speichern ◄── Sandbox ◄── Soft-Lock ◄── Balancing ◄── Referenzen ◄── Struktur
(Registry) (data/content/ (1000 -Wächter (Clamping/ (IDs, (JSON-
generated/) Ticks) Ablehnung) Kollisionen) Schema)
Die KI kann komplett neue Ressourcen, Gebäude (inkl. Grafik und Platzierung), Produktionsketten, Bevölkerungsstufen mit Bedürfnissen und ganze Zeitalter einführen. Über epochAdvance liefert sie die Aufstiegsbedingung einer bisher finalen Epoche nach, damit neue Zeitalter erreichbar bleiben.
- Struktur — JSON-Schema-Validierung (ajv).
- Referenzen — alle IDs existieren, keine Kollisionen mit Bestand.
- Normalisierung — fehlendes
placement/meta.art/needs/tierwird sicher ergänzt (z. B. Mine→Fels, Fischer→Wasser; Bedürfnis nur mit vorhandenem Produzenten). - Balancing (
data/balance.config.json) — kein Perpetuum mobile, Netto-Wertschöpfung ≤ Arbeiter×Grenzwert, max. +25 % über bestem Bestandsgebäude, Mindest-Amortisation. Werte werden wo möglich gekappt statt abgelehnt. - Soft-Lock-Wächter — lehnt Pakete ab, die einen neuen Fortschritts-Blocker einführen (unerreichbare Epoche, Bedürfnis/Input ohne Produzenten).
- Sandbox — 1000 Ticks Simulation gegen eine Kopie des Spielstands (fängt Exponential-Explosionen und NaN).
Abgelehntes landet mit Begründung in data/rejected/; jeder Lauf wird in der Tabelle ai_runs protokolliert.
Damit die nächtliche Autonomie vertrauenswürdig bleibt, gibt es im Spiel die KI-Zentrale (🤖-Button):
- Chronik — die erzählerischen Tagesberichte der KI.
- Läufe — jeder nächtliche Lauf mit Status, hinzugefügten Inhalten und konkreten Ablehnungsgründen.
- Inhalte — jedes generierte Pack lässt sich per Klick deaktivieren (Datei wird herausgenommen, Hot-Reload, verwaiste Gebäude werden aufgeräumt). Basis-Packs sind geschützt.
Zusätzlich:
- „Über Nacht erweitert" — beim Laden eine Zusammenfassung, was die KI seit dem letzten Besuch hinzugefügt hat.
- Backup/Restore — Spielzustand und generierte Inhalte lassen sich rotierend sichern und wiederherstellen (siehe unten).
base/— Start-Inhalte (vom Menschen gepflegt, nummeriert für die Ladereihenfolge).generated/<datum>/— von der KI erzeugte Packs.disabled/— vom Nutzer deaktivierte Packs (werden nicht geladen).- Schemas:
server/src/content/schemas/*.schema.json.
Ein Pack sieht so aus:
Es gibt keine Sprite-Dateien. Jedes Gebäude wird prozedural auf einem Canvas gezeichnet:
- Ein Klassifikator leitet den Zeichen-Archetyp aus der Funktion des Gebäudes ab (Produktions-Outputs, Name-Schlüsselwörter). Erfindet die KI z. B. eine „Bronzeschmelze", bekommt sie automatisch eine Schmelzhütten-Silhouette mit glühendem Schornstein.
- Über
meta.artkann die KI das Aussehen explizit steuern:shape(house, farm, mine, smelter, sawmill, fishery, market, temple, tower, warehouse …),accent,wall,roof. - Material folgt der Epoche, Variation der Gebäude-ID.
So kann die KI für neue Zeitalter neue Materialien, Gegenstände, Gebäude und Optik einführen — ohne dass irgendwo Grafik-Code angefasst werden muss.
| Route | Beschreibung |
|---|---|
GET /api/content |
Gemergte Content-Definitionen (das UI rendert ausschließlich diese) |
GET /api/state |
Spielzustand: Bestände, Raten, Freischaltungen, Epoche/Stufe/Bedürfnisse, Zufriedenheit, Logistik |
GET /api/map |
Statische Weltkarte (Terrain) |
POST /api/build {buildingId, x, y, rot?} |
Gebäude platzieren |
POST /api/demolish {instanceId} |
Gebäude abreißen (50 % Kostenerstattung) |
POST /api/rotate {instanceId} |
Gebäude um 90° drehen |
POST /api/workers {buildingId, delta} |
Arbeiter zuweisen |
POST /api/road {tiles, on} |
Straßen bauen/abreißen |
GET /api/players · `POST /api/players/enable |
disable` |
POST /api/ship {toIsland, resourceId, amount} |
Ware per Schiff zu einer Nachbarinsel |
POST /api/attack {targetIsland, soldiers} · POST /api/attack/cancel |
Raubzug erklären / zurückziehen (Schlacht beim nächtlichen KI-Lauf) |
GET /api/market · `POST /api/market/offer |
accept |
POST /api/online/connect · GET /api/online/status |
GitHub-Login (Device Flow) für den Online-Modus |
POST /api/online/publish |
Eigene Insel + LLM-Packs als PR ins Community-Repo |
POST /api/online/sync · GET /api/online/neighbors |
Online-Inseln laden / auflisten (tokenlos) |
GET /api/online/island/:owner · POST /api/online/adopt |
Nachbar-Insel besuchen / dessen Inhalte übernehmen |
GET /api/ai-log |
KI-Lauf-Protokoll (öffentlich, für die KI-Zentrale) |
POST /api/pack/disable {packId} |
Generiertes Pack deaktivieren + aufräumen |
GET /api/ai/export 🔒 |
Siedlungs-Status für die KI (Bearer AI_IMPORT_TOKEN) |
POST /api/ai/import 🔒 |
Pack einreichen → prüfen → balancen → Hot-Reload |
GET /api/ai/runs 🔒 |
Lauf-Protokoll (token-geschützt) |
🔒 = nur mit AI_IMPORT_TOKEN (Bearer). Diese Routen darf ausschließlich der ai-worker aufrufen.
Alles über .env (siehe .env.example):
| Variable | Bedeutung |
|---|---|
APP_PORT |
Port des Spiels (Standard 8420) |
POSTGRES_* |
Datenbank-Zugang |
AI_IMPORT_TOKEN |
Token, mit dem der ai-worker /api/ai/* aufruft |
TICK_SECONDS |
Länge eines Simulations-Ticks |
PERSIST_EVERY_TICKS |
Speicherintervall |
OFFLINE_CAP_HOURS |
Maximal nachgeholte Offline-Progression |
LLM_BASE_URL / LLM_MODEL |
OpenAI-kompatibler LLM-Endpunkt + Modell |
LLM_CTX / LLM_MAX_TOKENS / LLM_TEMPERATURE |
LLM-Parameter |
AI_CRON |
Zeitplan der nächtlichen Generierung (Cron-Syntax) |
AI_RUN_ON_START |
Sofortlauf beim Start (Debug) |
ONLINE_CLIENT_ID |
GitHub-OAuth-App-Client-ID für den Online-Modus (öffentlich, Standard gesetzt) |
ONLINE_REPO |
Community-Repo des Online-Modus (Standard bmetallica/idlevolution-online) |
./scripts/backup.sh # → data/backups/<timestamp>/ (db.sql.gz + content.tar.gz)
./scripts/restore.sh data/backups/<...> # Zustand + Inhalte zurückspielenDas Backup rotiert (BACKUP_KEEP, Standard 14). Empfohlen als Host-Cron vor der nächtlichen KI-Generierung:
55 2 * * * cd /opt/Idlevolution && ./scripts/backup.sh >> data/backups/backup.log 2>&1cd server && npm install && npm test # 64 Unit-Tests (Validator, Balancer, Engine, Welt/Inseln, Schiffe, Handel, Krieg, Online)
cd web && npm install && npm run dev # Vite-Dev-Server mit API-Proxy auf :8420- Engine-Tests laden bewusst nur
base-Content (loadRegistry(dir, log, { includeGenerated: false })) → deterministisch, unabhängig davon, was die KI generiert hat. - Rendering ist reines Canvas-2D mit Offscreen-Sprite-Cache (
createImageBitmap) — läuft flüssig ohne GPU-Zwang.
data/
balance.config.json # Spiel-Grundwerte + Balancing-Grenzen
content/base/ # Start-Inhalte (Mensch)
content/generated/<datum>/ # KI-Inhalte
content/disabled/ # deaktivierte Packs
rejected/ # abgelehnte KI-Pakete (mit Begründung)
backups/ # Backups (backup.sh)
server/
src/engine/ # Tick-Simulation, Welt/Inseln, Schiffe, Handel, Regeln, Zustand
src/content/ # Loader, Validator, Balancer, Schemas
src/ai/ # Export, Generator (Prompt), Importer, Scheduler, KI-Spieler (Stratege/Executor)
src/online/ # Online-Modus: Auth (Device Flow), Exporter, Sync, Validierung, Übernahme
src/routes/ # game / content / ai / online
src/db/migrations/ # SQL-Migrationen
test/ # Node-Test-Runner
web/
src/components/ # IsoMap, BuildPalette, EpochBanner, InfoPanel, OnlineSection, Chronicle …
src/lib/ # sprites, iso, npc, chains, placement, device (Mobile), api
public/ # PWA: manifest, Service-Worker, Icon
scripts/ # generate-now / backup / restore
docs/ # Screenshots + Roadmaps (KI-Spieler, Multiplayer)
Idlevolution — ein Spiel, das nie fertig wird, weil es sich jede Nacht selbst weiterschreibt.


{ "schemaVersion": 1, "pack": { "id": "ai-2026-07-05-abcd", "source": "ai" }, "chronicle": { "de": "Die ersten Schmelzöfen erhellen die Nacht …" }, "resources": [{ "id": "copper_ingot", "category": "processed", "epoch": "bronze_age", "baseValue": 8, "... ": "..." }], "buildings": [{ "id": "smelter", "category": "production", "epoch": "bronze_age", "production": { "inputs": { "copper_ore": 0.6 }, "outputs": { "copper_ingot": 0.24 } }, "placement": { "terrain": ["rock"], "adjacent": { "rock": 1 }, "size": { "w": 2, "h": 1 } }, "meta": { "art": { "shape": "smelter", "accent": "#ff4500" } } }], "epochs": [{ "id": "iron_age", "order": 2, "tier": { "name": { "de": "Eisenarbeiter" } }, "needs": { "steel": 0.01 } }], "epochAdvance": { "bronze_age": { "resources": { "copper_ingot": 0.02 }, "population": 20 } } }