Crowd Cheer System - Documentation

01Quick Start

Two paths: the shader alone (30 seconds, zero scripts) or the full system with global control and gameplay triggers. Start with the first, move to the second when you want the wave and the bounce.

A. Shader only - the minimum

1. Drop a Quad into your scene, or the included plate_crowd.fbx model.
2. Create a Material and set the shader to SerwusStudio/CrowdCheer.
3. Assign your atlas to the Crowd Texture Atlas slot.
4. Set Columns in Atlas = number of character variants (horizontal) and Anim Rows in Atlas = number of animation frames (vertical).
5. Dial in Tiling X / Y - that's how many characters fit on the plane.

Done. Characters animate on their own, with a randomized variant and a randomized phase offset. No scripts involved.

B. Full system - recommended

1. Place plate_crowd prefabs wherever the audience belongs (stands, sections, seating tiers).
2. Add CrowdController to each plane and set the per-plane values: atlas, columns, rows, tiling, offset.
3. Create an empty GameObject and add CrowdManager. Hit Auto Collect All - it gathers every controller in the scene.
4. Drive the whole crowd from the Manager: density, animation speed, fade, color, randomization, quality.
5. Optionally add CrowdWaveTrigger - wave and jump from a key, a UI button or a collider. No code required.

02How it works

The crowd renders entirely on the GPU. No GameObject per character, no Animators, no skinned meshes. A single flat plane displays dozens of animated characters through texture atlas tiling - one draw call regardless of how many characters are visible.

The fragment path

1. Clip bounds - when enabled, fragments outside the world-space box are discarded immediately.
2. Distance fade - camera distance is evaluated first; past Fade End the fragment is rejected before anything else runs. That's a fillrate saving, not just a visual effect.
3. Tiling - UVs multiplied by Tiling X/Y; the integer part is the tileID (one tile = one character), the fractional part is the local UV inside the tile.
4. Plane seed - the randomization seed is derived from the object pivot (unity_ObjectToWorld). Constant across the mesh, different for every plane in the scene - two identical plates side by side show a different crowd.
5. Person ID - planeSeed + tileID + RandomSeed. That single hash decides: whether the tile is occupied (density), which character variant, whether it is mirrored, its animation phase offset, and its tint shift.
6. Animation - frame = floor(_Time.y * AnimSpeed + timeOffset), modulo the row count. Each character carries its own timeOffset, so nobody claps in lockstep with their neighbour.
7. Wave / La Ola - the world-space position is projected onto the wave direction; if the fragment falls inside the Wave Width band, the animation row is swapped for Wave Pose. At Wave Speed = 0 the whole block is skipped - zero cost.
8. Sampling and masking - padded atlas UVs, a soft edge mask (Edge Smoothness), alpha cutout.

Passes

The shader has two passes: ForwardLit (color, main directional light + ambient SH) and DepthOnly. Both share the same CrowdTile() function, so depth always matches what you see. AlphaTest queue with ZWrite On - no transparency sorting.

03Texture atlas

The atlas is a uniform grid. Columns are character variants (shirt color, body type), rows are animation frames played top to bottom in sequence.

A 4 × 4 atlas → 4 character variants × 4 animation frames. With Random Flip X on it reads as 8 variants, at no extra memory cost.

Requirements

• All cells the same size, a grid with no gaps.
• Fully transparent background (alpha = 0) - the cutout depends on it.
• A few pixels of transparent padding around each character - without it, texture filtering bleeds pixels from the neighbouring cell.
• PNG or TGA with an alpha channel, power-of-two resolution (512², 1024², 2048²).
• On mobile / VR: Crunch compression in the import settings; 512² or 1024² is plenty.
• Set Columns in Atlas and Anim Rows in Atlas in the material to match the grid exactly. A mismatch means sliced characters.

04Components

Three runtime components and two custom inspectors. The key rule: CrowdManager is optional. CrowdController works standalone - the Manager simply takes over its global settings.

CrowdController

The per-plane component. [ExecuteAlways], [DisallowMultipleComponent], requires a Renderer on the same GameObject. Every value reaches the shader through a MaterialPropertyBlock - the shared material is never modified, so no material instances are created and GPU instancing is preserved.

• Per-plane: atlas, column and row counts, Tiling X/Y, Offset X/Y, clip bounds.
• Global: density, animation speed, fade, color, randomization, quality, wave parameters - driven by the Manager, editable locally when there isn't one.
• No Update, no LateUpdate. Values are pushed to the GPU only when something changes. Zero per-frame CPU cost.

CrowdManager

The scene-level component, usually one per scene. A single slider changes density on every plane at once. It keeps a list of controllers (Auto Collect gathers them on Awake) and, on every change, issues one batched SetGlobalParams() per controller - not one call per property.

• Global: Density, Anim Speed, Fade Start/End, Tint Color, Tint Variation, Random Seed, Flip, Edge Smoothness, Alpha Clip.
• Wave: direction, speed, band width, cheer-pose row, duration (0 = infinite).
• Jump: height, duration, wave propagation and delay per world unit.

CrowdWaveTrigger

Fires waves and jumps with no code. Needs a reference to the CrowdManager. Three modes, freely combined:

1. Keyboard - Trigger On Key Press plus a key (Space by default).
2. UI Button - in onClick, drag the object in and pick TriggerWave() or TriggerJump().
3. Collider zone - a Collider with Is Trigger, plus an optional tag filter (Player by default).

On top of that: a Cooldown (minimum gap between waves - blocks spamming) and two UnityEvents, On Wave Triggered and On Wave Blocked. Hook up a crowd roar, a controller rumble, whatever you need.

Custom inspectors

Both components ship with foldout inspectors. CrowdControllerEditor detects whether a Manager exists in the scene: global sections turn read-only (so you never edit the same value in two places) while per-plane sections stay active. It warns about a missing Renderer, a missing material and the wrong shader. CrowdManagerEditor gives you a controller count, Auto Collect All / Apply Globals Now buttons, and Trigger Wave / Jump plus Stop in Play mode. It also validates that Fade Start is below Fade End.

05Scripting API

Namespace SerwusStudio. Everything you set in the Inspector has a code equivalent - setters push to the GPU themselves, there is nothing to „refresh”.

CrowdManager - properties

CrowdManager - methods

CrowdController - methods

CrowdWaveTrigger - methods

Examples

using SerwusStudio;

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

    // goal - the crowd goes wild: faster animation, wave from the goal, jump
    public void OnGoalScored()
    {
        crowd.AnimSpeed = 8f;
        crowd.TriggerWaveFrom(homeGoal.position);
        crowd.TriggerJump();
        Invoke(nameof(CalmDown), 6f);
    }

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

    // team sectors - two Managers or two sets of materials
    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;
        }
    }

    // quality profile for VR / Quest
    public void ApplyVRProfile()
    {
        crowd.FadeStart = 30f;
        crowd.FadeEnd   = 60f;
    }
}

Register runtime-spawned planes manually - they then receive the full set of global settings:

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

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

06Shader parameters

The complete property list for the SerwusStudio/CrowdCheer shader - Inspector label, code-facing property name, range and default.

07Clip Bounds

Flat crowd planes on curved stands like to intersect - a corner of one plate pokes out from behind another, or through a railing. Clip Bounds solves it without cutting geometry: fragments outside a given world-space box are simply discarded.

• Enable Enable Clip Bounds on the CrowdController and set the Min/Max corners.
• The selected object draws an orange gizmo of the box - you see exactly what gets clipped.
• SetClipBoundsFromRenderer() snaps the box to the Renderer's current bounds - a good starting point before narrowing it by hand.
• The test is the first thing the shader does, so clipped fragments cost nothing further.

// clip the crowd to the sector bounds
controller.SetClipBounds(sector.bounds.min, sector.bounds.max);

// start from the mesh bounds, then narrow it down by hand
controller.SetClipBoundsFromRenderer();

// disable
controller.ClearClipBounds();

08Performance & VR

The system is lightweight by design, but the bottleneck will always be fillrate - the number of screen pixels covered by crowd planes. Everything below comes down to reducing that number.

What's free by construction

• Zero per-frame CPU cost - no component has an Update or LateUpdate. Data reaches the GPU only on change.
• MaterialPropertyBlock - no material duplication, GPU instancing preserved.
• Batched Apply() - a global change is one call per controller, not one per property.
• The wave costs nothing while asleep - at Wave Speed = 0 the shader never enters the wave block.
• Alpha cutout, not transparency - AlphaTest queue with ZWrite On, no transparency sorting.

VR / Quest / mobile

• Be aggressive with Distance Fade. On Quest: Fade Start 30, Fade End 60. On mobile: 40 / 80. Distant stands add nothing and cost fillrate.
• Lower tiling on far plates. A plane 40 metres out doesn't need 10×10 characters - 3×3 looks the same.
• 512² or 1024² atlas with Crunch compression. Characters are seen from a distance; the difference doesn't show.
• Enable GPU Instancing on the material when many planes share it.
• Single Pass Instanced works. The shader carries full stereo support: UNITY_VERTEX_INPUT_INSTANCE_ID, UNITY_VERTEX_OUTPUT_STEREO, UNITY_SETUP_STEREO_EYE_INDEX_POST_VERTEX. Tested on Quest 2 and Quest 3.

PC and console

You can afford a 2048² atlas, Fade End at 200+ and dense tiling. Lighting is the main directional light plus ambient SH - a realistic response to the scene at minimal cost.

09FAQ

10Changelog