# Projektregeln

Diese Regeln gelten für das gesamte Godot-4-Projekt.

## Struktur und Bestand

- Neue Scan-Assets unter `assets/scan/`, PBR-Texturen unter `assets/textures/`, Animationen unter `assets/animations/` ablegen. Szenen gehören nach `scenes/`, GDScript nach `scripts/`.
- Bestehende Assetpfade nicht allein zur Vereinheitlichung verschieben: importierte Ressourcen, Szenen und Laufzeitreferenzen müssen erhalten bleiben.
- Neue Assetpakete in eigenen Unterordnern mit Herkunft und Lizenz dokumentieren.

## Import und Materialien

- Bei jedem Import von FBX/OBJ-Scans oder PBR-Textursätzen automatisch passende externe `StandardMaterial3D`-Ressourcen als `.tres` im Assetpaket erstellen und den zugehörigen Mesh-Oberflächen zuweisen.
- Vorhandene Materialzuordnungen erhalten; bei mehreren Oberflächen separat zuordnen. Keine globale Überschreibung unterschiedlicher Materialien.
- Albedo, Normal, Roughness, Metallic und AO nach tatsächlich gelieferten Maps zuweisen. Normal-Maps aktivieren, OpenGL/DirectX-Konvention prüfen und bei DirectX den grünen Kanal korrekt invertieren. Keine Farbraumkorrektur auf Daten-Maps anwenden.
- Bei gepackten Maps die belegten Kanäle explizit zuordnen; fehlende Maps durch plausible skalare Werte ersetzen. Height-Maps nicht als Normal-Maps behandeln. Transparenz nur bei tatsächlich transparenten Oberflächen aktivieren.
- Import und Materialzuordnung mit Godot prüfen; Normalen, UV-Maßstab und Oberflächen im echten Render kontrollieren.
- Bestehende spezialisierte Shader und funktionierende Materialmodule nicht grundlos ersetzen.

## Module

- Kleine, spezialisierte Module mit klarer Verantwortung schreiben (z. B. PlayerMovement, WeaponManager, CameraController).
- Keine Monolith-Skripte. Funktionierende Systeme nicht ohne sachlichen Grund neu schreiben.
- Den vom Benutzer freigegebenen Umfang beachten; Grafikarbeiten ändern kein Gameplay.

## Validierung

- Nach jeder Projektänderung die relevanten Godot-Console-Logs prüfen, bevor der nächste Änderungsschritt beginnt.
- Warnungen und Fehler untersuchen und im autorisierten Umfang beheben; ein fehlgeschlagener Lauf ist kein bestandener Test.
- Headless für Import-, Parser- und Strukturprüfungen verwenden. Für Screenshots echten Renderer verwenden; ein Headless-Lauf ersetzt keine visuelle Kontrolle.
- Abschließend relevante Tests ausführen und verbleibende Einschränkungen ehrlich dokumentieren.

## Godot-4-Refactoring-Guardrail

- Zielversion ist die mitgelieferte Godot 4.5. Keine Godot-3-APIs einführen; CharacterBody3D, Node3D und StandardMaterial3D verwenden. CharacterBody3D.move_and_slide() ohne Argumente aufrufen.
- Neue Variablen mit konkretem expliziten Typ oder konkret inferierbarem := deklarieren. var name = value vermeiden.
- Variant nur an tatsächlich dynamischen Grenzen verwenden (JSON, Konfiguration, unvalidierte RPC-Daten, nullable Engine-API-Ergebnisse). Vor konkreter Verwendung validieren. Eine Variant-Annotation bedeutet nicht statische Spezialisierung oder garantierte Mehrleistung.
- Klassen direkt referenzieren, statt ihre statischen Methoden über dynamische Variablen aufzurufen.
- Nach Refactoring tests/audit_gdscript.py ausführen. Dieser prüft jede eigene .gd-Datei mit dem Godot-Parser und meldet untypisierte var-Deklarationen. Anschließend passende Laufzeittests ausführen.