GemShell

Appearance

File API ​

Save and load game data using a simple key-value store.

Overview ​

javascript
// Save game data
await gemshell.file.save('savegame', { level: 5, score: 1200 });

// Load game data
const data = await gemshell.file.load('savegame');
// { level: 5, score: 1200 }

Key-Value Store

The File API uses keys (not file paths). Data is automatically stored as JSON in the user's app data folder. No need to manage directories or file extensions.

Methods ​

save(key, data) ​

Save data under a key. Data is automatically serialized to JSON.

javascript
await gemshell.file.save('settings', { volume: 0.8, fullscreen: true });
await gemshell.file.save('progress', { level: 3, coins: 500 });

Parameters:

  • key - Unique identifier for the save (string)
  • data - Any JSON-serializable data (object, array, string, number, boolean)

Returns: Promise<boolean> - true on success

load(key) ​

Load data by key. Returns null if key doesn't exist.

javascript
const settings = await gemshell.file.load('settings');
if (settings) {
  applySettings(settings);
}

Parameters:

  • key - The key to load (string)

Returns: Promise<any | null> - The saved data, or null if not found

delete(key) ​

Delete a saved key.

javascript
await gemshell.file.delete('savegame');

Parameters:

  • key - The key to delete (string)

Returns: Promise<boolean> - true if deleted, false if not found

exists(key) ​

Check if a key exists.

javascript
if (await gemshell.file.exists('savegame')) {
  // Load existing save
  const save = await gemshell.file.load('savegame');
}

Parameters:

  • key - The key to check (string)

Returns: Promise<boolean>

list() ​

Get all saved keys.

javascript
const keys = await gemshell.file.list();
// ['settings', 'savegame', 'slot1', 'slot2']

Returns: Promise<string[]> - Array of all keys

getPath() ​

Get the full path to the saves directory.

javascript
const savesPath = await gemshell.file.getPath();
// macOS: ~/Library/Application Support/Electron/mygame/saves/
// Windows: %APPDATA%/mygame/saves/
// Linux: ~/.config/mygame/saves/

Returns: Promise<string> - Full path to saves folder

Examples ​

Basic Save/Load ​

javascript
// Save
async function saveGame() {
  const gameState = {
    level: currentLevel,
    score: playerScore,
    inventory: playerInventory,
    position: { x: player.x, y: player.y }
  };
  await gemshell.file.save('savegame', gameState);
}

// Load
async function loadGame() {
  const data = await gemshell.file.load('savegame');
  if (data) {
    currentLevel = data.level;
    playerScore = data.score;
    playerInventory = data.inventory;
    player.x = data.position.x;
    player.y = data.position.y;
    return true;
  }
  return false; // No save found
}

Multiple Save Slots ​

javascript
async function saveToSlot(slot) {
  const data = {
    level: currentLevel,
    score: playerScore,
    savedAt: Date.now()
  };
  await gemshell.file.save(`slot${slot}`, data);
}

async function loadFromSlot(slot) {
  return await gemshell.file.load(`slot${slot}`);
}

async function getSaveSlots() {
  const keys = await gemshell.file.list();
  const slots = [];
  
  for (const key of keys) {
    if (key.startsWith('slot')) {
      const data = await gemshell.file.load(key);
      slots.push({
        key,
        level: data.level,
        savedAt: new Date(data.savedAt).toLocaleDateString()
      });
    }
  }
  return slots;
}

async function deleteSlot(slot) {
  await gemshell.file.delete(`slot${slot}`);
}

Settings ​

javascript
const DEFAULT_SETTINGS = {
  volume: 1.0,
  musicVolume: 0.8,
  sfxVolume: 1.0,
  fullscreen: false,
  language: 'en'
};

async function loadSettings() {
  const saved = await gemshell.file.load('settings');
  return { ...DEFAULT_SETTINGS, ...saved };
}

async function saveSettings(settings) {
  await gemshell.file.save('settings', settings);
}

Auto-Save ​

javascript
let lastSaveTime = 0;
const AUTO_SAVE_INTERVAL = 60000; // 1 minute

function update() {
  // Game logic...
  
  // Auto-save check
  if (Date.now() - lastSaveTime > AUTO_SAVE_INTERVAL) {
    gemshell.file.save('autosave', getGameState());
    lastSaveTime = Date.now();
  }
}

Fallback for Web ​

javascript
async function saveGame(data) {
  if (typeof gemshell !== 'undefined') {
    // Native save
    await gemshell.file.save('savegame', data);
  } else {
    // Web fallback
    localStorage.setItem('savegame', JSON.stringify(data));
  }
}

async function loadGame() {
  if (typeof gemshell !== 'undefined') {
    return await gemshell.file.load('savegame');
  } else {
    const saved = localStorage.getItem('savegame');
    return saved ? JSON.parse(saved) : null;
  }
}

Storage Location ​

Saves are stored in the user's app data directory:

PlatformLocation
macOS~/Library/Application Support/Electron/<app-name>/saves/
Windows%APPDATA%/<app-name>/saves/
Linux~/.config/<app-name>/saves/

Each key is stored as a separate .json file.