Gaming Integration

This guide shows concrete HTTP and NATS examples for talking to Orbital from your game backend or client.

Quick start

1. Game Configuration

First, configure your game in Orbital:

const gameConfig = await fetch('/api/games/config', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    gameId: 'my-awesome-game',
    name: 'My Awesome Game',
    settings: {
      maxPlayers: 4,
      matchDuration: 600, // 10 minutes
    },
  }),
});

2. Player Sessions

Create a player session when a player joins:

const session = await fetch('/api/games/sessions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    gameId: 'my-awesome-game',
  }),
});

const { sessionId, playerId } = await session.json();

3. Game State Updates

Update game state in real-time:

await fetch(`/api/games/sessions/${sessionId}/state`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    score: 1500,
    level: 5,
    position: { x: 100, y: 200 },
    inventory: ['sword', 'shield'],
  }),
});

Real-time features

Subscribe to game events

import { connect } from 'nats.ws';

const nc = await connect({
  servers: 'wss://nats.orbital.com',
  token: yourAuthToken,
});

// Subscribe to game events
const sub = nc.subscribe('game.my-awesome-game.events');

for await (const msg of sub) {
  const event = JSON.parse(msg.data);

  switch (event.type) {
    case 'player.joined':
      console.log('Player joined:', event.playerId);
      break;
    case 'state.updated':
      updateGameState(event.state);
      break;
    case 'match.ended':
      showResults(event.results);
      break;
  }
}

Publish game events

// Notify other players
nc.publish('game.my-awesome-game.events', JSON.stringify({
  type: 'player.action',
  playerId: currentPlayer,
  action: 'attack',
  target: enemyId,
}));

Achievements

Define achievements

await fetch('/api/games/achievements', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    gameId: 'my-awesome-game',
    achievements: [
      {
        id: 'first-win',
        name: 'First Victory',
        description: 'Win your first match',
        icon: 'trophy',
      },
      {
        id: 'speed-demon',
        name: 'Speed Demon',
        description: 'Complete a level in under 60 seconds',
        icon: 'lightning',
      },
    ],
  }),
});

Unlock achievements

await fetch('/api/games/achievements/unlock', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    achievementId: 'first-win',
    playerId: currentPlayer,
  }),
});

Leaderboards

Update player score

await fetch('/api/games/leaderboard', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    gameId: 'my-awesome-game',
    playerId: currentPlayer,
    score: 9999,
    metadata: {
      level: 10,
      timePlayed: 3600,
    },
  }),
});

Get leaderboard

const leaderboard = await fetch('/api/games/leaderboard?gameId=my-awesome-game&limit=100', {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const rankings = await leaderboard.json();

In‑game purchases

Create purchase

const purchase = await fetch('/api/payments/transactions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [
      {
        sku: 'gold-pack-100',
        quantity: 1,
        price: 4.99,
      },
    ],
    currency: 'USD',
  }),
});

const { transactionId, paymentUrl } = await purchase.json();

// Redirect to payment
window.location.href = paymentUrl;

Handle purchase webhook

Set up a webhook to handle completed purchases:

// Your webhook endpoint
app.post('/webhooks/orbital/payment', async (req, res) => {
  const { transactionId, status, items } = req.body;

  if (status === 'completed') {
    // Grant items to player
    await grantItems(items);
  }

  res.sendStatus(200);
});

Next steps

• Authentication – player auth using passkeys
• Durable Streams – HTTP/SSE event delivery
• API Reference – all game‑related endpoints