Crowd Cheer System — Dokumentacja

01Quick Start

Dwie ścieżki: sam shader (30 sekund, zero skryptów) albo pełny system ze sterowaniem globalnym i triggerami. Zacznij od pierwszej, przejdź na drugą kiedy potrzebujesz fali i skoków.

A. Sam shader — minimum

1. Wrzuć na scenę Quada albo dołączony model plate_crowd.fbx.
2. Stwórz materiał i ustaw shader SerwusStudio/CrowdCheer.
3. Podepnij swój atlas w slot Crowd Texture Atlas.
4. Ustaw Columns in Atlas = liczba wariantów postaci (poziomo) i Anim Rows in Atlas = liczba klatek animacji (pionowo).
5. Pokręć Tiling X / Y — tyle postaci zmieści się na płaszczyźnie.

Gotowe. Postacie animują się same, z losowym wariantem i losowym przesunięciem fazy. Żadnych skryptów.

B. Pełny system — zalecane

1. Rozstaw prefaby plate_crowd tam, gdzie ma być publiczność (trybuny, sektory, widownia).
2. Dodaj CrowdController do każdej płaszczyzny i ustaw per-plane: atlas, kolumny, wiersze, tiling, offset.
3. Stwórz pusty GameObject i dodaj CrowdManager. Kliknij Auto Collect All — zbierze wszystkie kontrolery ze sceny.
4. Steruj całym tłumem z Managera: gęstość, prędkość animacji, fade, kolor, losowość, jakość.
5. Opcjonalnie dodaj CrowdWaveTrigger — fala i skok z klawisza, przycisku UI albo collidera. Bez pisania kodu.

02Jak to działa

Tłum renderuje się w całości na GPU. Nie ma GameObjectu na postać, nie ma Animatorów, nie ma skinowanych meshy. Jedna płaska płaszczyzna wyświetla kilkadziesiąt animowanych postaci przez tilowanie atlasu tekstur — jeden draw call niezależnie od tego, ile postaci widać.

Ścieżka fragmentu

1. Clip bounds — jeśli włączone, fragmenty poza prostopadłościanem world-space odpadają natychmiast.
2. Distance fade — odległość do kamery liczona pierwsza; poza Fade End fragment jest odrzucany, zanim cokolwiek zostanie policzone. To jest oszczędność fillrate, nie tylko efekt wizualny.
3. Tiling — UV mnożone przez Tiling X/Y, część całkowita to tileID (numer kafla = numer postaci), część ułamkowa to lokalne UV wewnątrz kafla.
4. Plane seed — ziarno losowości liczone z pivota obiektu (unity_ObjectToWorld). Stałe dla całego mesha, różne dla każdej płaszczyzny na scenie — dwie identyczne płyty obok siebie pokażą inny tłum.
5. Person ID — planeSeed + tileID + RandomSeed. Z tego jednego hasha wychodzi: czy kafel jest zajęty (gęstość), który wariant postaci, czy odbita w poziomie, jakie przesunięcie fazy animacji, jaki odcień tintu.
6. Animacja — frame = floor(_Time.y * AnimSpeed + timeOffset), modulo liczba wierszy. Każda postać ma własny timeOffset, więc nikt nie klaszcze w rytm sąsiada.
7. Fala / La Ola — pozycja world-space rzutowana na kierunek fali; jeśli fragment mieści się w paśmie Wave Width, wiersz animacji jest podmieniany na Wave Pose. Przy Wave Speed = 0 cały blok jest pomijany — zero kosztu.
8. Sampling i maska — UV atlasu z paddingiem, miękka maska krawędzi (Edge Smoothness), alpha cutout.

Passy

Shader ma dwa passy: ForwardLit (kolor, oświetlenie z głównego światła kierunkowego + ambient SH) oraz DepthOnly. Oba dzielą tę samą funkcję CrowdTile(), więc głębia zawsze zgadza się z tym, co widać. Kolejka AlphaTest z ZWrite On — bez sortowania przezroczystości.

03Atlas tekstur

Atlas to równa siatka. Kolumny to warianty postaci (kolor koszulki, sylwetka), wiersze to klatki animacji odtwarzane po kolei z góry na dół.

Atlas 4 × 4 → 4 warianty postaci × 4 klatki animacji. Z włączonym Random Flip X wygląda jak 8 wariantów, bez dodatkowej pamięci.

Wymagania

• Wszystkie komórki tej samej wielkości, siatka bez przerw.
• Tło w pełni przezroczyste (alpha = 0) — cutout tego wymaga.
• Kilka pikseli przezroczystego marginesu wokół każdej postaci — inaczej sąsiednie komórki będą się wzajemnie podbierać przy filtrowaniu.
• PNG lub TGA z kanałem alpha, rozdzielczość potęga dwójki (512², 1024², 2048²).
• Na mobile / VR: Crunch compression w ustawieniach importu, 512² lub 1024² w zupełności wystarcza.
• W materiale ustaw Columns in Atlas i Anim Rows in Atlas dokładnie tak, jak wygląda siatka. Niezgodność = pocięte postacie.

04Komponenty

Trzy komponenty runtime i dwa custom inspektory. Kluczowa zasada: CrowdManager jest opcjonalny. CrowdController działa samodzielnie — Manager tylko przejmuje nad nim sterowanie globalne.

CrowdController

Komponent per-płaszczyzna. [ExecuteAlways], [DisallowMultipleComponent], wymaga Renderer na tym samym obiekcie. Wszystkie wartości idą do shadera przez MaterialPropertyBlock — współdzielony materiał nigdy nie jest modyfikowany, więc nie powstają instancje materiału i GPU instancing zostaje zachowany.

• Per-plane: atlas, liczba kolumn i wierszy, Tiling X/Y, Offset X/Y, clip bounds.
• Globalne: gęstość, prędkość animacji, fade, kolor, losowość, jakość, parametry fali — sterowane z Managera, edytowalne lokalnie gdy Managera nie ma.
• Brak Update i LateUpdate. Wartości lecą do GPU tylko przy zmianie. Zerowy koszt CPU na klatkę.

CrowdManager

Komponent na poziomie sceny, zwykle jeden. Jeden suwak zmienia gęstość na wszystkich płaszczyznach naraz. Trzyma listę kontrolerów (Auto Collect zbiera je automatycznie na Awake) i przy każdej zmianie robi jeden batchowany SetGlobalParams() na kontroler — nie jedno wywołanie na właściwość.

• Globalne: Density, Anim Speed, Fade Start/End, Tint Color, Tint Variation, Random Seed, Flip, Edge Smoothness, Alpha Clip.
• Fala: kierunek, prędkość, szerokość pasa, wiersz pozy dopingu, czas trwania (0 = w nieskończoność).
• Skok: wysokość, czas trwania, propagacja falowa i opóźnienie na jednostkę świata.

CrowdWaveTrigger

Odpala falę i skok bez pisania kodu. Wymaga referencji do CrowdManagera. Trzy tryby, można łączyć:

1. Klawisz — Trigger On Key Press + wybrany klawisz (domyślnie Space).
2. Przycisk UI — w onClick przeciągnij obiekt i wybierz TriggerWave() lub TriggerJump().
3. Strefa collidera — Collider z Is Trigger, opcjonalny filtr po tagu (domyślnie Player).

Do tego Cooldown (minimalna przerwa między falami — blokuje spam) oraz dwa UnityEventy: On Wave Triggered i On Wave Blocked. Podepnij pod nie dźwięk tłumu, wibrację pada albo cokolwiek innego.

Custom inspektory

Oba komponenty mają własne inspektory z foldoutami. CrowdControllerEditor wykrywa obecność Managera na scenie: sekcje globalne stają się read-only (żeby nie edytować w dwóch miejscach naraz), a per-plane zostają zawsze aktywne. Ostrzega o braku Renderera, braku materiału i o złym shaderze. CrowdManagerEditor daje licznik kontrolerów, przyciski Auto Collect All / Apply Globals Now oraz Trigger Wave / Jump i Stop w trybie Play. Waliduje też, czy Fade Start jest mniejszy od Fade End.

05Scripting API

Namespace SerwusStudio. Wszystko, co ustawiasz w inspektorze, ma odpowiednik w kodzie — settery same wysyłają wartości do GPU, nie trzeba nic „odświeżać".

CrowdManager — właściwości

CrowdManager — metody

CrowdController — metody

CrowdWaveTrigger — metody

Przykłady

using SerwusStudio;

public class MatchEvents : MonoBehaviour
{
    public CrowdManager crowd;
    public Transform homeGoal;

    // gol — tłum wariuje: szybsza animacja, fala od bramki, skok
    public void OnGoalScored()
    {
        crowd.AnimSpeed = 8f;
        crowd.TriggerWaveFrom(homeGoal.position);
        crowd.TriggerJump();
        Invoke(nameof(CalmDown), 6f);
    }

    void CalmDown() => crowd.AnimSpeed = 2f;

    // sektory drużyn — dwa Managery albo dwa zestawy materiałów
    public void SetHomeColors()
    {
        crowd.TintColor     = new Color(1f, 0.82f, 0.82f);
        crowd.TintVariation = 0.25f;
    }

    // stadion pustoszeje po meczu
    IEnumerator EmptyStadium(float seconds)
    {
        float t = 0f;
        while (t < seconds)
        {
            t += Time.deltaTime;
            crowd.DensityLevel = Mathf.Lerp(1f, 0f, t / seconds);
            yield return null;
        }
    }

    // profil jakości pod VR / Quest
    public void ApplyVRProfile()
    {
        crowd.FadeStart = 30f;
        crowd.FadeEnd   = 60f;
    }
}

Płaszczyzny tworzone w runtime rejestruj ręcznie — dostaną wtedy komplet globalnych ustawień:

var plane = Instantiate(crowdPrefab, position, rotation);
crowd.RegisterController(plane.GetComponent<CrowdController>());

// przy usuwaniu
crowd.UnregisterController(controller);
Destroy(controller.gameObject);

06Parametry shadera

Kompletna lista właściwości shadera SerwusStudio/CrowdCheer — nazwa w inspektorze, nazwa właściwości do kodu, zakres i wartość domyślna.

07Clip Bounds

Płaskie płaszczyzny tłumu na zakrzywionych trybunach lubią się przecinać — róg jednej płyty wystaje zza drugiej albo przebija barierkę. Clip Bounds rozwiązuje to bez cięcia geometrii: fragmenty poza zadanym prostopadłościanem world-space są po prostu odrzucane.

• Włącz Enable Clip Bounds na CrowdController i ustaw narożniki Min/Max.
• Zaznaczony obiekt rysuje pomarańczowy gizmo bryły — widać dokładnie, co zostanie przycięte.
• SetClipBoundsFromRenderer() ustawia bryłę na aktualne granice Renderera — dobry punkt startowy do ręcznego zawężenia.
• Test jest pierwszą rzeczą w shaderze, więc przycięte fragmenty nie kosztują nic więcej.

// przytnij tłum do bryły sektora
controller.SetClipBounds(sector.bounds.min, sector.bounds.max);

// wyjściowo: dopasuj do własnych granic mesha, potem zawęź ręcznie
controller.SetClipBoundsFromRenderer();

// wyłącz
controller.ClearClipBounds();

08Wydajność i VR

System jest lekki z założenia, ale wąskim gardłem zawsze będzie fillrate — liczba pikseli ekranu pokrytych płaszczyznami tłumu. Wszystko poniżej sprowadza się do tego, żeby ich było mniej.

Co jest darmowe z definicji

• Zero kosztu CPU na klatkę — żaden komponent nie ma Update ani LateUpdate. Dane lecą do GPU tylko przy zmianie.
• MaterialPropertyBlock — brak duplikacji materiałów, GPU instancing zachowany.
• Batchowane Apply() — zmiana globalna to jedno wywołanie na kontroler, nie jedno na właściwość.
• Fala kosztuje zero, gdy śpi — przy Wave Speed = 0 shader nie wchodzi w blok fali.
• Alpha cutout, nie transparency — kolejka AlphaTest z ZWrite On, bez sortowania przezroczystości.

VR / Quest / mobile

• Distance Fade agresywnie. Na Queście Fade Start 30, Fade End 60. Na mobile 40 / 80. Odległe trybuny nic nie wnoszą, a kosztują fillrate.
• Mniejszy tiling na dalekich płytach. Płaszczyzna 40 metrów od kamery nie potrzebuje 10×10 postaci — 3×3 wygląda tak samo.
• Atlas 512² lub 1024² z Crunch compression. Postaci ogląda się z dystansu, nie widać różnicy.
• Włącz GPU Instancing w materiale, jeśli używasz wielu płaszczyzn z tym samym materiałem.
• Single Pass Instanced działa. Shader ma pełne wsparcie stereo: UNITY_VERTEX_INPUT_INSTANCE_ID, UNITY_VERTEX_OUTPUT_STEREO, UNITY_SETUP_STEREO_EYE_INDEX_POST_VERTEX. Testowane na Quest 2 i Quest 3.

PC i konsole

Można pozwolić sobie na atlas 2048², Fade End 200+ i gęsty tiling. Oświetlenie to główne światło kierunkowe plus ambient SH — realistyczna reakcja na scenę przy minimalnym koszcie.

09FAQ

10Changelog