Submit scores and record numeric events

Declare a board

Merge this field into a complete manifest:

{
  "leaderboards": [
    { "id": "best-score", "title": "Best score", "sort": "desc", "format": "integer" }
  ]
}

Use asc when lower is better. The host renders the board; game code does not fetch other players’ entries.

After init, submit at an appropriate gameplay milestone:

import llvls from '@llvls/sdk';

async function submitFinalScore(score: number): Promise<void> {
  const outcome = await llvls.scores.submit('best-score', score);
  if (!outcome.accepted) return;
  if (outcome.personalBest) console.info('Personal best accepted');
}
void submitFinalScore;

The caller must handle promise rejection. accepted: false is a normal outcome for signed-out players and scores not kept. Do not show a public-record confirmation simply because the call resolved. Use scores.show('best-score') to request the host overlay.

Declare an event

{
  "analyticsEvents": [
    { "name": "level_complete", "description": "A level ended", "props": ["level", "seconds"] }
  ]
}

After initialisation, call llvls.analytics.event('level_complete', { level: 2, seconds: 18 }) at the relevant transition.

Events are fire-and-forget and may be dropped under limits. Send numeric properties, never names, text, contact details or high-frequency per-frame telemetry. Event acceptance does not promise a particular dashboard report.

Verify

Check declarations, numeric values, signed-out submissions and preview limitations. Inspect SDK calls in the preview panel and test a real eligible release separately.