API Documentation

Pause / Resume

Games should listen for og-pause and og-resume postMessage events from the parent frame. This allows the playground to pause your game when the user switches tabs, opens settings, or interacts with other UI elements.

window.addEventListener('message', (event) => {
  if (event.data === 'og-pause') {
    // Pause game loop, mute audio, etc.
    gamePaused = true;
  }
  if (event.data === 'og-resume') {
    // Resume game loop, unmute audio, etc.
    gamePaused = false;
  }
});

Scoring

To submit scores to the leaderboard, use postMessage to send the score to the parent frame. The score must be a numeric value.

// Submit a score to the leaderboard
window.parent.postMessage({
  type: 'og-score',
  score: numericValue
}, '*');

Save / Load

Use the built-in window.og API for game state persistence. Saves are stored server-side per user, so progress follows players across devices. Falls back to localStorage for anonymous users.

// Save game state (fires instantly)
window.og.save({ level: 5, score: 1200, inventory: ['sword'] });

// Load saved game state (async — use await!)
const savedData = await window.og.load();
if (savedData) {
  restoreGame(savedData);
}

// Clear saved data
window.og.clearSave();

Console Bridge

Console errors from your game are automatically captured and surfaced to the playground. This means any console.error() calls or uncaught exceptions will appear in the playground's error panel, making it easy to debug issues without opening browser dev tools.

Self-Contained HTML

All games must be self-contained HTML documents. This means all CSS, JavaScript, and assets must be inlined within a single HTML file. External resources are not allowed beyond the approved CDN libraries (Three.js, TensorFlow.js). Do not reference external stylesheets, scripts, images, or fonts.

Games can call an LLM at runtime for NPC dialogue, dynamic content, hints, or story generation. The API key never enters the game — requests are proxied through the server via postMessage. The logged-in user's session is used for authentication. Each call costs 0.05 credits.

// Send a prompt to the LLM from your game
window.og.chat("Describe a mysterious cave entrance")
  .then(response => {
    showDialogue(response);
  });

// With options
window.og.chat("Give me a riddle", { maxTokens: 100 });

Use for: NPC dialogue, dynamic descriptions, hints, story generation. Avoid: game loop logic, physics calculations, per-frame calls.

The playtest endpoint launches your game in a headless browser, takes screenshots at intervals, and uses AI vision to analyze whether the game renders correctly, responds to input, and looks polished. You can provide either raw HTML code or reference an existing game by ID.

curl -X POST https://partida.ai/api/playtest \
  -H "Authorization: Bearer og_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "id": "abc123" }'

The automated scoring endpoint runs a batch of games through the testing pipeline and returns quality scores and detailed breakdowns. Use this to validate games before publishing or to benchmark game quality across iterations.

curl -X POST https://partida.ai/api/test-games \
  -H "Authorization: Bearer og_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "gameIds": ["abc123", "def456"] }'

Vitest Suite

The project includes a Vitest test suite for running unit and integration tests locally. Use this to validate API routes, utility functions, and game logic before deploying.

# Run the full test suite
npm test

# Run tests in watch mode
npm test -- --watch

# Run a specific test file
npm test -- path/to/test.test.ts

Automated Scoring Breakdown

Every game is scored by a static analysis pass that scans the HTML source for key patterns. Each category is scored 0-100, then weighted to produce a final composite score. Below is exactly what the test checks for in each category.

Grading Scale

The weighted composite score maps to a letter grade:

A game must score at least 40 with no critical technical errors to pass. Games that fail are not eligible for publishing.

Claude is the primary AI provider for Partida. It powers game generation, chat refinement, in-game AI, and automated playtesting.

Support for OpenAI models (GPT-4o, o1, etc.) is planned.

Support for xAI's Grok models is planned.

Support for Google's Gemini models is planned.