Retroplayer - Achievements and Leaderboards OSD.

[sunlollyking]

Description

Adds RetroAchievements integration to Kodi's RetroPlayer, including an achievements OSD dialog, leaderboard dialog with score entries, and rich presence support. Achievement detection is built on rc_client (rcheevos v12.3.0) which reads core memory directly every emulator frame, giving universal coverage across all libretro cores regardless of whether they declare RETRO_ENVIRONMENT_SET_SUPPORT_ACHIEVEMENTS.

Motivation and context

RetroAchievements is the leading achievement platform for retro gaming with over 500,000 achievements across thousands of games. Kodi's RetroPlayer has no achievement support today — players using Kodi as their retro gaming frontend have no way to earn or track achievements while playing.
Previous attempts at this integration (including an earlier GSoC implementation) used a callback polling system that depended on cores explicitly declaring achievement support. This excluded many popular cores including Genesis Plus GX, Picodrive, and Nestopia. By switching to rc_client, achievement detection works on any core that exposes memory — which all libretro cores do.

How has this been tested?

Tested on Ubuntu 26.04 (x86_64) with a from-source Kodi build and on LibreELEC with Garbear's prebuilt binaries.
Achievements confirmed working end-to-end (login, game load notification, achievement unlock toast, rich presence ping, offline award queue):

NES via game.libretro.fceumm — Balloon Fight, Felix the Cat, Kung Fu
SNES via game.libretro.snes9x — Super Mario World
Genesis/Mega Drive via game.libretro.genplus — Sonic the Hedgehog 2
Game Boy via game.libretro.gambatte

The leaderboard OSD dialog, achievement list dialog, and leaderboard entries dialog have been tested visually in the Estuary skin on Ubuntu.

What is the effect on users?

Users with a RetroAchievements account (retroachievements.org — free to register) can log in via Kodi's game settings, then earn achievements while playing retro games through RetroPlayer. On game load a notification shows the game title and current achievement count. When an achievement is earned a toast notification appears with the achievement badge and title. Rich presence is posted to the RA server every two minutes showing current game activity. An offline award queue retries any awards that failed due to connectivity issues.
The leaderboard OSD button opens a dialog showing all leaderboards for the current game. Selecting a leaderboard shows the full global score table with ranks and usernames.
Users who do not have a RetroAchievements account or do not log in are completely unaffected — the feature is entirely opt-in.

Screenshots (if appropriate):

Types of change

• [X ] Improvement (non-breaking change which improves existing functionality)
• [X ] New feature (non-breaking change which adds functionality)

Checklist:

• [X ] My code follows the Code Guidelines of this project
• I have updated the documentation accordingly
• [ X] All new and existing tests passed

[sunlollyking]

Opened this @garbear

The big change is the achievement detection engine has been replaced with rc_client (rcheevos v12.3.0). Instead of relying on cores declaring RETRO_ENVIRONMENT_SET_SUPPORT_ACHIEVEMENTS and the ActivateAchievement/DeactivateTriggeredAchievement cycle in game.libretro, rc_client reads core memory directly every frame and evaluates conditions itself.

This should fix the LibreELEC crash — the SIGSEGV in DeactivateTriggeredAchievement was in a code path that no longer exists. rc_client manages all achievement state internally now so game.libretro isn't involved in the trigger/deactivate cycle at all.

Side benefit is universal core coverage — Genesis Plus GX, Nestopia, Picodrive etc all work now without needing to declare SET_SUPPORT_ACHIEVEMENTS. Confirmed achievements firing on Genesis via genplus which was completely broken before.

All the leaderboard UI from #147 is preserved, just cherry-picked on top of the rc_client foundation.
Worth using this branch for future testbuilds instead of #147. Let me know if you want me to rebase on a different base.

[garbear]

Can you update rcheevos for platforms that use cmake depends? https://github.com/kodi-game/game.libretro/blob/Piers/depends/common/rcheevos/rcheevos.txt

[sunlollyking]

kodi-game/game.libretro#161

Cool all done

[garbear]

I have a solution to the rebasing retroplayer-22beta1 problem. Can you edit the PR to my master branch?

[sunlollyking]

Done pointing the branch now at master

[garbear]

Yet I got a lotta shit to rebase out. You can see the code that goes into my test builds.

[sunlollyking]

If you've got any tips going forward to try keep everything clean i'll follow the process best i can.

[garbear]

Just get a clean PR against my master

[sunlollyking]

This has hugely regressed :( Could be a while before i get it back to working again. Not sure what's fully happened.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

[sunlollyking]

@garbear working on a fix I'll have something pushed in a few hours then I'd appreciate the copilot review. Will report back shortly

[sunlollyking]

@garbear this should be good to go now. It'd be good to get copilot to have a sniff around and i'd also like to jazz up the leaderboard dialog a little bit but as for right now everything works, i've hardened the code and it now allows unlocks completely console agnostic with achievement and leaderboards dialogs.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

[garbear]

rcheevos headers added intentionally?

[sunlollyking]

Just on the copilot review - it's bringing in all the vendored cheevos code which doesn't need reviewing. Any tips to exclude it so copilot and go wild and the scope becomes more manageable.

Yes headers added intentionally rc_client needs to be compiled directly into RetroPlayer since it reads core memory every frame via rc_client_do_frame(), bypassing the game.libretro addon interface. I used the source cheevos module but again we can change if there's a better approach.

[garbear]

We don't want to carry the source, if it's needed by Kodi, it should be packaged in depends.

[sunlollyking]

Makes sense — I'll move rcheevos into depends. Should I model it on an existing package or is there a preferred pattern for header+source libraries that get compiled into Kodi directly rather than linked as a shared lib?"

[garbear]

If you go that way, we'll need an ENABLE_INTERNAL_RCHEEVOS flag. You can model it on the depends I add to my RetroPlayer build - those are in turn modeled on selected Kodi modules that have been updated most recently and use the newest patterns.

But adding a dependency is expensive, because it has to be added on all platforms. Much better to add dependencies in binary add-ons, because then they're truly optional. rcheevos is already in game.libretro. Can't we use that? Does the Game API need to be expanded for more functionality?

[sunlollyking]

Cool no that makes sense - will get looking into this now. Next push it should all be sorted! Makes this PR much leaner too.
I'll expand the Game API with addon→Kodi callbacks for achievement events:

OnAchievementTriggered(id, title, description, badge_url, points)
OnGameLoaded(title, game_id, achievement_count, unlocked_count, leaderboard_count)
OnRichPresenceUpdated(evaluation)
OnGameCompleted(title)
OnLoginResult(success, username)

game.libretro would own the full lifecycle (create in LoadGame, do_frame in RunFrame, events forwarded via the API). Kodi just receives events and shows OSD/dialogs.
Does that API shape work?

[sunlollyking]

@garbear I've done my best rearchitecting into the model you wanted:

#150
kodi-game/game.libretro#162

Unsure what you want to do with this PR because everything is all hooked up correctly i guess it's just been rearchitected inefficiently. Hopefully we can work through the issues in the next few days and then i'm most likely going to have to put this down for a while :(

[garbear]

Architecture is key. Like I said before, the current architecture is student-designed in the early stages of the project, so isn't likely to have been done with full consideration the entire codebase or featureset. The window is closed for any Game API changes, so as we can't really build on the current API without building rcheevos into Kodi, we may want to start thinking harder toward v23.

[garbear]

OK, here's a plan for the close future. I submitted: http://github.com/xbmc/xbmc/pull/28604. As a small task, it would be good to get RA sign-in working first, on top of that commit. RA sign-in was added in v20, and is currently broken, so it'd be good to get that fix in v22. After that, we can focus on a Game API bump, and working on a v23 "feature branch".