NFL Game Simulation — State Machine Flowchart¶

Interactive companion: nfl_sim_flowchart.html — pan, zoom, and click between phases.

A readable visualization of the state machine in nfl_model_flow_diagram.htm. The simulator models an NFL game as ~40 states with branching outcomes; this document organizes those states into 3 phases and presents each as a tree-shaped sub-diagram.

How to read:

Section 1 (Phase Map) shows the three-phase orchestration. Every sub-diagram below is a strict tree (top-to-bottom, no back-edges). Note: the loop from Play Aftermath back to Play Execution is documented in the sub-diagram descriptions.
Terminal exit nodes (→ X) name where the flow continues. Phase context comes from color: green = Play Execution target, yellow-bordered = Play Aftermath target.
Each sub-section heading shows the source's category field in italics for cross-reference with the HTML.

For term definitions (phase, sub-diagram, terminal exit node, etc.), see CONTEXT.md. For the design decisions behind the doc's structure, see UPDATING.md.

1. Phase Map¶

The three phases stacked top-to-bottom, with the 14 sub-diagrams shown clustered by phase. Inter-phase arrows show the high-level orchestration. Within Play Execution and Play Aftermath, sub-diagrams can chain to each other before crossing phase boundaries — see individual diagrams for specifics.

flowchart TD
    Start([Game Start]) --> Init

    subgraph Init [Initialization phase]
        direction LR
        CT[Coin Toss]
    end

    subgraph Cause [Play Execution phase]
        direction TB
        K[Kickoff]
        DC[Drive Cycle]
        subgraph Plays [Plays]
            direction TB
            PASS[Pass]
            RUSH[Rush]
            PUNT[Punt]
            FG[FG]
            SP[Spike]
            KN[Kneel]
        end
        PAT[PAT]
    end

    subgraph Effects [Play Aftermath phase]
        direction TB
        YS[Yards Gained]
        PPP[Post-Play Pipeline]
        LBR[Loose-Ball Recovery]
        EOP[End of Period]
    end

    Init --> Cause
    Cause -->|play executes / clock runs| Effects
    Effects --> GO([Game Over])
    DC --> Plays

    classDef init fill:#2a2a2e,stroke:#888,color:#fff
    classDef cause fill:#1a3a1f,stroke:#4caf50,color:#fff
    classDef effects fill:#3d3520,stroke:#ffc800,color:#fff
    classDef end_ fill:#3d1818,stroke:#ff6b6b,color:#fff

    class CT init
    class K,DC,PASS,RUSH,PUNT,FG,SP,KN,PAT cause
    class YS,PPP,LBR,EOP effects
    class GO end_

2. Initialization phase¶

One-time game-start sequence.

2a. Coin Toss — source category: `game_setup`¶

flowchart TD
    CT[Coin Toss] -->|Team A wins| CTE[Coin Toss — Election]
    CT -->|Team B wins| CTE
    CTE -->|Elect to receive| KO1([→ Kickoff])
    CTE -->|Elect to kick| KO2([→ Kickoff])

    classDef init fill:#2a2a2e,stroke:#888,color:#fff
    classDef causeExit fill:#1a3a1f,stroke:#4caf50,color:#fff
    class CT,CTE init
    class KO1,KO2 causeExit

3. Play Execution phase¶

Dead-ball moments and play executions. Eight diagrams. The Play Execution phase is internally a graph — most diagrams here exit to other Play Execution diagrams (Kickoff → Drive Cycle → Pass, etc.). Only when a play resolves does the flow cross into the Play Aftermath phase.

3a. Kickoff — source category: `kickoff`¶

flowchart TD
    K[Kickoff]
    K --> KR[Kickoff Return]
    K --> TB[Touchback]
    K --> OOB[Kickoff OOB]
    K --> FC[Fair Catch]
    K --> MUF[Muffed Kickoff]
    K --> ON[Onside Kick]

    KR -->|Downed| DC1([→ Drive Cycle])
    KR -->|Returned for a touchdown!| PAT1([→ PAT])
    KR -->|Fumble during the return| RF[Fumble During Return]
    RF -->|Receiving team recovers| DC5([→ Drive Cycle])
    RF -->|Kicking team recovers| DC6([→ Drive Cycle])

    TB --> DC2([→ Drive Cycle])
    FC --> DC3([→ Drive Cycle])
    OOB -->|Accept at own 40| DC4([→ Drive Cycle])
    OOB -->|Re-kick| KORE([→ Kickoff<br/>no Onside Kick])

    MUF -->|Receiving team recovers| DC7([→ Drive Cycle])
    MUF -->|Kicking team recovers| DC8([→ Drive Cycle])
    ON -->|Kicking team recovers| DC9([→ Drive Cycle])
    ON -->|Receiving team recovers| DC10([→ Drive Cycle])

    classDef cause fill:#1a3a1f,stroke:#4caf50,color:#fff
    classDef causeExit fill:#1a3a1f,stroke:#4caf50,color:#fff,stroke-dasharray: 3 3

    class K,KR,TB,OOB,FC,MUF,ON,RF cause
    class DC1,DC2,DC3,DC4,DC5,DC6,DC7,DC8,DC9,DC10,KORE,PAT1 causeExit

3b. Drive Cycle — source category: `drive`¶

The dead-ball pipeline that runs before every snap.

flowchart TD
    PS[Possession Set] --> TW[Timeout Window]
    TW -->|No timeout| PRE[Pre-Snap]
    TW -->|Team A calls timeout| PRE
    TW -->|Team B calls timeout| PRE
    PRE -->|Set personnel, formation & coverage| PC[Play Call]
    PC --> PASS([→ Pass])
    PC --> RUSH([→ Rush])
    PC --> PUNT([→ Punt])
    PC --> FG([→ FG])
    PC --> SPK([→ Spike])
    PC --> KNL([→ Kneel])

    classDef cause fill:#1a3a1f,stroke:#4caf50,color:#fff
    classDef causeExit fill:#1a3a1f,stroke:#4caf50,color:#fff,stroke-dasharray: 3 3

    class PS,TW,PRE,PC cause
    class PASS,RUSH,PUNT,FG,SPK,KNL causeExit

The following subsections (3b.1–3b.6) detail each play type selected by Play Call.

3b.1–3b.6. Play Execution (children of Drive Cycle)¶

3b.1. Pass — source category: `drive`¶

flowchart TD
    PASS[Pass]
    PASS -->|Completion| PC2[Pass Complete — YAC]
    PASS -->|Incomplete| PPP1([→ Post-Play Pipeline])
    PASS -->|Interception| INT[Interception]
    PASS -->|Sack| SACK[Sack]

    PC2 -->|Receiver downed| YS1([→ Yards Selector])
    PC2 -->|Receiver gains YAC| YS2([→ Yards Selector])
    PC2 -->|Touchdown — reaches the end zone!| PAT1([→ PAT])
    PC2 -->|Fumble| LBR1([→ Loose-Ball Recovery])

    INT -->|Downed at catch| DC1([→ Drive Cycle])
    INT -->|Returned downfield| INTR[Interception Return]
    INT -->|Returned for a touchdown!| PAT2([→ PAT])

    INTR -->|Downed in field| DC2([→ Drive Cycle])
    INTR -->|Returned for a TD!| PAT3([→ PAT])
    INTR -->|Fumble during return| LBR2([→ Loose-Ball Recovery])

    SACK -->|Downed| YS3([→ Yards Selector])
    SACK -->|Fumble| LBR3([→ Loose-Ball Recovery])
    SACK -->|Safety — QB downed in own end zone| KO1([→ Kickoff])

    classDef cause fill:#1a3a1f,stroke:#4caf50,color:#fff
    classDef causeExit fill:#1a3a1f,stroke:#4caf50,color:#fff,stroke-dasharray: 3 3
    classDef effectsExit fill:#3d3520,stroke:#ffc800,color:#fff,stroke-width:2px

    class PASS,PC2,INT,INTR,SACK cause
    class PAT1,PAT2,PAT3,KO1,DC1,DC2 causeExit
    class PPP1,YS1,YS2,YS3,LBR1,LBR2,LBR3 effectsExit

3b.2. Rush — source category: `drive`¶

flowchart TD
    RUSH[Rush]
    RUSH -->|Downed| YS1([→ Yards Selector])
    RUSH -->|Touchdown — ball carrier reaches the end zone!| PAT1([→ PAT])
    RUSH -->|Fumble| LBR1([→ Loose-Ball Recovery])
    RUSH -->|Safety — ball carrier downed in own end zone| KO1([→ Kickoff])

    classDef cause fill:#1a3a1f,stroke:#4caf50,color:#fff
    classDef causeExit fill:#1a3a1f,stroke:#4caf50,color:#fff,stroke-dasharray: 3 3
    classDef effectsExit fill:#3d3520,stroke:#ffc800,color:#fff,stroke-width:2px

    class RUSH cause
    class PAT1,KO1 causeExit
    class YS1,LBR1 effectsExit

3b.3. Punt — source category: `drive`¶

flowchart TD
    PUNT[Punt]
    PUNT -->|Return| PR[Punt Return]
    PUNT -->|Touchback| DC1([→ Drive Cycle])
    PUNT -->|Out of Bounds| DC2([→ Drive Cycle])
    PUNT -->|Fair Catch| DC3([→ Drive Cycle])
    PUNT -->|Muffed| LBR1([→ Loose-Ball Recovery])
    PUNT -->|Blocked| BK[Blocked Kick]

    PR -->|Downed| DC4([→ Drive Cycle])
    PR -->|Returned for a TD!| PAT1([→ PAT])
    PR -->|Fumble| LBR2([→ Loose-Ball Recovery])

    BK -->|Kicking recovers| DC5([→ Drive Cycle])
    BK -->|Defense recovers and advances| PR
    BK -->|Defense returns for a touchdown!| PAT2([→ PAT])

    classDef cause fill:#1a3a1f,stroke:#4caf50,color:#fff
    classDef causeExit fill:#1a3a1f,stroke:#4caf50,color:#fff,stroke-dasharray: 3 3
    classDef effectsExit fill:#3d3520,stroke:#ffc800,color:#fff,stroke-width:2px

    class PUNT,PR,BK cause
    class DC1,DC2,DC3,DC4,DC5,PAT1,PAT2 causeExit
    class LBR1,LBR2 effectsExit

3b.4. FG — source category: `drive`¶

flowchart TD
    FG[FG Attempt]
    FG -->|Good! — 3 points| KO1([→ Kickoff])
    FG -->|Missed| DC1([→ Drive Cycle])
    FG -->|Blocked| BK[Blocked Kick]

    BK -->|Kicking recovers| DC2([→ Drive Cycle])
    BK -->|Defense recovers and advances| PR[Punt Return]
    BK -->|Defense returns for a touchdown!| PAT1([→ PAT])

    PR -->|Downed| DC3([→ Drive Cycle])
    PR -->|Returned for a TD!| PAT2([→ PAT])
    PR -->|Fumble| LBR1([→ Loose-Ball Recovery])

    classDef cause fill:#1a3a1f,stroke:#4caf50,color:#fff
    classDef causeExit fill:#1a3a1f,stroke:#4caf50,color:#fff,stroke-dasharray: 3 3
    classDef effectsExit fill:#3d3520,stroke:#ffc800,color:#fff,stroke-width:2px

    class FG,BK,PR cause
    class KO1,DC1,DC2,DC3,PAT1,PAT2 causeExit
    class LBR1 effectsExit

3b.5. Spike — source category: `drive`¶

flowchart TD
    SPK[Spike] --> PPP1([→ Post-Play Pipeline])

    classDef cause fill:#1a3a1f,stroke:#4caf50,color:#fff
    classDef effectsExit fill:#3d3520,stroke:#ffc800,color:#fff,stroke-width:2px

    class SPK cause
    class PPP1 effectsExit

3b.6. Kneel — source category: `drive`¶

flowchart TD
    KNL[Kneel] --> PPP1([→ Post-Play Pipeline])
    KNL -->|End of period| EOP1([→ End of Period])

    classDef cause fill:#1a3a1f,stroke:#4caf50,color:#fff
    classDef effectsExit fill:#3d3520,stroke:#ffc800,color:#fff,stroke-width:2px

    class KNL cause
    class PPP1,EOP1 effectsExit

3c. PAT — source category: `scoring`¶

Each leaf has its own terminal → Kickoff exit — the post_td_kickoff state still runs in between (single outcome to kickoff, so elided into the terminal node).

flowchart TD
    PD[PAT Decision]
    PD -->|Kick| P1[1-Point Try]
    PD -->|Go for 2| P2C[2-Point Call]

    P1 -->|Made +1| KO1([→ Kickoff])
    P1 -->|Missed| KO2([→ Kickoff])
    P1 -->|Blocked + returned 2pt| KO3([→ Kickoff])
    P1 -->|Blocked| PB[PAT Blocked]

    P2C -->|Rush attempt| P2R[2-Point Result]
    P2C -->|Pass attempt| P2R
    P2R -->|Success +2| KO4([→ Kickoff])
    P2R -->|Fail| KO5([→ Kickoff])

    PB -->|Kicking recovers| KO6([→ Kickoff])
    PB -->|Defense returns +2| KO7([→ Kickoff])

    classDef cause fill:#1a3a1f,stroke:#4caf50,color:#fff
    classDef causeExit fill:#1a3a1f,stroke:#4caf50,color:#fff,stroke-dasharray: 3 3

    class PD,P1,P2C,P2R,PB cause
    class KO1,KO2,KO3,KO4,KO5,KO6,KO7 causeExit

4. Play Aftermath phase¶

Resolution logic that runs after plays execute. Four diagrams — three are post-play resolvers, one is the period-boundary handler.

4a. Yards Gained — source category: `drive`¶

Shared resolver — both Pass-completed and Rush route through here to quantify yardage.

flowchart TD
    YS[Yards Gained]
    YS -->|Yardage result| PPP1([→ Post-Play Pipeline])
    YS -->|4th down failed| PPP2([→ Post-Play Pipeline])
    YS -->|Crosses goal| PAT([→ PAT])
    YS -->|Pushed into own EZ| KO([→ Kickoff])

    classDef effects fill:#3d3520,stroke:#ffc800,color:#fff
    classDef causeExit fill:#1a3a1f,stroke:#4caf50,color:#fff,stroke-dasharray: 3 3
    classDef effectsExit fill:#3d3520,stroke:#ffc800,color:#fff,stroke-width:2px

    class YS effects
    class PAT,KO causeExit
    class PPP1,PPP2 effectsExit

4b. Post-Play Pipeline — source category: `drive`¶

Runs after every play.

flowchart TD
    PCK[Penalty Check]
    PCK --> POFF[Offense Penalty]
    PCK --> CLK[Clock Update]
    PCK --> PDEF[Defense Penalty]
    POFF -->|Defense accepts| CLK
    POFF -->|Defense declines| CLK
    PDEF -->|Offense accepts| CLK
    PDEF -->|Offense declines| CLK
    CLK -->|Clock ≤ 2:00| TMW[Two-Min Warning]
    CLK -->|Time remaining| DC1([→ Drive Cycle])
    CLK -->|Clock at 0:00| EOP1([→ End of Period])
    TMW --> DC2([→ Drive Cycle])

    classDef effects fill:#3d3520,stroke:#ffc800,color:#fff
    classDef causeExit fill:#1a3a1f,stroke:#4caf50,color:#fff,stroke-dasharray: 3 3
    classDef effectsExit fill:#3d3520,stroke:#ffc800,color:#fff,stroke-width:2px

    class PCK,POFF,PDEF,CLK,TMW effects
    class DC1,DC2 causeExit
    class EOP1 effectsExit

4c. Loose-Ball Recovery — source category: `drive`¶

Called from fumbles during plays (pass completions, rushes, sacks, punt returns, interception returns). Kickoff-phase loose balls (muffed kickoffs, return fumbles, onside kicks) resolve directly to Drive Cycle without entering this sub-diagram.

flowchart TD
    LB[Loose Ball]
    LB -->|Offense recovers| OREC[Offense at recovery spot]
    LB -->|Defense recovers| DREC[Defense at recovery spot]
    OREC --> PPP1([→ Post-Play Pipeline])
    DREC --> PPP2([→ Post-Play Pipeline])

    classDef effects fill:#3d3520,stroke:#ffc800,color:#fff
    classDef effectsExit fill:#3d3520,stroke:#ffc800,color:#fff,stroke-width:2px

    class LB,OREC,DREC effects
    class PPP1,PPP2 effectsExit

4d. End of Period — source category: `game_end`¶

flowchart TD
    EOP[End of Period]
    EOP -->|Q1 end| DC1([→ Drive Cycle<br/>same possession])
    EOP -->|Q2 end — halftime| KO([→ Kickoff])
    EOP -->|Q3 end| DC3([→ Drive Cycle<br/>same possession])
    EOP -->|Q4 end — game over| GO([Game Over])

    classDef effects fill:#3d3520,stroke:#ffc800,color:#fff
    classDef causeExit fill:#1a3a1f,stroke:#4caf50,color:#fff,stroke-dasharray: 3 3
    classDef end_ fill:#3d1818,stroke:#ff6b6b,color:#fff

    class EOP effects
    class DC1,DC3,KO causeExit
    class GO end_

NFL Game Simulation — State Machine Flowchart¶

1. Phase Map¶

2. Initialization phase¶

2a. Coin Toss — source category: game_setup¶

3. Play Execution phase¶

3a. Kickoff — source category: kickoff¶

3b. Drive Cycle — source category: drive¶

3b.1–3b.6. Play Execution (children of Drive Cycle)¶

3b.1. Pass — source category: drive¶

3b.2. Rush — source category: drive¶

3b.3. Punt — source category: drive¶

3b.4. FG — source category: drive¶

3b.5. Spike — source category: drive¶

3b.6. Kneel — source category: drive¶

3c. PAT — source category: scoring¶