c64-cheevos

Open source Commodore 64 games achievements and high scores tracking.

Contributions welcome from C64 game devs who would like to add their games to C64Cade. Or from anyone who would like to see their favourite game added to C64Cade. C64Cade lets players play C64 games with global high score leaderboards and achievements.

Ultimately I hope that one day the emulator devs will pull their thumbs out and add support for RetroAchievements. The game achievements already added here could then be used in C64 RetroAchievements.

For a guide in adding support for your game to the repo follow the Documentation here: Writing game class files

The usage guide below is for those wishing to use C64-cheevos in their own projects.

Games Support

All games with high score checkmarks are available to play in C64Cade with global high score leaderboards.
All games with achievement checkmarks have achievements that can be unlocked in C64Cade.

| Game | Detector ID | High Scores | Achievements | |------------------------|---------------------|-------------|--------------| | Beach Head | beach-head | ✅ | ❌ | | Chuckie Egg | chuckie-egg | ✅ | ❌ | | Forbidden Forest | forbidden-forest | ✅ | ❌ | | Galaga | galaga | ✅ | ❌ | | Gribbly's Day Out | gribbly | ✅ | ❌ | | Hercules | hercules | ✅ | ❌ | | Legend of Wilf | legend-of-wilf | ✅ | ❌ | | Mario's Cement Factory | mario-cf | ✅ | ✅ | | Mole Attack | mole-attack | ✅ | ❌ | | Munchy Worm | munchy-worm | ✅ | ❌ | | Park Patrol | park-patrol | ❌ | ❌ | | Potty Pigeon | potty-pigeon | ✅ | ❌ | | Stix | stix | ✅ | ❌ | | Tilt | tilt | ✅ | ❌ | | Up 'n Down | up-n-down | ✅ | ❌ | | Uridium | uridium | ✅ | ✅ | | Vegetables Deluxe | vegetables-deluxe | ✅ | ❌ |

Install

- Link to this repo in your project and run:
npm install c64-cheevos

- In development you can install from c64-cheevos file path:
//package.json:
"c64-cheevos": "file:../../../c64-cheevos"

Usage

import { Uridium } from 'c64-cheevos'

const cheevos = new Uridium({
  gameId: 'game-id',
  user: { id: 'user-id', username: 'player' },
  cheevosSet,
  poppedCheevos: [],
  postScore: async (gameId, score, userId, username, variant) => {},
  popCheevo: async (cheevosSetId, userId, cheevoId) => ({
    achievement: { title: 'Achievement', description: 'Unlocked' }
  })
})

cheevos.cpuReadNS = (addr) => emulator.cpuReadNS(addr)
cheevos.ramRead = (addr) => emulator.ramRead(addr)

// Call execute in a RAF loop to check current RAM for achievements and score / lives / game over updates:
function update () {
   cheevos.execute();
   requestAnimationFrame(update);
};

requestAnimationFrame(update);

API Contract

Game classes accept these options:

• gameId: Host application game ID.
• user: Current player object with id and username when scores are submitted.
• cheevosSet: Achievement set object with _id and cheevos array.
• poppedCheevos: Previously unlocked achievements.
• postScore: Host callback for score persistence.
• popCheevo: Host callback for achievement persistence.

After constructing a class, attach memory-reader methods before calling execute():

• cpuReadNS(addr)
• cpuRead(addr) where needed
• ramRead(addr) where needed

Events are emitted through each instance's watcher from signal-js.

Registry Factory

Host applications can avoid their own game switch statements by using createCheevos:

import { createCheevos } from 'c64-cheevos'

const id = 'uridium'
const cheevos = await createCheevos(id, options)

Registered detector IDs include values such as uridium, mario-cf, tilt, and galaga. Unknown IDs return CheevoTemplate.

Documentation

• Writing game class files