ncaa-dynasty-rerank 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. ncaa_dynasty_rerank-0.1.0/.github/workflows/ci.yml +45 -0
  2. ncaa_dynasty_rerank-0.1.0/.github/workflows/publish.yml +33 -0
  3. ncaa_dynasty_rerank-0.1.0/.gitignore +37 -0
  4. ncaa_dynasty_rerank-0.1.0/CHANGELOG.md +41 -0
  5. ncaa_dynasty_rerank-0.1.0/LICENSE +21 -0
  6. ncaa_dynasty_rerank-0.1.0/PKG-INFO +180 -0
  7. ncaa_dynasty_rerank-0.1.0/README.md +162 -0
  8. ncaa_dynasty_rerank-0.1.0/pyproject.toml +57 -0
  9. ncaa_dynasty_rerank-0.1.0/src/ncaa_dynasty_rerank/__init__.py +3 -0
  10. ncaa_dynasty_rerank-0.1.0/src/ncaa_dynasty_rerank/bitview.py +96 -0
  11. ncaa_dynasty_rerank-0.1.0/src/ncaa_dynasty_rerank/cli.py +311 -0
  12. ncaa_dynasty_rerank-0.1.0/src/ncaa_dynasty_rerank/config.py +112 -0
  13. ncaa_dynasty_rerank-0.1.0/src/ncaa_dynasty_rerank/config_rules.py +64 -0
  14. ncaa_dynasty_rerank-0.1.0/src/ncaa_dynasty_rerank/discover.py +80 -0
  15. ncaa_dynasty_rerank-0.1.0/src/ncaa_dynasty_rerank/engine.py +215 -0
  16. ncaa_dynasty_rerank-0.1.0/src/ncaa_dynasty_rerank/models.py +83 -0
  17. ncaa_dynasty_rerank-0.1.0/src/ncaa_dynasty_rerank/polls.py +23 -0
  18. ncaa_dynasty_rerank-0.1.0/src/ncaa_dynasty_rerank/strategies/__init__.py +13 -0
  19. ncaa_dynasty_rerank-0.1.0/src/ncaa_dynasty_rerank/strategies/ap.py +96 -0
  20. ncaa_dynasty_rerank-0.1.0/src/ncaa_dynasty_rerank/strategies/base.py +24 -0
  21. ncaa_dynasty_rerank-0.1.0/src/ncaa_dynasty_rerank/strategies/cfp.py +38 -0
  22. ncaa_dynasty_rerank-0.1.0/src/ncaa_dynasty_rerank/strategies/coaches.py +101 -0
  23. ncaa_dynasty_rerank-0.1.0/src/ncaa_dynasty_rerank/strategies/registry.py +30 -0
  24. ncaa_dynasty_rerank-0.1.0/src/ncaa_dynasty_rerank/tdb.py +314 -0
  25. ncaa_dynasty_rerank-0.1.0/tests/__init__.py +0 -0
  26. ncaa_dynasty_rerank-0.1.0/tests/synthetic_tdb.py +154 -0
  27. ncaa_dynasty_rerank-0.1.0/tests/test_bitview.py +92 -0
  28. ncaa_dynasty_rerank-0.1.0/tests/test_cli.py +63 -0
  29. ncaa_dynasty_rerank-0.1.0/tests/test_config.py +48 -0
  30. ncaa_dynasty_rerank-0.1.0/tests/test_engine.py +295 -0
  31. ncaa_dynasty_rerank-0.1.0/tests/test_strategies.py +41 -0
  32. ncaa_dynasty_rerank-0.1.0/tests/test_tdb.py +79 -0
  33. ncaa_dynasty_rerank-0.1.0/uv.lock +401 -0
@@ -0,0 +1,45 @@
1
+ name: CI & Code Quality
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ jobs:
10
+ lint-and-format:
11
+ name: Lint & Format (Ruff)
12
+ runs-on: ubuntu-latest
13
+ steps:
14
+ - uses: actions/checkout@v4
15
+
16
+ - name: Install uv
17
+ uses: astral-sh/setup-uv@v5
18
+ with:
19
+ enable-cache: true
20
+
21
+ - name: Check code formatting with Ruff
22
+ run: uv run --with ruff ruff format --check .
23
+
24
+ - name: Lint with Ruff
25
+ run: uv run --with ruff ruff check .
26
+
27
+ test:
28
+ name: Test on Python ${{ matrix.python-version }}
29
+ runs-on: ubuntu-latest
30
+ strategy:
31
+ matrix:
32
+ python-version: ["3.10", "3.11", "3.12", "3.13"]
33
+ steps:
34
+ - uses: actions/checkout@v4
35
+
36
+ - name: Install uv
37
+ uses: astral-sh/setup-uv@v5
38
+ with:
39
+ enable-cache: true
40
+
41
+ - name: Set up Python ${{ matrix.python-version }}
42
+ run: uv python install ${{ matrix.python-version }}
43
+
44
+ - name: Run pytest test suite
45
+ run: uv run --python ${{ matrix.python-version }} --extra dev pytest -v
@@ -0,0 +1,33 @@
1
+ name: Publish to PyPI
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - "v*"
7
+
8
+ jobs:
9
+ pypi-publish:
10
+ name: Build and publish to PyPI
11
+ runs-on: ubuntu-latest
12
+ environment:
13
+ name: pypi
14
+ url: https://pypi.org/p/ncaa-dynasty-rerank
15
+ permissions:
16
+ id-token: write # Mandatory for PyPI trusted publishing (OIDC)
17
+ contents: read
18
+ steps:
19
+ - uses: actions/checkout@v4
20
+
21
+ - name: Install uv
22
+ uses: astral-sh/setup-uv@v5
23
+ with:
24
+ enable-cache: true
25
+
26
+ - name: Set up Python
27
+ run: uv python install 3.11
28
+
29
+ - name: Build package distribution
30
+ run: uv build
31
+
32
+ - name: Publish package distributions to PyPI
33
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,37 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *$py.class
4
+ *.so
5
+ .Python
6
+ build/
7
+ develop-eggs/
8
+ dist/
9
+ downloads/
10
+ eggs/
11
+ .eggs/
12
+ lib/
13
+ lib64/
14
+ parts/
15
+ sdist/
16
+ var/
17
+ wheels/
18
+ share/python-wheels/
19
+ *.egg-info/
20
+ .installed.cfg
21
+ *.egg
22
+ MANIFEST
23
+
24
+ .env
25
+ .venv
26
+ env/
27
+ venv/
28
+ ENV/
29
+ env.bak/
30
+ venv.bak/
31
+
32
+ .pytest_cache/
33
+ .coverage
34
+ htmlcov/
35
+
36
+ .DS_Store
37
+ *.bak.*
@@ -0,0 +1,41 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [Unreleased]
9
+
10
+ ## [0.1.0] - 2026-11-07
11
+
12
+ ### Added
13
+ - **Pure-Python TDB Binary Parser & Writer**: Implementation of the EA Sports Database (`TDB`) format capable of reading and updating `TEAM` and `SCHD` tables.
14
+ - **Big-Endian Bit Manipulation Engine (`BitView`)**: Bit-level buffer manipulator supporting arbitrary bit offsets, unsigned/signed integer packed fields, and fixed-width strings with bounds validation.
15
+ - **College Football Ranking Analytics Engine (`RatingEngine`)**:
16
+ - Opponent Strength of Schedule (SOS) and Strength of Record (SOR) calculation.
17
+ - Quality win bonuses with diminishing returns.
18
+ - Margin of victory scaling with a configurable 24-point cap to prevent running up the score.
19
+ - Head-to-head tiebreaking resolution and cycle handling.
20
+ - Bye-week neutrality to ensure teams on a bye week are not unfairly penalized compared to active teams.
21
+ - **Extensible Poll Strategy Architecture (`PollRegistry`)**:
22
+ - `CFPStrategy` (`cfp`): Resume-first evaluation prioritizing SOS, top-25 wins, and power-conference schedule strength.
23
+ - `APStrategy` (`ap`): Media-style ranking prioritizing win-loss record and high-profile victories.
24
+ - `CoachesStrategy` (`coaches`): Traditional poll logic weighting raw win totals with mild resume adjustments.
25
+ - **Interactive Terminal Interface (`ncaa-dynasty-rerank` CLI)**:
26
+ - `rich` formatted Top 25 movement and comparison tables.
27
+ - Automatic detection and scanning of NCAA Football 14 dynasty saves across RPCS3 (`dev_hdd0`) and Steam Proton directories.
28
+ - Alias management subcommands (`add`, `list`, `set-default`, `remove`, `scan`) stored in `~/.config/ncaa-dynasty-rerank/config.json`.
29
+ - Simulation support with `--dry-run`.
30
+ - Automated timestamped backup generation (`USR-DATA.bak.YYYYMMDD_HHMMSS`) before committing any changes.
31
+ - Early-season override flag (`--force-cfp`) to populate CFP rankings before the in-game week threshold.
32
+ - Non-interactive batch execution flag (`-y` / `--yes`) for automated scripting.
33
+ - **Test Suite**:
34
+ - Synthetic TDB save file generator producing valid binary database structures in memory and temporary directories.
35
+ - Test coverage across bitview operations, TDB table updates, ranking engine invariants, strategy registration, and CLI commands.
36
+ - **CI/CD Automation**:
37
+ - GitHub Actions testing matrix across Python 3.10, 3.11, 3.12, and 3.13.
38
+ - Automated PyPI Trusted Publishing triggered on tagged releases (`v*`).
39
+
40
+ [Unreleased]: https://github.com/matthewkdies/ncaa-dynasty-rerank/compare/v0.1.0...HEAD
41
+ [0.1.0]: https://github.com/matthewkdies/ncaa-dynasty-rerank/releases/tag/v0.1.0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Matthew Dies
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,180 @@
1
+ Metadata-Version: 2.5
2
+ Name: ncaa-dynasty-rerank
3
+ Version: 0.1.0
4
+ Summary: Automated CFP, AP, and Coaches poll re-ranking engine for NCAA Football 14 dynasty saves.
5
+ Author: Matthew Dies
6
+ License: MIT
7
+ License-File: LICENSE
8
+ Classifier: License :: OSI Approved :: MIT License
9
+ Classifier: Operating System :: OS Independent
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Topic :: Games/Entertainment :: Simulation
12
+ Requires-Python: >=3.10
13
+ Requires-Dist: pydantic>=2.0.0
14
+ Requires-Dist: rich>=13.0.0
15
+ Provides-Extra: dev
16
+ Requires-Dist: pytest>=7.0.0; extra == 'dev'
17
+ Description-Content-Type: text/markdown
18
+
19
+ # 🏈 ncaa-dynasty-rerank
20
+
21
+ [![CI Test Suite](https://github.com/matthewkdies/ncaa-dynasty-rerank/actions/workflows/ci.yml/badge.svg)](https://github.com/matthewkdies/ncaa-dynasty-rerank/actions/workflows/ci.yml)
22
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
23
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
24
+
25
+ > *"Let's be honest: NCAA Football 14 is still better than the modern, Madden-copied games."*
26
+
27
+ An automated, 100% pure-Python re-ranking engine for NCAA Football 14 (and College Football Revamped) dynasty saves. It analyzes real game schedules, opponent win rates, strength of record (SOR), margin of victory, and head-to-head match-ups to produce authentic CFP, AP, and Coaches Poll rankings. The tool modifies your RPCS3 save file in directly, quickly, and cleanly.
28
+
29
+ ---
30
+
31
+ ## Why?
32
+
33
+ I love college football, and I love programming. But most of all, I love NCAA Football 14 (and my fiancé, and cats, and friends, and y'know, other things too). Even with modern consoles and new college football releases, nothing quite matches the magic, dynasty depth, and soul of NCAA 14.
34
+
35
+ Unfortunately, the in-game ranking algorithm has a bad habit of keeping 2-3 bluebloods in the Top 10 while undefeated mid-majors and 7-1 powerhouses languish at #22.
36
+
37
+ The [NCAA 14 Dynasty Tool](https://github.com/Bowersrd/NCAA14DynastyToolRelease) solved the problem of manual poll editing, but manually re-ranking 25 teams every single week takes time. After all, I'm a programmer. I want to run a script that automates this, darnit! This tool automates that process using a deterministic, resume-first analytics engine. It reads and writes your RPCS3 save directly, without needing a GUI or uploading files anywhere.
38
+
39
+ ### Acknowledgments & Shoutouts
40
+ Huge love and respect to the giants whose shoulders this stands on:
41
+
42
+ - **The [College Football Revamped](https://github.com/cfbrevamped) (CFBR) Team**: For breathing brand new life into NCAA 14 with modern uniforms, stadiums, fields, and logos. This is what inspired me to get back into the game, setting up Sunshine, and more.
43
+ - **The [NCAA 14 Dynasty Tool](https://github.com/Bowersrd/NCAA14DynastyToolRelease) Team**: For their reverse-engineering of EA DB formats, the 12-team playoff mods, and inspiring this automation. Even though I'll be using this tool to rank, I'll definitely be using the Dynasty Tool for the incredible other features like the CFP, historical views, etc.
44
+
45
+ ---
46
+
47
+ ## Features
48
+
49
+ - **Pure Python**: Zero external dependencies (e.g., no Node.js, no Proton, no C compilers, and no LLMs burning API tokens). Bit-level reading and writing of EA Sports TDB saves.
50
+ - **Re-Ranking the Three Polls, with Distinct "Personalities"**:
51
+ - **College Football Playoff (CFP)**: 100% resume-driven. Weighted on Top 25 wins, Strength of Schedule (SOS), quality road wins, and head-to-head. No inertia from preseason polls.
52
+ - **AP Top 25 Poll**: Media perspective factoring in margin of victory, momentum, and Cinderella respect for surging Group of 5 teams. Generates authentic voter points (~1575 max) and 1st-place votes.
53
+ - **USA Today Coaches Poll**: Traditional poll inertia (`TCPR`), making it harder to fall without losing and harder to jump rapidly, with blueblood pedigree consideration.
54
+ - **Baked-in Resume Rules**:
55
+ - **Soft Tiers & Leapfrogging**: A 7-1 team with multiple top-10 wins can rightfully jump an untested 8-0 team playing an FCS/easy schedule.
56
+ - **Bye-Week Invariance**: Evaluates quality density and average game performance so a 7-0 team with a late bye is never punished against an 8-0 team.
57
+ - **Head-to-Head Enforcement**: Strict priority for teams with equal records; weighted tiebreaker bonus for 1-loss differences.
58
+ - **Margin Diminishing Returns**: Blowout wins are rewarded up to a $\pm 24$ cap with diminishing returns, preventing you (and others) from "FCS farming" (or running up the score... have some sportsmanship, please!).
59
+ - **Safety**:
60
+ - Automatic timestamped backups (`USR-DATA.bak.YYYYMMDD_HHMMSS`) before modifying a single byte.
61
+ - `--dry-run` mode to preview proposed rankings in beautiful terminal tables.
62
+ - Early-season CFP protection: detects when the in-game BCS/CFP poll is dormant (pre-Week 8) to prevent game UI glitches.
63
+ - **Dynasty Aliases for Ease of Use**:
64
+ - Profile manager (`alias add`, `alias list`, `alias scan`) to switch between multiple dynasty careers with short names (e.g. `wvu`, `osu`, etc.).
65
+
66
+ ---
67
+
68
+ ## Installation
69
+
70
+ Install via `pip`:
71
+ ```bash
72
+ pip install ncaa-dynasty-rerank
73
+ ```
74
+
75
+ Or using `uv`:
76
+ ```bash
77
+ uv tool install ncaa-dynasty-rerank
78
+ ```
79
+
80
+ ---
81
+
82
+ ## Usage Guide
83
+
84
+ ### Scan & Map Your Dynasty Save
85
+
86
+ Scan your system to auto-detect any dynasty saves in RPCS3 or Steam Proton:
87
+
88
+ ```bash
89
+ ncaa-dynasty-rerank alias scan
90
+ ```
91
+
92
+ Or manually map an alias:
93
+
94
+ ```bash
95
+ ncaa-dynasty-rerank alias add wvu ~/.config/rpcs3/dev_hdd0/home/00000001/savedata/BLUS31159-DYNASTY-DEFAULT/USR-DATA --default
96
+ ```
97
+
98
+ ### Preview the Re-Rank (`--dry-run`)
99
+
100
+ Inspect the proposed Top 25 for all three polls with colorized (shoutout to [`rich`](https://github.com/textualize/rich)) movement indicators:
101
+
102
+ ```bash
103
+ ncaa-dynasty-rerank --dry-run
104
+ ```
105
+
106
+ ### Apply to Your Save
107
+
108
+ When you're ready, run without flags. It will display the comparison, prompt for confirmation, create an automatic backup, and update the save file:
109
+
110
+ ```bash
111
+ $ ncaa-dynasty-rerank
112
+
113
+ ╭──────────────────────────────────────────────────────────────────────────────╮
114
+ │ Loading save: ~/.config/rpcs3/dev_hdd0/.../BLUS31159-DYNASTY-DEFAULT/USR-DATA│
115
+ ╰──────────────────────────────────────────────────────────────────────────────╯
116
+ Loaded 142 teams and 528 completed games.
117
+
118
+ PROPOSED RANKINGS
119
+
120
+ College Football Playoff (CFP) Rankings
121
+ ┏━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
122
+ ┃ Rank ┃ Move ┃ Team ┃ Record ┃ Resume Score ┃
123
+ ┡━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
124
+ │ 1 │ = │ Florida Gators │ 7-0 │ 187.25 │
125
+ │ 2 │ ▲ +2 │ Alabama Crimson Tide │ 8-0 │ 173.73 │
126
+ │ 3 │ ▲ +2 │ West Virginia Mountaineers │ 8-0 │ 159.29 │
127
+ │ 4 │ ▼ -1 │ Ohio State Buckeyes │ 8-0 │ 158.55 │
128
+ │ 5 │ ▼ -3 │ Clemson Tigers │ 8-0 │ 157.06 │
129
+ │ 6 │ ▲ +5 │ UCLA Bruins │ 6-1 │ 133.45 │
130
+ ...
131
+ Apply these rankings to your save file? [y/N]: y
132
+ ✓ Created backup: USR-DATA.bak.20261107_113000
133
+ ✓ Successfully applied new rankings to save file!
134
+ ```
135
+
136
+ ---
137
+
138
+ ## Configuration & Extensibility
139
+
140
+ If you want to tweak conference weights, adjust margin caps, or add custom polls, you can! The library uses the [Strategy Pattern](https://en.wikipedia.org/wiki/Strategy_pattern):
141
+
142
+ ```python
143
+ from ncaa_dynasty_rerank.config_rules import EngineConfig
144
+ from ncaa_dynasty_rerank.engine import RankingEngine
145
+ from ncaa_dynasty_rerank.strategies.base import PollStrategy
146
+ from ncaa_dynasty_rerank.strategies.registry import PollRegistry
147
+
148
+ # Custom conference weights or margin caps
149
+ config = EngineConfig(
150
+ conference_weights={11: 1.20, 1: 1.20, 0: 1.05}, # Boost SEC & Big Ten
151
+ margin_cap=21,
152
+ )
153
+
154
+
155
+ # Custom poll rating model (e.g. SP+ or /r/CFB poll)
156
+ class RedditCFBPoll(PollStrategy):
157
+ name = "/r/CFB User Poll"
158
+ poll_type = "rcfb"
159
+
160
+ def rank(self, teams, engine):
161
+ # Your custom ranking logic here
162
+ return ...
163
+
164
+
165
+ registry = PollRegistry()
166
+ registry.register(RedditCFBPoll())
167
+ ```
168
+
169
+ > [!note]
170
+ > I have future plans to make this all more configurable, both at the CLI level and at the user-level. Eventually, I want to support preferences being saved to a config file, which is loaded at runtime. But... later.
171
+
172
+ ---
173
+
174
+ ## Testing
175
+
176
+ The test suite runs against self-contained synthetic binary fixtures:
177
+
178
+ ```bash
179
+ uv run --extra dev pytest -v
180
+ ```
@@ -0,0 +1,162 @@
1
+ # 🏈 ncaa-dynasty-rerank
2
+
3
+ [![CI Test Suite](https://github.com/matthewkdies/ncaa-dynasty-rerank/actions/workflows/ci.yml/badge.svg)](https://github.com/matthewkdies/ncaa-dynasty-rerank/actions/workflows/ci.yml)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
6
+
7
+ > *"Let's be honest: NCAA Football 14 is still better than the modern, Madden-copied games."*
8
+
9
+ An automated, 100% pure-Python re-ranking engine for NCAA Football 14 (and College Football Revamped) dynasty saves. It analyzes real game schedules, opponent win rates, strength of record (SOR), margin of victory, and head-to-head match-ups to produce authentic CFP, AP, and Coaches Poll rankings. The tool modifies your RPCS3 save file in directly, quickly, and cleanly.
10
+
11
+ ---
12
+
13
+ ## Why?
14
+
15
+ I love college football, and I love programming. But most of all, I love NCAA Football 14 (and my fiancé, and cats, and friends, and y'know, other things too). Even with modern consoles and new college football releases, nothing quite matches the magic, dynasty depth, and soul of NCAA 14.
16
+
17
+ Unfortunately, the in-game ranking algorithm has a bad habit of keeping 2-3 bluebloods in the Top 10 while undefeated mid-majors and 7-1 powerhouses languish at #22.
18
+
19
+ The [NCAA 14 Dynasty Tool](https://github.com/Bowersrd/NCAA14DynastyToolRelease) solved the problem of manual poll editing, but manually re-ranking 25 teams every single week takes time. After all, I'm a programmer. I want to run a script that automates this, darnit! This tool automates that process using a deterministic, resume-first analytics engine. It reads and writes your RPCS3 save directly, without needing a GUI or uploading files anywhere.
20
+
21
+ ### Acknowledgments & Shoutouts
22
+ Huge love and respect to the giants whose shoulders this stands on:
23
+
24
+ - **The [College Football Revamped](https://github.com/cfbrevamped) (CFBR) Team**: For breathing brand new life into NCAA 14 with modern uniforms, stadiums, fields, and logos. This is what inspired me to get back into the game, setting up Sunshine, and more.
25
+ - **The [NCAA 14 Dynasty Tool](https://github.com/Bowersrd/NCAA14DynastyToolRelease) Team**: For their reverse-engineering of EA DB formats, the 12-team playoff mods, and inspiring this automation. Even though I'll be using this tool to rank, I'll definitely be using the Dynasty Tool for the incredible other features like the CFP, historical views, etc.
26
+
27
+ ---
28
+
29
+ ## Features
30
+
31
+ - **Pure Python**: Zero external dependencies (e.g., no Node.js, no Proton, no C compilers, and no LLMs burning API tokens). Bit-level reading and writing of EA Sports TDB saves.
32
+ - **Re-Ranking the Three Polls, with Distinct "Personalities"**:
33
+ - **College Football Playoff (CFP)**: 100% resume-driven. Weighted on Top 25 wins, Strength of Schedule (SOS), quality road wins, and head-to-head. No inertia from preseason polls.
34
+ - **AP Top 25 Poll**: Media perspective factoring in margin of victory, momentum, and Cinderella respect for surging Group of 5 teams. Generates authentic voter points (~1575 max) and 1st-place votes.
35
+ - **USA Today Coaches Poll**: Traditional poll inertia (`TCPR`), making it harder to fall without losing and harder to jump rapidly, with blueblood pedigree consideration.
36
+ - **Baked-in Resume Rules**:
37
+ - **Soft Tiers & Leapfrogging**: A 7-1 team with multiple top-10 wins can rightfully jump an untested 8-0 team playing an FCS/easy schedule.
38
+ - **Bye-Week Invariance**: Evaluates quality density and average game performance so a 7-0 team with a late bye is never punished against an 8-0 team.
39
+ - **Head-to-Head Enforcement**: Strict priority for teams with equal records; weighted tiebreaker bonus for 1-loss differences.
40
+ - **Margin Diminishing Returns**: Blowout wins are rewarded up to a $\pm 24$ cap with diminishing returns, preventing you (and others) from "FCS farming" (or running up the score... have some sportsmanship, please!).
41
+ - **Safety**:
42
+ - Automatic timestamped backups (`USR-DATA.bak.YYYYMMDD_HHMMSS`) before modifying a single byte.
43
+ - `--dry-run` mode to preview proposed rankings in beautiful terminal tables.
44
+ - Early-season CFP protection: detects when the in-game BCS/CFP poll is dormant (pre-Week 8) to prevent game UI glitches.
45
+ - **Dynasty Aliases for Ease of Use**:
46
+ - Profile manager (`alias add`, `alias list`, `alias scan`) to switch between multiple dynasty careers with short names (e.g. `wvu`, `osu`, etc.).
47
+
48
+ ---
49
+
50
+ ## Installation
51
+
52
+ Install via `pip`:
53
+ ```bash
54
+ pip install ncaa-dynasty-rerank
55
+ ```
56
+
57
+ Or using `uv`:
58
+ ```bash
59
+ uv tool install ncaa-dynasty-rerank
60
+ ```
61
+
62
+ ---
63
+
64
+ ## Usage Guide
65
+
66
+ ### Scan & Map Your Dynasty Save
67
+
68
+ Scan your system to auto-detect any dynasty saves in RPCS3 or Steam Proton:
69
+
70
+ ```bash
71
+ ncaa-dynasty-rerank alias scan
72
+ ```
73
+
74
+ Or manually map an alias:
75
+
76
+ ```bash
77
+ ncaa-dynasty-rerank alias add wvu ~/.config/rpcs3/dev_hdd0/home/00000001/savedata/BLUS31159-DYNASTY-DEFAULT/USR-DATA --default
78
+ ```
79
+
80
+ ### Preview the Re-Rank (`--dry-run`)
81
+
82
+ Inspect the proposed Top 25 for all three polls with colorized (shoutout to [`rich`](https://github.com/textualize/rich)) movement indicators:
83
+
84
+ ```bash
85
+ ncaa-dynasty-rerank --dry-run
86
+ ```
87
+
88
+ ### Apply to Your Save
89
+
90
+ When you're ready, run without flags. It will display the comparison, prompt for confirmation, create an automatic backup, and update the save file:
91
+
92
+ ```bash
93
+ $ ncaa-dynasty-rerank
94
+
95
+ ╭──────────────────────────────────────────────────────────────────────────────╮
96
+ │ Loading save: ~/.config/rpcs3/dev_hdd0/.../BLUS31159-DYNASTY-DEFAULT/USR-DATA│
97
+ ╰──────────────────────────────────────────────────────────────────────────────╯
98
+ Loaded 142 teams and 528 completed games.
99
+
100
+ PROPOSED RANKINGS
101
+
102
+ College Football Playoff (CFP) Rankings
103
+ ┏━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
104
+ ┃ Rank ┃ Move ┃ Team ┃ Record ┃ Resume Score ┃
105
+ ┡━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
106
+ │ 1 │ = │ Florida Gators │ 7-0 │ 187.25 │
107
+ │ 2 │ ▲ +2 │ Alabama Crimson Tide │ 8-0 │ 173.73 │
108
+ │ 3 │ ▲ +2 │ West Virginia Mountaineers │ 8-0 │ 159.29 │
109
+ │ 4 │ ▼ -1 │ Ohio State Buckeyes │ 8-0 │ 158.55 │
110
+ │ 5 │ ▼ -3 │ Clemson Tigers │ 8-0 │ 157.06 │
111
+ │ 6 │ ▲ +5 │ UCLA Bruins │ 6-1 │ 133.45 │
112
+ ...
113
+ Apply these rankings to your save file? [y/N]: y
114
+ ✓ Created backup: USR-DATA.bak.20261107_113000
115
+ ✓ Successfully applied new rankings to save file!
116
+ ```
117
+
118
+ ---
119
+
120
+ ## Configuration & Extensibility
121
+
122
+ If you want to tweak conference weights, adjust margin caps, or add custom polls, you can! The library uses the [Strategy Pattern](https://en.wikipedia.org/wiki/Strategy_pattern):
123
+
124
+ ```python
125
+ from ncaa_dynasty_rerank.config_rules import EngineConfig
126
+ from ncaa_dynasty_rerank.engine import RankingEngine
127
+ from ncaa_dynasty_rerank.strategies.base import PollStrategy
128
+ from ncaa_dynasty_rerank.strategies.registry import PollRegistry
129
+
130
+ # Custom conference weights or margin caps
131
+ config = EngineConfig(
132
+ conference_weights={11: 1.20, 1: 1.20, 0: 1.05}, # Boost SEC & Big Ten
133
+ margin_cap=21,
134
+ )
135
+
136
+
137
+ # Custom poll rating model (e.g. SP+ or /r/CFB poll)
138
+ class RedditCFBPoll(PollStrategy):
139
+ name = "/r/CFB User Poll"
140
+ poll_type = "rcfb"
141
+
142
+ def rank(self, teams, engine):
143
+ # Your custom ranking logic here
144
+ return ...
145
+
146
+
147
+ registry = PollRegistry()
148
+ registry.register(RedditCFBPoll())
149
+ ```
150
+
151
+ > [!note]
152
+ > I have future plans to make this all more configurable, both at the CLI level and at the user-level. Eventually, I want to support preferences being saved to a config file, which is loaded at runtime. But... later.
153
+
154
+ ---
155
+
156
+ ## Testing
157
+
158
+ The test suite runs against self-contained synthetic binary fixtures:
159
+
160
+ ```bash
161
+ uv run --extra dev pytest -v
162
+ ```
@@ -0,0 +1,57 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "ncaa-dynasty-rerank"
7
+ version = "0.1.0"
8
+ description = "Automated CFP, AP, and Coaches poll re-ranking engine for NCAA Football 14 dynasty saves."
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = { text = "MIT" }
12
+ authors = [
13
+ { name = "Matthew Dies" }
14
+ ]
15
+ classifiers = [
16
+ "Programming Language :: Python :: 3",
17
+ "License :: OSI Approved :: MIT License",
18
+ "Operating System :: OS Independent",
19
+ "Topic :: Games/Entertainment :: Simulation",
20
+ ]
21
+ dependencies = [
22
+ "rich>=13.0.0",
23
+ "pydantic>=2.0.0",
24
+ ]
25
+
26
+ [project.optional-dependencies]
27
+ dev = [
28
+ "pytest>=7.0.0",
29
+ ]
30
+
31
+ [project.scripts]
32
+ ncaa-dynasty-rerank = "ncaa_dynasty_rerank.cli:main"
33
+
34
+ [tool.hatch.build.targets.wheel]
35
+ packages = ["src/ncaa_dynasty_rerank"]
36
+
37
+ [tool.pytest.ini_options]
38
+ testpaths = ["tests"]
39
+ pythonpath = ["src", "."]
40
+
41
+ [tool.ruff]
42
+ target-version = "py310"
43
+ line-length = 120
44
+
45
+ [tool.ruff.lint]
46
+ select = [
47
+ "E", # pycodestyle errors
48
+ "W", # pycodestyle warnings
49
+ "F", # pyflakes
50
+ "I", # isort
51
+ "B", # flake8-bugbear
52
+ "UP", # pyupgrade
53
+ "SIM", # flake8-simplify
54
+ ]
55
+ ignore = [
56
+ "E501", # line too long (handled by ruff format)
57
+ ]
@@ -0,0 +1,3 @@
1
+ """ncaa-dynasty-rerank: Automated poll re-ranking engine for NCAA Football 14 dynasty saves."""
2
+
3
+ __version__ = "0.1.0"