From c2fe5c23f11d9cb7ddd5e344293cf54987c5808d Mon Sep 17 00:00:00 2001 From: madgerm Date: Tue, 3 Feb 2026 01:19:43 +0100 Subject: [PATCH] Add AGENTS guidance referencing SSOT --- AGENTS.md | 21 +++ docs/game_rulebook.md | 384 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 405 insertions(+) create mode 100644 AGENTS.md create mode 100644 docs/game_rulebook.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..9059d14 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,21 @@ +# AGENTS (Repository Guidance) + +## Repository Intent +- The `web/desktop` and `web/mobile` folders host the live HUD demo (Desktop and mobile). Keep everything that should be served from a webserver inside those folders. +- `docs/game_rulebook.md` is the **Single Source of Truth (SSOT)** for Galaxy Forge’s game logic, builder system, resources, and requirements. Any UI work, game behavior, or rules must align with — not contradict — that document unless a new decision is logged. +- `docs/` stores documentation while `planning/` holds sketches/notes that are not meant for deployment. + +## Key Instructions for Agents +1. **Reference SSOT first.** When implementing features or answering questions related to game balance, resources, blueprints, buildings, or world generation, open `docs/game_rulebook.md` and confirm compliance. Note any missing detail needs a Decision Log entry (see section 13). +2. **Respect folder intent.** Changes to web assets go in `web/desktop` or `web/mobile` only. Use `planning/` for drafts and `docs/` for textual explanations. +3. **Document assumptions.** If you must deviate from `docs/game_rulebook.md`, append an entry to the Decision Log (section 13) explaining the why/when. +4. **Keep mobile/desktop aligned.** When adjusting UI/partials, mirror updates in both `web/desktop` and `web/mobile` unless the change is explicitly mobile-only or desktop-only and documented. + +## When touching docs +- Expand `docs/game_rulebook.md` if you update core rules, flow, or systems described there. Keep numbering/sections intact; append entries in the Decision Log (section 13) with dates. +- The root `README.md` should mention where to find the SSOT and purpose of each folder. + +## Decision Log Reminder +- Section 13 of `docs/game_rulebook.md` is the Decision Log. Add a dated entry whenever: + - You introduce a new rule variant or exception. + - The implementation deviates from the documented defaults. diff --git a/docs/game_rulebook.md b/docs/game_rulebook.md new file mode 100644 index 0000000..ef15d22 --- /dev/null +++ b/docs/game_rulebook.md @@ -0,0 +1,384 @@ +# Galaxy Forge — game_rulebook.md (SSOT) v1.0 +*Single Source of Truth für Game-Logik, Baukasten-Systeme und Generator-Regeln* + +--- + +## 0) Zweck & Arbeitsweise (SSOT) +Dieses Dokument ist die **Single Source of Truth (SSOT)**. +**Codex/Entwicklung darf nichts implementieren, was dem widerspricht.** + +**Wenn etwas fehlt oder unklar ist:** +1) **Default-Regeln** in diesem Dokument anwenden, +2) Entscheidung im **Decision Log** (am Ende) festhalten, +3) danach erst implementieren. + +--- + +## 1) High-Level Vision +Galaxy Forge ist ein persistentes Weltraum-Browsergame, dessen Inhalte **datengetrieben** sind: +- Spieler (und später ggf. User-Designer) erstellen **Blueprints** (Gebäude, Schiffe, Forschung, Rassen, Spezialisierungen) über einen **Baukasten**. +- Blueprints bestehen aus **Capabilities (Flags)**, **Effects (standardisierte Bausteine)**, **Requirements**, **Access Rules**. +- Balance soll möglichst **automatisch** über ein **Punkte-/Budget-System** + **Auto-Cost** funktionieren, um Admin-Aufwand zu minimieren. + +--- + +## 2) Kernbegriffe + +### 2.1 Blueprint (universell) +Ein Blueprint ist ein datengetriebenes Objekt mit einheitlichem Schema: + +- `kind`: `building | ship | research | race | specialization | space_object` (erweiterbar) +- `key`: eindeutiger String +- `name`: Anzeigename +- `tags`: freie Taxonomie-Strings +- `capabilities`: freie Taxonomie-Strings (Flags) +- `effects`: Liste standardisierter Effekt-Bausteine (kleine, feste Bibliothek) +- `requirements`: Liste standardisierter Requirements (kleine, feste Bibliothek) +- `access`: Whitelist/Blacklist nach Race/Specialization (und später ggf. weitere Dimensionen) +- `balance`: Budget/Punkte/Auto-Cost (für usergenerierte Inhalte) + +**Wichtig:** Neue Tags/Capabilities/Blueprints müssen ohne Codeänderung möglich sein. +Neue **Effect-Typen** oder **Requirement-Typen** erfordern ggf. Code (Engine-Erweiterung) und sind bewusst klein zu halten. + +--- + +## 3) Ressourcenmodell + +### 3.1 Ressourcenarten (SSOT) +Galaxy Forge verwendet diese Ressourcen (erweiterbar, aber stabil halten): +- `metal` (Metall) +- `alloy` (Legierung) +- `crystals` (Kristalle) +- `energy` (Energie) +- `credits` (Credits) +- `population` (Einwohner) +- `water` (Wasser) +- `deuterium` (Deuterium) +- `food` (Nahrungsgüter) + +### 3.2 Zeitbasierte Simulation (serverseitig, authoritative) +Der Server speichert pro Planet: +- aktuelle Mengen pro Ressource +- `last_resource_update_at` + +Beim Lesen oder bei Aktionen (Bauen, Abholen, Missionen etc.) muss der Server Ressourcen **nachziehen**: + +1) `dt = now - last_resource_update_at` +2) `net_rates_per_hour = calc_net_rates(planet)` (Produktion − Verbrauch, inkl. Drossel) +3) `amount += net_rates * dt/3600` +4) optional: clamping auf `0..cap` (siehe 3.3) +5) `last_resource_update_at = now` + +### 3.3 Caps (Speicherlimits) +Caps sind optional pro Ressource und entstehen über Effects (z.B. `capacity_add`). +Wenn Cap für eine Ressource nicht definiert ist, gilt `cap = infinity` (Default). +Caps dürfen auch für `energy` existieren (Batterien). + +--- + +## 4) Multiplikatoren-System (Planet + Race + Spec + Research + …) + +### 4.1 Grundsatz +Blueprints definieren **Grundwerte** (z.B. Mine produziert 50/h). +Der tatsächliche Effekt entsteht durch eine **Multiplikator-Kette**. + +Für eine Ressource `r` gilt: + +`effective_value(r) = base_value(r) × Π (1 + bonus_i(r))` + +- +10% = `+0.10`, −15% = `−0.15` +- Multiplikation ist Absicht (Synergien, komplexeres Wirtschaften) + +### 4.2 Quellen der Boni (Standard-Kette) +Boni werden gesammelt (Reihenfolge nur für Debug/Anzeige): +1) Planet (konkrete Planet-Modifier) +2) Race (Rassenmodifier) +3) Specialization (Spezialisierungsmodifier) +4) Research (Forschungsmodifier) +5) optional später: Events, Artefakte, Offiziere, Allianzboni … + +### 4.3 Separate Behandlung von Produktion & Verbrauch +- Produktion (`produce`, `convert outputs`) und Verbrauch (`consume`, `convert inputs`) können getrennte Boni haben. +- Default: Wenn kein spezieller Bonus existiert, wirkt ein Bonus nur auf das passende Feld (prod vs consume). + +### 4.4 Debug-Breakdown (Pflicht für UI) +Die UI soll optional einen Breakdown anzeigen: +- Base +- Planet +- Race +- Spec +- Research +- Result + +Das ist essenziell für Transparenz & Balancing. + +--- + +## 5) Weltmodell & Space Objects + +### 5.1 Koordinaten +Koordinaten sind `galaxy:system:position` (G:S:P). + +### 5.2 Space Objects (Mehrfachobjekte pro Koordinate) +An einer Koordinate können mehrere Space Objects existieren: +- planet +- wormhole +- blackhole +- station +- anomaly +- mission_marker +- debris_field +- beacon +- … (erweiterbar) + +Ein Planet ist ein Space Object vom Typ `planet`. + +### 5.3 Targeting für Flotten/Missionen +Ein Ziel kann sein: +- `target_object_id` (bevorzugt) oder +- `(coords + target_type)` + +Dadurch kann die UI z.B. „anfliegen: Planet / Wurmloch / Station“ auswählen. + +--- + +## 6) Planetklassen & Universum-Generator (Constraints + Budget) + +### 6.1 Planetklasse ist „Vorgabe-Regelwerk“ +Planetklassen (ice/desert/rock/…) geben dem Generator: +- **Constraints (MUSS):** harte Min/Max-Bedingungen für bestimmte Resource-Modifier +- **Bias (SOLL):** Verteilungspräferenzen, welche Ressourcen eher hoch/runter gehen + +Beispiel (Ice): +- water immer >= +50% +- energy immer <= −60% + +### 6.2 Planet-Modifier werden pro Planet gezogen und sind stabil +Jeder Planet hat: +- `planet_class_key` +- `planet_seed` +- **konkrete** Modifier-Werte pro Ressource (werden gespeichert) + +Warum speichern? +- Balancing-Änderungen sollen nicht rückwirkend alte Planeten verändern. + +### 6.3 Budget-/Score-System für Vergleichbarkeit +Planeten sollen trotz Spezialisierung **vergleichbar** sein. + +Definiere: +- Gewichte `W[r]` pro Ressource (Wertigkeit) +- Modifier `m[r]` pro Ressource (z.B. +2.0 = +200%, −1.0 = −100%) +- Planet-Score `S = Σ(W[r] × m[r])` + +Jeder Planet gehört zu einem Tier mit `target_score`: +- normal: `S ≈ 0` +- rich: `S ≈ +0.4` +- legendary: `S ≈ +1.0` +(Spawnwahrscheinlichkeiten per weight) + +**Generator-Regel:** +Nach Anwenden der Klassen-Constraints werden die restlichen Modifier so ergänzt/justiert, dass `S` im Zielbereich liegt (epsilon). + +### 6.4 Ablauf Planetgenerierung (deterministisch) +1) planet_class anhand spawn_weight wählen +2) alle `m[r] = 0` initialisieren +3) Constraints anwenden (min/max + ggf. random within range) +4) aktuellen Score S berechnen +5) Rest-Modifier verteilen (unter Einhaltung globaler Bounds + Bias), bis Zielscore erreicht +6) Falls unmöglich: re-roll oder Tier wechseln (SSOT-Default: re-roll bis max N; dann Tier switch) + +--- + +## 7) Baukasten-System: Capabilities, Effects, Requirements, Access + +### 7.1 Capabilities (Flags) — frei erweiterbar (Formular-Add) +Capabilities sind freie Strings, z.B.: +- `menu:research` +- `menu:bank` +- `menu:spy` +- `menu:black_market` +- `menu:lottery` +- `shipyard:small|medium|large|mega` +- `defense:orbital` +- `terraforming` +- `ground:cloning` +- `stargate` + +**Regel (Feature Unlock):** +Ein Menüpunkt/Feature ist verfügbar, wenn der Spieler **mindestens einen Besitz/State** hat, der die Capability liefert: +- meist: mindestens ein Gebäude mit `capabilities` enthält `menu:xyz` +- alternativ: Forschung kann Capability gewähren (`grant_capability`) + +### 7.2 Effects (kleine, feste Bibliothek) +Der Baukasten erlaubt nur diese Effect-Typen (v1): +1) `produce` — +X pro Stunde Ressource +2) `consume` — −X pro Stunde Ressource +3) `convert` — Inputs/h → Outputs/h (z.B. 20 metal + 5 energy → 5 alloy) +4) `capacity_add` — Cap +X für Ressource (z.B. Lager, Batterie) +5) `queue_slots_add` — zusätzliche Bau-/Queue-Slots (z.B. Bauzentrum) +6) `points_add` — +X pro Stunde für Punkt-Ressourcen (z.B. research_points, spy_points) +7) `modifier_add` — Additiver Bonus (z.B. +0.02 metal prod) auf Ziel (by_resource/by_tag/by_key) +8) `grant_capability` — schaltet Capability frei (v.a. Forschung) + +**Hinweis:** Neue Effect-Typen sind möglich, aber erfordern Code-Erweiterung und SSOT-Update. + +### 7.3 Requirements (kleine, feste Bibliothek) +Der Baukasten erlaubt diese Requirements (v1): +- `building_count` (min count eines bestimmten Gebäudes) +- `building_tag_count` (min count aller Gebäude mit Tag) +- `research_level` (min Level einer Forschung) +- `has_capability` (z.B. `menu:research` muss vorhanden sein) +- `player_race_in` / `player_race_not_in` +- `player_spec_in` / `player_spec_not_in` + +### 7.4 Access Rules (Whitelist/Blacklist) — überall gleich +Zusätzlich oder alternativ zu Requirements können Blueprints `access` definieren: + +- `allowed_races`, `blocked_races` +- `allowed_specializations`, `blocked_specializations` + +**Regeln:** +- Wenn `allowed_*` nicht leer → muss enthalten sein. +- Wenn in `blocked_*` enthalten → verboten. + +Beispiel: Roboter dürfen keine Klonfabrik, aber dürfen Robotik-Werkstatt: +- clone_factory: blocked_races=["robot"] +- robot_workshop: allowed_races=["robot"] + +--- + +## 8) Gebäude (Buildings) — stackable/levelable und Bauzentren-Queues + +### 8.1 Gebäude-Modelle +Gebäude unterstützen mindestens: +- `stackable`: man baut N Instanzen (Count) +- `levelable`: ein Gebäude hat Level L (Upgrade) +(hybrid ist optional später) + +### 8.2 Paralleles Bauen über Bauzentren +Es gibt ein Gebäude (Blueprint) mit Capability/Effect, das **Queue-Slots** liefert. +Standard: `build_center` ist stackable und hat Effect `queue_slots_add: +1 je count`. + +**Regel:** +`queue_slots = base_slots + Σ(queue_slots_add effects)` +SSOT-Default: `base_slots = 0` und mindestens 1 Bauzentrum im Startpaket. + +### 8.3 Bauauftrag (Build Job) +Ein Bauauftrag enthält: +- planet_id +- building_key +- mode: + - stackable: delta_count + - levelable: target_level +- started_at, finish_at +- slot_index (0..queue_slots-1) + +### 8.4 Start eines Bauauftrags +1) update_resources(planet) +2) freie Slots prüfen (active_jobs < queue_slots) +3) Requirements + Access prüfen +4) Auto-Cost berechnen (oder config cost) +5) Ressourcen sofort abziehen +6) Job anlegen (finish_at) + +### 8.5 Abschluss +Wenn `now >= finish_at`: +- stackable: count += delta_count +- levelable: level = target_level +- Job entfernen +- optional: Report/Event + +--- + +## 9) Zerstörbarkeit & Bombardierung (Gebäude können zerstört werden) + +### 9.1 Gebäude-Property: destroyable +Gebäude können `properties.destroyable` haben: +- Default: `true` +- Wenn `false`, darf Bombardierung dieses Gebäude nicht reduzieren. + +Optional: +- `structure` (Robustheit) +- `bombard_priority` (Zielgewicht) +- `debris_yield` (Ressourcenanteil der Kosten als Trümmer) + +### 9.2 Minimalregel (v1) +Bombardierung reduziert direkt: +- stackable: count sinkt +- levelable: level sinkt +Kein separater Damage-State im v1. + +--- + +## 10) Balance für usergenerierte Inhalte: Punkte + Auto-Cost (Anti-Exploit) + +### 10.1 Ziel +User sollen Inhalte bauen können, ohne das Spiel zu brechen. +Admin soll nicht jedes Ding manuell balancen müssen. + +### 10.2 Grundregel (Anti-Exploit) +**User wählen Effekte, nicht frei Kosten/Zeit.** +Kosten/Zeit/Upkeep werden **automatisch** aus Effekten abgeleitet (Auto-Cost). + +Optional gibt es einen Tradeoff-Slider (z.B. „billiger vs schneller“), aber nur in engem Korridor: +- Default: max ±2 Budgetpunkte oder max ±20% Abweichung. + +Damit ist „0 Kosten + lange Zeit“ nicht ausnutzbar, weil Kosten nicht frei sind. + +### 10.3 Budget pro Blueprint-Kategorie +Jede Kategorie hat ein Budget (Startwerte v1, später balancen): +- building: z.B. 15 +- ship: z.B. 20 +- research: z.B. 12 +- race: z.B. 0 (Summe Traits muss nahe 0) +- specialization: z.B. 0 (nahe 0) + +### 10.4 Scoring (Power Score) +Jeder Effect trägt Punkte bei, abhängig von: +- Ressource (über Werttabelle) +- Art des Effekts (produce/convert/stats/modifier) +- Inputs (consume) reduzieren Score +- Constraints/Exklusivität kann Score reduzieren (z.B. „nur race robot“ erlaubt -> leichter Preisabschlag möglich) + +**Werttabelle (v1, grob):** +- metal: 1.0 +- crystals: 1.2 +- deuterium: 1.3 +- water: 1.1 +- food: 0.9 +- energy: 0.8 +- alloy: 2.5 +- credits: 0.7 +(population/points separat) + +Die konkrete Score-Formel ist ein Implementierungsdetail, muss aber: +- deterministisch +- transparent (UI zeigt Score) +- nicht trivialisierbar + +### 10.5 Auto-Cost Ableitung (Grundsatz) +`cost` und `build_time` steigen monoton mit Score. +Optional zusätzlich: `upkeep` (consume) als natürliche Bremse, statt Hardcaps. + +--- + +## 11) Start-Defaults (v1) +- Universe: 9 Galaxien, 499 Systeme, 15 Positionen (anpassbar per config) +- Start: 1 Planet pro Spieler +- Start: 1 Bauzentrum (damit mindestens 1 Queue-Slot existiert) +- Planetklasse: temperate (oder nach Race preference), aber Generatorregel gilt +- Gebäudeanzahl: keine Hardcaps (Balance über Kosten/Zeit/Upkeep) + +--- + +## 12) Konfig-Dateien (Empfehlung) +- `config/universe.json` (Seeds, Dimensionen, Tier-Weights) +- `config/resources.json` (Werttabelle, caps defaults) +- `config/planet_classes.json` (spawn_weight, constraints, bias) +- `config/blueprints/*.json` (Gebäude, Schiffe, Forschung, Rassen, Specs) +- `config/taxonomy_capabilities.json` (optional UI-Hilfe/Labels) + +--- + +## 13) Decision Log +- [2026-02-03] v1.0 erstellt: Baukasten-Blueprint-System + Planet-Generator (Constraints+Budget) + Build-Center-Queues + destroyable Flag + Auto-Cost Prinzip.