How-to: Raumtemplate registrieren

Katalog und Ladeweg

Der aktive manuelle Katalog ist src/HolodeckArena.Game3D/Features/Dungeons/Rooms/Metadata/RoomTemplateCatalogV3.tres. Seine Resource-Klasse RoomTemplateCatalog.cs exportiert Array<PackedScene> Templates. DungeonRun3DScene.tscn weist diesen Katalog an DungeonRun3DController.TemplateCatalog zu. Es gibt kein automatisches Directory-Scanning.

Schritte

1. Scene als RoomTemplate3D-Root speichern und mit Raum erstellen validieren.
2. Im Godot Inspector den Katalog öffnen und PackedScene an Templates anhängen. Bei Textbearbeitung müssten ext_resource, load_steps und Array gemeinsam geändert werden; Editor ist sicherer.
3. TemplateId eindeutig, stabil und snake_case halten. Catalog vergleicht ordinal/case-sensitive.
4. Category/Size/GameplayRole/LogicalWidth/LogicalHeight müssen exakt eine aktive V3-Anforderung erfüllen.
5. SelectionWeight > 0; höhere Werte erhöhen deterministisch die Auswahlchance. Null/negativ ist ungültig.
6. MinDepth/MaxDepth einschließend setzen. Tags sind gespeichert, aber derzeit kein Filter. AllowedThemes wird derzeit nicht in Candidate übertragen.
7. Alle möglichen Door-Richtungen als Sockets anbieten. Selector akzeptiert Kandidaten, wenn nach einer 90°-Rotation jede erforderliche Weltrichtung unterstützt wird.
8. Boss/Start/Exit werden über Category/Role gekennzeichnet, nicht mit separaten Bool-Flags. Pflichtmarker entsprechend setzen.
9. Preview-F6 und Integration-F6 ausführen. ValidateCatalog() prüft Duplicate IDs, Scene-Root, Templatevalidator und V3-Coverage.

Auswahlverhalten

Kandidaten werden nach TemplateId sortiert, jede kompatible Rotation ist ein gewichteter Kandidat. Der Seed kommt aus RunSeed/RoomId/Index/Purpose. Ein einziges Template pro Typ ist erlaubt und wird mehrfach instanziiert. Entfernen des letzten Templates einer Matrixposition macht den gesamten Katalog ungültig. Es gibt keinen Category-/Size-Fallback.

Typische Catalog-Fehler

• Empty PackedScene oder Root nicht RoomTemplate3D.
• Duplicate TemplateId trotz anderer Scene-Datei.
• Role-Schreibweise stimmt nicht exakt (SmallRoom, nicht small_room).
• Logical Maße entsprechen sichtbarer Geometrie, aber nicht der kanonischen Matrix.
• Template besitzt nur aktuelle benötigte Doors und ist für andere Graphorientierungen ungeeignet.
• Weight 0, Depth schließt jeden Request aus oder Pflichtmarker fehlt.

Tests

RoomTemplateSelectorTests.cs: Filter/Rotation/Seed/Weight. RoomDoorSocketTests.cs: Socketzustände. Katalog-Resource selbst benötigt aktuell manuelle Godot-Validierung; ein automatisierter Resource-Load-Test wäre sinnvoll.

Verwandt: Raumtemplates, Troubleshooting.