retroachievements-js

🎮   A universal JavaScript wrapper for the RetroAchievements PHP API.

---

Features

• Aligns with the official RetroAchievements web API.
• Is promise-based.
• Supports Node environments.
• Supports browsers.
• Supports TypeScript.
• Small, <10Kb.

Contents

• Getting started
• Examples
  • Initializing the client
  • Top ten users by points
  • Get all console IDs
  • Get list of all registered Gameboy games
  • Basic game information for Super Mario Land (GB)
  • Full game information for Super Mario Land (GB)
  • Complete summary of Scott's progress for game ID 3
  • Scott's global rank and score
  • Scott's 10 most recently played games
  • Scott's progress on games with IDs 2, 3, and 75
  • Scott's user summary
  • Achievements earned by Scott on January 4th, 2014
  • Scott's game completion progress

Getting started

Install

npm install --save retroachievements-js

OR

yarn add retroachievements-js

Usage with Node

Node 10 and above are officially supported. The package can be imported via:

const RetroAchievementsClient = require('retroachievements-js');

Usage with TypeScript

You can use import syntax to utilize the package in your app. This library provides its own type definitions. "It just works", no need to install anything from @types.

import { RetroAchievementsClient } from 'retroachievements-js';

Understanding the Promise-based API

All methods in the API are async and return a native Promise.

These methods can be used with the native Promise API or the more modern async/await syntax.

// Native Promise API.
client.getTopTen().then(topTen => {
  console.log({ topTen });
});

// async/await syntax.
const logTopTenUsers = async () => {
  const topTen = await client.getTopTen();
  console.log({ topTen });
};

Examples

Initializing the Client

To initialize the client, you will need your username and your RetroAchievements Web API key. To get your Web API key, visit your control panel on the RetroAchievements website.

You can initialize the client like so:

import { RetroAchievementsClient } from 'retroachievements-js';

const client = new RetroAchievementsClient({
  userName: 'MyUserName', // this is your actual account name on the site
  apiKey: 'MyApiKey'
});

Please note if you are using this library in the browser then your API key will be exposed. This is not destructive, as the API is read-only, but that could change at any time. For this reason, I recommend only using the library on the server where your API key can be kept a secret.

Top ten users by points

const printTopTenUsers = async () => {
  const topTen = await client.getTopTenUsers();
  console.log({ topTen });
};

Get all console IDs

const printAllConsoleIds = async () => {
  const allConsoleIds = await client.getConsoleIds();
  console.log({ allConsoleIds });
};

Get list of all registered Gameboy games

const printAllGameboyGames = async () => {
  const allGameboyGames = await client.getGameListByConsoleId(4);
  console.log({ allGameboyGames });
};

Basic game information for Super Mario Land (GB)

const printGameInfo = async () => {
  const superMarioLandInfo = await client.getGameInfoByGameId(504);
  console.log({ superMarioLandInfo });
};

Full game information for Super Mario Land (GB)

const printExtendedGameInfo = async () => {
  const superMarioLandExtendedInfo = await client.getExtendedGameInfoByGameId(
    504
  );

  console.log({ superMarioLandExtendedInfo });
};

Complete summary of Scott's progress for game ID 3

const printUserGameProgress = async () => {
  const userGameProgress = await client.getUserProgressForGameId('Scott', 3);
  console.log({ userGameProgress });
};

Scott's global rank and score

const printUserGlobalRankAndScore = async () => {
  const userRankAndScore = await client.getUserRankAndScore('Scott');
  console.log({ userRankAndScore });
};

Scott's 10 most recently played games

const printUserRecentGames = async () => {
  const userRecentGames = await client.getUserRecentlyPlayedGames('Scott', 10);
  console.log({ userRecentGames });
};

Scott's progress on games with IDs 2, 3, and 75

const printUserMultipleGameProgress = async () => {
  const userProgress = await client.getUserProgressForGames('Scott', [
    2,
    3,
    75
  ]);

  console.log({ userProgress });
};

Scott's user summary

const printUserSummary = async () => {
  const userSummary = await client.getUserSummary('Scott');
  console.log({ userSummary });
};

Achievements earned by Scott on January 4th, 2014

const printUserAchievementsOnDate = async () => {
  const achievementsOnDate = await client.getUserAchievementsEarnedOnDate(
    'Scott',
    new Date('01-04-2014')
  );

  console.log({ achievementsOnDate });
};

Scott's game completion progress

const printUserCompletionProgress = async () => {
  const completionProgress = await client.getUserGameCompletionStats('Scott');
  console.log({ completionProgress });
};