GemShell

Appearance

Window API ​

Control the game window.

Methods ​

setSize(width, height) ​

Set the window size.

javascript
await gemshell.window.setSize(1280, 720);

Parameters:

  • width - Window width in pixels (number)
  • height - Window height in pixels (number)

Returns: Promise<boolean>

getSize() ​

Get the current window size.

javascript
const { width, height } = await gemshell.window.getSize();
console.log(`Window: ${width}x${height}`);

Returns: Promise<{ width: number, height: number }>

setPosition(x, y) ​

Set the window position on the screen.

javascript
await gemshell.window.setPosition(100, 100);

Parameters:

  • x - Horizontal position in pixels (number)
  • y - Vertical position in pixels (number)

Returns: Promise<boolean>

getPosition() ​

Get the current window position.

javascript
const { x, y } = await gemshell.window.getPosition();

Returns: Promise<{ x: number, y: number }>

setBounds(bounds) ​

Set position and size at once.

javascript
await gemshell.window.setBounds({ x: 100, y: 100, width: 1280, height: 720 });

Parameters:

  • bounds - Object with x, y, width, height (numbers)

Returns: Promise<boolean>

getBounds() ​

Get position and size of the window.

javascript
const bounds = await gemshell.window.getBounds();
// { x, y, width, height }

Returns: Promise<{ x: number, y: number, width: number, height: number }>

setMinSize(width, height) ​

Set the minimum window size.

javascript
await gemshell.window.setMinSize(800, 600);

Parameters:

  • width - Minimum width in pixels (number)
  • height - Minimum height in pixels (number)

Returns: Promise<boolean>

getMinSize() ​

Get the current minimum window size.

javascript
const { width, height } = await gemshell.window.getMinSize();

Returns: Promise<{ width: number, height: number }>

setTitle(title) ​

Set the window title.

javascript
await gemshell.window.setTitle('My Game - Level 5');

Parameters:

  • title - Window title (string)

Returns: Promise<boolean>

getTitle() ​

Get the current window title.

javascript
const title = await gemshell.window.getTitle();

Returns: Promise<string>

setFullscreen(enabled) ​

Enable or disable fullscreen mode.

javascript
await gemshell.window.setFullscreen(true);

Parameters:

  • enabled - true for fullscreen, false for windowed (boolean)

Returns: Promise<boolean>

isFullscreen() ​

Check if window is in fullscreen mode.

javascript
const fullscreen = await gemshell.window.isFullscreen();

Returns: Promise<boolean>

toggleFullscreen() ​

Toggle between fullscreen and windowed mode.

javascript
await gemshell.window.toggleFullscreen();

Returns: Promise<boolean>

setFrameless(enabled) ​

Show or hide the native window frame (titlebar and borders) at runtime.

The window is recreated internally, preserving position, size, title, fullscreen and maximized state.

javascript
await gemshell.window.setFrameless(true);

Parameters:

  • enabled - true for frameless, false for native frame (boolean)

Returns: Promise<boolean>

isFrameless() ​

Check if the window is currently frameless.

javascript
const frameless = await gemshell.window.isFrameless();

Returns: Promise<boolean>

toggleFrameless() ​

Toggle the frameless state.

javascript
await gemshell.window.toggleFrameless();

Returns: Promise<boolean>

setResizable(enabled) ​

Allow or prevent the user from resizing the window.

javascript
await gemshell.window.setResizable(false);

Parameters:

  • enabled - true to allow resizing (boolean)

Returns: Promise<boolean>

isResizable() ​

Check if the window is resizable.

javascript
const resizable = await gemshell.window.isResizable();

Returns: Promise<boolean>

setAlwaysOnTop(enabled) ​

Make the window stay above all other windows.

javascript
await gemshell.window.setAlwaysOnTop(true);

Parameters:

  • enabled - true to keep on top (boolean)

Returns: Promise<boolean>

isAlwaysOnTop() ​

Check whether the window is always-on-top.

javascript
const onTop = await gemshell.window.isAlwaysOnTop();

Returns: Promise<boolean>

toggleAlwaysOnTop() ​

Toggle the always-on-top state.

javascript
await gemshell.window.toggleAlwaysOnTop();

Returns: Promise<boolean>

setOpacity(opacity) ​

Set the window opacity. Values are clamped to 0..1.

javascript
await gemshell.window.setOpacity(0.8);

Parameters:

  • opacity - Opacity from 0 (transparent) to 1 (opaque) (number)

Returns: Promise<boolean>

getOpacity() ​

Get the current opacity.

javascript
const opacity = await gemshell.window.getOpacity();

Returns: Promise<number>

isMaximized() ​

Check if the window is maximized.

javascript
const maximized = await gemshell.window.isMaximized();

Returns: Promise<boolean>

isMinimized() ​

Check if the window is minimized.

javascript
const minimized = await gemshell.window.isMinimized();

Returns: Promise<boolean>

isVisible() ​

Check if the window is currently visible.

javascript
const visible = await gemshell.window.isVisible();

Returns: Promise<boolean>

isFocused() ​

Check if the window currently has focus.

javascript
const focused = await gemshell.window.isFocused();

Returns: Promise<boolean>

show() ​

Show the window if it was hidden.

javascript
await gemshell.window.show();

Returns: Promise<boolean>

hide() ​

Hide the window without closing it.

javascript
await gemshell.window.hide();

Returns: Promise<boolean>

minimize() ​

Minimize the window.

javascript
await gemshell.window.minimize();

Returns: Promise<boolean>

maximize() ​

Maximize the window (or unmaximize if already maximized).

javascript
await gemshell.window.maximize();

Returns: Promise<boolean>

restore() ​

Restore window from minimized state.

javascript
await gemshell.window.restore();

Returns: Promise<boolean>

focus() ​

Bring window to front and focus it.

javascript
await gemshell.window.focus();

Returns: Promise<boolean>

center() ​

Center the window on screen.

javascript
await gemshell.window.center();

Returns: Promise<boolean>

Quitting the game

There is no window.close() method. Use gemshell.app.quit() to exit the game.

Examples ​

Resolution Settings ​

javascript
const RESOLUTIONS = [
  { name: '720p', width: 1280, height: 720 },
  { name: '1080p', width: 1920, height: 1080 },
  { name: '1440p', width: 2560, height: 1440 },
];

async function setResolution(index) {
  const res = RESOLUTIONS[index];
  await gemshell.window.setSize(res.width, res.height);
}

Fullscreen Toggle ​

javascript
async function toggleFullscreen() {
  await gemshell.window.toggleFullscreen();
  const isFs = await gemshell.window.isFullscreen();
  updateFullscreenButton(isFs);
}

document.addEventListener('keydown', async (e) => {
  if (e.key === 'F11') {
    await gemshell.window.toggleFullscreen();
  }
});

Borderless Mode ​

javascript
async function enableBorderlessMode() {
  await gemshell.window.setFrameless(true);
  await gemshell.window.maximize();
}

Dynamic Title ​

javascript
async function updateTitle() {
  const baseTitle = 'My Awesome Game';
  const level = `Level ${currentLevel}`;
  const score = `Score: ${playerScore}`;
  
  await gemshell.window.setTitle(`${baseTitle} - ${level} - ${score}`);
}

Window State Management ​

javascript
async function saveWindowState() {
  const bounds = await gemshell.window.getBounds();
  const fullscreen = await gemshell.window.isFullscreen();
  const frameless = await gemshell.window.isFrameless();
  
  await gemshell.file.save('windowState', { bounds, fullscreen, frameless });
}

async function restoreWindowState() {
  const state = await gemshell.file.load('windowState');
  if (!state) return;
  await gemshell.window.setBounds(state.bounds);
  await gemshell.window.setFullscreen(state.fullscreen);
  await gemshell.window.setFrameless(state.frameless);
}

Picture-in-Picture Companion ​

javascript
async function pipMode() {
  await gemshell.window.setAlwaysOnTop(true);
  await gemshell.window.setOpacity(0.85);
  await gemshell.window.setSize(480, 270);
}

async function exitPipMode() {
  await gemshell.window.setAlwaysOnTop(false);
  await gemshell.window.setOpacity(1.0);
}

Quit Confirmation ​

javascript
async function quitGame() {
  const confirmed = await gemshell.dialog.confirm('Quit Game?', 'Are you sure you want to quit?');
  if (confirmed) {
    await gemshell.app.quit();
  }
}