Skip to content

NFL Game Simulation Flowchart — Glossary

Terms used across the flowchart and its supporting docs. Domain vocabulary (NFL game / simulator state machine) and doc-framework vocabulary (how this project models the source) both live here.

Language

Source-machine terms

State: A node in the simulator's state machine, defined as an entry in the HTML's STATES object with a title, category, and outcomes array. Avoid: node, step (when referring to source-machine entries specifically).

Outcome: A labeled transition from one State to another. Each outcome carries a label, a next (target state ID), and an effect. Avoid: transition (use only when discussing the abstract edge), branch, choice.

Effect: The game-state modification applied when an Outcome is taken — e.g., changing possession, advancing the down, ticking the clock. Avoid: side effect, mutation.

Source category: The category field on a State in the HTML. Five values exist: game_setup, kickoff, drive, scoring, game_end. Used for cross-referencing the doc to the source — not used to organize the doc. Avoid: phase (these are distinct concepts here — see below).

Doc-framework terms

Phase: A top-level grouping in the flowchart. Three phases exist: Initialization, Play Execution, Play Aftermath. Phases group sub-diagrams by causal role, not by source category. Avoid: tier, section (use "section" only for markdown headings).

Initialization phase: The one-time game-start sequence. Contains the Coin Toss sub-diagram only.

Play Execution phase: Dead-ball moments and play executions — where a team makes a choice or where a play unfolds. Eight sub-diagrams: Kickoff, Drive Cycle, Pass, Rush, Punt, FG, Spike & Kneel, PAT. Avoid: decision phase (we considered this — "Play Execution" was chosen because it covers both decisions and the executions that follow). Note: called "Cause phase" in early drafts; renamed for football-domain readability.

Play Aftermath phase: Resolution logic that runs after plays execute — quantifying yardage, advancing the clock, settling fumbles, handling period boundaries. Four sub-diagrams: Yards Selector, Post-Play Pipeline, Loose-Ball Recovery, End of Period. Avoid: resolution phase, post-play phase. Note: called "Effects phase" in early drafts; renamed for football-domain readability.

Sub-diagram: A single Mermaid flowchart inside a phase section (e.g., the Pass sub-diagram in section 3b.1). Each sub-diagram is a strict tree. Avoid: diagram (ambiguous between the whole doc's diagrams and a single one).

Strict tree: A sub-diagram with no back-edges and no convergence — every node has at most one inbound edge from within the same sub-diagram. Flow is purely top-to-bottom. The Phase Map (section 1) is the only deliberate exception.

Terminal exit node: A leaf node in a sub-diagram labeled → DestinationName (e.g., → Drive Cycle). Names where the flow continues in another sub-diagram. Drawn with stadium shape (([…])) and colored by the destination's phase. Avoid: exit, leaf (too generic).

Phase Map: The high-level orchestration diagram in section 1 of the flowchart. The only place that shows cycles between phases. Every other sub-diagram is a strict tree.

Elision rule: A label-only pass-through state in the source — one with a single outgoing transition and no distinct routing logic — is omitted from the flowchart. The source edge label carries the event name; the diagram jumps directly to the terminal exit. States with two or more outgoing transitions are always shown explicitly, even when all routes lead to the same next state. Documented in UPDATING.md.

Relationships

  • A State has zero or more Outcomes.
  • An Outcome has exactly one next State and zero or one Effect.
  • A State belongs to exactly one Source category.
  • A Sub-diagram in the flowchart depicts one or more States as a Strict tree.
  • A Sub-diagram belongs to exactly one Phase.
  • A Sub-diagram has zero or more Terminal exit nodes pointing to other sub-diagrams.
  • A Phase contains one or more Sub-diagrams.

Example dialogue

Reader: "What's a Play Execution phase diagram? Is the Pass diagram in Play Execution or Play Aftermath?" Maintainer: "Pass is in Play Execution. The Play Execution phase covers dead-ball moments AND play executions — when the offense calls Pass, the simulator transitions to the Pass state and the play unfolds. The resolutions (yardage, fumble recovery, clock) are Play Aftermath." Reader: "And the source's category field calls Pass drive, right? Why don't we use that?" Maintainer: "The source groups by game area; we group by causal role. Source category appears as italic metadata on each heading so you can map back, but it doesn't drive the doc structure. See UPDATING.md."

Flagged ambiguities

  • "Phase" vs "source category" — early drafts used "phase" interchangeably for both the doc's 3-phase abstraction and the source's 5 category values. Resolved: "phase" refers exclusively to the doc-framework grouping (Initialization / Play Execution / Play Aftermath); "source category" refers to the HTML's category field.

  • "Decision" vs "Play Execution" — an earlier draft named the middle phase "Decision," but the play-execution sub-diagrams (Pass, Rush, etc.) don't fit that label well since the decision was made in Drive Cycle's Play Call. The working name "Cause" was used briefly but felt too abstract and generic. Resolved: "Play Execution" is broader, football-domain specific, and accurately covers both decisions and the play executions they trigger.