ChuckBuilds · ChuckBuilds · Jul 10, 2026
diff --git a/plugins.json b/plugins.json
@@ -972,6 +972,28 @@
       "verified": false,
       "screenshot": "",
       "latest_version": "1.0.0"
+    },
+    {
+      "id": "afl-scoreboard",
+      "name": "AFL Scoreboard",
+      "description": "Live, recent, and upcoming AFL (Australian Football League) games with real-time scores and game status.",
+      "author": "ChuckBuilds",
+      "category": "sports",
+      "tags": [
+        "afl",
+        "australian-football",
+        "sports",
+        "scoreboard",
+        "live-scores"
+      ],
+      "repo": "https://github.com/ChuckBuilds/ledmatrix-plugins",
+      "branch": "main",
+      "plugin_path": "plugins/afl-scoreboard",
+      "stars": 0,
+      "downloads": 0,
+      "verified": true,
+      "screenshot": "",
+      "latest_version": "1.0.0"
     }
   ]
 }
diff --git a/plugins/afl-scoreboard/.gitignore b/plugins/afl-scoreboard/.gitignore
@@ -0,0 +1,146 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypcache__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# OS specific files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Project specific
+*.log
+config.json
+*.pem
diff --git a/plugins/afl-scoreboard/LICENSE b/plugins/afl-scoreboard/LICENSE
@@ -0,0 +1,17 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2025 LEDMatrix Team
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
diff --git a/plugins/afl-scoreboard/README.md b/plugins/afl-scoreboard/README.md
@@ -0,0 +1,152 @@
+-----------------------------------------------------------------------------------
+### Connect with ChuckBuilds
+
+- Show support on Youtube: https://www.youtube.com/@ChuckBuilds
+- Stay in touch on Instagram: https://www.instagram.com/ChuckBuilds/
+- Want to chat or need support? Reach out on the ChuckBuilds Discord: https://discord.com/invite/uW36dVAtcT
+- Feeling Generous? Support the project:
+  - Github Sponsorship: https://github.com/sponsors/ChuckBuilds
+  - Buy Me a Coffee: https://buymeacoffee.com/chuckbuilds
+  - Ko-fi: https://ko-fi.com/chuckbuilds/ 
+
+-----------------------------------------------------------------------------------
+
+# AFL Scoreboard Plugin
+
+A plugin for LEDMatrix that displays live, recent, and upcoming **AFL (Australian
+Football League)** games with real-time scores and game status.
+
+## Features
+
+- **Live Game Tracking**: Real-time scores, quarter (Q1–Q4), and running clock
+- **Recent Games**: Recently completed games with final scores
+- **Upcoming Games**: Scheduled games with start times
+- **Favorite Teams**: Prioritize (or exclusively show) games involving your favorite teams
+- **Switch or Scroll**: Show one game at a time, or scroll all games horizontally
+- **Dynamic Duration & Live Priority**: Spend more time on live games; let live games interrupt the rotation
+- **Background Data Fetching**: Efficient API calls without blocking the display
+
+## Display Modes
+
+The plugin exposes three display modes:
+
+1. **afl_live** — currently active games (quarter + clock)
+2. **afl_recent** — recently completed games with final scores
+3. **afl_upcoming** — scheduled upcoming games with start times
+
+During a live game the status area shows:
+
+- **Q1 / Q2 / Q3 / Q4** — the current quarter, followed by the running clock (e.g. `Q3 12:45`)
+- **HALF** — the main break after the second quarter
+- **Final** — completed game
+- the scheduled start time for upcoming games
+
+## Configuration
+
+AFL is a single league, so all settings live at the top level of the plugin
+config (there is no per-league nesting).
+
+```json
+{
+  "enabled": true,
+  "favorite_teams": ["COLL", "GEEL", "RICH"],
+  "exclude_teams": [],
+  "show_favorite_teams_only": false,
+  "display_modes": {
+    "live": true,
+    "recent": true,
+    "upcoming": true,
+    "live_display_mode": "switch",
+    "recent_display_mode": "switch",
+    "upcoming_display_mode": "switch"
+  },
+  "display_duration": 30,
+  "live_game_duration": 20,
+  "non_favorite_live_game_duration": 0,
+  "recent_game_duration": 15,
+  "upcoming_game_duration": 15,
+  "recent_games_to_show": 5,
+  "upcoming_games_to_show": 10,
+  "update_interval_seconds": 300,
+  "live_update_interval": 30,
+  "show_records": false,
+  "show_odds": false,
+  "live_priority": false,
+  "celebration_enabled": true,
+  "celebration_duration": 8
+}
+```
+
+### Key settings
+
+| Setting | Default | Effect |
+|---|---|---|
+| `favorite_teams` | `[]` | AFL team abbreviations to prioritize (e.g. `COLL`, `GEEL`, `RICH`). |
+| `exclude_teams` | `[]` | Teams to always hide — from both the live rotation and recent/final scores (spoiler protection). |
+| `show_favorite_teams_only` | `false` | Only show games involving `favorite_teams`. |
+| `display_modes.*_display_mode` | `switch` | `switch` shows one game at a time; `scroll` scrolls all games horizontally. |
+| `display_duration` | `30` | How long each display mode stays on screen before cycling. |
+| `live_game_duration` | `20` | Seconds each live game stays on screen. |
+| `non_favorite_live_game_duration` | `0` | Shorter dwell for live games with no favorite team (0 = off). |
+| `live_priority` | `false` | Let live AFL games interrupt the recent/upcoming rotation. |
+| `dynamic_duration` | off | Size a mode's total on-screen time to the number of games it has. |
+| `mode_durations` | null | Fix the total duration of each mode (overrides dynamic calculation). |
+
+## Team Names & Abbreviations
+
+The `favorite_teams` / `exclude_teams` fields require the **ESPN API
+abbreviation** for each team (e.g. `"COLL"` for Collingwood, `"GEEL"` for
+Geelong). Full team names are not supported.
+
+> **Tip:** If you're unsure of an abbreviation, enable debug logging — the plugin
+> logs `home_abbr` and `away_abbr` for every game it processes.
+
+## Team Logos
+
+Team logos are downloaded automatically from ESPN's CDN on first use and cached to
+disk — no manual asset work is required. If a logo can't be fetched, a generated
+text-abbreviation placeholder is drawn instead.
+
+## Data Source
+
+Game data is fetched from ESPN's public AFL scoreboard endpoint (no API key
+required):
+
+```
+https://site.api.espn.com/apis/site/v2/sports/australian-football/afl/scoreboard
+```
+
+## Dependencies
+
+This plugin requires the main LEDMatrix installation and uses the plugin system
+base classes.
+
+## Installation
+
+The easiest way is the Plugin Store in the LEDMatrix web UI:
+
+1. Open `http://your-pi-ip:5000`
+2. Open the **Plugin Manager** tab
+3. Find **AFL Scoreboard** in the **Plugin Store** section and click **Install**
+4. Open the plugin's tab in the second nav row to configure favorite teams and
+   display modes
+
+Manual install: copy this directory into your LEDMatrix `plugins_directory`
+(default `plugin-repos/`) and restart the display service.
+
+## Testing
+
+- `python test_afl_plugin.py` — standalone smoke tests (display modes, mode
+  routing, live content, AFL quarter parsing). No network or host required.
+- `test/harness.json` — a deterministic fixture (one live, one recent, one
+  upcoming game) for the core plugin safety harness
+  (`LEDMatrix/scripts/check_plugin.py`).
+
+## Troubleshooting
+
+- **No games showing**: Confirm the ESPN endpoint is reachable and that at least
+  one display mode is enabled.
+- **Missing team logos**: The plugin auto-downloads logos; check the display's
+  internet access and logo cache directory permissions.
+- **Slow updates**: Adjust `update_interval_seconds` / `live_update_interval`.
+- **API errors**: Check your internet connection and ESPN API availability.