GemShell

Appearance

Getting Started ​

GemShell turns your HTML5 game into a native desktop application for Windows, macOS, and Linux.

Requirements ​

  • GemShell (download from itch.io or gemshell.dev)
  • An HTML5 game with an index.html entry point
  • macOS, Windows, or Linux for building

Quick Start ​

1. Open GemShell ​

Launch GemShell and you'll see the dashboard with your recent games.

2. Start a Project ​

You have two options:

Option A: Create New Game ​

Click "Create New Game" to start from a template:

  1. Choose a game framework (Phaser, Kaplay, PixiJS, Three.js, and more)
  2. Select a starter template (TypeScript, JavaScript, etc.)
  3. Pick a location and name for your project
  4. Click "Create Project" - GemShell downloads the template and sets everything up

Your new project is ready to develop! Open it in your favorite code editor.

Build Before Packaging

After developing your game, you need to build it before packaging with GemShell:

bash
npm install      # Install dependencies (first time only)
npm run build    # Create production build

GemShell packages the built output (usually dist/ folder), not the source code.

Visual Game Editors

Using GDevelop or Construct? Select the editor in the template list and follow the export guide. No code needed - just export as HTML5 and open the folder in GemShell.

Option B: Open Existing Game ​

Click "Open Folder" and choose the folder containing your HTML5 game.

Your game folder should have this structure:

my-game/
├── index.html    (required - entry point)
├── game.js
├── style.css
├── node_modules/ (optional - npm packages)
└── assets/
    ├── sprites/
    └── sounds/

Node.js is available

Your game has full Node.js access — require() works out of the box. If you need npm packages, just npm install them in your game folder. GemShell automatically includes node_modules/ in your build.

Pure-JS packages (e.g. lodash, dayjs, socket.io-client) work immediately.

Native packages (ones with compiled .node binaries like better-sqlite3, uiohook-napi) need to be installed for Electron's Node version instead of your system Node:

bash
npm install <package> --runtime=electron --target=33.3.1 --disturl=https://electronjs.org/headers

GemShell currently uses Electron 33.3.1. You can verify by typing process.versions.electron in DevTools.

3. Configure Settings ​

Set your game's basic information:

  • Game Title - Display name
  • App Name - Unique identifier (e.g., my-awesome-game)
  • Version - Semantic version (e.g., 1.0.0)
  • Window Size - Default width and height

4. Select Platforms ​

Choose which platforms to build for:

  • macOS - ARM64 (Apple Silicon), x64 (Intel)
  • Windows - x64, ARM64, 32-bit
  • Linux - x64, ARM64

5. Build ​

Click "Build" and GemShell will:

  1. Copy your game files
  2. Optimize assets (Pro)
  3. Package with Electron
  4. Create platform-specific executables

Your builds will be in ~/GemShell-Builds/GameName-Version/.

6. Deploy (Pro) ​

With GemShell Pro, deploy to Steam and itch.io in one click. Configure once, then ship updates instantly.

Next Steps ​