GemShell

Appearance

Dialog API ​

Native system dialogs for files, messages, and confirmations.

Methods ​

openFile(options?) ​

Open a single file picker.

javascript
const filePath = await gemshell.dialog.openFile({
  title: 'Select File',
  filters: [
    { name: 'Images', extensions: ['png', 'jpg', 'jpeg'] },
    { name: 'All Files', extensions: ['*'] }
  ]
});

if (filePath) {
  console.log('Selected:', filePath);
}

Parameters:

  • options - Optional configuration object
    • title - Dialog title (string)
    • filters - File type filters (array)
    • defaultPath - Starting directory (string)

Returns: Promise<string | null> - File path or null if cancelled

openFiles(options?) ​

Open a file picker that allows multiple selection.

javascript
const files = await gemshell.dialog.openFiles({
  title: 'Select Multiple Files',
  filters: [
    { name: 'Images', extensions: ['png', 'jpg', 'jpeg'] }
  ]
});

if (files && files.length > 0) {
  console.log('Selected:', files);
}

Parameters:

  • options - Same as openFile()

Returns: Promise<string[] | null> - Array of file paths or null if cancelled

saveFile(options?) ​

Open a save file dialog.

javascript
const savePath = await gemshell.dialog.saveFile({
  title: 'Save As',
  defaultPath: 'untitled.txt',
  filters: [
    { name: 'Text Files', extensions: ['txt'] }
  ]
});

if (savePath) {
  console.log('Save to:', savePath);
}

Parameters:

  • options - Optional configuration object
    • title - Dialog title (string)
    • defaultPath - Default filename (string)
    • filters - File type filters (array)

Returns: Promise<string | null> - File path or null if cancelled

selectFolder() ​

Open a folder picker.

javascript
const folder = await gemshell.dialog.selectFolder();

if (folder) {
  console.log('Selected folder:', folder);
}

Returns: Promise<string | null> - Folder path or null if cancelled

message(title, message) ​

Show a message dialog.

javascript
await gemshell.dialog.message('Success', 'Game saved!');
await gemshell.dialog.message('Error', 'Failed to load file');

Parameters:

  • title - Dialog title (string)
  • message - Message text (string)

Returns: Promise<boolean>

confirm(title, message) ​

Show a confirmation dialog.

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

Parameters:

  • title - Dialog title (string)
  • message - Message text (string)

Returns: Promise<boolean> - true if confirmed, false if cancelled

Examples ​

Import Custom Level ​

javascript
async function importLevel() {
  const filePath = await gemshell.dialog.openFile({
    title: 'Import Level',
    filters: [
      { name: 'Level Files', extensions: ['json', 'level'] }
    ]
  });
  
  if (filePath) {
    // Note: You'd need to use Node.js fs or fetch the file
    // The dialog just returns the path
    console.log('Import from:', filePath);
  }
}

Export Game Data ​

javascript
async function exportData() {
  const savePath = await gemshell.dialog.saveFile({
    title: 'Export Game Data',
    defaultPath: 'gamedata.json',
    filters: [
      { name: 'JSON', extensions: ['json'] }
    ]
  });
  
  if (savePath) {
    console.log('Export to:', savePath);
  }
}

Select Mod Folder ​

javascript
async function selectModFolder() {
  const folder = await gemshell.dialog.selectFolder({
    title: 'Select Mods Folder'
  });
  
  if (folder) {
    await gemshell.file.save('settings', { modFolder: folder });
  }
}

Confirm Quit ​

javascript
async function confirmQuit() {
  const save = await gemshell.dialog.confirm(
    'Unsaved Progress',
    'You have unsaved progress. Quit anyway?'
  );
  
  if (save) {
    await gemshell.window.close();
  }
}

Error Messages ​

javascript
async function showError(error) {
  await gemshell.dialog.message(
    'Error',
    `Something went wrong: ${error.message}`
  );
}

async function showSuccess(message) {
  await gemshell.dialog.message('Success', message);
}

Delete Confirmation ​

javascript
async function deleteSaveSlot(slot) {
  const confirmed = await gemshell.dialog.confirm(
    'Delete Save?',
    `Are you sure you want to delete save slot ${slot}? This cannot be undone.`
  );
  
  if (confirmed) {
    await gemshell.file.delete(`slot${slot}`);
    refreshSaveList();
  }
}

Image Selection ​

javascript
async function selectAvatar() {
  const file = await gemshell.dialog.openFile({
    title: 'Select Avatar Image',
    filters: [
      { name: 'Images', extensions: ['png', 'jpg', 'jpeg', 'gif', 'webp'] }
    ]
  });
  
  if (file) {
    setPlayerAvatar(file);
  }
}