GameGlue SDK

The official JavaScript SDK for GameGlue - build game addons with nothing more than HTML and JavaScript.

What is GameGlue?

GameGlue streams real-time telemetry from PC games to your web applications. The SDK supports bidirectional data flow - receive telemetry updates and send commands back to control the game.

Supported Games:

• Microsoft Flight Simulator (MSFS)
• X-Plane 12

Installation

# npm
npm install gameglue

# yarn
yarn add gameglue

Or use the CDN:

<script src="https://unpkg.com/gameglue/dist/gg.umd.js"></script>

Quick Start

import GameGlue from 'gameglue';

const gg = new GameGlue({
  clientId: '<your-client-id>',
  redirect_uri: window.location.origin,
  scopes: ['msfs:read', 'msfs:write']  // or ['xplane:read', 'xplane:write']
});

// Check authentication (handles OAuth callback automatically)
if (!await gg.isAuthenticated()) {
  gg.login();
  return;
}

// Create a listener
const listener = await gg.createListener({
  userId: gg.getUser(),
  gameId: 'msfs'  // or 'xplane'
});

// Receive telemetry
listener.on('update', (evt) => {
  console.log('Altitude:', evt.data.indicated_altitude);
  console.log('Airspeed:', evt.data.airspeed_indicated);
});

// Send commands
await listener.sendCommand('autopilot_on', true);

Getting Started

1. Sign up at developer.gameglue.gg
2. Register your application in the Developer Hub
3. Install the SDK and initialize with your client ID

Telemetry Updates

Subscribe to real-time telemetry with listener.on('update', ...):

listener.on('update', (evt) => {
  // evt.data contains normalized field names (work across all sims)
  console.log('Altitude:', evt.data.indicated_altitude);
  console.log('Heading:', evt.data.heading_indicator);

  // evt.raw contains the original game-specific field names
  console.log('Raw data:', evt.raw);
});

Field Subscriptions

Subscribe to specific fields only (reduces bandwidth):

const listener = await gg.createListener({
  userId: gg.getUser(),
  gameId: 'msfs',
  fields: ['indicated_altitude', 'airspeed_indicated', 'heading_indicator']
});

Manage subscriptions dynamically:

// Add fields
await listener.subscribe(['vertical_speed', 'autopilot_master']);

// Remove fields
await listener.unsubscribe(['heading_indicator']);

// Check current subscriptions
const fields = listener.getFields();  // Returns array or null (all fields)

Note: You cannot unsubscribe if you initialized the listener with all fields (fields: null or omitted). Use subscribe() first to set an explicit field list.

Key Events

Beyond raw telemetry, the SDK provides computed events for significant flight moments:

Landing Events

listener.on('landing', (evt) => {
  console.log(`${evt.quality} landing at ${Math.abs(evt.landing_rate)} fpm`);
  console.log(`Bounces: ${evt.bounce_count}`);
});

Landing quality ratings: butter (<60 fpm), smooth (60-120), normal (120-180), firm (180-300), hard (300-600), crash (>600)

Takeoff Events

listener.on('takeoff', (evt) => {
  console.log(`Rotation at ${evt.rotation_speed} kts`);
  console.log(`Pitch: ${evt.pitch_at_liftoff}°`);
});

Flight Phase Events

listener.on('flight_phase', (evt) => {
  console.log(`Phase: ${evt.previous_phase} → ${evt.phase}`);
});

Phases: parked, taxi_out, takeoff_roll, initial_climb, climb, cruise, descent, approach, final, landing_roll, taxi_in

Sending Commands

Send commands to control the simulator:

const result = await listener.sendCommand('autopilot_on', true);

if (result.status === 'success') {
  console.log('Command sent');
} else {
  console.error('Failed:', result.reason);
}

Commands use normalized names that work across simulators:

// Autopilot
await listener.sendCommand('autopilot_on', true);
await listener.sendCommand('autopilot_heading_hold_on', true);
await listener.sendCommand('set_autopilot_altitude', 35000);

// Gear and Flaps
await listener.sendCommand('gear_toggle', true);
await listener.sendCommand('flaps_down', true);

// Lights
await listener.sendCommand('landing_lights_on', true);
await listener.sendCommand('nav_lights_toggle', true);

See the full command reference for all available commands.

Authentication

// Check if authenticated (handles OAuth callback automatically)
const isAuth = await gg.isAuthenticated();

// Redirect to login
gg.login();

// Get user ID
const userId = gg.getUser();

// Get access token
const token = gg.getAccessToken();

// Logout (clear local tokens only)
gg.logout({ redirect: false });

// Logout and redirect to Keycloak logout
gg.logout();

Scopes

| Scope | Description | |-------|-------------| | msfs:read | Read MSFS telemetry | | msfs:write | Send commands to MSFS | | xplane:read | Read X-Plane telemetry | | xplane:write | Send commands to X-Plane |

API Reference

GameGlue

| Method | Description | |--------|-------------| | new GameGlue(config) | Initialize SDK with clientId, redirect_uri, scopes | | isAuthenticated() | Check auth status. Handles OAuth callback if present. Returns Promise<boolean> | | login() | Redirect to GameGlue login | | logout(options?) | Log out. Pass { redirect: false } to only clear local tokens | | getUser() | Returns authenticated user's ID | | getAccessToken() | Returns current access token | | createListener(config) | Create listener for game telemetry | | onTokenRefreshed(callback) | Register callback for token refresh events |

Listener

| Method | Description | |--------|-------------| | on('update', callback) | Subscribe to telemetry updates | | on('landing', callback) | Subscribe to landing events | | on('takeoff', callback) | Subscribe to takeoff events | | on('flight_phase', callback) | Subscribe to flight phase changes | | sendCommand(command, value) | Send command to simulator | | subscribe(fields) | Add fields to subscription | | unsubscribe(fields) | Remove fields from subscription | | getFields() | Get current subscribed fields (null = all) |

TypeScript

The SDK includes TypeScript definitions:

import GameGlue, {
  LandingEvent,
  TakeoffEvent,
  FlightPhaseEvent,
  UpdateEvent
} from 'gameglue';

listener.on('landing', (evt: LandingEvent) => {
  console.log(evt.quality, evt.landing_rate);
});

listener.on('update', (evt: UpdateEvent) => {
  console.log(evt.data.indicated_altitude);
});

Examples

See the examples/ directory:

• flight-dashboard.html - Complete flight dashboard with instruments and autopilot control
• telemetry-validator.html - Developer tool for testing all fields and commands

Documentation

Full documentation at docs.gameglue.gg:

• Quick Start Guide
• Authentication Guide
• Key Events Guide
• Sending Commands
• MSFS Reference
• X-Plane Reference

License

MIT