GemShell

Appearance

GemShell API ​

Native desktop features available in your game at runtime.

Access via the global gemshell object in your game code.

Overview ​

javascript
// 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 ​

APIDescription
FileSave/load game data (key-value store)
WindowWindow size, fullscreen, title
InputPointer lock for FPS games
DialogNative file/folder dialogs
ClipboardCopy/paste text
NotificationSystem notifications
OSSystem info, open URLs

Version ​

javascript
// Get GemShell version
console.log(gemshell.version);
// '0.8.0'

Quick Examples ​

Save Game Data ​

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

Load Game Data ​

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

Toggle Fullscreen ​

javascript
await gemshell.window.toggleFullscreen();

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

Get System Info ​

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

Show Confirmation ​

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

if (confirmed) {
  await gemshell.file.delete('savegame');
}
javascript
await gemshell.os.openURL('https://mygame.com');

Feature Detection ​

Always check for availability to support both web and native:

javascript
// 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 ​

GemShell provides TypeScript definitions for autocomplete and type-checking:

typescript
declare global {
  interface Window {
    gemshell?: GemShellAPI;
  }
}

// Now you get autocomplete
if (window.gemshell) {
  const size = await window.gemshell.window.getSize();
}