Stats Perform NRL Match State Reference¶
Single source of truth for the Stats Perform Rugby League game state model and its mapping to the Foundry domain.
Related Files¶
- Mapper:
src/Integration/LBS.Fantasy.Integration/Importers/StatsPerform/League/StatsPerformNrlScoreboardMapper.cs - Timer:
src/Integration/LBS.Fantasy.Integration/Importers/StatsPerform/League/StatsPerformNrlScoreboardTimerService.cs - Importer overview: statsperform-nrl-scoreboard-importer.md
1. Stats Perform Game State Definitions¶
gameStateId |
SP State Name | Category | Description |
|---|---|---|---|
| 2 | Pre Game | Pre-match | Match has not yet started |
| 3 | First Half | Live | First period of play is active |
| 4 | Half Time | Interval | Half-time break |
| 5 | Second Half | Live | Second period of play is active |
| 6 | Extra Time | Live | Overtime in progress (ET1, ET2, or Golden Point) |
| 7 | Full Time | Post-match | Siren has sounded; match over but data not yet reviewed |
| 8 | Final | Post-match | Authoritative confirmed result; Stats Perform review complete |
| 9 | Live | Deprecated | Legacy state, no longer used |
| 11 | Game End | Post-match | Match processing complete on SP side; precedes Final |
| 12 | Postponed | Disruption | Match deferred; may resume later |
| 13 | Suspended | Disruption | Play stopped mid-match; period state unknown |
| 14 | Cancelled | Terminal | Match will not be played; terminal state |
2. State Transition Rules¶
Normal Match Flow¶
Pre Game (2) -> First Half (3) -> Half Time (4) -> Second Half (5) -> Full Time (7) -> Game End (11) -> Final (8)
Extra Time Flow¶
Second Half (5) -> [siren] -> Full Time (7) -> Extra Time (6) [period 3 or 4 or 5+] -> Full Time (7) -> Game End (11) -> Final (8)
Disruption Paths¶
Any state -> Postponed (12) -> Pre Game (2) [resumes]
-> Cancelled (14) [terminal]
Any state -> Suspended (13) -> resumes from prior play state
-> Cancelled (14) [terminal]
3. Post-Match State Progression¶
The three post-match states are important for data integrity:
| State | SP ID | Trigger |
|---|---|---|
| Full Time | 7 | Siren sounds - raw data, not yet reviewed |
| Game End | 11 | Stats Perform internal processing complete |
| Final | 8 | Human review complete - authoritative data |
Polling must continue through Full Time (7) and Game End (11) until Final (8) arrives.
CompletionTime is set when Final (8) is received, ensuring the 30-minute cache removal countdown does not start prematurely during post-match processing.
CompletionTime is also set when Cancelled (14) is received, since Abandoned is a terminal state with no further polling — the 30-minute countdown ensures the match is eventually evicted from the in-memory cache.
4. Foundry Mapping Tables¶
MatchStatus Mapping¶
| SP ID | SP State | Foundry MatchStatus |
Notes |
|---|---|---|---|
| 2 | Pre Game | Prematch |
|
| 3 | First Half | InProgress |
|
| 4 | Half Time | Halftime |
|
| 5 | Second Half | InProgress |
|
| 6 | Extra Time | InProgress |
|
| 7 | Full Time | FullTime |
Siren sounded; data not yet confirmed |
| 8 | Final | Completed |
Only state that maps to Completed |
| 9 | Live | Unknown |
Deprecated; no longer issued |
| 11 | Game End | FullTime |
SP processing done; awaiting Final |
| 12 | Postponed | Delayed |
|
| 13 | Suspended | Delayed |
|
| 14 | Cancelled | Abandoned |
Terminal |
Period Mapping¶
| SP ID | SP State | Foundry Period |
Notes |
|---|---|---|---|
| 2 | Pre Game | Prematch |
|
| 3 | First Half | FirstHalf |
|
| 4 | Half Time | FirstHalf |
Show completed period during interval |
| 5 | Second Half | SecondHalf |
|
| 6 | Extra Time | ExtraTime1 / ExtraTime2 / GoldenPoint |
Depends on numberOfPeriods |
| 7 | Full Time | FullTime |
|
| 8 | Final | FullTime |
|
| 9 | Live | Unknown |
Deprecated |
| 11 | Game End | FullTime |
|
| 12 | Postponed | Prematch |
No play has occurred |
| 13 | Suspended | Unknown |
Cannot determine prior period |
| 14 | Cancelled | Prematch |
No play has occurred |
5. Extra Time Behaviour¶
Extra time is signalled by a single gameStateId: 6. The numberOfPeriods field on GameStats determines which extra-time period is active:
numberOfPeriods |
Foundry Period |
|---|---|
| 3 | ExtraTime1 |
| 4 | ExtraTime2 |
| 5+ | GoldenPoint |
Each extra-time period boundary is indicated by stat events (period start/end).
Stats Perform does not issue a new gameStateId when moving from ET1 to ET2 — only numberOfPeriods changes.
6. Period Boundary Events¶
Stats Perform issues stat events at period transitions. Two sets are available:
Set A (recommended)¶
| Stat ID | Event |
|---|---|
period_start |
Period begins |
period_end |
Period ends |
Set B (alternative)¶
| Stat ID | Event |
|---|---|
half_start |
Half begins |
half_end |
Half ends |
Use Set A where available; fall back to Set B for older feeds.
7. Team Lineup Status¶
The teamLineUpStatusID field on each team record indicates the state of the announced squad:
| Value | Meaning |
|---|---|
| 1 | Not submitted |
| 2 | 24-man squad submitted |
| 3 | 17-man team submitted |
| 4 | Team locked (kick-off imminent or in progress) |
Lock lineups when teamLineUpStatusID == 4 or when play begins (gameStateId 3).
8. XY Coordinate System¶
Stats Perform uses a normalised field coordinate space:
- Origin: top-left corner of the field (from the attacking team's perspective)
- X axis: 0 to 100 (left to right)
- Y axis: 0 to 100 (top to bottom)
- Centre: (50, 50)
Zone codes correspond to field thirds and halves as defined in the Stats Perform zone reference (contact Stats Perform for the full zone boundary table).
9. Live Feed Behaviour¶
| Property | Detail |
|---|---|
| Update frequency | Push events within seconds of on-field action |
| Latency | Typically 5-15 seconds from event to feed delivery |
| Data completeness | Incomplete until Final (8); corrections may arrive after Full Time |
| Stat corrections | Stats Perform may amend stats after Game End until Final is issued |
Always wait for Final (8) before treating stats as authoritative.
10. Score Field Relationships¶
| Field | When populated |
|---|---|
teamHalfTimeScore |
After Half Time (4) |
teamFullTimeScore |
After Full Time (7) — may include ET score in regular-time-only matches |
teamExtraTimeScore |
Only when extra time is played |
teamFinalScore |
After Final (8) — authoritative total |
Note: teamFullTimeScore reflects score at the end of regulation, not end of extra time. Use teamFinalScore for the definitive result.
11. Timer Polling Rates¶
Foundry MatchStatus |
Source State(s) | Poll Interval |
|---|---|---|
Prematch |
Pre Game (2) | Sliding scale: 10s within 1 min, 1 min within 10 min, 10 min otherwise |
InProgress |
First Half (3), Second Half (5), Extra Time (6) | Every 5 seconds |
Halftime |
Half Time (4) | Every 1 minute |
FullTime |
Full Time (7), Game End (11) | Every 1 minute — awaiting Final |
Completed |
Final (8) | Every 5 minutes — wind-down, removed after 30 minutes |
Delayed |
Postponed (12), Suspended (13) | Every 5 minutes |
Abandoned |
Cancelled (14) | No polling — terminal state |
12. Open Items¶
| # | Item | Status |
|---|---|---|
| 1 | Zone boundary coordinates | Not yet received from Stats Perform |
| 2 | Milestone score timing (first try, 50th point, etc.) | Under investigation |
| 3 | Push feed schema for real-time delivery | Pending Stats Perform documentation |
| 4 | Exact timing of numberOfPeriods increment at ET period start |
Unconfirmed from live data |