Rounds & Stock Levels

Four phases

RoundController moves a level through Waiting → Countdown → Running → Finished, and every other piece of the level reacts to the phase rather than tracking its own idea of what is going on.

The two zones

A round needs a start zone and an end zone, each a TriggerBehaviour. They are ordinary trigger volumes — the same component any other rule uses — so a start pad can also run instructions, play a sound or gate on a condition without becoming a special case.

The start zone answers "is everyone here yet?". The end zone answers "have you finished?" — and how strictly it answers that is a field, because getting it wrong is very visible:

Configuring the round

Making a level a round

1. Mark the two zones

   Put a TriggerBehaviour on a start volume and another on a finish volume. Box colliders marked as triggers; size them generously for the start, deliberately for the finish.

2. Add the controller

   Add RoundController to the level and assign both zones.

3. Pick the shape of the game

   AllPlayersFinish for a co-op course everyone completes together, FirstPlayerFinishes for a race. Set the time limit; it is what turns a stuck round into a results board rather than a stalemate.

4. Decide the rules of the run

   Out-of-bounds respawn or game over. Stats to switch off. Whether gates re-close each round. Every one of these is a field, and none of them is code.

Results

Each participant gets a RoundPlayerResult: whether they finished, their finish time in seconds since the round started, and how many times they failed. Unfinished players at the time limit are DNFs, and in a FirstPlayerFinishes round everyone but the winner is.

Subscribe to OnPhaseChanged and OnResultsChanged rather than polling — the HUD does, and so should anything you add:

using Curitor.PartyCoreKit.Rounds;
using UnityEngine;

public class RoundWatcher : MonoBehaviour
{
    private void OnEnable()
    {
        RoundController round = RoundController.Active;
        if (round == null) return;

        round.OnPhaseChanged += HandlePhase;
        round.OnResultsChanged += HandleResults;
    }

    private void OnDisable()
    {
        RoundController round = RoundController.Active;
        if (round == null) return;

        round.OnPhaseChanged -= HandlePhase;
        round.OnResultsChanged -= HandleResults;
    }

    private void HandlePhase(RoundPhase phase)
    {
        // PhaseRemaining counts down within Countdown, Running and Finished.
        Debug.Log($"{phase}, {RoundController.Active.PhaseRemaining:0.0}s left");
    }

    private void HandleResults()
    {
        foreach (RoundPlayerResult result in RoundController.Active.Results)
        {
            Debug.Log(result.Finished
                ? $"{result.PlayerId} finished in {result.FinishTime:0.00}s"
                : $"{result.PlayerId} DNF after {result.Fails} fails");
        }
    }
}

When the end zone is not the answer

A lap race does not finish by entering a volume — it finishes after three laps, which happens to pass through the same volume twice before it counts. So "has this player finished?" is an extension seam, not a hard-coded zone test:

namespace Curitor.PartyCoreKit.Rounds
{
    public interface IRoundFinishSource
    {
        bool HasFinished(GameObject playerRoot);
    }
}

Call SetFinishSource on the controller and your rule replaces the zone test entirely. LapTracker is the shipped implementation, and it is worth reading as the reference: checkpoints in order, a lap count, and a finish that only counts once the laps are done. Every gate a runner passes in order also becomes their respawn checkpoint (Gates Are Checkpoints on the Lap Tracker, on by default), so a fall sends them back to the last gate they passed, facing the next one — not to the start line.

Open it: SceneFlow/Levels/RoundsShowcase.unity is this pattern built and running — four gates in route order, a LapTracker wired up in the hierarchy, and a door that stays shut until the final lap. The door is an ordinary Trigger with a lap condition on it; swap that condition for Has Item or Compare Number and the same wiring becomes a key door or a score gate. The scene also runs as a best-of-three RoundSeries (below) — select the Round object to see it configured, and check the standings on the results panel between rounds.

Series: best of N

RoundController on its own loops forever — Finished auto-reloads back to Waiting, round after round, with no concept of a match. RoundSeriesis the opt-in aggregate on top: drop it on the same GameObject as the controller and it tallies points from each round's finish placement, stops the auto-reload once the series is decided, and leaves the final standings up instead of quietly starting round 4.

Placement comes from the exact same ordering the results screen already shows (finishers by time, then DNFs by however far they got) — the series can never rank a round differently than the player just watched it resolve on screen. A round win (forFirstToNWins) is 1st place with Finished true; an unfinished leader does not bank a win.

The seam: vetoing the auto-reload

RoundSeries is not special-cased into RoundController — it plugs into the same kind of small seam IRoundFinishSourceuses for a custom finish rule, one level later in the round's life:

namespace Curitor.PartyCoreKit.Rounds
{
    public interface IRoundContinuationSource
    {
        // True lets the round's own auto-reload proceed, unchanged.
        // False vetoes it: the round stays in RoundPhase.Finished, frozen
        // on its current results, and does NOT reload. Authority-side
        // only, consulted once per round end.
        bool ShouldAutoReload();
    }
}

RoundController.SetContinuationSource(source) installs one; null (the default) is exactly the old behaviour — every round auto-reloads. This is the smallest seam that madeRoundSeriespossible without touching the round's own state machine, and it is just as available for a custom match structure — a tournament bracket, a sudden-death decider, anything that needs the last word on whether a finished round moves on.

Multiplayer