99 lines
2.8 KiB
Markdown
99 lines
2.8 KiB
Markdown
# 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 })
|
|
}
|
|
``` |