RetroAchievements (Cheevos) — LibRetro Core Status

Audit date: 2026-03-22 Audited by: Claude / Agent (issue #3386) Parent epic: #2705

Summary

All libretro cores in Provenance reach RetroArch's cheevos.c runtime. HAVE_CHEEVOS is compiled into every build variant (Lite, Standard, XL, iOS, tvOS). Achievements are fully wired at the RetroArch framework level; no per-core flag exists that could disable them.

Architecture Overview

User signs in via PVCheevos (Swift)
        │
        ▼
RetroArchConfigManager writes credentials to retroarch.cfg
        │
        ▼
RetroArch starts content via libretro API
        │
        ▼
cheevos.c reads settings->bools.cheevos_enable
  (controlled by retroarch.cfg / PVSettings)
        │
        ▼
rcheevos identifies ROM via hash (rhash/hash.c)
        │
        ▼
rcheevos polls RETRO_ENVIRONMENT_GET_MEMORY_DATA every frame
  (called from runloop.c:rcheevos_test())
        │
        ▼
Achievements unlocked, Rich Presence updated, leaderboards posted

Key observation: the cheevos path lives entirely inside RetroArch. Every libretro core loaded by PVRetroArchCore is subject to the same runloop.c tick path — there is no per-core cheevos opt-in or opt-out.

Build Flag Audit

HAVE_CHEEVOS Definition Sites

Verdict: HAVE_CHEEVOS is defined globally for Lite, Standard, and XL variants in both debug and release builds.

griffin.c Cheevos Section (lines 190–240)

/*============================================================
ACHIEVEMENTS
============================================================ */
#if defined(HAVE_CHEEVOS)
// cheevos.c, cheevos_client.c, cheevos_menu.c
// + rcheevos source files (rc_client, rc_libretro, rhash, etc.)
#endif

All cheevos/rcheevos source files are included unconditionally when HAVE_CHEEVOS is defined (exact count varies as RetroArch updates; use the audit script to verify).

retroarch.cfg Default State

The Provenance-bundled retroarch.cfg ships with:

cheevos_enable = "false"          # Disabled by default — user must opt in
cheevos_hardcore_mode_enable = "false"
cheevos_username = ""
cheevos_password = ""             # Written by RetroArchConfigManager (not cheevos_token)
cheevos_richpresence_enable = "true"
cheevos_verbose_enable = "true"

Important: cheevos_enable = "false" is the default. Achievements only activate after the user authenticates and enables the feature via the Provenance settings UI, which calls RetroArchConfigManager to update retroarch.cfg.

Per-Core RetroAchievements Status

All cores below are loaded by PVRetroArchCore and therefore share the same cheevos runtime. The "RA Coverage" column describes upstream RetroAchievements game database coverage — it does not reflect a compile-time flag.

Tier 1 — Highest RA Database Coverage

Tier 2 — Good RA Coverage

Tier 3 — Niche / Low RA Coverage

Special Cases — Sideload Only (not App Store)

tvOS-Only Cores

Disabled Cores (not built)

Gaps and Findings

Finding 1 — cheevos_enable = "false" Default

Severity: Medium (UX concern, not a build defect)

retroarch.cfg ships with cheevos_enable = "false". Achievements are silently inactive for users who sign in but don't also toggle the switch in RetroArch settings.

RetroArchConfigManager.updateCredentials(username:password:) writes RetroAchievements credentials to retroarch.cfg. The cheevos_enable setting is written separately, based on the isRetroAchievementsEnabled flag — toggled via the PVCheevos Settings UI — which triggers syncToRetroArch().

Recommendation: Verify that the PVCheevos "Enable RetroAchievements" toggle correctly updates isRetroAchievementsEnabled so that RetroArchConfigManager writes cheevos_enable = "true" in retroarch.cfg when achievements are enabled, and consider a combined sign-in + enable flow to reduce UX confusion.

Finding 2 — achievementsActive Always Returns false

Severity: Low (stubs)

PVRetroArchCoreCore+RetroAchievements.swift:achievementsActive is hardcoded to return false:

public var achievementsActive: Bool {
    // TODO: query cheevos_state() once the C-to-Swift bridge is wired.
    return false
}

This means the PVLibrary / SwiftUI layer cannot query whether an active cheevos session is running.

Recommendation: Implement the C-to-Swift bridge that reads rcheevos state (e.g. rcheevos_hardcore_active, the cheevos_state struct, or a cheevos_get_active() helper) and exposes it as a Swift Bool property, or set a flag from the runloop when achievements activate.

Finding 3 — Per-frame Callback Not Wired (TODO in PVRetroArchCoreCore+RetroAchievements.swift)

Severity: Low (RetroArch handles internally)

PVRetroArchCoreCore+RetroAchievements.swift notes:

In PVLibRetroCore.m, when HAVE_CHEEVOS is defined, intercept the cheevos callback notifications (cheevos_set_rcheevos_callbacks) and forward them to a Swift-side handler.

The C callback bridge is described but marked as a TODO. Native iOS haptics on unlock and PVLibrary progress tracking are not wired.

Recommendation: Implement cheevos_set_rcheevos_callbacks bridge for native unlock notifications (tracked separately from this audit).

Finding 4 — RC_DISABLE_LUA Is Set

Severity: Informational

BuildFlags.xcconfig includes -DRC_DISABLE_LUA. This is correct for iOS/tvOS — Lua support is not available in mobile builds and is not required for rcheevos.

Finding 5 — No Per-Scheme Conditional Compilation of Cheevos

Severity: None (positive finding)

Unlike some RetroArch forks, Provenance does not gate HAVE_CHEEVOS per scheme. The Lite scheme gets the same cheevos-enabled binary as the XL scheme. This is correct behaviour.

Test Plan

Since cheevos are a runtime feature (credentials + enabled flag required), compile-time verification is the primary audit mechanism. Full runtime testing requires:

1. A RetroAchievements account with a known-verified game hash.
2. Set cheevos_enable = "true" and credentials in retroarch.cfg (or via Settings UI).
3. Load the game and observe rcheevos_test() calls in the runloop.
4. Confirm via verbose logging (cheevos_verbose_enable = "true") that the session activates.

Cores with very high RA coverage that are recommended for smoke testing:

Conclusion

All libretro cores in Provenance reach cheevos.c.

The HAVE_CHEEVOS flag is set unconditionally in Build.xcconfig, BuildFlags.xcconfig, and CoresRetro/Package.swift. The griffin.c unified build includes all rcheevos source files under #if defined(HAVE_CHEEVOS). Every core loaded through PVRetroArchCore runs inside the same RetroArch runloop that calls rcheevos_test() per frame.

The three open items (default disabled flag, achievementsActive stub, unlock callback bridge) are UX improvements, not correctness bugs — achievements do work for users who enable them.

Part of epic #2705 — RetroAchievements integration