Add Your Framework

Want your HTML5 game framework to appear in GemShell's template selector? We'd love to include it!

Benefits for Frameworks

By adding your framework to GemShell, you get:

• Instant Visibility - Your framework appears alongside popular engines like Phaser and Three.js
• One-Click Setup - Users can create projects with your framework in seconds
• Desktop Publishing - Games built with your framework can be packaged as native desktop apps
• Steam Integration - Your framework's games get access to Steamworks features out of the box
• Growing User Base - Reach game developers looking for easy desktop deployment

Pre-integrate GemShell APIs

You can make your templates even more powerful by pre-integrating GemShell's APIs. This gives your users immediate access to desktop and Steam features:

Steamworks API

Your templates can include Steam integration for achievements, leaderboards, and more:

// Check if running in GemShell desktop build
if (window.gemshell?.steam) {
  // Unlock a Steam achievement
  window.gemshell.steam.unlockAchievement('FIRST_BLOOD');
  
  // Submit to leaderboard
  window.gemshell.steam.submitScore('highscores', 1000);
}

See the full Steamworks API documentation for all available methods.

Native Desktop API

Access native desktop features like file system, window controls, and more:

if (window.gemshell) {
  // Save game data to disk
  window.gemshell.fs.writeFile('save.json', JSON.stringify(gameState));
  
  // Toggle fullscreen
  window.gemshell.window.setFullscreen(true);
}

See the API Overview for all available native methods including:

• File System - Read/write files
• Window - Fullscreen, resize, etc.
• Dialog - Native dialogs
• Clipboard - Copy/paste
• Notifications - System notifications

Feature Detection

Always check for window.gemshell before using APIs. This ensures your game still works in browsers and other environments.

Currently Supported

Code Frameworks

• Kaplay
• Phaser
• PixiJS
• Excalibur
• melonJS
• LittleJS
• Three.js
• Babylon.js
• Kontra

Game Editors

GemShell also works great with visual game editors! No code integration needed - just export your game as HTML5 and open the folder in GemShell.

• GDevelop - Free, open-source game engine
• Construct - Powerful editor with visual scripting
• RPG Maker MV/MZ - Create RPGs without programming

Requirements

To be added to the registry, your framework needs:

1. A GitHub repository with a starter template (downloadable as ZIP)
2. Vite-compatible build (or similar modern bundler)
3. index.html as the entry point
4. Active maintenance - the template should work with current versions

What We Need From You

Send us a link to a gemshell.json file hosted in your repository or gist. The JSON should contain:

{
  "id": "your-framework",
  "name": "Your Framework",
  "version": "1.0.0",
  "description": "A brief description of your framework",
  "logo": "https://your-domain.com/logo.png",
  "website": "https://your-framework.com",
  "docs": "https://your-framework.com/docs",
  "discord": "https://discord.gg/your-invite",
  "tags": ["2d", "typescript", "beginner-friendly"],
  "templates": [
    {
      "id": "starter",
      "name": "Starter Template",
      "description": "Basic setup to get started quickly",
      "source": "https://github.com/your-org/your-template/archive/refs/heads/main.zip",
      "default": true
    }
  ]
}

Field Reference

Field	Required	Description
id	Yes	Unique lowercase identifier (e.g., my-framework)
name	Yes	Display name
version	Yes	Current framework version
description	Yes	Short description (1 sentence)
logo	Yes	URL to logo image (PNG/SVG, min 128x128)
website	Yes	Official website URL
docs	Yes	Documentation URL
discord	No	Discord invite link (displayed in app)
tags	Yes	Array of tags: 2d, 3d, typescript, lightweight, beginner-friendly, ecs, webgl, webgpu, etc.
templates	Yes	Array of template objects

Template Object

Field	Required	Description
id	Yes	Unique identifier within framework
name	Yes	Display name
description	Yes	Short description
source	Yes	GitHub ZIP download URL
default	No	Set true for the recommended template

GitHub ZIP URL Format

Use this format for GitHub repositories:

https://github.com/OWNER/REPO/archive/refs/heads/BRANCH.zip

Example: https://github.com/phaserjs/template-vite-ts/archive/refs/heads/main.zip

Submit Your Framework

Ready to submit? Send us a DM on Discord!

Discord

Join GemShell Discord

Send us a DM with a link to your gemshell.json and we'll review it within a few days.

Questions?

If you have any questions about the submission process or need help preparing your template, feel free to ask on Discord. We're happy to help!