portals-mcp 1.3.4 → 1.3.5

package/dist/resources/logic/js-function-reference.md

@@ -119,6 +119,67 @@ PrepareEffector({{Object}}, 'SetTransform', '{"scale":[2,2,2]}', 'grow');
 
 **Targets:** `{{Object}}`, `{{Parent}}`, `{{Child}}` are unquoted template tokens. String IDs like `'760'` are quoted.
 
+## Reading Leaderboard Data (async)
+
+`GetLeaderboard(name, options?)` fetches a leaderboard's ranked rows from the backend and resolves to a **real JS array** of entries. Use it to build a custom leaderboard UI with `displayHtml(...)` — for example a styled overlay, a "your rank" callout, or a top-N mini board — instead of the native `OpenLeaderboard` panel. It reads leaderboard scores that were posted with `PostScoreToLeaderboard` (numeric) or recorded automatically by `StopTimer` (time-based); see `docs://logic/js-use-effector` for posting.
+
+`GetLeaderboard` is **async** — it does an HTTP fetch — so you must `await` it. Top-level `await` is NOT supported in the sandbox, so wrap it in an async IIFE and `catch` errors (the Promise **rejects** on network/parse failure, so a bare `await` throws and can surface a visible error overlay).
+
+```javascript
+(async function () {
+  try {
+    const rows = await GetLeaderboard('MyBoard');   // whole board, best-first
+    // rows: [{ rank, name, score, isLocalPlayer }, ...]
+    var html = '<ol>' + rows.map(function (r) {
+      return '<li>' + r.rank + '. ' + r.name + ' — ' + r.score +
+             (r.isLocalPlayer ? ' (you)' : '') + '</li>';
+    }).join('') + '</ol>';
+    displayHtml('<div id="lb">' + html + '</div>');
+  } catch (e) {
+    logFromJS('GetLeaderboard failed: ' + e);
+  }
+})();
+```
+
+### Arguments
+
+| Arg | Type | Required | Description |
+|-----|------|----------|-------------|
+| `name` | string | Yes | Leaderboard name — must match the leaderboard's `ln` field (the score/timer label it tracks). |
+| `options` | object | No | `{ competitionId?, offset?, limit? }`. A bare string is also accepted and treated as `competitionId`. Omit for the whole board. |
+
+Options fields:
+- `competitionId` (string) — scope to a specific competition; omit/empty for the standard board.
+- `offset` (int, default `0`) — skip this many rows from the top. Out-of-range offset yields an empty array.
+- `limit` (int, default `-1`) — max rows to return; `-1` means everything from `offset` onward.
+
+Paging is applied client-side today, so `rank` stays **absolute** across pages (see below).
+
+### Returned entry shape
+
+Each entry is `{ rank, name, score, isLocalPlayer }`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `rank` | int | Absolute 1-based position across the whole board — stays correct on any page. |
+| `name` | string | Player's display name. |
+| `score` | number | The posted score. **Time-based leaderboards return `score` in milliseconds** — divide/format as needed. |
+| `isLocalPlayer` | bool | `true` for the row belonging to the current player (handy for highlighting "you"). |
+
+### Paging example
+
+```javascript
+(async function () {
+  const page2 = await GetLeaderboard('MyBoard', { offset: 10, limit: 10 });  // ranks 11–20
+  const comp  = await GetLeaderboard('MyBoard', { competitionId: 'abc', limit: 5 });
+})();
+```
+
+> **Gotchas.**
+> - `GetLeaderboard` **reads** scores; it does not post them. Post with `UseEffector(..., 'PostScoreToLeaderboard', ...)` (numeric) or record automatically via `StopTimer` (time-based).
+> - Object options do NOT marshal on the Jint fallback engine (exotic platforms) — name-only calls still work there. Prefer name-only when you don't need paging.
+> - It's the async, list-shaped analogue of the synchronous `$N{...}` variable read: leaderboard data is remote and a list, so it can't come through the `$N{...}` substitution path.
+
 ## Critical Rules
 
 ### 1. Code formatting

package/dist/resources/logic/js-use-effector.md

@@ -485,6 +485,8 @@ UseEffector({{Object}}, 'AttachItemToPlayer', '{"bodyPart":"RightHand","localOff
 #### PostScoreToLeaderboard 🟡
 `'PostScoreToLeaderboard'` — `label` (string, default `"Score"`), `ow` (bool) (UE004 — JS call executed without error, but the leaderboard row did NOT visibly appear. Keep docs conservative; consider a custom `displayHtml` leaderboard built from `SelectPlayersParameters({{Players}}, ...)` until row display is confirmed.)
 
+> **Reading leaderboard rows into JS:** to build a custom leaderboard UI, use the async `GetLeaderboard(name, options?)` bridge function — it resolves to `[{ rank, name, score, isLocalPlayer }, ...]` (time-based boards return `score` in ms). See `docs://logic/js-function-reference` → "Reading Leaderboard Data".
+
 #### OpenLeaderboard ✅
 `'OpenLeaderboard'` — `lb` (string), `ci` (string), `tb` (bool, default `true`) (UE004 — native leaderboard panel opens with the requested label as title.)
 

package/dist/resources/ref/systems/function-effector-js.json

@@ -2,7 +2,7 @@
   "id": "system:function-effector-js",
   "name": "FunctionEffectorJS",
   "description": "JavaScript runtime for game logic. More powerful than NCalc — supports loops, string manipulation, UseEffector calls, and multi-step procedural logic.",
-  "aliases": ["js", "javascript", "functioneffectorjs", "js function", "click function", "onclick js", "on click js", "js logic", "js script", "js code", "javascript function", "js onclick", "js variable", "reactive watcher", "S true", "R true", "activate on start"],
+  "aliases": ["js", "javascript", "functioneffectorjs", "js function", "click function", "onclick js", "on click js", "js logic", "js script", "js code", "javascript function", "js onclick", "js variable", "reactive watcher", "S true", "R true", "activate on start", "getleaderboard", "read leaderboard", "leaderboard data", "custom leaderboard", "leaderboard rows"],
   "structure": {
     "$type": "FunctionEffectorJS",
     "V": "JavaScript code (single-line or multi-line both supported)",
@@ -21,6 +21,9 @@
     "PrepareEffector": "PrepareEffector(target, 'EffectName', '{json params}', 'customId') — create/cache the temporary effector without activating it.",
     "SetPlayerParameter": "SetPlayerParameter('paramName', value) — set a parameter on the local player."
   },
+  "async_functions": {
+    "GetLeaderboard": "await GetLeaderboard('BoardName', { competitionId?, offset?, limit? }) — fetches leaderboard rows and resolves to a JS array [{ rank, name, score, isLocalPlayer }, ...]. rank is absolute 1-based (stable across pages). Time-based boards return score in milliseconds. MUST be awaited inside an async IIFE (no top-level await); rejects on network/parse error, so wrap in try/catch. Use to build custom displayHtml leaderboards. Options don't marshal on the Jint fallback engine — name-only calls still work. Reads scores posted via PostScoreToLeaderboard / recorded by StopTimer; it does not post."
+  },
   "targets": {
     "{{Object}}": "The item the JS is on (unquoted)",
     "{{Parent}}": "Parent of the item (unquoted)",
@@ -47,7 +50,8 @@
     "Missing $N{x} reads return null, not throws — coerce defaults (Number($N{x}) || 0)",
     "Player-list token: {{Players}} (NOT NCalc [Players]); validator rejects the wrong form at upload",
     "Sandbox: window/localStorage/fetch/requestAnimationFrame/getComputedStyle/AudioContext/Audio/Date.now() are NOT available — use globalThis and setInterval",
-    "RESERVED VARIABLE NAMES: 'position', 'rotation', 'scale' are engine builtins. $N{position} returns the player's world [x,y,z] array, not a custom variable. Use 'tile', 'spot', 'progress' etc. instead."
+    "RESERVED VARIABLE NAMES: 'position', 'rotation', 'scale' are engine builtins. $N{position} returns the player's world [x,y,z] array, not a custom variable. Use 'tile', 'spot', 'progress' etc. instead.",
+    "GetLeaderboard is async — must be awaited inside an async IIFE (top-level await is unsupported) and wrapped in try/catch (it rejects on network/parse error). Time-based boards return score in ms. It reads scores only; post with PostScoreToLeaderboard or record via StopTimer."
   ],
   "common_patterns": {
     "add_to_variable": "var h = Number($N{health}) || 0.0; SetVariable('health', h + 30.0, 0.0);",
@@ -57,7 +61,8 @@
     "change_movement": "UseEffector({{Object}}, 'ChangeMovementProfile', '{\"mvmtProfile\":\"speedy\"}');",
     "play_sound": "UseEffector({{Object}}, 'PlaySoundOnce', '{\"Url\":\"https://example.com/sound.mp3\",\"volume\":1.0}');",
     "move_item": "UseEffector({{Object}}, 'MoveToSpot', '{\"transformState\":{\"position\":[0,5,0],\"rotation\":[0,0,0,1],\"scale\":[1,1,1],\"duration\":2.0},\"relative\":true}');",
-    "prepare_transform": "PrepareEffector({{Object}}, 'SetTransform', '{\"scale\":[2,2,2]}', 'grow');"
+    "prepare_transform": "PrepareEffector({{Object}}, 'SetTransform', '{\"scale\":[2,2,2]}', 'grow');",
+    "custom_leaderboard": "(async function(){ try { var rows = await GetLeaderboard('MyBoard'); var html = rows.map(function(r){ return r.rank + '. ' + r.name + ' — ' + r.score + (r.isLocalPlayer ? ' (you)' : ''); }).join('<br>'); displayHtml('<div id=\"lb\">' + html + '</div>'); } catch(e){ logFromJS('GetLeaderboard failed: ' + e); } })();"
   },
   "deep_dive_uri": "docs://logic/js-function-reference"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portals-mcp",
-  "version": "1.3.4",
+  "version": "1.3.5",
   "description": "AI-first MCP server for Portals room workflows",
   "type": "module",
   "main": "dist/index.js",