com.superfive.js 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Francois
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Readme.md

@@ -0,0 +1,203 @@
+# SuperFive JS API
+
+This is the JS API for the SuperFive.io gaming platform where players can compete in a hypercasual games tournament. Use it to adapt your game for the platform.
+
+## API usage
+
+```js
+import {
+  isInPlatformMode,
+  subscribeToPlatformMessages
+} from 'com.superfive.js'
+
+// Check if the platform is loading this game
+if (isInPlatformMode()) {
+
+  // Subscribe to the platform's messages
+  subscribeToPlatformMessages();
+  window.addEventListener('platformMessage', (event: Event) => {
+    const customEvent = event as CustomEvent;
+    const { type } = customEvent.detail;
+
+    if (type === 'game_restart') {
+      this.yourRestartGame();
+    }
+  });
+
+}
+```
+
+## API events
+
+The platform can send the following events to your game:
+
+### `platformMessage` (Custom Event)
+
+This event is dispatched when the platform sends a message to your game. Listen for this event to handle platform communications.
+
+**Event Structure:**
+```js
+{
+  detail: {
+    type: string,    // The message type
+    payload: any     // Optional payload data
+  }
+}
+```
+
+**Available Message Types:**
+- `game_restart` - Platform requests the game to (re)start
+- `game_mute` - Platform requests the game to mute/unmute audio
+
+**Example:**
+```js
+window.addEventListener('platformMessage', (event) => {
+  const customEvent = event as CustomEvent;
+  const { type, payload } = customEvent.detail;
+  
+  switch (type) {
+    case 'game_restart':
+      // Restart your game
+      break;
+    case 'game_mute':
+      // Handle mute/unmute based on payload
+      const isMuted = payload.muted;
+      break;
+  }
+});
+```
+
+## API methods
+
+### Platform Detection
+
+#### `isInPlatformMode(): boolean`
+
+Checks if the game is running within the SuperFive platform.
+
+**Returns:** `boolean` - `true` if running in platform mode, `false` otherwise
+
+**Example:**
+```js
+if (isInPlatformMode()) {
+  // Game is running in SuperFive platform
+  console.log('Platform mode detected');
+}
+```
+
+#### `getDifficulty(): number`
+
+Gets the difficulty level set by the platform.
+
+**Returns:** `number` - Difficulty level (0-2)
+- `0` - Easy (default)
+- `1` - Medium  
+- `2` - Hard
+
+**Example:**
+```js
+const difficulty = getDifficulty();
+console.log(`Game difficulty: ${difficulty}`);
+```
+
+#### `startMuted(): boolean`
+
+The player can set if they want to play without sound effects.
+This should be checked before starting the game or playing any sounds.
+
+**Returns:** `boolean`
+
+**Example:**
+```js
+const isMuted = startMuted();
+console.log(`Game muted?: ${isMuted}`);
+```
+
+### Message Handling
+
+#### `subscribeToPlatformMessages(): void`
+
+Subscribes to platform messages. Call this when your game starts to receive platform events.
+
+**Example:**
+```js
+// Subscribe to platform messages
+subscribeToPlatformMessages();
+```
+
+#### `unsubscribeFromPlatformMessages(): void`
+
+Unsubscribes from platform messages. Call this when your game is shutting down.
+
+**Example:**
+```js
+// Clean up when game ends
+unsubscribeFromPlatformMessages();
+```
+
+### Sending Messages to Platform
+
+#### `sendPlatformMessage(type, payload?): void`
+
+Sends a message to the SuperFive platform.
+
+**Parameters:**
+- `type` - Message type (see PlatformMessage types below)
+- `payload` - Optional data to send with the message
+
+**Example:**
+```js
+// Send custom message with data
+sendPlatformMessage('custom_event', { score: 100 });
+```
+
+#### `sendReady(): void`
+
+Notifies the platform that your game is loaded and ready to play.
+
+**Example:**
+```js
+// When your game is fully loaded
+sendReady();
+```
+
+#### `sendWin(): void`
+
+Notifies the platform that the player has won the game.
+
+**Example:**
+```js
+// When player completes the game successfully
+sendWin();
+```
+
+#### `sendLose(): void`
+
+Notifies the platform that the player has lost the game.
+
+**Example:**
+```js
+// When player fails the game
+sendLose();
+```
+
+### Message Types
+
+The following message types can be sent to the platform:
+
+```typescript
+type PlatformMessageType = 
+  | 'game_ready'    // Game is loaded and ready
+  | 'game_won'      // Player won the game
+  | 'game_lost'     // Player lost the game
+  | 'game_restart'  // Platform requests restart
+  | 'game_mute'     // Platform requests mute/unmute
+```
+
+# Game development
+
+- The game should work in portrait (9:16)
+- The game should work on desktop (mouse input) and mobile (touch input)
+- The game should not start unless it receives the ``game_restart`` message from the platform
+- The game should not play any music - only sound effects (the platform plays music)
+- The game can have different difficulty levels (0 = 'Easy', 1 = 'Medium', 2 = 'Hard').

package/dist/main.js

@@ -0,0 +1,49 @@
+function getUrlParam(name) {
+	return new URLSearchParams(window.location.search).get(name);
+}
+function isInPlatformMode() {
+	return getUrlParam("p") === "1";
+}
+function startMuted() {
+	return getUrlParam("muted") === "1";
+}
+function getDifficulty() {
+	return parseInt(getUrlParam("difficulty") || "0", 10);
+}
+function subscribeToPlatformMessages() {
+	if (!isInPlatformMode()) return;
+	window.addEventListener("message", handlePlatformMessage);
+}
+function unsubscribeFromPlatformMessages() {
+	window.removeEventListener("message", handlePlatformMessage);
+}
+function handlePlatformMessage(event) {
+	const data = event.data;
+	if (!data || !data.type) return;
+	if (typeof data.type !== "string") return;
+	const customEvent = new CustomEvent("platformMessage", { detail: {
+		type: data.type,
+		payload: data.payload
+	} });
+	window.dispatchEvent(customEvent);
+}
+function sendPlatformMessage(type, payload) {
+	if (!isInPlatformMode()) return;
+	const message = {
+		type,
+		payload
+	};
+	window.parent.postMessage(message, "*");
+}
+function sendReady() {
+	sendPlatformMessage("game_ready");
+}
+function sendWin() {
+	sendPlatformMessage("game_won");
+}
+function sendLose() {
+	sendPlatformMessage("game_lost");
+}
+export { getDifficulty, isInPlatformMode, sendLose, sendPlatformMessage, sendReady, sendWin, startMuted, subscribeToPlatformMessages, unsubscribeFromPlatformMessages };
+
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","names":["message: PlatformMessage"],"sources":["../src/main.ts"],"sourcesContent":["import type { PlatformMessage } from './types.ts';\n\nfunction getUrlParam(name: string): string | null {\n  const urlParams = new URLSearchParams(window.location.search);\n  return urlParams.get(name);\n}\n\n/**\n * Check if the game is running in the SuperFive platform\n *\n * @returns True if the game is in platform mode, false otherwise\n */\nexport function isInPlatformMode(): boolean {\n  return getUrlParam('p') === '1';\n}\n\n/**\n * Check if the game should start muted\n *\n * @returns True if the game should start muted, false otherwise\n */\nexport function startMuted(): boolean {\n  return getUrlParam('muted') === '1';\n}\n\n/**\n * Get the difficulty of the game\n *\n * The difficulty is a number between 0 and 2\n * - 0: Easy\n * - 1: Medium\n * - 2: Hard\n *\n * @returns The difficulty of the game as a number between 0 and 2\n */\nexport function getDifficulty(): number {\n  return parseInt(getUrlParam('difficulty') || '0', 10);\n}\n\n// ==============================================================\n// Message Handling\n// ==============================================================\n\n/**\n * Subscribe to the platform's messages to handle platform events\n *\n * @returns void\n */\nexport function subscribeToPlatformMessages(): void {\n  if (!isInPlatformMode()) return;\n  window.addEventListener('message', handlePlatformMessage);\n}\n\n/**\n * Unsubscribe from the platform's messages\n *\n * @returns void\n */\nexport function unsubscribeFromPlatformMessages(): void {\n  window.removeEventListener('message', handlePlatformMessage);\n}\n\n/**\n * Handle the platform's messages\n *\n * @param event The message event\n * @returns void\n */\nfunction handlePlatformMessage(event: MessageEvent): void {\n  const data = event.data;\n  if (!data || !data.type) return;\n\n  // Validate message shape\n  if (typeof data.type !== 'string') return;\n\n  // Emit custom event for game to handle\n  const customEvent = new CustomEvent('platformMessage', { \n    detail: { type: data.type, payload: data.payload } \n  });\n  window.dispatchEvent(customEvent);\n}\n\n// ==============================================================\n// Sending Messages Methods\n// ==============================================================\n\n/**\n * Send a message to the platform\n *\n * @param type The type of the message\n * @param payload The payload of the message\n * @returns void\n */\nexport function sendPlatformMessage(type: PlatformMessage['type'], payload?: any): void {\n  if (!isInPlatformMode()) return;\n  const message: PlatformMessage = { type, payload };\n  window.parent.postMessage(message, '*');\n}\n\n/**\n * Send a message to the platform to indicate that the game is ready (loaded and ready to play)\n *\n * @returns void\n */\nexport function sendReady(): void {\n  sendPlatformMessage('game_ready');\n}\n\n/**\n * Send a message to the platform to indicate that the game is won\n *\n * @returns void\n */\nexport function sendWin(): void {\n  sendPlatformMessage('game_won');\n}\n\n/**\n * Send a message to the platform to indicate that the game is lost\n *\n * @returns void\n */\nexport function sendLose(): void {\n  sendPlatformMessage('game_lost');\n}\n"],"mappings":"AAEA,SAAS,YAAY,MAA6B;AAEhD,QADkB,IAAI,gBAAgB,OAAO,SAAS,OAAO,CAC5C,IAAI,KAAK;;AAQ5B,SAAgB,mBAA4B;AAC1C,QAAO,YAAY,IAAI,KAAK;;AAQ9B,SAAgB,aAAsB;AACpC,QAAO,YAAY,QAAQ,KAAK;;AAalC,SAAgB,gBAAwB;AACtC,QAAO,SAAS,YAAY,aAAa,IAAI,KAAK,GAAG;;AAYvD,SAAgB,8BAAoC;AAClD,KAAI,CAAC,kBAAkB,CAAE;AACzB,QAAO,iBAAiB,WAAW,sBAAsB;;AAQ3D,SAAgB,kCAAwC;AACtD,QAAO,oBAAoB,WAAW,sBAAsB;;AAS9D,SAAS,sBAAsB,OAA2B;CACxD,MAAM,OAAO,MAAM;AACnB,KAAI,CAAC,QAAQ,CAAC,KAAK,KAAM;AAGzB,KAAI,OAAO,KAAK,SAAS,SAAU;CAGnC,MAAM,cAAc,IAAI,YAAY,mBAAmB,EACrD,QAAQ;EAAE,MAAM,KAAK;EAAM,SAAS,KAAK;EAAS,EACnD,CAAC;AACF,QAAO,cAAc,YAAY;;AAcnC,SAAgB,oBAAoB,MAA+B,SAAqB;AACtF,KAAI,CAAC,kBAAkB,CAAE;CACzB,MAAMA,UAA2B;EAAE;EAAM;EAAS;AAClD,QAAO,OAAO,YAAY,SAAS,IAAI;;AAQzC,SAAgB,YAAkB;AAChC,qBAAoB,aAAa;;AAQnC,SAAgB,UAAgB;AAC9B,qBAAoB,WAAW;;AAQjC,SAAgB,WAAiB;AAC/B,qBAAoB,YAAY"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "com.superfive.js",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/main.js",
+  "module": "./dist/main.js",
+  "types": "./dist/main.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/main.js",
+      "types": "./dist/main.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "description": "The JS API for the SuperFive.io gaming platform where players can compete in a hypercasual games tournament",
+  "author": "Dibulo",
+  "license": "MIT",
+  "homepage": "https://superfive.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dibulo/superfive-js-api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dibulo/superfive-js-api/issues"
+  },
+  "keywords": [
+    "superfive",
+    "gaming",
+    "js",
+    "api"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -p tsconfig.build.json && vite build",
+    "build:types": "tsc --emitDeclarationOnly --outDir dist",
+    "preview": "vite preview",
+    "prepublishOnly": "pnpm run build"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.3",
+    "vite": "npm:rolldown-vite@7.1.14"
+  },
+  "pnpm": {
+    "overrides": {
+      "vite": "npm:rolldown-vite@7.1.14"
+    }
+  }
+}