Skip to content

Dungeon-Generierung und Raumtemplates

Status: V3 produktiver Entwicklungspfad; V2/Legacy nur GeneratedFallback

Zweck und Verantwortlichkeiten

Shared erzeugt Graph, Rollen, Bounds, Doors, Spawns und Hash ohne Godot. Game3D wählt für jeden kanonischen Raum eine kompatible PackedScene, instanziiert sie und liefert Marker über RoomRuntimeContext an Player/Encounter/Exit.

Wichtige Pfade

  • Shared Generator: src/HolodeckArena.Shared/Dungeons/Definitions und Dungeons/Generation.
  • Template-Basis: src/HolodeckArena.Game3D/Features/Dungeons/Rooms/Templates/RoomTemplate3D.cs.
  • Beispiele/Blank: Features/Dungeons/Rooms/Templates/examples.
  • Metadaten/Katalog: Features/Dungeons/Rooms/Metadata/RoomTemplateMetadata.cs, RoomTemplateCatalog.cs, RoomTemplateCatalogV3.tres.
  • Auswahl: RoomTemplateRequestFactory.cs, RoomTemplateSelector.cs und RoomSeedDerivation.cs.
  • Template und Rotation werden über StableSeedDerivation und den versionierten DeterministicRandom gewählt; System.Random ist kein Bestandteil des reproduzierbaren Auswahlvertrags.
  • Instanz: Rooms/Runtime/RoomTemplateInstantiator.cs und RoomRuntimeContext.cs.
  • Validator: RoomTemplateValidator.cs.
  • Preview/Integration: Rooms/Preview/RoomTemplatePreview.tscn, Rooms/Integration/DungeonTemplateIntegrationTest.tscn.

Aktive V3-Matrix

Kategorie Größe GameplayRole logische Maße Pflichtmarker
Start Small StartLounge 18×12 PlayerSpawn
Combat Small SmallRoom 22×16 EnemySpawn
Combat Large LargeRoom 34×24 EnemySpawn
Treasure Small TreasureRoom 20×16 keiner im Validator; Runtime nutzt Interaction/Center
Boss BossArena BossRoom 40×30 BossSpawn
Exit Medium ExitRoom 24×16 Interaction

Shared kennt mehr Rollen/Größen als die aktive Matrix; sie sind nicht automatisch katalogfähig. Template-Kategorien enthalten außerdem Elite/Event/Social/Utility, werden vom aktuellen RoomTemplateRequestFactory aber nicht aus kanonischen V3-Räumen angefordert.

Auswahl und Doors

Der Request enthält Kategorie, Größe, Role, Bounds.Width - 1/Height - 1, benötigte Weltrichtungen, Depth und Difficulty. Kandidaten werden ordinal nach TemplateId sortiert, über vier Rotationen geprüft und gewichtet mit einem Room-Seed gewählt. Bei einem Kandidaten darf dieselbe PackedScene mehrfach als getrennte Instanz verwendet werden. Kein Kandidat führt zu einem ausführlichen Fehler; es gibt keinen stillen Fallback.

RoomDoorSocket3D ist eine mögliche Wandöffnung. Open blendet WallPlug aus und deaktiviert Plug-Collision/NavigationObstacle; Sealed tut das Gegenteil. RuntimeDoor3D ist die einmalige, laufzeitgesteuerte Verbindungstür. Richtungen: North −Z, East +X, South +Z, West −X; Socket-Forward zeigt nach außen. Pivot/Bodenmitte ist Y=0, ein logisches Feld sind 2 m.

Marker, Navigation und Collision

RoomTemplate3D.CacheMarkers sammelt und sortiert Door-, Enemy-, Boss-, Player-, Interaction-, Cover-, Decoration-, Center- und Camera-Marker. LootMarker existiert nicht. Geometry und StaticBody-Collision gehören ins Template. Ein optionales NavigationRegion3D ist vorgesehen; der aktuelle Gegner nutzt zusätzlich DungeonGridNavigator3D, daher Navigationänderungen in beiden Pfaden prüfen.

Tests, Debugging, Performance und Fallstricke

Tests: RoomDoorSocketTests.cs, RoomTemplateSelectorTests.cs, DungeonGraphValidationTests.cs. Validator prüft IDs, Maße, Weight, GeometryRoot, Socket-Boundary/Forward/Plug/Collision, Marker-IDs und Pflichtmarker. Preview per F6, Integration mit template-integration-01. Template-Instanziierung ist Run-Setup; keine wiederholte Kataloginstanziierung im Frame-Loop.

Der Blank-Raum besitzt Default-Metadaten und nur einen North-Socket und ist nicht ohne Anpassung V3-gültig. Beispieltemplates verwenden ExampleRoomTemplate3D, das Inhalte teilweise im Code aufbaut; für Art-Räume die tatsächliche Scene-Struktur kontrollieren.

How-tos: Raum erstellen, registrieren.