@playus.club/games-sdk 0.1.0

package/LICENSE.md

@@ -0,0 +1,35 @@
+# Playus Games SDK License
+
+Copyright (c) 2026 Dapps Pte Ltd. All rights reserved.
+
+## Grant
+
+Subject to the terms below, Dapps Pte Ltd grants you a limited, non-exclusive, non-transferable, revocable, royalty-free license to use, reproduce, and modify this SDK solely to develop, test, and build web games intended for review by and distribution within the Playus apps operated by Dapps Pte Ltd ("Playus"), and to distribute the SDK only in compiled form as part of such a game bundle delivered to Playus.
+
+## Restrictions
+
+You may not:
+
+- use the SDK, or any part of it (including the native bridge protocol implementation), to integrate or run games or other web content in any app, platform, or service other than Playus;
+- redistribute, sublicense, sell, or publish the SDK or modified versions of it outside of a game bundle delivered to Playus;
+- remove or alter copyright or license notices.
+
+## Your games remain yours
+
+This license covers the SDK only. You keep all rights to your own game code and assets. Terms for reviewing, publishing, and monetizing games inside Playus are agreed separately with Dapps Pte Ltd and take precedence over this license where they conflict.
+
+## Contributions
+
+By submitting a contribution to this repository you grant Dapps Pte Ltd a perpetual, worldwide, royalty-free license to use, modify, and distribute it as part of the SDK.
+
+## Termination
+
+This license terminates automatically if you breach it or when Dapps Pte Ltd withdraws it in writing. On termination you must stop using the SDK for new development; game bundles already accepted by Playus remain unaffected.
+
+## No warranty
+
+THE SDK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. TO THE MAXIMUM EXTENT PERMITTED BY LAW, DAPPS PTE LTD SHALL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM THE USE OF THE SDK.
+
+## Contact
+
+Dapps Pte Ltd — https://dapps.ltd — team@dapps.ltd

package/README.md

@@ -0,0 +1,129 @@
+<p align="center">
+  <img src="docs/assets/playus-web-preview.jpg" alt="Playus dice logo" width="720" />
+</p>
+
+# Playus Games SDK
+
+SDK and local host simulator for building Playus-compatible web games.
+
+Partners build games in their own repository and deliver a pre-built static bundle to Playus. The bundle must already use the Playus SDK runtime so it works inside the Playus iOS and Android WebViews without a source-code adaptation step.
+
+## Getting The SDK
+
+```sh
+npm install @playus.club/games-sdk
+```
+
+The npm package contains the runtime only. For the local host simulator and the example games, clone this repository (see Quick Start below).
+
+The SDK speaks Playus bridge protocol v3. Note the SDK version you built with — it is part of the bundle delivery metadata.
+
+## Quick Start (this repo)
+
+```sh
+npm install
+npm run dev
+```
+
+Open the local host simulator:
+
+```txt
+http://localhost:8091
+```
+
+The simulator loads the included examples and validates the real Playus bridge flow, including `ready`, `hostReady`, `hostReadyAck`, live score updates, finish events, language params, debug mode, and host mute callbacks.
+
+## SDK Usage
+
+Import the SDK in your entry module (not behind a dynamic import — the host verifies the bridge exists right after page load):
+
+```ts
+import {
+  createTapToStartOverlay,
+  nativeBridge,
+  sound,
+} from '@playus.club/games-sdk';
+import '@playus.club/games-sdk/styles.css';
+
+nativeBridge.configure({ gameId: 'your-game-id' });
+
+createTapToStartOverlay({
+  text: {
+    en: 'Tap to start',
+    de: 'Tippen zum Starten',
+    fr: 'Touchez pour commencer',
+    es: 'Toca para empezar',
+    it: 'Tocca per iniziare',
+  },
+  mode: 'dismiss-only',
+  onStart: () => {
+    nativeBridge.game.started();
+    nativeBridge.game.score(0);
+  },
+});
+
+await sound.preload(['positive-input']);
+nativeBridge.game.ready({ version: '1.0.0' });
+```
+
+When the run ends:
+
+```ts
+nativeBridge.game.finished(finalScore);
+```
+
+Engine helpers: `@playus.club/games-sdk/phaser`, `@playus.club/games-sdk/babylon`, and `@playus.club/games-sdk/three` provide ready-made containers and configs. See [the game contract](docs/game-contract.md) for the full runtime rules.
+
+## Examples
+
+Three small complete games. All follow the full [game contract](docs/game-contract.md) with localized overlays, sounds, and haptics — and each shows a different feature mix:
+
+| | `games/starter-game` (plain TS) | `games/phaser-example` | `games/babylon-example` |
+| --- | --- | --- | --- |
+| Game | Hit 5 targets fast | Pop bubbles for 20s | Tap the odd cube, endless levels |
+| Score | Time: negative seconds, `score(0)` at start, whole-second live updates, exact fractional final | Points with live updates | Levels with an endless difficulty ramp |
+| Seeded random | New layout per try | Same pattern every try (`includePlayContext: false`) | `seededShuffle` + float ranges |
+| Start overlay | `dismiss-only`, default tap hint | `dismiss-only`, `tap-rapid` hint | `pass-first-input`, board visible behind hint |
+| Also shows | Real-time score timer (no clamping) | Delta clamping, countdown clock, warning sound | Transparent background, debug overlay, DPR cap, brief end feedback, `error()` |
+
+## Testing Your Own Bundle
+
+The simulator's full handshake only works same-origin. To test your built bundle:
+
+1. Copy your build output into `public/<your-game-id>/` in this repo.
+2. Run `npm run dev` and enter `/<your-game-id>/` as the Game URL in the simulator.
+
+Cross-origin URLs (e.g. your own dev server) still show outgoing events, but `hostReady` cannot be delivered — the simulator marks this and skips handshake checks.
+
+## Delivering A Bundle
+
+Plain source delivery is preferred when you can share it — see [CONTRIBUTING.md](CONTRIBUTING.md). For bundle delivery, Playus expects a static web bundle:
+
+```txt
+dist/
+  index.html
+  assets/...
+```
+
+The bundle must:
+
+- run from a static host path with no backend required
+- reference all assets **relatively** — with Vite set `base: './'` and check that the built `index.html` uses `./assets/...`, not `/assets/...` (Playus hosts serve bundles from a subpath)
+- include the Playus SDK in the compiled output
+- send its bundle version via `ready({ version })`
+- call `ready()` only after required assets for the first playable frame are loaded
+- send meaningful live `score()` updates
+- call `finished(finalScore)` exactly once
+- support `lang` from the URL hash for in-game text and overlays
+
+Playus handles signing, hosting, game metadata, score type assignment, leaderboard UI, and final result UI.
+
+## Docs
+
+- [Game contract](docs/game-contract.md) — the runtime rules every bundle must follow
+- [Assets and mobile performance](docs/assets-and-performance.md)
+- [Submission checklist](docs/submission-checklist.md)
+
+## License
+
+Source-available under the [Playus Games SDK License](LICENSE.md): free to use for building and delivering games for the Playus apps; not for use in other apps or platforms.

package/dist/sdk/babylon/canvas.d.ts

@@ -0,0 +1,30 @@
+import { type BackgroundConfig } from '../types/background';
+import { Color4 } from '@babylonjs/core/Maths/math.color';
+export type CanvasOptions = {
+    background?: BackgroundConfig;
+};
+export declare function createCanvas(options?: CanvasOptions): HTMLCanvasElement;
+/**
+ * Returns Engine options based on background config with performance optimizations.
+ * Use this when creating the Babylon.js Engine.
+ *
+ * @example
+ * const engineOpts = getEngineOptions(background);
+ * this.engine = new Engine(this.canvas, true, engineOpts);
+ */
+export declare function getEngineOptions(background?: BackgroundConfig): {
+    alpha: boolean;
+    antialias: boolean;
+    preserveDrawingBuffer: boolean;
+    stencil: boolean;
+    desynchronized: boolean;
+};
+/**
+ * Returns a Color4 for scene.clearColor based on background config.
+ * Use this when setting up the scene.
+ *
+ * @example
+ * this.scene.clearColor = getClearColor(background);
+ */
+export declare function getClearColor(background?: BackgroundConfig): Color4;
+//# sourceMappingURL=canvas.d.ts.map

package/dist/sdk/babylon/canvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas.d.ts","sourceRoot":"","sources":["../../../src/playus/babylon/canvas.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,gBAAgB,EAAqC,MAAM,qBAAqB,CAAC;AAC/F,OAAO,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAC;AAE1D,MAAM,MAAM,aAAa,GAAG;IAC1B,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B,CAAC;AAEF,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,iBAAiB,CAuDvE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,CAAC,EAAE,gBAAgB;;;;;;EAS7D;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,UAAU,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAmBnE"}

package/dist/sdk/babylon/index.d.ts

@@ -0,0 +1,3 @@
+export { createCanvas, getClearColor, getEngineOptions } from './canvas';
+export type { CanvasOptions } from './canvas';
+//# sourceMappingURL=index.d.ts.map

package/dist/sdk/babylon/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/playus/babylon/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACzE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC"}

package/dist/sdk/babylon.js

@@ -0,0 +1,52 @@
+import { i as e, n as t, o as n, r } from "./chunks/background-DLy8kjVf.js";
+import { r as i } from "./chunks/debug-BKXPXMKn.js";
+import { Color4 as a } from "@babylonjs/core/Maths/math.color";
+//#region src/playus/babylon/canvas.ts
+function o(r) {
+	let a = t(r?.background), o = document.createElement("div");
+	o.id = "game-root", Object.assign(o.style, {
+		position: "fixed",
+		inset: "0",
+		display: "grid",
+		placeItems: "center",
+		...a && { background: a }
+	}), e(o), document.body.appendChild(o);
+	let s = document.createElement("div");
+	if (s.id = "game-viewport", Object.assign(s.style, {
+		width: "min(100vw, calc(100vh * 0.625))",
+		aspectRatio: "0.625",
+		position: "relative",
+		...a && { background: a }
+	}), e(s), o.appendChild(s), i()) {
+		let e = document.createElement("div");
+		e.id = "debug-background", Object.assign(e.style, {
+			position: "absolute",
+			inset: "0",
+			background: "rgba(0, 0, 0, 0.1)",
+			pointerEvents: "none",
+			zIndex: "-1"
+		}), s.appendChild(e);
+	}
+	let c = document.createElement("canvas");
+	return c.id = "gameCanvas", Object.assign(c.style, {
+		width: "100%",
+		height: "100%",
+		display: "block"
+	}), e(c), n(c), s.appendChild(c), c;
+}
+function s(e) {
+	return {
+		alpha: r(e),
+		antialias: !0,
+		preserveDrawingBuffer: !1,
+		stencil: !1,
+		desynchronized: !1
+	};
+}
+function c(e) {
+	if (r(e)) return new a(0, 0, 0, 0);
+	let n = t(e), i = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(n);
+	return i ? new a(parseInt(i[1], 16) / 255, parseInt(i[2], 16) / 255, parseInt(i[3], 16) / 255, 1) : new a(0, 0, 0, 1);
+}
+//#endregion
+export { o as createCanvas, c as getClearColor, s as getEngineOptions };

package/dist/sdk/bridge.d.ts

@@ -0,0 +1,2 @@
+export { ColorConfig, NativeBridge, nativeBridge, roundScoreForBridge, } from './native-bridge';
+//# sourceMappingURL=bridge.d.ts.map

package/dist/sdk/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../src/playus/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,mBAAmB,GACpB,MAAM,iBAAiB,CAAC"}

package/dist/sdk/chunks/background-DLy8kjVf.js

@@ -0,0 +1,47 @@
+//#region src/playus/mobile-interaction.ts
+var e = new URLSearchParams(window.location.search), t = d("playusNoMobilePolicy"), n = d("playusNoTouchDefaultGuard"), r = e.get("playusTouchAction"), i = [
+	"a[href]",
+	"button",
+	"input",
+	"select",
+	"textarea",
+	"[contenteditable]",
+	"[role=\"button\"]",
+	"[role=\"slider\"]"
+].join(","), a = !1, o = /* @__PURE__ */ new WeakSet();
+function s() {
+	t || a || (a = !0, u(document.documentElement), document.body ? u(document.body) : document.addEventListener("DOMContentLoaded", () => {
+		document.body && u(document.body);
+	}, { once: !0 }), document.addEventListener("selectstart", f, !0), document.addEventListener("contextmenu", f, !0), document.addEventListener("dragstart", f, !0));
+}
+function c(e) {
+	return t ? e : (u(e), e.style.touchAction = r || "none", e);
+}
+function l(e) {
+	return t || n || o.has(e) ? e : (o.add(e), e.addEventListener("touchstart", f, { passive: !1 }), e.addEventListener("touchmove", f, { passive: !1 }), e);
+}
+function u(e) {
+	let t = e.style;
+	t.userSelect = "none", t.webkitUserSelect = "none", t.webkitTouchCallout = "none", t.webkitTapHighlightColor = "transparent", t.overscrollBehavior = "none";
+}
+function d(t) {
+	let n = e.get(t);
+	return n === "" || n === "1" || n === "true";
+}
+function f(e) {
+	p(e.target) || e.preventDefault();
+}
+function p(e) {
+	return e instanceof Element ? e.closest(i) !== null : !1;
+}
+//#endregion
+//#region src/playus/types/background.ts
+var m = { transparent: !0 };
+function h(e) {
+	return !e || e.transparent;
+}
+function g(e) {
+	if (!(!e || e.transparent === !0)) return e.color;
+}
+//#endregion
+export { s as a, c as i, g as n, l as o, h as r, m as t };

package/dist/sdk/chunks/debug-BKXPXMKn.js

@@ -0,0 +1,92 @@
+//#region src/playus/url-params.ts
+function e(e) {
+	try {
+		let t = window.location.hash.substring(1);
+		return new URLSearchParams(t).get(e) || new URLSearchParams(window.location.search).get(e);
+	} catch {
+		return null;
+	}
+}
+function t(t) {
+	let n = e("groupgame");
+	if (n) return t?.includePlayContext === !1 ? n : `${n}.${e("playcontext")}`;
+}
+//#endregion
+//#region src/playus/overlay/debug.ts
+function n() {
+	try {
+		let e = document.createElement("canvas"), t = e.getContext("webgl2") || e.getContext("webgl");
+		if (!t) return {
+			supported: !1,
+			renderer: "Canvas 2D (no WebGL)",
+			vendor: "CPU"
+		};
+		let n = t.getExtension("WEBGL_debug_renderer_info");
+		return n ? {
+			supported: !0,
+			renderer: t.getParameter(n.UNMASKED_RENDERER_WEBGL),
+			vendor: t.getParameter(n.UNMASKED_VENDOR_WEBGL)
+		} : {
+			supported: !0,
+			renderer: "WebGL (details hidden)",
+			vendor: "Unknown"
+		};
+	} catch {
+		return {
+			supported: !1,
+			renderer: "Detection failed",
+			vendor: "Unknown"
+		};
+	}
+}
+function r() {
+	return e("d") === "1";
+}
+function i(e) {
+	let t = document.createElement("div");
+	t.id = "debug-overlay", Object.assign(t.style, {
+		position: "absolute",
+		top: "5px",
+		left: "50%",
+		transform: "translateX(-50%)",
+		padding: "2px 6px",
+		background: "rgba(0,0,0,0.35)",
+		color: "#fff",
+		fontFamily: "system-ui, -apple-system, Segoe UI, Roboto, sans-serif",
+		fontSize: "12px",
+		lineHeight: "1.2",
+		borderRadius: "6px",
+		pointerEvents: "none",
+		userSelect: "none",
+		display: "none",
+		zIndex: "9999"
+	}), e.appendChild(t);
+	let n = document.createElement("div");
+	n.textContent = "— fps", t.appendChild(n);
+	let r = document.createElement("div");
+	r.style.fontSize = "10px", r.style.opacity = "0.8", r.textContent = "", t.appendChild(r);
+	function i(e) {
+		n.textContent = `${e | 0} fps`;
+	}
+	function a(e) {
+		r.textContent = e;
+	}
+	function o() {
+		t.style.display = "block";
+	}
+	function s() {
+		t.style.display = "none";
+	}
+	function c() {
+		t.parentElement && t.parentElement.removeChild(t);
+	}
+	return {
+		setFps: i,
+		setRenderer: a,
+		show: o,
+		hide: s,
+		destroy: c
+	};
+}
+//#endregion
+export { e as a, t as i, n, r, i as t };

package/dist/sdk/chunks/touch-hint-BZBB3COY.js

@@ -0,0 +1,148 @@
+//#region src/playus/overlay/touch-hint.ts
+var e = !1;
+function t() {
+	if (e) return;
+	e = !0;
+	let t = document.createElement("style");
+	t.id = "touch-hint-keyframes", t.textContent = "\n    @keyframes th-tap {\n      0%, 100% { transform: translate(-50%, -50%) scale(1); opacity: 0.4; }\n      50% { transform: translate(-50%, -50%) scale(1.35); opacity: 1.0; }\n    }\n    @keyframes th-tap-rapid {\n      0% { transform: translate(-50%, -50%) scale(1); opacity: 0; }\n      20% { transform: translate(-50%, -50%) scale(1.25); opacity: 1.0; }\n      50% { transform: translate(-50%, -50%) scale(1); opacity: 0; }\n      100% { transform: translate(-50%, -50%) scale(1); opacity: 0; }\n    }\n    @keyframes th-drag-h {\n      0%, 100% { left: 5%; }\n      50% { left: 95%; }\n    }\n    @keyframes th-tap-sides-l {\n      0%, 48%, 100% { opacity: 0.2; transform: translate(-50%, -50%) scale(1); }\n      12%, 38% { opacity: 1.0; transform: translate(-50%, -50%) scale(1.25); }\n    }\n    @keyframes th-tap-sides-r {\n      0%, 52%, 100% { opacity: 0.2; transform: translate(-50%, -50%) scale(1); }\n      62%, 88% { opacity: 1.0; transform: translate(-50%, -50%) scale(1.25); }\n    }\n    @keyframes th-tap-timed {\n      0%, 60% { transform: translate(-50%, -50%) scale(1); opacity: 0.25; }\n      70% { transform: translate(-50%, -50%) scale(1.4); opacity: 1.0; }\n      85%, 100% { transform: translate(-50%, -50%) scale(1); opacity: 0.25; }\n    }\n    @keyframes th-drag-free {\n      0%   { transform: translate(-50%, -50%) translate(90%, -70%); }\n      12%  { transform: translate(-50%, -50%) translate(30%, 90%); }\n      25%  { transform: translate(-50%, -50%) translate(-90%, 30%); }\n      37%  { transform: translate(-50%, -50%) translate(-30%, -90%); }\n      50%  { transform: translate(-50%, -50%) translate(90%, -30%); }\n      62%  { transform: translate(-50%, -50%) translate(30%, 90%); }\n      75%  { transform: translate(-50%, -50%) translate(-90%, 30%); }\n      87%  { transform: translate(-50%, -50%) translate(-30%, -90%); }\n      100% { transform: translate(-50%, -50%) translate(90%, -70%); }\n    }\n    @keyframes th-swipe-4dir {\n      0%  { transform: translate(-50%, -50%) translate(140%, 0); opacity: 0; }\n      5%  { transform: translate(-50%, -50%) translate(90%, 0); opacity: 0.9; }\n      8%  { transform: translate(-50%, -50%) translate(-90%, 0); opacity: 0.9; }\n      13% { transform: translate(-50%, -50%) translate(-140%, 0); opacity: 0; }\n\n      25% { transform: translate(-50%, -50%) translate(-140%, 0); opacity: 0; }\n      30% { transform: translate(-50%, -50%) translate(-90%, 0); opacity: 0.9; }\n      33% { transform: translate(-50%, -50%) translate(90%, 0); opacity: 0.9; }\n      38% { transform: translate(-50%, -50%) translate(140%, 0); opacity: 0; }\n\n      50% { transform: translate(-50%, -50%) translate(0, 80%); opacity: 0; }\n      55% { transform: translate(-50%, -50%) translate(0, 50%); opacity: 0.9; }\n      58% { transform: translate(-50%, -50%) translate(0, -50%); opacity: 0.9; }\n      63% { transform: translate(-50%, -50%) translate(0, -80%); opacity: 0; }\n\n      75% { transform: translate(-50%, -50%) translate(0, -80%); opacity: 0; }\n      80% { transform: translate(-50%, -50%) translate(0, -50%); opacity: 0.9; }\n      83% { transform: translate(-50%, -50%) translate(0, 50%); opacity: 0.9; }\n      88% { transform: translate(-50%, -50%) translate(0, 80%); opacity: 0; }\n      100% { transform: translate(-50%, -50%) translate(0, 80%); opacity: 0; }\n    }\n    @keyframes th-swipe-h {\n      0%  { transform: translate(-50%, -50%) translate(140%, 0); opacity: 0; }\n      5%  { transform: translate(-50%, -50%) translate(90%, 0); opacity: 0.9; }\n      8%  { transform: translate(-50%, -50%) translate(-90%, 0); opacity: 0.9; }\n      13% { transform: translate(-50%, -50%) translate(-140%, 0); opacity: 0; }\n\n      50% { transform: translate(-50%, -50%) translate(-140%, 0); opacity: 0; }\n      55% { transform: translate(-50%, -50%) translate(-90%, 0); opacity: 0.9; }\n      58% { transform: translate(-50%, -50%) translate(90%, 0); opacity: 0.9; }\n      63% { transform: translate(-50%, -50%) translate(140%, 0); opacity: 0; }\n      100% { transform: translate(-50%, -50%) translate(140%, 0); opacity: 0; }\n    }\n    @keyframes th-swipe-down {\n      0%  { transform: translate(-50%, -50%) translate(0, -80%); opacity: 0; }\n      8%  { transform: translate(-50%, -50%) translate(0, -50%); opacity: 0.9; }\n      14% { transform: translate(-50%, -50%) translate(0, 50%); opacity: 0.9; }\n      22% { transform: translate(-50%, -50%) translate(0, 80%); opacity: 0; }\n      100% { transform: translate(-50%, -50%) translate(0, 80%); opacity: 0; }\n    }\n  ", document.head.appendChild(t);
+}
+var n = {
+	position: "absolute",
+	borderRadius: "50%",
+	background: "rgba(255, 255, 255, 1.0)",
+	pointerEvents: "none"
+};
+function r(e, t) {
+	let r = document.createElement("div");
+	return Object.assign(r.style, {
+		...n,
+		background: t,
+		width: e,
+		aspectRatio: "1"
+	}), r;
+}
+function i(e, t) {
+	let n = r("30%", t);
+	Object.assign(n.style, {
+		top: "50%",
+		left: "50%",
+		animation: "th-tap 1.2s ease-in-out infinite"
+	}), e.appendChild(n);
+}
+function a(e, t) {
+	let n = r("28%", t);
+	Object.assign(n.style, {
+		top: "50%",
+		left: "5%",
+		transform: "translate(-50%, -50%)",
+		opacity: "0.7",
+		animation: "th-drag-h 2s ease-in-out infinite"
+	}), e.appendChild(n);
+}
+function o(e, t) {
+	let n = r("22%", t);
+	Object.assign(n.style, {
+		top: "50%",
+		left: "15%",
+		opacity: "0.15",
+		animation: "th-tap-sides-l 2s ease-in-out infinite"
+	}), e.appendChild(n);
+	let i = r("22%", t);
+	Object.assign(i.style, {
+		top: "50%",
+		left: "85%",
+		opacity: "0.15",
+		animation: "th-tap-sides-r 2s ease-in-out infinite"
+	}), e.appendChild(i);
+}
+function s(e, t) {
+	let n = r("30%", t);
+	Object.assign(n.style, {
+		top: "50%",
+		left: "50%",
+		animation: "th-tap-timed 2s ease-in-out infinite"
+	}), e.appendChild(n);
+}
+function c(e, t) {
+	let n = r("26%", t);
+	Object.assign(n.style, {
+		top: "50%",
+		left: "50%",
+		opacity: "0.7",
+		animation: "th-drag-free 3.5s ease-in-out infinite"
+	}), e.appendChild(n);
+}
+function l(e, t) {
+	let n = r("18%", t);
+	Object.assign(n.style, {
+		top: "35%",
+		left: "50%",
+		animation: "th-swipe-4dir 4s linear infinite"
+	}), e.appendChild(n);
+}
+function u(e, t) {
+	let n = r("30%", t);
+	Object.assign(n.style, {
+		top: "50%",
+		left: "50%",
+		animation: "th-tap-rapid 0.9s ease-in-out infinite"
+	}), e.appendChild(n);
+}
+function d(e, t) {
+	let n = r("18%", t);
+	Object.assign(n.style, {
+		top: "50%",
+		left: "50%",
+		animation: "th-swipe-h 3s linear infinite"
+	}), e.appendChild(n);
+}
+function f(e, t) {
+	let n = r("24%", t);
+	Object.assign(n.style, {
+		top: "50%",
+		left: "50%",
+		animation: "th-swipe-down 2s linear infinite"
+	}), e.appendChild(n);
+}
+var p = {
+	tap: i,
+	"drag-horizontal": a,
+	"tap-sides": o,
+	"tap-timed": s,
+	"drag-free": c,
+	"swipe-4dir": l,
+	"swipe-horizontal": d,
+	"swipe-down": f,
+	"tap-rapid": u
+}, m = {
+	"tap-sides": "75%",
+	"swipe-4dir": "85%",
+	"swipe-horizontal": "85%"
+};
+function h(e, n, r = "#ffffff", i) {
+	t();
+	let a = document.createElement("div");
+	return Object.assign(a.style, {
+		position: "absolute",
+		top: i?.top ?? "62%",
+		left: "50%",
+		transform: "translateX(-50%)",
+		width: i?.width ?? m[e] ?? "40%",
+		aspectRatio: "1",
+		pointerEvents: "none",
+		zIndex: "11",
+		display: "none"
+	}), p[e](a, r), n.appendChild(a), {
+		show() {
+			a.style.display = "block";
+		},
+		hide() {
+			a.style.display = "none";
+		},
+		destroy() {
+			a.remove();
+		}
+	};
+}
+//#endregion
+export { h as t };

package/dist/sdk/helpers/timeFormat.d.ts

@@ -0,0 +1,3 @@
+export declare function formatSecondsAsClock(secondsInput: number): string;
+export declare function formatMillisecondsAsClock(millisecondsInput: number): string;
+//# sourceMappingURL=timeFormat.d.ts.map

package/dist/sdk/helpers/timeFormat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeFormat.d.ts","sourceRoot":"","sources":["../../../src/playus/helpers/timeFormat.ts"],"names":[],"mappings":"AAAA,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAWjE;AAED,wBAAgB,yBAAyB,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAO3E"}

package/dist/sdk/i18n.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Supported languages - single source of truth
+ */
+export declare const SUPPORTED_LANGUAGES: readonly ["en", "de", "fr", "es", "it"];
+export type Language = typeof SUPPORTED_LANGUAGES[number];
+export declare const DEFAULT_LANGUAGE: Language;
+/**
+ * Translation dictionary type - key-first structure
+ * All translations for a key are grouped together
+ */
+export type TranslationDict<Keys extends string> = {
+    [K in Keys]: {
+        [L in Language]?: string;
+    };
+};
+/**
+ * Get current language from URL parameter
+ * Reads ?lang=de from URL (follows debug.ts pattern)
+ *
+ * @returns Language code or default ('en')
+ *
+ * @example
+ * // URL: http://localhost:8080/?lang=de
+ * getCurrentLanguage(); // Returns 'de'
+ *
+ * // URL: http://localhost:8080/
+ * getCurrentLanguage(); // Returns 'en'
+ */
+export declare function getCurrentLanguage(): Language;
+/**
+ * Create a type-safe translation function with template support
+ *
+ * This is the main API that games use. It:
+ * 1. Detects current language from URL
+ * 2. Returns translation function with full type safety
+ * 3. Automatically falls back to English if translation missing
+ * 4. Supports template variables for dynamic strings
+ *
+ * @param translations - Dictionary of translations (key-first structure)
+ * @returns Translation function t(key) or t(key, vars)
+ *
+ * @example
+ * const translations = {
+ *   hint: { en: "Tap to start", de: "Tippen zum Starten" },
+ *   level: { en: "Level {n}", de: "Level {n}" }
+ * };
+ * const t = createTranslator(translations);
+ * t('hint');              // Returns "Tap to start" or "Tippen zum Starten"
+ * t('level', { n: 5 });   // Returns "Level 5"
+ */
+export declare function createTranslator<Keys extends string>(translations: TranslationDict<Keys>): {
+    (key: Keys): string;
+    (key: Keys, vars: Record<string, string | number>): string;
+};
+//# sourceMappingURL=i18n.d.ts.map

package/dist/sdk/i18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../../src/playus/i18n.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,mBAAmB,yCAA0C,CAAC;AAC3E,MAAM,MAAM,QAAQ,GAAG,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAC1D,eAAO,MAAM,gBAAgB,EAAE,QAAe,CAAC;AAE/C;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,IAAI,SAAS,MAAM,IAAI;KAChD,CAAC,IAAI,IAAI,GAAG;SACV,CAAC,IAAI,QAAQ,CAAC,CAAC,EAAE,MAAM;KACzB;CACF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,IAAI,QAAQ,CAM7C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,SAAS,MAAM,EAClD,YAAY,EAAE,eAAe,CAAC,IAAI,CAAC,GAClC;IACD,CAAC,GAAG,EAAE,IAAI,GAAG,MAAM,CAAC;IACpB,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC;CAC5D,CAoBA"}

package/dist/sdk/index.d.ts

@@ -0,0 +1,19 @@
+export { ColorConfig, NativeBridge, nativeBridge, roundScoreForBridge, } from './bridge';
+export { createSeededRandom, seededBetween, seededFloatBetween, seededShuffle } from './random';
+export { getGameSeed, getUrlParam } from './url-params';
+export { clampGameplayDeltaMs, clampGameplayDeltaSeconds } from './timing';
+export { createTranslator, getCurrentLanguage } from './i18n';
+export type { Language, TranslationDict } from './i18n';
+export { createTapToStartOverlay } from './tap-to-start';
+export type { LocalizedText, TapToStartMode, TapToStartOverlay } from './tap-to-start';
+export { sound } from './sound';
+export type { SoundId, SoundPlayOptions } from './sound';
+export { applyMobileSurfaceStyle, installMobileSelectionPolicy, installTouchDefaultGuard, } from './mobile-interaction';
+export { createDebugOverlay, getRendererInfo, isDebugMode } from './overlay/debug';
+export { createTouchHint } from './overlay/touch-hint';
+export type { DebugOverlay } from './overlay/debug';
+export type { TouchHint, TouchHintType } from './overlay/touch-hint';
+export type { BackgroundConfig } from './types/background';
+export { DEFAULT_BACKGROUND, getBackgroundColor, isTransparent } from './types/background';
+export { formatMillisecondsAsClock, formatSecondsAsClock } from './helpers/timeFormat';
+//# sourceMappingURL=index.d.ts.map

package/dist/sdk/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/playus/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,mBAAmB,GACpB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAChG,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAC9D,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACvF,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnF,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrE,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC3F,OAAO,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}