GemShell

Appearance

Steam Achievements ​

Unlock and query achievements.

Methods ​

unlockAchievement(name) ​

Unlock an achievement.

javascript
await steam.unlockAchievement('ACH_WIN_FIRST_GAME');
await steam.storeStats(); // Required to save

getAchievement(name) ​

Check if achievement is unlocked.

javascript
const unlocked = await steam.getAchievement('ACH_WIN_FIRST_GAME');
// true or false

clearAchievement(name) ​

Clear an achievement (for testing).

javascript
await steam.clearAchievement('ACH_WIN_FIRST_GAME');
await steam.storeStats();

storeStats() ​

Save achievements and stats to Steam.

javascript
await steam.storeStats();

WARNING

Always call storeStats() after modifying achievements or stats.

Stats ​

setStatInt(name, value) ​

Set an integer stat.

javascript
await steam.setStatInt('TOTAL_KILLS', 100);
await steam.storeStats();

getStatInt(name) ​

Get an integer stat.

javascript
const kills = await steam.getStatInt('TOTAL_KILLS');

setStatFloat(name, value) ​

Set a float stat.

javascript
await steam.setStatFloat('TOTAL_DISTANCE', 1234.56);
await steam.storeStats();

getStatFloat(name) ​

Get a float stat.

javascript
const distance = await steam.getStatFloat('TOTAL_DISTANCE');

Examples ​

Basic Achievement ​

javascript
async function onBossDefeated(bossName) {
  // Achievement for first boss
  if (bossName === 'Dragon') {
    await steam.unlockAchievement('ACH_DEFEAT_DRAGON');
    await steam.storeStats();
  }
}

Progress Achievement ​

javascript
async function onEnemyKilled() {
  const kills = await steam.getStatInt('TOTAL_KILLS') || 0;
  await steam.setStatInt('TOTAL_KILLS', kills + 1);
  
  // Achievement at 100 kills
  if (kills + 1 >= 100) {
    await steam.unlockAchievement('ACH_100_KILLS');
  }
  
  await steam.storeStats();
}

Track Distance ​

javascript
let sessionDistance = 0;

function onMove(delta) {
  sessionDistance += delta;
}

async function onGameEnd() {
  const total = await steam.getStatFloat('TOTAL_DISTANCE') || 0;
  await steam.setStatFloat('TOTAL_DISTANCE', total + sessionDistance);
  
  // Achievement for 10km
  if (total + sessionDistance >= 10000) {
    await steam.unlockAchievement('ACH_MARATHON');
  }
  
  await steam.storeStats();
  sessionDistance = 0;
}

Multiple Achievements ​

javascript
const ACHIEVEMENTS = {
  firstWin: 'ACH_FIRST_WIN',
  perfectLevel: 'ACH_PERFECT',
  speedrun: 'ACH_SPEEDRUN',
  collector: 'ACH_ALL_ITEMS'
};

async function checkAchievements(gameState) {
  if (gameState.wins >= 1) {
    await steam.unlockAchievement(ACHIEVEMENTS.firstWin);
  }
  
  if (gameState.perfectLevels >= 1) {
    await steam.unlockAchievement(ACHIEVEMENTS.perfectLevel);
  }
  
  if (gameState.fastestTime < 60) {
    await steam.unlockAchievement(ACHIEVEMENTS.speedrun);
  }
  
  if (gameState.items.length >= 50) {
    await steam.unlockAchievement(ACHIEVEMENTS.collector);
  }
  
  await steam.storeStats();
}

Steamworks Dashboard ​

Define achievements in your Steamworks dashboard:

  1. Go to Steamworks Partner
  2. Select your app
  3. Navigate to Stats & Achievements
  4. Add achievements with API names
  5. Upload icons (64x64 locked, 64x64 unlocked)