Skip to main content

​
Prerequisites

Before you begin, make sure you have:
  • Node.js 18+ installed (download)
  • pnpm 10+ package manager (install instructions)
  • macOS 11+ (currently macOS only, Windows/Linux support planned)
GameLord uses pnpm as its package manager. Always use pnpm commands, never npm or yarn.

​
Installation

1

Clone the repository

git clone https://github.com/ryanmagoon/gamelord.git
cd gamelord
2

Install dependencies

pnpm install
This will install all dependencies for the monorepo, including the desktop app and UI packages.
3

Build the native addon

cd apps/desktop/native
npx node-gyp rebuild
cd ../../..
The bundled node-gyp in npm is incompatible with Node.js 24+. Always use npx node-gyp to ensure you’re using the latest version.
4

Start the development server

pnpm start
This starts the Electron app in development mode with hot reloading.

​
Add your first game

Once GameLord is running:
1

Place ROMs in a folder

Create a folder for your ROMs, for example:
mkdir ~/Games/NES
mkdir ~/Games/SNES
GameLord supports multiple formats including .nes, .sfc, .smc, .gb, .gba, .n64, .nds, .iso, .chd, and .zip archives.
2

Scan your library

In the GameLord UI:
  1. Click the Settings button in the toolbar
  2. Select Add Library Folder
  3. Choose your ROMs folder
  4. Wait for the scan to complete
GameLord will automatically detect system types based on file extensions and folder names. ZIP archives are extracted automatically (except for arcade games).
3

Download metadata and artwork

After scanning, GameLord can fetch game metadata and cover art from ScreenScraper:
  1. Click the Sync Artwork button
  2. Wait for the download to complete
You’ll need ScreenScraper API credentials for metadata fetching. See the Configuration section below.
4

Play your game

Simply click on a game card to launch it! GameLord will:
  • Automatically download the required libretro core if needed
  • Apply appropriate shaders based on system type
  • Start the emulation with optimized performance settings

​
Configuration

​
ScreenScraper API credentials

To enable metadata and cover art fetching, you need ScreenScraper API credentials:
1

Register for a ScreenScraper account

Visit ScreenScraper and register for a developer account.
2

Create a .env file

In apps/desktop/, create a .env file:
.env
# ScreenScraper API developer credentials
SCREENSCRAPER_DEV_ID=your-dev-id
SCREENSCRAPER_DEV_PASSWORD=your-dev-password
3

Restart GameLord

Stop and restart the development server:
pnpm start

​
Keyboard shortcuts

GameLord includes several keyboard shortcuts for quick actions:
ShortcutAction
F5Quick save
F9Quick load
SpacePause/Resume
EscStop emulation
Cmd+FToggle fullscreen

​
Next steps

Full installation guide

Learn about advanced configuration and setup options

Architecture

Understand how GameLord works under the hood

User Guide

Learn how to play and manage games

API Reference

Explore the developer API

Build docs developers (and LLMs) love

Get started for freeTalk to us