Draft: Implement gradual difficulty and performance calculation

[Error44s]

Summary

This draft pull request introduces gradual difficulty and performance calculation support for parsecore.

Gradual calculation is already implemented for osu!catch. Support for osu!, osu!taiko, and osu!mania is planned but has not been implemented yet and is currently represented by TODO sections.

The purpose of this draft PR is to track the implementation progress, review the shared API and structure early, and complete support for all game modes before marking the PR as ready for review.

---

Type of Change

• Bug fix
• New feature
• Breaking change
• Performance improvement
• Documentation update
• Tests
• Chore / tooling / CI

---

Current Status

• osu!
• osu!taiko
• osu!catch
• osu!mania

Gradual difficulty and performance calculation is currently available only for osu!catch.

The remaining game modes still contain incomplete sections marked with TODO.

---

Changes

• Added gradual difficulty calculation support
• Added gradual performance calculation support
• Added object-by-object processing for osu!catch
• Added CatchScoreState
• Added CatchGradualDifficulty
• Added CatchGradualPerformance
• Added support for advancing calculations using next(), nth(), and last()
• Added the initial structure for gradual support across the remaining game modes
• Added TODO markers for unfinished osu!, taiko, and mania implementations

---

Implemented: osu!catch

The catch implementation currently supports:

• Incremental difficulty calculation
• Incremental performance calculation
• Fruit, droplet, and tiny droplet tracking
• Score-state based performance calculation
• Iterator-based progression
• Advancing by a specified number of objects
• Advancing directly to the final object
• Existing mod and clock-rate configuration
• Converted catch beatmaps

---

Remaining Work

osu!

• Implement gradual difficulty calculation
• Implement gradual performance calculation
• Add an osu! score-state model
• Handle gradual aim, speed, flashlight, and rhythm processing
• Add tests and parity validation

osu!taiko

• Implement gradual difficulty calculation
• Implement gradual performance calculation
• Add a taiko score-state model
• Handle gradual rhythm, colour, stamina, and reading processing
• Add tests and parity validation

osu!mania

• Implement gradual difficulty calculation
• Implement gradual performance calculation
• Add a mania score-state model
• Handle gradual strain processing
• Add tests and parity validation

Shared Work

• Finalize the public gradual API
• Remove or complete all remaining TODO sections
• Add unit tests
• Add integration tests
• Add parity tests
• Add examples
• Add API documentation
• Verify mod handling for all supported modes
• Run formatting, linting, and the complete test suite

---

Testing

The catch implementation still requires complete automated validation.

The existing test suite can be run with:

pytest tests/

[github-actions]

🤖 ParseCore Bot — PR Review

Hi @Error44s! I checked this pull request automatically. Here is my verdict:

❌ Not ready yet

Some checks did not pass. Please fix the points marked with ❌ below and I will re-check automatically on your next push or edit.

	Check	Result
❌	Conventional title	PR title must follow Conventional Commits: type(scope): subject e.g. fix(pp): correct taiko convert scroll speed. Allowed types: feat, fix, docs, style, refactor, perf, test, chore, revert. Allowed scopes: beatmap, mods, pp, ci, packaging.
✅	PR template	PR template is filled out
❌	Parity statement	This PR touches parsecore/Performance/ but the Parity section is empty or N/A. Please state which official reference code (ppy/osu file + version) the change mirrors and confirm the parity suite passes with zero differences.
✅	Comment-free code	No inline comments added to parsecore code
⚠️	PR size	This PR adds more than 800 lines. Consider splitting it into smaller, focused PRs large diffs slow down review and increase parity risk. (+1361 lines)

What to fix

• ❌ Conventional title: PR title must follow Conventional Commits: type(scope): subject e.g. fix(pp): correct taiko convert scroll speed. Allowed types: feat, fix, docs, style, refactor, perf, test, chore, revert. Allowed scopes: beatmap, mods, pp, ci, packaging.
• ❌ Parity statement: This PR touches parsecore/Performance/ but the Parity section is empty or N/A. Please state which official reference code (ppy/osu file + version) the change mirrors and confirm the parity suite passes with zero differences.

---

_{🤖 I am not a human I re-run on every push and edit. Configure me in .github/parsecore-bot/config.json. Override switches: [skip-comment-check], [skip-docs] in the PR description.}

[github-actions]

⚠️ Docs Update Check

This PR modifies public API files but does not include any documentation updates.

If your changes affect the public API or behavior, please update the relevant docs or README.md.
If no docs update is needed, add [skip-docs] to your PR description.

[github-advanced-security]

CodeQL found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.