@pixlland/sdk

The official Pixlland SDK for HTML5 games — lifecycle, ads, accounts, cross-device save. Poki-compatible contract, so migrations are usually a one-import rename.

npm install @pixlland/sdk
# or load the CDN bundle
<script src="https://pixlland.com/sdk/v1/pixlland.js" defer></script>

Quick start

import { PixllandSDK } from '@pixlland/sdk';
// or use window.PixllandSDK when loading via <script>

await PixllandSDK.init();
PixllandSDK.gameLoadingFinished();
PixllandSDK.gameplayStart();

// Between rounds:
await PixllandSDK.commercialBreak();

// Grant a reward after an ad:
const { granted } = await PixllandSDK.rewardedBreak();
if (granted) player.coins += 100;

Lifecycle

init()  →  gameLoadingProgress(0..1)*  →  gameLoadingFinished()
       →  gameplayStart()  …  gameplayStop()

Calling out of order isn't fatal but hurts session analytics and ad pacing. Full deep-dive in the SDK Basics docs.

Feature matrix

| Area | Methods | | --- | --- | | Lifecycle | init, gameLoadingProgress, gameLoadingFinished, gameplayStart, gameplayStop | | Ads | commercialBreak, rewardedBreak | | Accounts | account.isSignedIn, id, displayName, get, getToken, signIn, onChange | | Cross-device save | data.get, set, delete, keys (JSON, 64 KB per key) | | Deep links | shareableURL(params), getURLParam(name) | | UI hints | movePill(topPct, topPx), requestHapticFeedback('light'\|'medium'\|'heavy'), playerLocale() | | Observability | captureError, measure(category, what, action), happyTime(seconds) |

Full typings ship with the package (dist/index.d.ts). Generated API reference: pixlland.com/sdk-docs.

Rules (match Poki)

• gameplayStart() only on first input — never on load, never twice in a row.
• gameplayStop() never twice in a row.
• No SDK events during an ad.
• commercialBreak is recommended before every gameplayStart.
• rewardedBreak resolves { granted: false, reason: 'ad_blocked' } when no ad loads — never grants the reward silently.

Standalone fallback

Every method is safe to call without a Pixlland portal — it degrades to local-only stubs so you can develop against a local file:// iframe and nothing throws.

• init() resolves in 4s with best-effort defaults if no handshake arrives.
• commercialBreak() / rewardedBreak() instantly resolve no_fill / { granted: false }.
• data.* / account.* return null / [].

Scaffold a game

npx @pixlland/cli init my-game
cd my-game
pnpm dev

Engine guides

Copy-paste integrations for every major HTML5 engine:

• Vanilla HTML5
• Phaser
• Godot (HTML5 export)
• Unity (WebGL)
• Defold
• GameMaker
• Construct 3
• GDevelop
• Cocos Creator

License

MIT · see LICENSE.

Support

• Email: [email protected]
• Developer portal: https://pixlland.com/developers
• Submit a game: https://pixlland.com/share