@skillprint/cocos-sdk 0.0.1 → 1.0.0

package/README.md

@@ -0,0 +1,126 @@
+# Skillprint Cocos Creator SDK
+
+TypeScript SDK for integrating Skillprint into Cocos Creator 3.8.x games. This SDK enables real-time session tracking, automated screenshot canvas captures for mood/skill analysis, and dynamic parameter adjustments (adaptive difficulty, relaxation pacing, grit challenges) based on player analytics.
+
+For details on the published npm package, visit [npm package @skillprint/cocos-sdk](https://www.npmjs.com/package/@skillprint/cocos-sdk).
+
+---
+
+## 🚀 Installation
+
+Install the package in your Cocos Creator project root:
+
+```bash
+npm install @skillprint/cocos-sdk
+```
+
+---
+
+## 🛠️ Cocos Creator Setup
+
+Cocos Creator's editor registers serializable component classes and inspector fields from files located inside the `assets/` directory. To use the SDK's editor-facing configuration and manager components:
+
+### 1. Create Local Wrappers
+
+Create a directory in your project under `assets/scripts/SkillprintSDK/` and add the following wrapper scripts. They inherit from the npm package components, allowing them to register in the Cocos Creator Asset database and inspector.
+
+#### 📄 `assets/scripts/SkillprintSDK/SkillprintConfigComponent.ts`
+```typescript
+import { _decorator } from 'cc';
+import { SkillprintConfigComponent as SDKConfig } from '@skillprint/cocos-sdk';
+const { ccclass } = _decorator;
+
+@ccclass('SkillprintConfigComponent')
+export class SkillprintConfigComponent extends SDKConfig {}
+```
+
+#### 📄 `assets/scripts/SkillprintSDK/SkillprintManager.ts`
+```typescript
+import { _decorator } from 'cc';
+import { SkillprintManager as SDKManager } from '@skillprint/cocos-sdk';
+const { ccclass } = _decorator;
+
+@ccclass('SkillprintManager')
+export class SkillprintManager extends SDKManager {}
+```
+
+### 2. Configure in Scene Editor
+1. Create a Node in your Cocos Creator hierarchy (e.g. named `SkillprintManager`).
+2. Attach both the local `SkillprintManager` and `SkillprintConfigComponent` to it.
+3. In the **Inspector** panel for `SkillprintConfigComponent`:
+   - Set your **Game Name (Slug)** (e.g., `fruit-boom`).
+   - Select your target environment (`Staging` or `Production`).
+   - Input your **Staging/Production Partner API Keys** and **Base URLs**.
+   - Configure screenshot frequencies (default: `2s` capture, `5s` post intervals) and downscaling width (default: `960px`).
+   
+---
+
+## 💻 Integration & Usage
+
+Use a controller script (e.g. attached to your main scene node) to initialize the SDK and react to parameter updates.
+
+### Code Example: `SkillprintTestController.ts`
+```typescript
+import { _decorator, Component } from 'cc';
+import { SkillprintConfig, ApiEnvironment, ParameterType } from '@skillprint/cocos-sdk';
+import { SkillprintManager } from './SkillprintSDK/SkillprintManager';
+
+const { ccclass } = _decorator;
+
+@ccclass('SkillprintTestController')
+export class SkillprintTestController extends Component {
+    
+    start() {
+        // 1. Get the local Manager component instance
+        let manager = this.getComponent(SkillprintManager);
+        if (!manager) {
+            manager = this.node.addComponent(SkillprintManager);
+        }
+
+        // 2. Register modifiers for parameters your game should adapt
+        SkillprintManager.instance.registerParameterModifier<number>('playerSpeed', (newSpeed) => {
+            console.log(`[Game Logic] Adjusting speed -> ${newSpeed}`);
+            // Apply speed to your player object here
+        });
+
+        SkillprintManager.instance.registerParameterModifier<boolean>('showTutorialHints', (show) => {
+            console.log(`[Game Logic] Toggle hints -> ${show}`);
+            // Apply hint display settings
+        });
+
+        // 3. Start the game session
+        // (It will read URL overrides if launched in browser preview: ?mood=focus&playerId=test-user)
+        SkillprintManager.instance.startGameSessionFromUrl('focus', 'player-id-123');
+    }
+
+    onDestroy() {
+        // Ensure session terminates correctly when scene changes or controller destroys
+        if (SkillprintManager.instance) {
+            SkillprintManager.instance.stopGameSession();
+        }
+    }
+}
+```
+
+### Reference in UI scripts (like `HomeUI.ts`)
+To reference your configuration from other scripts:
+```typescript
+import { _decorator, Component } from 'cc';
+import { SkillprintConfigComponent } from './SkillprintSDK/SkillprintConfigComponent';
+import { SkillprintManager } from './SkillprintSDK/SkillprintManager';
+
+const { ccclass, property } = _decorator;
+
+@ccclass('HomeUI')
+export class HomeUI extends Component {
+    @property(SkillprintConfigComponent)
+    public skillprintConfig: SkillprintConfigComponent = null!;
+
+    start() {
+        const manager = this.node.addComponent(SkillprintManager);
+        if (this.skillprintConfig) {
+            manager.init(this.skillprintConfig.getConfig());
+        }
+    }
+}
+```

package/dist/SkillprintAPIClient.d.ts

@@ -1,4 +1,4 @@
-import { ParameterInfo, ParameterUpdateResult } from './SkillprintTypes';
+import { ParameterInfo, ParameterUpdateResult } from './SkillprintTypes.js';
 export declare class SkillprintAPIClient {
     private baseUrl;
     private partnerApiKey;

package/dist/SkillprintConfigComponent.d.ts

@@ -1,5 +1,5 @@
 import { Component } from 'cc';
-import { ApiEnvironment, SkillprintConfig } from './SkillprintTypes';
+import { ApiEnvironment, SkillprintConfig } from './SkillprintTypes.js';
 export declare class SkillprintConfigComponent extends Component {
     gameName: string;
     targetEnvironment: ApiEnvironment;

package/dist/SkillprintConfigComponent.js

@@ -5,7 +5,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { _decorator, Component, Enum } from 'cc';
-import { ApiEnvironment } from './SkillprintTypes';
+import { ApiEnvironment } from './SkillprintTypes.js';
 const { ccclass, property } = _decorator;
 Enum(ApiEnvironment);
 let SkillprintConfigComponent = class SkillprintConfigComponent extends Component {

package/dist/SkillprintManager.d.ts

@@ -1,5 +1,5 @@
 import { Component } from 'cc';
-import { SkillprintConfig } from './SkillprintTypes';
+import { SkillprintConfig } from './SkillprintTypes.js';
 export declare class SkillprintManager extends Component {
     private static _instance;
     static get instance(): SkillprintManager;

package/dist/SkillprintManager.js

@@ -6,9 +6,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 var SkillprintManager_1;
 import { _decorator, Component, director, Camera, sys, Enum } from 'cc';
-import { ParameterType, ApiEnvironment } from './SkillprintTypes';
-import { SkillprintAPIClient } from './SkillprintAPIClient';
-import { ScreenshotUtility } from './ScreenshotUtility';
+import { ParameterType, ApiEnvironment } from './SkillprintTypes.js';
+import { SkillprintAPIClient } from './SkillprintAPIClient.js';
+import { ScreenshotUtility } from './ScreenshotUtility.js';
 const { ccclass, property } = _decorator;
 Enum(ApiEnvironment);
 let SkillprintManager = SkillprintManager_1 = class SkillprintManager extends Component {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export * from './SkillprintTypes';
-export * from './SkillprintAPIClient';
-export * from './ScreenshotUtility';
-export * from './SkillprintManager';
-export * from './SkillprintConfigComponent';
+export * from './SkillprintTypes.js';
+export * from './SkillprintAPIClient.js';
+export * from './ScreenshotUtility.js';
+export * from './SkillprintManager.js';
+export * from './SkillprintConfigComponent.js';

package/dist/index.js

@@ -1,5 +1,5 @@
-export * from './SkillprintTypes';
-export * from './SkillprintAPIClient';
-export * from './ScreenshotUtility';
-export * from './SkillprintManager';
-export * from './SkillprintConfigComponent';
+export * from './SkillprintTypes.js';
+export * from './SkillprintAPIClient.js';
+export * from './ScreenshotUtility.js';
+export * from './SkillprintManager.js';
+export * from './SkillprintConfigComponent.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillprint/cocos-sdk",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "type": "module",
   "description": "Skillprint SDK for Cocos Creator 3.x",
   "main": "dist/index.js",
@@ -9,7 +9,8 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "release": "./publish.sh"
   },
   "peerDependencies": {
     "cc": "*"

package/publish.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+# Exit immediately if a command exits with a non-zero status
+set -e
+
+echo "=== 🚀 Starting build and release process ==="
+
+# Get current branch
+CURRENT_BRANCH=$(git branch --show-current)
+if [ -z "$CURRENT_BRANCH" ]; then
+  echo "❌ Could not determine current git branch. Aborting."
+  exit 1
+fi
+
+# 1. Build the project to verify it compiles before making any changes
+echo "Building the SDK..."
+npm run build
+
+# 2. Check if git working directory is clean
+if [ -n "$(git status --porcelain)" ]; then
+  echo "⚠️ Working directory is not clean. Please commit or stash your changes before releasing."
+  exit 1
+fi
+
+# 3. Determine version bump type (from argument or prompt)
+BUMP_TYPE=$1
+
+if [ -z "$BUMP_TYPE" ]; then
+  echo "Select version bump type:"
+  echo "1) patch (e.g. bump last digit)"
+  echo "2) minor (e.g. bump middle digit)"
+  echo "3) major (e.g. bump first digit)"
+  read -p "Enter choice [1-3] (default: patch): " choice
+
+  case "$choice" in
+    2) BUMP_TYPE="minor" ;;
+    3) BUMP_TYPE="major" ;;
+    *) BUMP_TYPE="patch" ;;
+  esac
+fi
+
+# Validate bump type
+if [ "$BUMP_TYPE" != "patch" ] && [ "$BUMP_TYPE" != "minor" ] && [ "$BUMP_TYPE" != "major" ]; then
+  echo "❌ Invalid bump type '$BUMP_TYPE'. Must be 'patch', 'minor', or 'major'."
+  exit 1
+fi
+
+echo "Incrementing $BUMP_TYPE version..."
+NEW_VERSION=$(npm version "$BUMP_TYPE")
+echo "New version: $NEW_VERSION"
+
+# 4. Push git commit and tags to remote origin
+echo "Pushing changes and tags to GitHub ($CURRENT_BRANCH)..."
+git push origin "$CURRENT_BRANCH"
+git push origin "$NEW_VERSION"
+
+# 5. Publish to npm
+echo "Publishing to npm..."
+# This will run interactively and prompt for 2FA OTP if required by the account settings
+npm publish
+
+# 6. Create GitHub release
+echo "Creating GitHub release..."
+if which gh > /dev/null 2>&1; then
+  gh release create "$NEW_VERSION" --title "$NEW_VERSION" --notes "Release $NEW_VERSION of @skillprint/cocos-sdk"
+  echo "GitHub release created successfully."
+else
+  echo "⚠️ GitHub CLI (gh) not found or not authenticated. Skipping release creation."
+fi
+
+echo "=== 🎉 Release $NEW_VERSION successfully published! ==="

package/src/SkillprintAPIClient.ts

@@ -1,4 +1,4 @@
-import { ParameterInfo, ParameterUpdateResult, PollResultsResponse } from './SkillprintTypes';
+import { ParameterInfo, ParameterUpdateResult, PollResultsResponse } from './SkillprintTypes.js';
 
 export class SkillprintAPIClient {
     private baseUrl: string;

package/src/SkillprintConfigComponent.ts

@@ -1,5 +1,5 @@
 import { _decorator, Component, Enum } from 'cc';
-import { ApiEnvironment, SkillprintConfig } from './SkillprintTypes';
+import { ApiEnvironment, SkillprintConfig } from './SkillprintTypes.js';
 
 const { ccclass, property } = _decorator;
 

package/src/SkillprintManager.ts

@@ -1,7 +1,7 @@
 import { _decorator, Component, director, Camera, sys, Enum } from 'cc';
-import { SkillprintConfig, ParameterDefinition, ParameterType, ParameterInfo, ParameterUpdateResult, Mood, ApiEnvironment } from './SkillprintTypes';
-import { SkillprintAPIClient } from './SkillprintAPIClient';
-import { ScreenshotUtility } from './ScreenshotUtility';
+import { SkillprintConfig, ParameterDefinition, ParameterType, ParameterInfo, ParameterUpdateResult, Mood, ApiEnvironment } from './SkillprintTypes.js';
+import { SkillprintAPIClient } from './SkillprintAPIClient.js';
+import { ScreenshotUtility } from './ScreenshotUtility.js';
 
 const { ccclass, property } = _decorator;
 

package/src/index.ts

@@ -1,5 +1,5 @@
-export * from './SkillprintTypes';
-export * from './SkillprintAPIClient';
-export * from './ScreenshotUtility';
-export * from './SkillprintManager';
-export * from './SkillprintConfigComponent';
+export * from './SkillprintTypes.js';
+export * from './SkillprintAPIClient.js';
+export * from './ScreenshotUtility.js';
+export * from './SkillprintManager.js';
+export * from './SkillprintConfigComponent.js';