GemShell API

Native desktop features available in your game at runtime.

Access via the global gemshell object in your game code.

Overview

// Check if running in GemShell
if (typeof gemshell !== 'undefined') {
  // Native features available
  const os = await gemshell.os.getName();
  console.log(`Running on ${os}`);
}

Available APIs

Core (always available)

API	Description
File	Save/load game data (key-value store)
Assets	External asset loading: drop a mods/ folder for hot-swap + Steam Workshop auto-mount
Window	Window size, position, fullscreen, frameless, opacity
App	App name/version, paths, quit, relaunch
Screen	Display info and cursor position
Input	Pointer lock for FPS games
Dialog	Native file/folder dialogs
Clipboard	Copy/paste text
Notification	System notifications
OS	System info, open URLs

Steamworks (when enabled in gemshell.config.json)

API	Description
Overview	Init, callbacks, lifecycle
User Info	Steam ID, persona name, friends, avatars
Achievements	Unlock, query, stats
Cloud Saves	Steam Cloud file storage
Leaderboards	Find, upload, download scores
Lobbies & P2P	Matchmaking and peer-to-peer networking
Rich Presence	Set "playing as..." text
Overlay	Steam in-game overlay
Input	Controller and Steam Input API
Utils & DLC	DLC, Big Picture, Steam Deck, server time

Tooling

TypeScript Support	Official .d.ts for autocomplete + type-checking

Game Version

console.log(gemshell.version);  // e.g. '1.0.0'

Returns your game's version, taken from app.version in your gemshell.config.json. Synchronous shortcut for await gemshell.app.getVersion().

Quick Examples

Save Game Data

const gameState = {
  level: currentLevel,
  score: playerScore,
  inventory: playerInventory
};
await gemshell.file.save('savegame', gameState);

Load Game Data

const save = await gemshell.file.load('savegame');
if (save) {
  currentLevel = save.level;
  playerScore = save.score;
  playerInventory = save.inventory;
}

Toggle Fullscreen

await gemshell.window.toggleFullscreen();

// Or check and set
const isFullscreen = await gemshell.window.isFullscreen();
await gemshell.window.setFullscreen(!isFullscreen);

Get System Info

const os = await gemshell.os.getName();     // 'macOS', 'Windows', 'Linux'
const locale = await gemshell.os.getLocale(); // 'en_US', 'de_DE', etc.

Show Confirmation

const confirmed = await gemshell.dialog.confirm(
  'Delete Save?',
  'This cannot be undone.'
);

if (confirmed) {
  await gemshell.file.delete('savegame');
}

Open External Link

await gemshell.os.openURL('https://mygame.com');

Feature Detection

Always check for availability to support both web and native:

// Check if GemShell is available
function hasGemShell() {
  return typeof gemshell !== 'undefined';
}

// Save with fallback to localStorage
async function saveGame(data) {
  if (hasGemShell()) {
    await gemshell.file.save('savegame', data);
  } else {
    localStorage.setItem('savegame', JSON.stringify(data));
  }
}

// Load with fallback
async function loadGame() {
  if (hasGemShell()) {
    return await gemshell.file.load('savegame');
  } else {
    const saved = localStorage.getItem('savegame');
    return saved ? JSON.parse(saved) : null;
  }
}

TypeScript Support

Official type definitions covering the entire API (including Steamworks) are available as a single file:

Download gemshell.d.ts - or read the full setup guide.

/// <reference path="./gemshell.d.ts" />

if (gemshell) {
  const size = await gemshell.window.getSize();
  // Autocomplete, parameter hints and type-checking everywhere
}