@playabl/sdk

Browser SDK for Playabl games providing parent-platform communication, game state persistence, device APIs, live tweaks, asset replacement, and iOS-friendly audio helpers.

Installation

npm install @playabl/sdk

Usage

Core

import sdk from '@playabl/sdk'

const ready = await sdk.ready()
console.log('Connected to Playabl parent:', ready.parentOrigin)

Game State and Leaderboard

import sdk from '@playabl/sdk'

type SaveData = {
  highScore: number
}

const saved = await sdk.gameState.load<SaveData>()
let highScore = saved?.highScore ?? 0

async function submitScore(score: number): Promise<void> {
  if (score > highScore) {
    highScore = score

    const result = await sdk.gameState.save({ highScore })
    if (!result.ok) {
      console.warn('Could not save game state:', result.error?.code)
    }
  }

  const submitResult = await sdk.leaderboard.submit(score)
  console.log('Score accepted:', submitResult.accepted)
}

Device APIs

import sdk from '@playabl/sdk'

// Haptics
if (sdk.device.haptics.isSupported()) {
  await sdk.device.haptics.vibrate([100, 50, 100])
}

// Camera
if (sdk.device.camera.isSupported()) {
  const stream = await sdk.device.camera.getStream({ facingMode: 'environment' })
  const photo = await sdk.device.camera.capturePhoto({ quality: 'high' })
  sdk.device.camera.stopStream()
}

// Geolocation
if (sdk.device.geolocation.isSupported()) {
  const position = await sdk.device.geolocation.getCurrentPosition()
  const stopWatching = sdk.device.geolocation.watchPosition((pos) => {
    console.log('Position:', pos)
  })

  stopWatching()
}

// Sensors
if (sdk.device.sensors.isMotionSupported()) {
  await sdk.device.sensors.requestMotionPermission()

  const stopMotion = sdk.device.sensors.watchMotion((data) => {
    console.log('Gravity:', data.gravity)
  })

  stopMotion()
}

if (sdk.device.sensors.isOrientationSupported()) {
  const stopOrientation = sdk.device.sensors.watchOrientation((data) => {
    console.log('Orientation:', data)
  })

  stopOrientation()
}

// File System
if (sdk.device.fileSystem.isSupported()) {
  const { files } = await sdk.device.fileSystem.openFile({
    accept: ['image/*'],
    multiple: true,
  })

  const text = await sdk.device.fileSystem.readAsText(files[0]!)
  await sdk.device.fileSystem.saveFile(new Blob([text]), 'save.txt')
}

Tweaks

import sdk from '@playabl/sdk'

const tweaks = await sdk.tweaks.init({
  speed: {
    type: 'number',
    value: 1,
    min: 0.5,
    max: 3,
    step: 0.1,
    name: 'Player speed',
  },
  debugMode: {
    type: 'boolean',
    value: false,
  },
  playerColor: {
    type: 'color',
    value: '#00ff88',
  },
})

const speed = tweaks.get('speed')

const unsubscribe = tweaks.subscribe('speed', (value, previous) => {
  console.log('Speed changed:', previous, value)
})

unsubscribe()

Assets

import sdk from '@playabl/sdk'

const assets = await sdk.assets.register({
  player: '/assets/player.png',
  jump: '/assets/jump.mp3',
})

const playerUrl = assets.get('player')
const replacedUrl = assets.getReplacedUrl('/assets/player.png')

console.log('Current asset mapping:', assets.snapshot())
console.log(playerUrl, replacedUrl)

Audio (iOS Silent Mode Compatible)

import sdk from '@playabl/sdk'

if (sdk.audio.isSupported()) {
  const audio = await sdk.audio.getContext()

  button.onclick = async () => {
    await audio.unlock()

    const oscillator = audio.context.createOscillator()
    oscillator.connect(audio.context.destination)
    oscillator.start()
    oscillator.stop(audio.context.currentTime + 1)
  }
}

API Surface

• sdk.ready() - Connects to the Playabl parent iframe host.
• sdk.leaderboard.submit(score) - Sends a score to the parent platform.
• sdk.gameState.save/load/clear() - Persists JSON-serializable game state with localStorage.
• sdk.device - Provides haptics, camera, geolocation, sensors, and file system helpers.
• sdk.tweaks.init(schema) - Registers live-tunable values controlled by the host.
• sdk.assets.register(mapping) - Registers game assets so the host can replace them.
• sdk.audio - Creates Web Audio contexts with an iOS Safari silent-mode patch.