Skip to main content

​
System requirements

​
Operating system

GameLord currently supports macOS 11+ only. Windows and Linux support is planned for a future release.
  • macOS 11 Big Sur or later
  • Apple Silicon (M1/M2/M3) or Intel processor

​
Software dependencies

  • Node.js 18+ - JavaScript runtime (download)
  • pnpm 10+ - Fast, disk space efficient package manager
  • Git - Version control (usually pre-installed on macOS)

​
Hardware recommendations

  • RAM: 8GB minimum, 16GB recommended
  • GPU: Integrated graphics sufficient for most systems; dedicated GPU recommended for intensive shaders
  • Display: Any resolution; high refresh rate displays (120Hz+) supported with vsync-aligned rendering

​
Installing dependencies

​
Install Node.js

brew install node@18
Verify the installation: 
node --version  # Should output v18.x.x or higher

​
Install pnpm

npm install -g pnpm
Verify the installation: 
pnpm --version  # Should output 10.x.x or higher
GameLord uses pnpm’s workspace feature. Always use pnpm commands, never npm or yarn.

​
Clone the repository

git clone https://github.com/yourusername/gamelord.git
cd gamelord

​
Install project dependencies

pnpm install
This installs all dependencies for the monorepo, including:
  • apps/desktop - The main Electron application
  • packages/ui - Shared UI components

​
Build the native addon

GameLord uses a native Node.js addon to load libretro cores directly. This must be compiled for your system: 
cd apps/desktop/native
npx node-gyp rebuild
cd ../../..
The build process uses node-gyp to compile C++ code. On macOS, this requires Xcode Command Line Tools, which are usually installed automatically.

​
Troubleshooting native addon build

If you encounter build errors:
The bundled node-gyp in npm versions 5.x is too old for Node.js 24+.Solution: Always use npx node-gyp instead of npm run build in the native directory:
cd apps/desktop/native
npx node-gyp rebuild
node-gyp requires Python 3.x.Solution: Install Python:
brew install python@3
The native addon wasn’t built or is in the wrong location.Solution: Rebuild the addon:
cd apps/desktop/native
npx node-gyp clean
npx node-gyp rebuild

​
Configuration

​
Environment variables

Create a .env file in apps/desktop/:
apps/desktop/.env
# ScreenScraper API developer credentials
# Register at https://www.screenscraper.fr/forumsujets.php?frub=12&numpage=0
SCREENSCRAPER_DEV_ID=your-dev-id
SCREENSCRAPER_DEV_PASSWORD=your-dev-password
Never commit your .env file to version control. It’s already in .gitignore.

​
Application directories

GameLord stores data in standard macOS locations:
TypePath
Library database~/Library/Application Support/GameLord/library.db
Libretro cores~/Library/Application Support/GameLord/cores/
BIOS files~/Library/Application Support/GameLord/BIOS/
Save states~/Library/Application Support/GameLord/saves/
Save RAM~/Library/Application Support/GameLord/saves/
Screenshots~/Library/Application Support/GameLord/screenshots/
Cover art cache~/Library/Application Support/GameLord/artwork/
Extracted ROMs~/Library/Application Support/GameLord/roms-cache/
These directories are created automatically on first launch.

​
BIOS files

Some systems require BIOS files for emulation:
  • Sega Saturn: sega_101.bin, mpr-17933.bin
  • PlayStation: scph5500.bin, scph5501.bin, scph5502.bin
  • Nintendo DS: bios7.bin, bios9.bin, firmware.bin
Place BIOS files in ~/Library/Application Support/GameLord/BIOS/.
BIOS files are copyrighted material. GameLord does not provide BIOS files. You must obtain them legally.

​
Running GameLord

​
Development mode

Start the app with hot reloading: 
pnpm start
This runs the following commands in parallel:
  • electron-vite dev - Builds and watches main/renderer/preload processes
  • Launches Electron with the development build

​
Production build

Build the app for distribution: 
pnpm run build
This creates optimized builds in apps/desktop/out/.

​
Other useful commands

# Type checking
pnpm typecheck

# Linting
pnpm lint

# Run tests
pnpm test

# Build Storybook (UI component documentation)
pnpm run build-storybook

​
Project structure

gamelord/
├── apps/
│   └── desktop/              # Main Electron application
│       ├── native/           # Native Node.js addon (C++)
│       │   ├── src/
│       │   │   ├── libretro_core.cc  # Core loading & API
│       │   │   ├── libretro_core.h
│       │   │   ├── libretro.h        # Libretro definitions
│       │   │   └── addon.cc          # N-API registration
│       │   └── binding.gyp           # Build configuration
│       ├── src/
│       │   ├── main/         # Main process
│       │   │   ├── index.ts
│       │   │   ├── GameWindowManager.ts
│       │   │   ├── emulator/
│       │   │   │   ├── EmulatorManager.ts
│       │   │   │   ├── EmulationWorkerClient.ts
│       │   │   │   └── LibretroNativeCore.ts
│       │   │   ├── workers/
│       │   │   │   └── core-worker.ts  # Utility process
│       │   │   └── ipc/
│       │   │       └── handlers.ts
│       │   ├── renderer/     # Renderer process (React)
│       │   │   ├── App.tsx
│       │   │   ├── components/
│       │   │   ├── hooks/
│       │   │   └── stores/
│       │   └── preload/      # Preload scripts
│       └── electron.vite.config.ts
├── packages/
│   └── ui/                   # Shared UI components
│       ├── src/
│       │   ├── components/
│       │   └── lib/
│       └── tsconfig.json
├── turbo.json                # Turborepo configuration
├── package.json              # Root package.json
└── pnpm-workspace.yaml       # pnpm workspace config

​
Next steps

Quickstart

Get your first game running quickly

Architecture

Learn about GameLord’s technical design

Playing games

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