@series-inc/venus-sdk 3.0.2 → 3.0.3

package/README.md

@@ -690,6 +690,192 @@ VenusAPI.logging.debug('Debug info')
 
 ---
 
+### Leaderboard API (BETA)
+
+Competitive leaderboards with anti-cheat, multiple modes, and time periods.
+
+#### API Methods
+
+```typescript
+// Start a leaderboard session
+const session = await VenusAPI.leaderboard.startRunAsync({
+  mode: 'classic' // Optional: 'classic', 'hard', etc. Defaults to 'default'
+})
+// Returns: { sessionId, startTime, expiresAt, hashNonce?, mode }
+
+// Submit a score (within 1 hour of starting session)
+const result = await VenusAPI.leaderboard.submitScoreAsync({
+  sessionId: session.sessionId,
+  score: 1500,
+  durationSec: 120,
+  mode: 'classic', // Optional: must match session mode
+  metadata: { // Optional: game-specific data (max 20KB)
+    levelCompleted: 10,
+    powerUpsUsed: 3
+  },
+  telemetry: { // Optional: anti-cheat data (max 2KB, primitives only)
+    clickCount: 245,
+    avgReactionTime: 0.32
+  },
+  hash: computedHash // Required if leaderboard uses hash verification
+})
+// Returns: { accepted, rank, zScore, isAnomaly }
+
+// Get leaderboard (paginated)
+const leaderboard = await VenusAPI.leaderboard.getLeaderboardAsync({
+  mode: 'classic',      // Optional: game mode
+  period: 'daily',      // Optional: 'daily', 'weekly', 'monthly', 'alltime'
+  periodDate: Date.now(), // Optional: specific period to view
+  limit: 50,            // Optional: entries per page (max 50)
+  cursor: nextCursor    // Optional: for pagination
+})
+// Returns: { 
+//   variant: 'standard',
+//   entries: [{ profileId, username, avatarUrl, score, rank, ... }],
+//   totalEntries: 1234,
+//   nextCursor: 'abc123...',
+//   playerRank: 42,
+//   periodInstance: 'daily_2025-11-04'
+// }
+
+// Get leaderboard highlight (top players + context around you)
+const highlight = await VenusAPI.leaderboard.getLeaderboardHighlightAsync({
+  mode: 'classic',
+  period: 'daily',
+  topCount: 3,        // Top N players (podium)
+  contextAhead: 4,    // Players ahead of you
+  contextBehind: 2    // Players behind you
+})
+// Returns: {
+//   variant: 'highlight',
+//   entries: [...],
+//   context: {
+//     topEntries: [...],      // Top 3
+//     beforePlayer: [...],    // 4 players ahead
+//     playerEntry: {...},     // Your entry
+//     afterPlayer: [...],     // 2 players behind
+//     omittedBefore: 35,      // Gap between top 3 and you
+//     omittedAfter: 100       // Players below you
+//   },
+//   playerRank: 42,
+//   totalEntries: 150
+// }
+
+// Get player stats
+const stats = await VenusAPI.leaderboard.getPlayerStatsAsync({
+  mode: 'classic',
+  period: 'daily'
+})
+// Returns: {
+//   rank: 42,
+//   score: 1500,
+//   totalPlayers: 150,
+//   percentile: 0.72,  // 72nd percentile
+//   trustScore: 85,
+//   periodInstance: 'daily_2025-11-04'
+// }
+```
+
+#### Configuration
+
+Add a `leaderboard` object to your game's `config.json` file:
+
+```json
+{
+  "leaderboard": {
+    "isDisabled": false,
+    "disabledMessage": "Leaderboards are temporarily unavailable.",
+    "requiresHash": true,
+    "hashSecret": "your-secret-key-change-in-production",
+    "scoringFields": ["score", "durationSec", "sessionId"],
+    "minDurationSec": 10,
+    "maxDurationSec": 600,
+    "minScore": 0,
+    "maxScore": 999999999,
+    "modes": {
+      "default": {
+        "displayName": "Classic Mode"
+      },
+      "hard": {
+        "displayName": "Hard Mode",
+        "minDurationSec": 5,
+        "maxDurationSec": 300
+      }
+    },
+    "periods": {
+      "daily": {
+        "displayName": "Daily",
+        "type": "daily"
+      },
+      "alltime": {
+        "displayName": "All Time",
+        "type": "alltime"
+      }
+    },
+    "antiCheat": {
+      "enableZScoreDetection": false,
+      "zScoreThreshold": 3,
+      "enableRateLimit": true,
+      "minTimeBetweenSubmissionsSec": 60,
+      "trustScoreDecayPerFlag": 10,
+      "shadowBanThreshold": 20
+    },
+    "displaySettings": {
+      "maxEntriesPerPage": 50
+    },
+    "seedEntries": {
+      "default": {
+        "daily": [
+          {
+            "score": 18500,
+            "username": "ProPlayer",
+            "avatarUrl": null,
+            "durationSec": 180
+          },
+          {
+            "score": 15200,
+            "username": "Challenger",
+            "avatarUrl": null,
+            "durationSec": 210
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+**Configuration Options:**
+
+- `isDisabled`: Globally disable leaderboards
+- `requiresHash`: Enable HMAC-based score verification (recommended for production)
+- `hashSecret`: Secret key for HMAC verification (keep this secure!)
+- `scoringFields`: Fields included in hash verification (can include nested fields like `metadata.level`)
+- `minDurationSec` / `maxDurationSec`: Valid gameplay duration range
+- `minScore` / `maxScore`: Valid score bounds
+- `modes`: Game modes (can override min/max values per mode)
+- `periods`: Time periods for leaderboards (`daily`, `weekly`, `monthly`, `alltime`)
+- `antiCheat`: Anti-cheat settings
+- `seedEntries`: Pre-populate leaderboards with NPC scores (nested by mode → period)
+
+**Features:**
+- **Multiple Modes**: Support different game modes (classic, hard, etc.)
+- **Time Periods**: Daily, weekly, monthly, and all-time leaderboards
+- **Anti-Cheat**: Session validation, rate limiting, hash verification, z-score anomaly detection
+- **Shadow Banning**: Cheaters see their own scores but are hidden from others
+- **Trust Scores**: Per-player reputation that decays with suspicious behavior
+- **Seed Entries**: Pre-populate leaderboards with NPC scores
+- **Pagination**: Cursor-based pagination for large leaderboards
+- **UTC-Based Periods**: All players globally compete in same daily/weekly/monthly periods
+
+**Security Notes:**
+- Session tokens expire after 1 hour and can only be used once to prevent replay attacks
+- Use `requiresHash: true` in production with a strong `hashSecret`
+- Keep `hashSecret` out of version control (use environment variables or local config)
+- Store `hashSecret` in `config.local.json` (gitignored) for local development
+
+---
+
 ## Mock Mode
 
 All APIs have complete mock implementations for local development:

package/dist/{chunk-NQGU2VZM.mjs → chunk-JO6V5EXF.mjs}

@@ -3544,7 +3544,7 @@ function initializeTime(venusApi, host) {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.0.2";
+var SDK_VERSION = "3.0.3";
 
 // src/shared-assets/consts.ts
 var BurgerTimeAssetsCdnPath = "burger-time/Core.stow";
@@ -4954,6 +4954,7 @@ var MockHost = class {
   tryResume() {
     if (this.state === 1 /* PAUSED */) {
       this.triggerLifecycleEvent("RESUME" /* RESUME */);
+      this.state = 0 /* PLAYING */;
     }
   }
   async showAdOverlay(type) {
@@ -5288,5 +5289,5 @@ function initializeSocial(venusApi, host) {
 }
 
 export { HapticFeedbackStyle, HostCdnApi, HostProfileApi, HostTimeApi, MockAdsApi, MockAiApi, MockAnalyticsApi, MockAvatarApi, MockCdnApi, MockFeaturesApi, MockHapticsApi, MockIapApi, MockLeaderboardApi, MockLifecycleApi, MockLoggingApi, MockNavigationApi, MockNotificationsApi, MockPopupsApi, MockPreloaderApi, MockProfileApi, MockSharedAssetsApi, MockSimulationApi, MockSocialApi, MockStorageApi, MockTimeApi, RemoteHost, RpcAdsApi, RpcAiApi, RpcAnalyticsApi, RpcAvatarApi, RpcClient, RpcFeaturesApi, RpcHapticsApi, RpcIapApi, RpcLeaderboardApi, RpcLifecycleApi, RpcLoggingApi, RpcNavigationApi, RpcNotificationsApi, RpcPopupsApi, RpcPreloaderApi, RpcSharedAssetsApi, RpcSimulationApi, RpcSocialApi, RpcStorageApi, SDK_VERSION, VenusMessageId, VenusRoom, createHost, createMockStorageApi, init_rooms, initializeAds, initializeAi, initializeAnalytics, initializeAvatar3d, initializeCdn, initializeFeaturesApi, initializeHaptics, initializeIap, initializeLeaderboard, initializeLifecycleApi, initializeLocalNotifications, initializeLoggingApi, initializePopups, initializePost, initializePreloader, initializeProfile, initializeRoomsApi, initializeSimulation, initializeSocial, initializeStackNavigation, initializeStorage, initializeTime, isPacificDaylightTime, setupRoomNotifications };
-//# sourceMappingURL=chunk-NQGU2VZM.mjs.map
-//# sourceMappingURL=chunk-NQGU2VZM.mjs.map
+//# sourceMappingURL=chunk-JO6V5EXF.mjs.map
+//# sourceMappingURL=chunk-JO6V5EXF.mjs.map