getGameList function

Future<GameList> getGameList(
  1. AuthObject authorization, {
  2. required int consoleId,
  3. bool shouldOnlyRetrieveGamesWithAchievements = true,
  4. bool shouldRetrieveGameHashes = true,
})

A call to this function will retrieve the complete list of games for a specified console on the RetroAchievements.org platform.

@param authorization An object containing your userName and webApiKey. This can be constructed with buildAuthorization().

@param payload.consoleId The unique console ID to retrieve a list of games from. The list of consoleIds can be retrieved using the getConsoleIds() function provided by this library.

@param payload.shouldOnlyRetrieveGamesWithAchievements If truthy, will not return games that do not have achievements.

@param payload.shouldRetrieveGameHashes If truthy, will return valid hashes for game ROMs in an array attached to each game in the list.

@example

final gameList = await getGameList(
  authorization,
  GetGameListPayload(consoleId: 1, shouldOnlyRetrieveGamesWithAchievements: true),
);

@returns A list containing a list of games for a given consoleId.

[
  {
    title: 'Elemental Master',
    id: 4247,
    consoleId: 1,
    consoleName: 'Mega Drive',
    imageIcon: '/Images/048245.png',
    numAchievements: 44,
    numLeaderboards: 0,
    points: 500,
    dateModified: '2021-12-09 17:05:39',
    forumTopicId: 1972,
    hashes: ['32e1a15161ef1f070b023738353bde51']
  }
]

Implementation

Future<GameList> getGameList(
  AuthObject authorization, {
  required int consoleId,
  bool shouldOnlyRetrieveGamesWithAchievements = true,
  bool shouldRetrieveGameHashes = true,
}) async {
  Map<String, dynamic> callPayload = {'i': consoleId};

  if (shouldOnlyRetrieveGamesWithAchievements) {
    callPayload.addAll({
      'f': shouldOnlyRetrieveGamesWithAchievements ? 1 : 0,
    });
  }

  if (shouldRetrieveGameHashes) {
    callPayload.addAll({
      'h': shouldRetrieveGameHashes ? 1 : 0,
    });
  }

  final url = buildRequestUrl(
    apiBaseUrl,
    '/API_GetGameList.php',
    authorization,
    args: callPayload,
  );

  final response = await http.get(Uri.parse(url));

  if (response.statusCode == 200) {
    final rawResponse = jsonDecode(response.body) as List<dynamic>;
    final gameList = rawResponse.map((game) => GameEntity.fromJson(game)).toList();
    return gameList;
  } else {
    throw Exception('Failed to load game list');
  }
}