Getting Started with Overlays

This guide walks you through creating your first Grids overlay — a custom web UI that renders transparently on top of the game viewport.

Prerequisites

• Node.js 20+
• npm 10+
• The Grids game project cloned locally

Scaffold a New Overlay

Use the CLI scaffolder to create a new overlay project:

cd overlays
npm run create

You'll be prompted for a name. The scaffolder creates a new directory under overlays/core/<name>/ with:

• package.json — dependencies on @grids/overlay-sdk, @grids/ui, React 19, Tailwind 4
• vite.config.ts — Vite build configuration with React and Tailwind plugins
• tsconfig.json — TypeScript configuration
• index.html — Entry point
• src/main.tsx — React 19 root
• src/App.tsx — Your overlay component
• src/styles.css — Tailwind + design system imports

Development

Start the dev server:

npm run dev -w core/<name>

This launches Vite at http://localhost:3100+ (port varies by overlay). You'll see the SDK in dev mode — a mock bridge with a devtools panel for simulating game events.

Using the SDK

Import and use the SDK to communicate with the game:

import { grids } from '@grids/overlay-sdk';

// Listen for events from the game engine
grids.on('my-overlay:init', (data) => {
  console.log('Received init data:', data);
});

// Send events to the game engine
grids.send('my-overlay:action', { value: 42 });

// Request input focus (overlay becomes interactive)
grids.requestFocus();

// Release input back to the game
grids.releaseFocus();

// Request the overlay to close
grids.close();

Using Design System Components

Import pre-built components from @grids/ui:

import { Button, Card, Badge, Input, ScrollArea, Spinner } from '@grids/ui';

export function App() {
  return (
    <Card variant="raised" padding="md">
      <h1>My Overlay</h1>
      <Button variant="primary" onClick={() => grids.close()}>
        Close
      </Button>
    </Card>
  );
}

Build & Deploy

Build the overlay for production:

npm run build -w core/<name>

Deploy to the game's content directory:

npm run deploy -w core/<name>

This copies the built files to Content/Overlays/<name>/. The overlay is now accessible in-game via:

grids.overlay.open <name>

Overlay Styles

By default, the design system applies a semi-transparent dark backdrop (rgba(0, 0, 0, 0.5)). If your overlay should float without a backdrop (like toasts or context menus), override it in your styles.css:

body {
  background: transparent;
}