Skip to content

v1.0.0

Latest
Latest

Choose a tag to compare

View all tags
@MichelleFindlay MichelleFindlay released this 10 Oct 20:27
v1.0.0
e5a27b4

The first stable release of XP Ledger: a self-hosted gaming dashboard that
brings Steam, Xbox, PlayStation, Nintendo and RetroAchievements together on one
page, with a live Twitch banner for when you're streaming. It's built in the
spirit of lastfm-dash and
styled as a game HUD that recolours itself from the current game's art.

Platforms

Platform Now playing Playtime Achievements Connects via
Steam (required) Live Lifetime, per-OS, plus the playtime ledger Yes, with unlock dates Official Web API key
Xbox / PC Game Pass Live, with rich presence Per game, where reported Gamerscore and progress OpenXBL (unofficial)
PlayStation (PS4 / PS5) Live Per game (PS4 / PS5) Trophies, by tier NPSSO token (unofficial)
Nintendo (Switch / Switch 2) Last played only Per game, plus the last 7 days None (Nintendo has none) Nintendo Account sign-in (unofficial)
RetroAchievements Live, with rich presence None Yes Official API key
Twitch Live banner when you're streaming n/a n/a Official Helix API

Everything except Steam is optional. Leave a platform's settings blank and it
stays out of the way.

Highlights

  • Now Playing across platforms: shows the game you're in on any connected
    platform, or the last one you played, with art, playtime,
    achievement/trophy progress, a session timer and a "previously played" card.
    Refreshes every 30 seconds.
  • Twitch live banner: when you go live, a banner with your stream
    embedded, title, game, viewers and uptime appears at the top of the page. It
    disappears when you stop, with no reload needed.
  • Playtime ledger: Steam only reports lifetime totals, so XP Ledger records
    how each game's playtime changes over time. That builds the dated history
    behind This Year / This Month / This Week / Today.
  • Most Played, Recently Played and Genre Breakdown, with a period picker.
  • Platform panels for Xbox (gamerscore, hours, recent titles), PlayStation
    (trophy level and platinum/gold/silver/bronze counts), Nintendo (hours and a
    7-day bar chart) and RetroAchievements (points, rank, mastered games).
  • Hover info cards on every game image: developer, release date, genres,
    your playtime and OS split, achievements or trophies, and review scores.
  • 10 insight widgets: Achievement Clock, Weekly Rhythm (with a play
    streak), Time Well Spent (your hours in Mario speedruns, Minecraft days and
    Games Done Quick marathons), Loot Tiers, Pile of Shame, Completionist, Rarest
    Unlocks, Hidden Gems, Mainstream Meter and Where You Play.
  • Gaming HUD look: display font, glowing corner brackets, segmented
    XP-style bars, and a player card showing your Steam level and XP.
  • MCP server (mcp.php, optional): lets AI assistants such as Claude and
    ChatGPT read your library, play history, achievements and every connected
    platform. Read-only.
  • Background job (cron.php): records playtime, fills in achievements and
    store data a batch at a time, keeps platform sign-ins fresh and pre-loads
    the page.

Requirements

  • PHP 7.4 or newer (8.x recommended). No database; everything is stored as
    files under cache/.
  • A free Steam Web API key, and a Steam profile with Game details set to
    Public.

Getting started

  1. cp config.sample.php config.php, then set steam_api_key and steam_id.
  2. Point a PHP web server at the folder, or run php -S localhost:8000.
  3. Schedule cron.php every 15 minutes, then set 'cron_enabled' => true.
  4. Optionally connect more platforms:
    • Xbox: paste your OpenXBL key into openxbl_api_key.
    • PlayStation: paste your NPSSO token into psn_npsso.
    • Nintendo: open nintendo-link.php and follow the steps.
    • Twitch: register a free app at dev.twitch.tv and add its Client ID
      and Secret.

The README has step-by-step setup for every platform and a full configuration
reference.

Known limitations

  • Period totals start when XP Ledger does. Steam keeps no dated history, so
    earlier play can't be reconstructed. Views say when their data is partial.
  • Most Played, Genre Breakdown and the playtime ledger are Steam-only.
    Other platforms' playtime shows in their own panels.
  • Xbox, PlayStation and Nintendo use unofficial APIs that can change
    without notice. OpenXBL's free tier allows 150 requests an hour (XP Ledger
    uses about 40–50).
  • Sign-ins expire: the PlayStation token lasts about two months and the
    Nintendo token about two years. The dashboard shows a banner when either
    needs renewing.
  • Nintendo has no live "now playing", and its play history updates a
    while after a session ends.
  • Playtime gaps: some Xbox games don't report playtime, and PlayStation
    playtime is PS4/PS5 only.
  • Twitch only plays its embedded player on a domain name. Use localhost
    or your site's domain, not a bare IP address.

Security notes

  • config.php holds your API keys and sign-in tokens. It's gitignored; keep
    it private.
  • cache/ stores access tokens and your playtime history. The included
    .htaccess blocks web access to it on Apache. On other web servers, block
    that folder yourself.
  • The MCP endpoint stays off until you set mcp_api_key.
  • nintendo-link.php stores nothing on the server. Delete it after
    connecting if you'd rather it wasn't there.
Assets 2
Loading