Überblick

Das Culling System besteht aus zwei Komponenten, die zusammenarbeiten:

Targets melden sich selbst beim Manager an (OnEnable / OnDisable), nicht umgekehrt. Das ist der Grund, warum das System problemlos über mehrere additiv geladene Szenen hinweg funktioniert — dazu mehr unter Mehrere Szenen.

Installation

1. Beide Skripte (SuraFixVR_CameraCullingManager.cs, SuraFixVR_VisualCullingTarget.cs) irgendwo unter Assets/ ablegen.
2. Ein leeres GameObject _CullingManager in deine Bootstrap- bzw. Persistent-Szene legen und SuraFixVR_CameraCullingManager draufziehen.
3. Kamera und Spieler-Transform im Inspector zuweisen, oder leer lassen — der Manager findet sie automatisch über cameraTag bzw. SuraFix_PlayerTracker.
4. SuraFixVR_VisualCullingTarget auf jedes Objekt setzen, das gecullt werden soll (Props, Räume, Licht-Rigs, Partikel-Setups).

Schnellstart

Minimal-Setup für ein einzelnes Objekt mit Distanz- und Frustum-Culling:

using UnityEngine;

// Wird automatisch beim Manager registriert, sobald aktiv.
[RequireComponent(typeof(SuraFixVR_VisualCullingTarget))]
public class ExampleProp : MonoBehaviour { }

Mehr ist nicht nötig — Renderer, Partikel und Animatoren werden beim Awake automatisch gecached.

CameraCullingManager

Läuft pro Frame über eine Teilmenge aller registrierten Targets (targetsPerFrame) und wertet für jedes Target Distanz und Frustum-Sichtbarkeit aus.

Time-Slicing

Bei vielen Objekten ist es teurer, alle pro Frame zu prüfen als die Prüfung über mehrere Frames zu verteilen. targetsPerFrame steuert genau das — höhere Werte reagieren schneller auf Bewegung, niedrigere Werte sparen CPU.

Auto-Refresh der Zielliste

refreshInterval bestimmt, wie oft die komplette Liste aktiver Targets neu eingesammelt wird (z.B. nach dem Laden neuer Räume). Auf 0 setzen, um Auto-Refresh komplett zu deaktivieren — sinnvoll, wenn Register/Unregister manuell oder über Szenen-Events gesteuert wird.

VisualCullingTarget

Jedes Target unterstützt drei Bounds-Modi:

Partikelsysteme (ParticleSystemRenderer) werden seit v1.1 separat erfasst und fließen sowohl in die Sichtbarkeits-Bounds als auch ins Ein-/Ausblenden ein — relevant, wenn ein Effekt-Objekt keinen eigenen MeshRenderer besitzt.

Room-Modus

Im Room-Modus gilt ein Objekt immer als sichtbar, solange sich der Spieler innerhalb der definierten cullingBoundsSize befindet — unabhängig vom Frustum. Das verhindert Pop-in direkt im Rücken des Spielers in Innenräumen.

Addressable Streaming: Konzept

Während das Culling-System nur Rendering an- und ausschaltet, geht SuraFix_AddressableRoomLoader einen Schritt weiter: Es lädt und entlädt ganze Prefabs über die Addressables-API, abhängig von der Distanz zum Spieler. Damit sinkt nicht nur die Render-Last, sondern auch der tatsächliche Speicherverbrauch.

Hysterese statt harter Grenze

Laden und Entladen nutzen bewusst zwei unterschiedliche Radien:

Ohne diesen Puffer würde ein Objekt exakt an der Grenze ständig laden und sofort wieder entladen, sobald sich der Spieler minimal hin- und herbewegt. Der Puffer verhindert dieses Flackern.

SuraFix_AddressableRoomLoader

Prüft per Coroutine (checkInterval, Standard 0,25s) regelmäßig die Distanz zum Spieler und steuert darüber den Ladezustand.

Ablauf beim Laden

1. Distanzprüfung erkennt: Spieler ist innerhalb von loadRadius.
2. Addressables.InstantiateAsync(structureAddressKey, transform) wird gestartet.
3. Nach erfolgreichem Laden wird die Instanz unter das Loader-Objekt gehängt, lokal zentriert und zunächst deaktiviert, einen Frame gewartet, dann erst aktiviert — das vermeidet Initialisierungs-Hakler in Skripten, die in OnEnable auf bereits gesetzte Transform-Werte angewiesen sind.

Ablauf beim Entladen

Sobald die Distanz unloadRadius überschreitet, wird Addressables.ReleaseInstance(...) aufgerufen. Eine laufende Lade-Coroutine wird dabei sauber abgebrochen, falls der Spieler den Bereich verlässt, bevor das Laden abgeschlossen ist.

Gizmos

Im Editor zeigt das Objekt zwei Wireframe-Kugeln: grün für loadRadius, gelb für die effektive Entlade-Distanz.

SuraFix_PlayerTracker

Eine bewusst minimale, statische Referenz auf den aktuellen Spieler-Transform — genutzt vom RoomLoader und als Fallback vom CameraCullingManager, falls dort kein Spieler-Transform manuell zugewiesen wurde.

Setup & Scripting Define Symbol

Das Addressable-System ist optional und kompiliert auch ohne installiertes Addressables-Package — dafür sorgt das Define SURA_FIX_ADDRESSABLES.

1. Addressables-Package über den Package Manager installieren.
2. Project Settings → Player → Scripting Define Symbols öffnen.
3. SURA_FIX_ADDRESSABLES hinzufügen.
4. Für jedes Raum-Prefab, das per structureAddressKey geladen werden soll, eine Addressable-Gruppe im Addressables-Fenster anlegen.

Key Fixer (Editor-Tool)

Erreichbar über SuraFix → Addressables → Fix Keys im Editor-Menü. Gleicht den Addressable-address-Wert jedes Eintrags an den tatsächlichen Dateinamen des Assets an.

Sinnvoll, wenn Assets im Project-Fenster umbenannt wurden, ohne dass die Addressable-Adresse mitgepflegt wurde — structureAddressKey im RoomLoader muss exakt mit dieser Adresse übereinstimmen, sonst schlägt das Laden mit einem Fehler in der Konsole fehl.

Licht-Culling: Konzept & Inspector

Lichter werden pro Eintrag (LightCullingEntry) individuell konfiguriert. Jeder Eintrag hat zwei Cutoff-Distanzen:

Directional Lights

Beim automatischen Caching werden LightType.Directional-Lichter standardmäßig mit enableCulling = false angelegt. Eine Sonne hat keine sinnvolle Distanz zum Spieler — sie würde sonst je nach Position des Objekts willkürlich an- und ausgehen.

Szenenübergreifender Einsatz

Das System ist bewusst so gebaut, dass es additiv geladene, mehrfach gleichzeitig aktive Szenen unterstützt:

• Der Manager ist ein einzelnes Singleton, unabhängig davon, wie viele Szenen aktuell geladen sind.
• Targets registrieren sich selbst beim Aktivieren (OnEnable) und entfernen sich beim Deaktivieren (OnDisable) — das passiert automatisch beim Laden/Entladen einer Szene, ganz ohne Zusatzcode.
• RefreshTargets() kann zusätzlich manuell nach einem Szenenwechsel aufgerufen werden, falls refreshInterval auf 0 steht.

Empfohlenes Setup für mehrere Szenen

1. Eine Persistent-Szene anlegen, die nie entladen wird und ausschließlich den _CullingManager enthält.
2. Alle Gameplay-Szenen additiv dazu laden (SceneManager.LoadSceneAsync(..., LoadSceneMode.Additive)).
3. Jede Szene bringt ihre eigenen VisualCullingTarget-Objekte mit — keine manuelle Registrierung nötig.

API-Referenz: CameraCullingManager

API-Referenz: VisualCullingTarget

FAQ

Meine Partikeleffekte verschwinden unerwartet.

Seit v1.1 werden ParticleSystemRenderer in die Bounds-Berechnung mit einbezogen. Stelle sicher, dass du die aktuelle Version beider Skripte verwendest — ältere Versionen kannten nur MeshRenderer und SkinnedMeshRenderer.

Ein Licht in einem Room-Objekt schaltet zu früh ab.

Prüfe, ob respectFrustum für dieses Licht aktiv ist — im Room-Modus zählen dann die Room-Bounds, nicht die individuelle Lichtreichweite. Siehe Room-Modus.

Funktioniert das System mit Unity vor 2023.1?

Ja — der Manager nutzt automatisch FindObjectsOfType als Fallback über #if UNITY_2023_1_OR_NEWER.

Der RoomLoader tut nichts, keine Fehler, keine Logs.

Prüfe, ob SURA_FIX_ADDRESSABLES unter Scripting Define Symbols gesetzt ist (siehe Setup). Ohne dieses Define kompiliert das Skript zwar, lädt aber bewusst nichts.

Mein Raum-Prefab lädt nicht, obwohl Addressables aktiv ist.

structureAddressKey muss exakt der Addressable-address entsprechen. Nach Umbenennungen im Project-Fenster hilft SuraFix → Addressables → Fix Keys, siehe Key Fixer.