# 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

```json
{
  "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)
```javascript
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.
```javascript
sdk.on('pause', () => { ... })
```
Called when the arcade overlay loses focus (e.g. user switches tab).
Pause timers, animations, and any ongoing audio.

```javascript
sdk.on('resume', () => { ... })
```
Called when the overlay regains focus. Resume paused state.

Events Emitted TO Frankie
```javascript
sdk.emit('ready')
```

Tell Frankie your game is loaded and ready. Required after 'init'.
```javascript
sdk.emit('xp', { amount: number, reason: string })
```

Award XP to the player. reason is a short label shown in toasts.
```javascript
sdk.emit('win')
```

Record a win for this game (increments win counter and awards XP).
```javascript
sdk.emit('score', { value: number })
```

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

```javascript
sdk.emit('close')
```

Close the game and return to the arcade grid.

LLM Access (for kind: "LLM" games)
```javascript
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 })
}
```