portals-mcp 1.3.3 → 1.3.4

package/dist/marketplace-client.d.ts

@@ -24,6 +24,12 @@ export interface MarketplaceItem {
     claimCount: number;
     acquireCount: number;
 }
+export interface MarketplaceGlbResolution {
+    glb: string | null;
+    source: "catalog_direct" | "user_inventory" | "room_build_items" | "unresolved";
+    attachedToRoomInventory: boolean;
+    reason?: string | undefined;
+}
 export interface MarketplaceFilter {
     query?: string | undefined;
     type?: string | undefined;
@@ -44,6 +50,8 @@ export interface ClaimResult {
     itemId: string;
     message?: string | undefined;
 }
+export declare function isMarketplaceAssetRoute(value: string | null | undefined): boolean;
+export declare function isRuntimeGlbUrl(value: string | null | undefined): boolean;
 export declare function clearMarketplaceCache(): void;
 export declare function searchMarketplace(filter?: MarketplaceFilter): Promise<MarketplaceItem[]>;
 export declare function getPackItems(packId: string): Promise<MarketplaceItem[]>;
@@ -116,4 +124,5 @@ export interface OwnershipCheck {
 export declare function verifyOwnership(cids: string[]): Promise<OwnershipCheck[]>;
 export declare function attachItemsToRoom(roomId: string, itemIds: string[]): Promise<AttachToRoomResult>;
 export declare function claimMarketplaceItem(itemId: string): Promise<ClaimResult>;
+export declare function resolveMarketplaceGlbUrl(item: MarketplaceItem, roomId?: string): Promise<MarketplaceGlbResolution>;
 //# sourceMappingURL=marketplace-client.d.ts.map

package/dist/marketplace-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"marketplace-client.d.ts","sourceRoot":"","sources":["../src/marketplace-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"marketplace-client.d.ts","sourceRoot":"","sources":["../src/marketplace-client.ts"],"names":[],"mappings":"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"}

package/dist/marketplace-client.js

@@ -1,7 +1,54 @@
 import fetch from "node-fetch";
+import { getAccessKey, isAuthenticated } from "./api.js";
 const API_BASE = process.env.API_BASE || "https://portals.to";
 const CACHE_TTL_MS = 60_000;
 let catalogueCache = null;
+function getRuntimeAccessKey() {
+    if (process.env.PORTALS_ACCESS_KEY)
+        return process.env.PORTALS_ACCESS_KEY;
+    if (!isAuthenticated())
+        return null;
+    try {
+        return getAccessKey();
+    }
+    catch {
+        return null;
+    }
+}
+function authHeaders() {
+    const headers = {};
+    const token = process.env.PORTALS_USER_TOKEN;
+    const accessKey = getRuntimeAccessKey();
+    if (token)
+        headers["Authorization"] = `Bearer ${token}`;
+    if (accessKey)
+        headers["x-access-key"] = accessKey;
+    return headers;
+}
+function jsonAuthHeaders() {
+    return { "Content-Type": "application/json", ...authHeaders() };
+}
+export function isMarketplaceAssetRoute(value) {
+    if (!value)
+        return false;
+    try {
+        return new URL(value, API_BASE).pathname.startsWith("/api/v2/marketplace/asset/");
+    }
+    catch {
+        return value.startsWith("/api/v2/marketplace/asset/");
+    }
+}
+export function isRuntimeGlbUrl(value) {
+    if (!value)
+        return false;
+    if (isMarketplaceAssetRoute(value))
+        return false;
+    const trimmed = value.trim();
+    if (trimmed.startsWith("http://") || trimmed.startsWith("https://") || trimmed.startsWith("~") || trimmed.startsWith("#")) {
+        return /\.glb(?:[?#]|$)/i.test(trimmed);
+    }
+    return false;
+}
 async function fetchCatalogue() {
     if (catalogueCache && Date.now() - catalogueCache.ts < CACHE_TTL_MS) {
         return catalogueCache.items;
@@ -156,7 +203,7 @@ export async function getUserInventory() {
     if (!token)
         return [];
     const res = await fetch(`${API_BASE}/api/v2/marketplace/my-items`, {
-        headers: { Authorization: `Bearer ${token}` },
+        headers: authHeaders(),
     });
     if (!res.ok)
         return [];
@@ -171,17 +218,10 @@ export async function getUserInventory() {
  * scene with AI so we know what assets the user actually has.
  */
 export async function getRoomBuildItems(roomId) {
-    const token = process.env.PORTALS_USER_TOKEN;
-    const accessKey = process.env.PORTALS_ACCESS_KEY;
     if (!roomId)
         return [];
-    const headers = {};
-    if (token)
-        headers["Authorization"] = `Bearer ${token}`;
-    if (accessKey)
-        headers["x-access-key"] = accessKey;
     try {
-        const res = await fetch(`${API_BASE}/api/v2/room/get-build-items?roomId=${encodeURIComponent(roomId)}`, { headers });
+        const res = await fetch(`${API_BASE}/api/v2/room/get-build-items?roomId=${encodeURIComponent(roomId)}`, { headers: authHeaders() });
         if (!res.ok)
             return [];
         const json = (await res.json());
@@ -199,7 +239,7 @@ export async function getRoomBuildItems(roomId) {
  */
 export async function verifyOwnership(cids) {
     const token = process.env.PORTALS_USER_TOKEN;
-    const accessKey = process.env.PORTALS_ACCESS_KEY;
+    const accessKey = getRuntimeAccessKey();
     if (!token && !accessKey) {
         // No auth — return unknowns (the caller decides how to proceed).
         return cids.map((cid) => ({
@@ -210,9 +250,7 @@ export async function verifyOwnership(cids) {
         }));
     }
     // Pull catalogue + user inventory in parallel.
-    const headers = {};
-    if (token)
-        headers["Authorization"] = `Bearer ${token}`;
+    const headers = authHeaders();
     const [inventoryRes, catalogue] = await Promise.all([
         token ? fetch(`${API_BASE}/api/v2/marketplace/my-items`, { headers }) : Promise.resolve(null),
         fetchCatalogue(),
@@ -248,18 +286,14 @@ export async function verifyOwnership(cids) {
 }
 export async function attachItemsToRoom(roomId, itemIds) {
     const token = process.env.PORTALS_USER_TOKEN;
-    const accessKey = process.env.PORTALS_ACCESS_KEY;
+    const accessKey = getRuntimeAccessKey();
     if (!token && !accessKey) {
-        return { ok: false, code: "AUTH_REQUIRED", message: "No Firebase token or access key in env.", attachedItemIds: [] };
+        return { ok: false, code: "AUTH_REQUIRED", message: "No Firebase token, access key env, or authenticated MCP access key available.", attachedItemIds: [] };
     }
     if (!roomId) {
         return { ok: false, code: "ROOM_ID_REQUIRED", message: "roomId is required.", attachedItemIds: [] };
     }
-    const headers = { "Content-Type": "application/json" };
-    if (token)
-        headers["Authorization"] = `Bearer ${token}`;
-    if (accessKey)
-        headers["x-access-key"] = accessKey;
+    const headers = jsonAuthHeaders();
     let existing = [];
     try {
         const settingsRes = await fetch(`${API_BASE}/api/v2/room/get-settings?roomID=${encodeURIComponent(roomId)}`, { headers });
@@ -324,3 +358,69 @@ export async function claimMarketplaceItem(itemId) {
         message: body.message,
     };
 }
+function matchBuildItem(items, itemId) {
+    return items.find((item) => item.id === itemId) ?? null;
+}
+function matchInventoryItem(items, itemId) {
+    return items.find((item) => item.itemId === itemId || item.id === itemId) ?? null;
+}
+export async function resolveMarketplaceGlbUrl(item, roomId) {
+    if (isRuntimeGlbUrl(item.glb)) {
+        return {
+            glb: item.glb,
+            source: "catalog_direct",
+            attachedToRoomInventory: false,
+        };
+    }
+    const inventoryItem = matchInventoryItem(await getUserInventory(), item.id);
+    if (inventoryItem?.glb && isRuntimeGlbUrl(inventoryItem.glb)) {
+        return {
+            glb: inventoryItem.glb,
+            source: "user_inventory",
+            attachedToRoomInventory: false,
+        };
+    }
+    if (!roomId) {
+        return {
+            glb: null,
+            source: "unresolved",
+            attachedToRoomInventory: false,
+            reason: isMarketplaceAssetRoute(item.glb)
+                ? "Catalog glb is a protected marketplace asset route; pass roomId so MCP can resolve the room build-palette CDN URL."
+                : "Catalog item did not include a runtime GLB URL.",
+        };
+    }
+    let buildItems = await getRoomBuildItems(roomId);
+    let buildItem = matchBuildItem(buildItems, item.id);
+    if (buildItem?.glb && isRuntimeGlbUrl(buildItem.glb)) {
+        return {
+            glb: buildItem.glb,
+            source: "room_build_items",
+            attachedToRoomInventory: false,
+        };
+    }
+    const attachResult = await attachItemsToRoom(roomId, [item.id]);
+    if (!attachResult.ok) {
+        return {
+            glb: null,
+            source: "unresolved",
+            attachedToRoomInventory: false,
+            reason: `Could not attach marketplace item to room inventory for URL resolution (${attachResult.code}${attachResult.message ? `: ${attachResult.message}` : ""}).`,
+        };
+    }
+    buildItems = await getRoomBuildItems(roomId);
+    buildItem = matchBuildItem(buildItems, item.id);
+    if (buildItem?.glb && isRuntimeGlbUrl(buildItem.glb)) {
+        return {
+            glb: buildItem.glb,
+            source: "room_build_items",
+            attachedToRoomInventory: true,
+        };
+    }
+    return {
+        glb: null,
+        source: "unresolved",
+        attachedToRoomInventory: true,
+        reason: "Item was attached to the room inventory, but get_room_build_items did not return a runtime .glb URL for it.",
+    };
+}

package/dist/resources/index/effects.json

@@ -39,6 +39,16 @@
         "Scale in relative mode is ADDITIVE (scale [1,1,1] adds 1 to each axis per trigger)"
       ]
     },
+    {
+      "$type": "SetTransform",
+      "category": "movement",
+      "parameters": {
+        "position": "array - optional [x,y,z] world position",
+        "rotation": "array - optional [x,y,z] Euler degrees",
+        "scale": "array - optional [x,y,z] scale"
+      },
+      "gotchas": ["Immediate local-player transform write. Include at least one of position, rotation, or scale."]
+    },
     {
       "$type": "PortalsAnimation",
       "category": "movement",
@@ -76,6 +86,82 @@
       "parameters": {},
       "gotchas": []
     },
+    {
+      "$type": "AddForceToCubeEffector",
+      "category": "physics",
+      "parameters": {
+        "fx": "float - impulse X",
+        "fy": "float - impulse Y",
+        "fz": "float - impulse Z",
+        "rel": "bool - true=force vector is local to item rotation"
+      },
+      "gotchas": ["Direct task effector only; not in ReactGUI UseEffector/PrepareEffector map. Works on ResizableCube and GLB-family physics items."]
+    },
+    {
+      "$type": "AddTorqueToCubeEffector",
+      "category": "physics",
+      "parameters": {
+        "tx": "float - rotational impulse X",
+        "ty": "float - rotational impulse Y",
+        "tz": "float - rotational impulse Z",
+        "rel": "bool - true=torque vector is local to item rotation"
+      },
+      "gotchas": ["Direct task effector only; not in ReactGUI UseEffector/PrepareEffector map. Works on ResizableCube and GLB-family physics items."]
+    },
+    {
+      "$type": "ExplosionForceCubeEffector",
+      "category": "physics",
+      "parameters": {
+        "f": "float - explosion impulse force",
+        "r": "float - explosion radius",
+        "u": "float - upward modifier",
+        "ox/oy/oz": "floats - origin offset from item position",
+        "aff": "bool - true=also affect nearby physics cubes"
+      },
+      "gotchas": ["Direct task effector only; not in ReactGUI UseEffector/PrepareEffector map."]
+    },
+    {
+      "$type": "SetCubeVelocityEffector",
+      "category": "physics",
+      "parameters": {
+        "vx/vy/vz": "floats - linear velocity",
+        "ax/ay/az": "floats - angular velocity",
+        "sl": "bool - set linear velocity",
+        "sa": "bool - set angular velocity",
+        "rel": "bool - true=vectors are local to item rotation"
+      },
+      "gotchas": ["Direct task effector only. Velocity assignment is most reliable when this client already owns the physics item."]
+    },
+    {
+      "$type": "ResetCubeVelocityEffector",
+      "category": "physics",
+      "parameters": {},
+      "gotchas": ["Direct task effector only. Stops linear and angular velocity on the owned physics item."]
+    },
+    {
+      "$type": "ToggleCubeGravityEffector",
+      "category": "physics",
+      "parameters": {
+        "g": "bool - true=use gravity, false=float"
+      },
+      "gotchas": ["Direct task effector only. Ensures physics is attached before changing gravity."]
+    },
+    {
+      "$type": "AttachToMouseCubeEffector",
+      "category": "physics",
+      "parameters": {
+        "snap": "bool - true=snap item bottom to placeable surfaces"
+      },
+      "gotchas": ["JS UseEffector name is AttachToMouse, while direct room-data $type is AttachToMouseCubeEffector."]
+    },
+    {
+      "$type": "DetachFromMouseCubeEffector",
+      "category": "physics",
+      "parameters": {
+        "save": "bool - true=persist final drop position when server permissions and item opt-in allow it"
+      },
+      "gotchas": ["JS UseEffector name is DetachFromMouse, while direct room-data $type is DetachFromMouseCubeEffector."]
+    },
     {
       "$type": "AddVelocityToPlayer",
       "category": "player",
@@ -235,7 +321,8 @@
       "category": "camera",
       "parameters": {
         "camState": "string — camera state name (matches CameraObject sn)",
-        "transitionSpeed": "float — transition speed"
+        "smoothTransition": "bool — blend to the new state, default true",
+        "transitionSpeed": "float — transition speed, default 6.0"
       },
       "gotchas": []
     },

package/dist/resources/index/items.json

@@ -15,9 +15,52 @@
         "s": "bool — shadows (false=off)",
         "nav": "bool — AI nav mesh surface",
         "t": "float — texture tiling",
+        "sm": "float — material smoothness 0-1",
+        "m": "float — material metallic 0-1",
+        "p": "bool — has physics",
+        "sp": "bool — save settled physics position",
+        "pm": "bool — pushable by player",
+        "mass": "float — physics mass 0.1-50",
+        "lbl": "string — physics label for trigger-zone filtering",
         "title": "string — internal label"
       },
-      "valid_triggers": ["OnClickEvent", "OnCollideEvent", "OnCollisionStoppedEvent", "OnHoverStartEvent", "OnHoverEndEvent", "OnPlayerLoggedIn", "OnKeyPressedEvent", "OnKeyReleasedEvent", "OnPlayerDied", "OnPlayerRevived", "OnPlayerMove", "OnPlayerStoppedMoving", "OnMicrophoneUnmuted", "OnTimerStopped", "OnCountdownTimerFinished", "ScoreTrigger", "OnAnimationStoppedEvent", "OnItemClickEvent", "PlayerLeave", "SwapVolume", "OnDestroyedEvent"],
+      "valid_triggers": ["OnClickEvent", "OnDragStartEvent", "OnCollideEvent", "OnCollisionStoppedEvent", "OnHoverStartEvent", "OnHoverEndEvent", "OnPlayerLoggedIn", "OnKeyPressedEvent", "OnKeyReleasedEvent", "OnPlayerDied", "OnPlayerRevived", "OnPlayerMove", "OnPlayerStoppedMoving", "OnMicrophoneUnmuted", "OnTimerStopped", "OnCountdownTimerFinished", "ScoreTrigger", "OnAnimationStoppedEvent", "OnItemClickEvent", "PlayerLeave", "SwapVolume", "OnDestroyedEvent"],
+      "spec_uri": "docs://ref/items/cube"
+    },
+    {
+      "id": "resizable-shapes",
+      "name": "Resizable Shape Variants",
+      "prefabNames": ["ResizableSphere", "ResizableCylinder", "ResizableCone", "ResizablePyramid", "ResizableWedge", "ResizableTriangularPrism", "ResizableCapsule", "ResizableTorus"],
+      "category": "building",
+      "aliases": {
+        "Sphere": "ResizableSphere",
+        "Cylinder": "ResizableCylinder",
+        "Cone": "ResizableCone",
+        "Pyramid": "ResizablePyramid",
+        "Ramp": "ResizableWedge",
+        "Wedge": "ResizableWedge",
+        "Prism": "ResizableTriangularPrism",
+        "TriangularPrism": "ResizableTriangularPrism",
+        "Capsule": "ResizableCapsule",
+        "Ring": "ResizableTorus",
+        "Torus": "ResizableTorus"
+      },
+      "key_fields": {
+        "col": "string (6-char hex, no #) — color",
+        "contentString": "string — optional texture URL",
+        "e": "float — emission/glow 0.0-1.0+",
+        "o": "float — opacity 0.0-1.0",
+        "sm": "float — material smoothness 0-1",
+        "m": "float — material metallic 0-1",
+        "c": "bool — collider (false=pass-through)",
+        "nav": "bool — AI nav mesh surface",
+        "p": "bool — has physics",
+        "pm": "bool — pushable by player",
+        "mass": "float — physics mass 0.1-50",
+        "lbl": "string — physics label for trigger-zone filtering"
+      },
+      "notes": "ReactGUI Shapes panel variants use the same extraData schema as ResizableCube. cf is GLB-only and is invalid on these shapes.",
+      "valid_triggers": ["OnClickEvent", "OnDragStartEvent", "OnCollideEvent", "OnCollisionStoppedEvent", "OnHoverStartEvent", "OnHoverEndEvent", "OnPlayerLoggedIn", "OnKeyPressedEvent", "OnKeyReleasedEvent", "OnPlayerDied", "OnPlayerRevived", "OnPlayerMove", "OnPlayerStoppedMoving", "OnMicrophoneUnmuted", "OnTimerStopped", "OnCountdownTimerFinished", "ScoreTrigger", "OnAnimationStoppedEvent", "OnItemClickEvent", "PlayerLeave", "SwapVolume", "OnDestroyedEvent"],
       "spec_uri": "docs://ref/items/cube"
     },
     {
@@ -27,9 +70,10 @@
       "category": "building",
       "key_fields": {
         "text": "string — content with Unity rich text tags",
-        "lookAtCamera": "bool — billboard mode (default true)"
+        "lookAtCamera": "bool — billboard mode (default true)",
+        "font": "string — optional ReactGUI font identifier/name"
       },
-      "valid_triggers": ["OnClickEvent", "OnCollideEvent", "OnCollisionStoppedEvent", "OnHoverStartEvent", "OnHoverEndEvent", "OnPlayerLoggedIn", "OnKeyPressedEvent", "OnKeyReleasedEvent", "ScoreTrigger", "OnAnimationStoppedEvent", "OnPlayerDied", "OnPlayerRevived", "PlayerLeave"],
+      "valid_triggers": ["OnClickEvent", "OnDragStartEvent", "OnCollideEvent", "OnCollisionStoppedEvent", "OnHoverStartEvent", "OnHoverEndEvent", "OnPlayerLoggedIn", "OnKeyPressedEvent", "OnKeyReleasedEvent", "ScoreTrigger", "OnAnimationStoppedEvent", "OnPlayerDied", "OnPlayerRevived", "PlayerLeave"],
       "spec_uri": "docs://ref/items/text"
     },
     {
@@ -68,7 +112,12 @@
         "c": "bool — collider",
         "l": "bool — local animation (true=per-client)",
         "f": "bool — camera fade",
-        "r": "bool — remove first frame"
+        "r": "bool — remove first frame",
+        "p": "bool — has physics",
+        "pm": "bool — pushable by player",
+        "mass": "float — physics mass 0.1-50",
+        "lbl": "string — physics label for trigger-zone filtering",
+        "cf": "int — physics collider shape 0-3"
       },
       "valid_triggers": ["OnClickEvent", "OnCollideEvent", "OnCollisionStoppedEvent", "OnHoverStartEvent", "OnHoverEndEvent", "OnPlayerLoggedIn", "OnKeyPressedEvent", "OnKeyReleasedEvent", "ScoreTrigger", "OnAnimationStoppedEvent", "OnPlayerDied", "OnPlayerRevived", "PlayerLeave"],
       "spec_uri": "docs://ref/items/glb"
@@ -118,8 +167,8 @@
         "cm": "string — custom press message",
         "opacity": "float — editor opacity"
       },
-      "valid_triggers": ["OnEnterEvent", "OnExitEvent", "OnKeyPressedEvent", "OnKeyReleasedEvent", "OnPlayerLoggedIn", "ScoreTrigger", "OnTimerStopped", "OnCountdownTimerFinished", "OnAnimationStoppedEvent", "OnPlayerDied", "OnPlayerRevived", "PlayerLeave"],
-      "notes": "Invisible during play. NEVER use OnClickEvent/OnHoverStart/OnHoverEnd on triggers. pressBtn:true gates OnEnterEvent until keyCode is pressed while inside; it is not global OnKeyPressedEvent.",
+      "valid_triggers": ["OnEnterEvent", "OnExitEvent", "OnPhysicsItemEnterEvent", "OnPhysicsItemExitEvent", "OnKeyPressedEvent", "OnKeyReleasedEvent", "OnPlayerLoggedIn", "ScoreTrigger", "OnTimerStopped", "OnCountdownTimerFinished", "OnAnimationStoppedEvent", "OnPlayerDied", "OnPlayerRevived", "PlayerLeave"],
+      "notes": "Invisible during play. NEVER use OnClickEvent/OnHoverStart/OnHoverEnd on triggers. pressBtn:true gates OnEnterEvent until keyCode is pressed while inside; it is not global OnKeyPressedEvent. Physics item enter/exit only detects physics items with p:true/CubePhysicsSync, optionally filtered by lbl/label.",
       "spec_uri": "docs://ref/items/trigger-zone"
     },
     {
@@ -173,7 +222,9 @@
       "category": "gameplay",
       "key_fields": {
         "fov": "float — field of view degrees",
-        "sn": "string — state name (must match customCameraStates)"
+        "sn": "string — unique CameraObject state name for ChangeCamState",
+        "aP": "bool — Look At Player",
+        "renderRateFollow": "bool — active camera copies this CameraObject every render frame"
       },
       "valid_triggers": [],
       "notes": "Place at desired camera viewpoint. Use ChangeCamState effect to activate.",
@@ -385,7 +436,7 @@
       "prefabName": "Addressable",
       "category": "effects",
       "key_fields": {},
-      "notes": "contentString=FurnitureAddressables/{EffectName}. No special extraData. Toggle with Show/HideObjectEvent.",
+      "notes": "contentString=FurnitureAddressables/{EffectName}. Set c:false to avoid blocking movement. ReactGUI catalog includes fire, explosions, lightning, sparks, smoke, weather, water, trails, and hit impacts. Toggle with Show/HideObjectEvent.",
       "valid_triggers": ["OnPlayerLoggedIn", "OnClickEvent", "OnCollideEvent"],
       "spec_uri": "docs://ref/items/effects-vfx"
     }

package/dist/resources/index/knowledge-map.json

@@ -224,6 +224,12 @@
                 "description": "Quick reference for MCP tool calls and room JSON structure",
                 "uri": "docs://reference/api-cheatsheet"
               },
+              {
+                "id": "logic.guides.reactgui-feature-test-room",
+                "label": "ReactGUI Feature Test Room",
+                "description": "Checklist, generator, and validation notes for ReactGUI/Core feature coverage in room data",
+                "uri": "docs://reference/reactgui-feature-test-room"
+              },
               {
                 "id": "logic.guides.sandbox-environment",
                 "label": "JS Sandbox Environment",

package/dist/resources/index/triggers.json

@@ -8,6 +8,16 @@
       "applicable_items": "any",
       "gotchas": ["Requires VISIBLE item — NEVER use on Trigger cubes (invisible)"]
     },
+    {
+      "$type": "OnDragStartEvent",
+      "description": "Build/edit drag starts on this item",
+      "applicable_items": "any",
+      "params": {
+        "adminOnly": "optional bool; true restricts to admins/builders",
+        "dis": "optional distance in meters; 0 or omitted means unlimited"
+      },
+      "gotchas": ["This is a creator/build interaction trigger, not a runtime physics collision trigger."]
+    },
     {
       "$type": "OnEnterEvent",
       "description": "Player enters trigger zone. If the Trigger item has pressBtn:true, this fires only after the player enters and presses the Trigger keyCode.",
@@ -20,6 +30,24 @@
       "applicable_items": ["Trigger"],
       "gotchas": ["ONLY works on Trigger cubes, not ResizableCubes or GLBs"]
     },
+    {
+      "$type": "OnPhysicsItemEnterEvent",
+      "description": "Physics-enabled item enters a trigger zone, optionally filtered by physics label",
+      "applicable_items": ["Trigger"],
+      "params": {
+        "label": "optional string; empty or omitted matches any physics item"
+      },
+      "gotchas": ["ONLY works on Trigger cubes", "The entering item needs physics p:true and a CubePhysicsSync body", "Held/build-mode items are ignored by Core's physics trigger detector"]
+    },
+    {
+      "$type": "OnPhysicsItemExitEvent",
+      "description": "Physics-enabled item exits a trigger zone, optionally filtered by physics label",
+      "applicable_items": ["Trigger"],
+      "params": {
+        "label": "optional string; empty or omitted matches any physics item"
+      },
+      "gotchas": ["ONLY works on Trigger cubes", "The exiting item needs physics p:true and a CubePhysicsSync body", "Held/build-mode items are ignored by Core's physics trigger detector"]
+    },
     {
       "$type": "OnCollideEvent",
       "description": "Player collides with item",

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

@@ -38,18 +38,23 @@ FunctionEffectorJS runs JavaScript code inside the Portals engine. It is more po
 | `S` | bool | Conditional | **Activate on Start.** REQUIRED when trigger is `OnPlayerLoggedIn`. Without it, the JS silently never fires on login. |
 | `R` | bool | Optional | **Trigger on Tasks Change.** Auto-re-fires the JS whenever any referenced variable or task changes. Use for reactive watchers. |
 
-## Reading Variables
+## Reading Values
 
-Use `$N{}` to read **all** variable types (numeric and string):
+Use `$N{}` to read variables, player data, and timer-like values:
 
 ```javascript
 var score = $N{score};
 var team = $N{teamname};
 ```
 
-**`$N{}` is the only way to read variables in JS.** There is no `$S{}` syntax.
+`FunctionEffectorJS` in the current ReactGUI branch also rewrites task-state macros before evaluation:
 
-**`$T{}` and `$TN{}` for quest state were NOT verified working in JS** (B002/B003). They are listed in some older docs but live testing produced no usable value. To read quest state from JS, write a mirror numeric/string variable from the same task or effector that writes the quest state, and read the mirror with `$N{...}`. `SetTask(...)` to write quest state IS verified (B003 — use the bare task suffix, not the `0_…` numbered name).
+```javascript
+var stateName = $T{intro};   // "NotActive", "Active", "Completed", or "Undefined"
+var stateCode = $TN{intro};  // 0, 1, 2, or -1
+```
+
+`$N{}` is still the preferred read path for ordinary numeric/string variables. There is no `$S{}` syntax.
 
 ## Writing Variables
 
@@ -83,6 +88,10 @@ var alive = CountArray(SelectPlayers({{Players}}, 'alive', 'true'));
 // Assign sequential numbers
 AssignNumbersInOrder({{Players}}, 'playernum');
 
+// Set/read a parameter for the local player
+SetPlayerParameter('ready', 'true');
+var localReady = SelectPlayerParameter('ready');
+
 // Chain operations with +
 SetPlayersParameters({{Players}}, 'team', 'blue') + SetPlayersParameters(SelectRandomPlayers({{Players}}, 3), 'team', 'red');
 
@@ -99,12 +108,13 @@ See `docs://logic/multiplayer` for full reference on opTypes, variable scopes, a
 
 ## Calling Effects from JS
 
-Use `UseEffector()` to trigger any Portals effect. See `docs://logic/js-use-effector` for the full effect catalog.
+Use `UseEffector()` to trigger any Portals effect exposed by Core's `EffectorsLists`. Use `PrepareEffector()` with the same arguments to create/cache the temporary effector without activating it yet. See `docs://logic/js-use-effector` for the full effect catalog.
 
 ```javascript
 UseEffector({{Object}}, 'HideObject');
 UseEffector('760', 'ShowObject');
 UseEffector({{Object}}, 'MoveToSpot', '{"transformState":{"position":[0,5,0],"rotation":[0,0,0,1],"scale":[1,1,1],"duration":2.0},"relative":true}');
+PrepareEffector({{Object}}, 'SetTransform', '{"scale":[2,2,2]}', 'grow');
 ```
 
 **Targets:** `{{Object}}`, `{{Parent}}`, `{{Child}}` are unquoted template tokens. String IDs like `'760'` are quoted.
@@ -153,7 +163,7 @@ In FunctionEffectorJS, use `return;` to exit early. Do not use the NCalc pattern
 "V": "if (Number($N{done}) == 1.0) { return; } SetVariable('counter', $N{counter} + 1.0, 0.0);"
 ```
 
-Use a mirror variable like `done` for quest/task state checks in JS. `$T{}` / `$TN{}` task reads were not verified working in B002/B003.
+For quest/task state checks, the current ReactGUI JS bridge rewrites `$T{task}` to a state name and `$TN{task}` to a numeric state code. Use mirror variables only when you need custom derived state.
 
 ### 6. Reserved-keyword caveats
 Some older docs warn that `from` causes a silent parse error. Live testing (B002) showed `var from = 6.0;` worked on the current build, so the warning is unreliable as a strict rule. Still — prefer non-keyword names (`source`, `origin`, `start`) so the code is robust across engine versions.