FrankieSDK v1

Include this in your arcade game to talk to Frankie OS.

Game Structure

Your game must be packaged as a .zip containing:

my-game.zip
├── frankie-game.json ← Erforderliches Manifest (Format siehe unten)
├── index.html ← Erforderlicher Einstiegspunkt
└── assets/ ← Optional: JS, CSS, Bilder, Audio, etc.

frankie-game.json Format

{
  "id":          "my-game",          // slug: lowercase letters, digits, hyphens (1-64 chars)
  "version":     "1.0.0",            // your game version
  "title":       "My Game",          // shown on the cartridge
  "tagline":     "A one-line pitch", // shown under the title
  "icon":        "🎮",               // emoji shown on the cartridge
  "kind":        "ARCADE",           // badge: ARCADE | VS | LLM | PET
  "author":      "Your Name",        // shown in the admin panel
  "order":       50,                 // sort position in the arcade grid (lower = first)
  "sdk_version": 1                   // must be 1; future versions may be incompatible
}

Lifecycle Hooks (Events Received FROM Frankie)

sdk.on('init', ({ userId, username, gameId, theme }) => { ... })

Called once after the iframe loads. Initialize your game here. You MUST call sdk.emit('ready') when your game has finished loading.

sdk.on('pause', () => { ... })

Called when the arcade overlay loses focus (e.g. user switches tab). Pause timers, animations, and any ongoing audio.

sdk.on('resume', () => { ... })

Called when the overlay regains focus. Resume paused state.

Events Emitted TO Frankie

sdk.emit('ready')

Tell Frankie your game is loaded and ready. Required after 'init'.

sdk.emit('xp', { amount: number, reason: string })

Award XP to the player. reason is a short label shown in toasts.

sdk.emit('win')

Record a win for this game (increments win counter and awards XP).

sdk.emit('score', { value: number })

Submit a high score. Frankie keeps the all-time best per game.

sdk.emit('close')

Close the game and return to the arcade grid.

LLM Access (for kind: "LLM" games)

const reply = await sdk.llm([
  { role: 'system', content: 'You are a trivia host.' },
  { role: 'user',   content: 'Ask me a question.' }
])
console.log(reply) // string — the model's response text
Example (Vanilla JS)
import sdk from './frankie-sdk.js'

sdk.on('init', ({ username }) => {
  document.querySelector('#welcome').textContent = `Hello, ${username}!`
  sdk.emit('ready')
})

sdk.on('pause', () => clearInterval(gameLoop))
sdk.on('resume', () => { gameLoop = setInterval(tick, 16) })

function onPlayerWin() {
  sdk.emit('win')
  sdk.emit('xp', { amount: 50, reason: 'Victory' })
  sdk.emit('score', { value: playerScore })
}