portals-mcp 1.3.0-beta.0 → 1.3.0

package/dist/resources/index/effects.json

@@ -1,699 +1,703 @@
-{
-  "version": "0.1.0",
-  "description": "Compact lookup of all Portals effects. Wrap in TaskEffectorSubscription (quest-driven) or DirectEffector (basic interaction).",
-  "effects": [
-    {
-      "$type": "ShowObjectEvent",
-      "category": "visibility",
-      "parameters": {},
-      "gotchas": []
-    },
-    {
-      "$type": "HideObjectEvent",
-      "category": "visibility",
-      "parameters": {},
-      "gotchas": ["Hidden items lose collider too — players pass through them"]
-    },
-    {
-      "$type": "ShowOutline",
-      "category": "visibility",
-      "parameters": {},
-      "gotchas": []
-    },
-    {
-      "$type": "HideOutline",
-      "category": "visibility",
-      "parameters": {},
-      "gotchas": []
-    },
-    {
-      "$type": "MoveToSpot",
-      "category": "movement",
-      "parameters": {
-        "_transformState": "object — {position:[x,y,z], rotation:[qx,qy,qz,qw], scale:[x,y,z], duration:float}",
-        "relative": "bool — false(default)=absolute world coords, true=offset from current transform"
-      },
-      "gotchas": [
-        "All values ABSOLUTE by default — position is world coords, not offset",
-        "relative:true makes values accumulate per trigger (3 clicks = 3x offset)",
-        "Scale in relative mode is ADDITIVE (scale [1,1,1] adds 1 to each axis per trigger)"
-      ]
-    },
-    {
-      "$type": "PortalsAnimation",
-      "category": "movement",
-      "parameters": {
-        "_transformStates": "array — [{position, rotation, scale},...] quaternion-based keyframes",
-        "states": "array — [{x,y,z,rx,sx,sy,sz,duration},...] euler-based keyframes with timing",
-        "stateEvents": "array — MUST be flat [] for basic animations. NOT a parallel array — never use [[], []] matching keyframe count, as this silently breaks the animation",
-        "loopAnimation": "bool — loop continuously",
-        "seamless": "bool — smooth loop transition",
-        "fixedUpdate": "bool — optimize for collision detection"
-      },
-      "gotchas": [
-        "_transformStates and states arrays must have same length and describe same positions",
-        "Does NOT support relative mode — always absolute",
-        "Each keyframe in states has its own duration",
-        "stateEvents must be a flat array [] for basic animations — do NOT create a parallel array like [[], []] matching the keyframe count, as this silently breaks the animation"
-      ]
-    },
-    {
-      "$type": "DuplicateItem",
-      "category": "movement",
-      "parameters": {
-        "TS": "object — {position:[x,y,z], rotation:[qx,qy,qz,qw], scale:[x,y,z]}",
-        "destroyAfterTime": "float — seconds before auto-destroy (0=permanent)"
-      },
-      "gotchas": ["Uses 'TS' not '_transformState' for transform"]
-    },
-    {
-      "$type": "MoveItemToPlayer",
-      "category": "movement",
-      "parameters": {},
-      "gotchas": []
-    },
-    {
-      "$type": "AddVelocityToPlayer",
-      "category": "player",
-      "parameters": {
-        "vel": "array — [x,y,z] velocity vector",
-        "local": "bool — true=relative to player facing, false=world"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "TeleportEvent",
-      "category": "player",
-      "parameters": {
-        "id": "string — destination room ID",
-        "sn": "string — spawn name",
-        "sr": "float — spawn radius (meters). Random scatter distance from spawn point. NOT rotation. Default 0. Typically 0–5."
-      },
-      "gotchas": ["sr is spawn RADIUS in meters (random scatter distance), NOT rotation in degrees. Values like 90 or 180 will scatter players 90–180m away. Use 0 for exact spawn placement, or 1–5 for small spread."]
-    },
-    {
-      "$type": "ChangePlayerHealth",
-      "category": "player",
-      "parameters": {
-        "healthChange": "int — amount to heal/damage",
-        "op": "int — omit=heal, 2=damage"
-      },
-      "gotchas": ["Omit 'op' for healing. Set op:2 for damage."]
-    },
-    {
-      "$type": "DamageOverTime",
-      "category": "player",
-      "parameters": {},
-      "gotchas": ["Continuous damage on contact — use with trigger zones"]
-    },
-    {
-      "$type": "LockMovement",
-      "category": "player",
-      "parameters": {},
-      "gotchas": []
-    },
-    {
-      "$type": "UnlockMovement",
-      "category": "player",
-      "parameters": {},
-      "gotchas": []
-    },
-    {
-      "$type": "StartAutoRun",
-      "category": "player",
-      "parameters": {},
-      "gotchas": []
-    },
-    {
-      "$type": "StopAutoRun",
-      "category": "player",
-      "parameters": {},
-      "gotchas": []
-    },
-    {
-      "$type": "PlayerEmote",
-      "category": "player",
-      "parameters": {
-        "animationName": "string — Sitting, Can Can, Wave, Salute, Jive, Salsa, Shuffling, Chicken, Slide n Jive, Robot"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "MutePlayer",
-      "category": "player",
-      "parameters": {},
-      "gotchas": []
-    },
-    {
-      "$type": "HideAllPlayersEvent",
-      "category": "player",
-      "parameters": {},
-      "gotchas": []
-    },
-    {
-      "$type": "LockAvatarChange",
-      "category": "player",
-      "parameters": {},
-      "gotchas": []
-    },
-    {
-      "$type": "UnlockAvatarChange",
-      "category": "player",
-      "parameters": {},
-      "gotchas": []
-    },
-    {
-      "$type": "DisplayAvatarScreen",
-      "category": "player",
-      "parameters": {},
-      "gotchas": []
-    },
-    {
-      "$type": "ChangeAvatarEffector",
-      "category": "player",
-      "parameters": {
-        "Url": "string — GLB model URL",
-        "Persistent": "bool — persist across sessions"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "ChangeMovementProfile",
-      "category": "player",
-      "parameters": {
-        "mvmtProfile": "string — movement profile name"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "ChangeRoundyWearableEffector",
-      "category": "player",
-      "parameters": {
-        "ItemID": "string — wearable item ID"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "LockCamera",
-      "category": "camera",
-      "parameters": {},
-      "gotchas": []
-    },
-    {
-      "$type": "UnlockCamera",
-      "category": "camera",
-      "parameters": {},
-      "gotchas": []
-    },
-    {
-      "$type": "ChangeCameraZoom",
-      "category": "camera",
-      "parameters": {
-        "zoomAmount": "float — zoom level",
-        "lockZoom": "bool — prevent player zoom adjustment"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "ToggleFreeCam",
-      "category": "camera",
-      "parameters": {
-        "enterFreeCam": "bool (optional) — true=enter, false=exit. Omit all params to toggle.",
-        "x": "float (optional) — camera X position",
-        "y": "float (optional) — camera Y position",
-        "z": "float (optional) — camera Z position",
-        "lookAtPlayer": "bool (optional) — camera looks at player"
-      },
-      "gotchas": ["No params = toggle. With params = explicit control with optional position and orientation."]
-    },
-    {
-      "$type": "ChangeCamState",
-      "category": "camera",
-      "parameters": {
-        "camState": "string — camera state name (matches CameraObject sn)",
-        "transitionSpeed": "float — transition speed"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "SetCameraFilter",
-      "category": "camera",
-      "parameters": {
-        "url": "string — image overlay URL",
-        "alpha": "float — overlay opacity"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "ToggleLockCursor",
-      "category": "camera",
-      "parameters": {
-        "lockCursor": "bool (optional) — true=lock, false=unlock. Omit to toggle."
-      },
-      "gotchas": ["No params = toggle. With lockCursor = explicit lock/unlock."]
-    },
-    {
-      "$type": "NotificationPillEvent",
-      "category": "ui",
-      "parameters": {
-        "nt": "string — notification text",
-        "c": "string — hex color",
-        "hideBackground": "bool — transparent background"
-      },
-      "gotchas": ["Supports |varName| pipe syntax for inline variable display"]
-    },
-    {
-      "$type": "DisplayValueEvent",
-      "category": "values",
-      "parameters": {
-        "label": "string — variable name to display",
-        "color": "string — hex color"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "HideValueEvent",
-      "category": "values",
-      "parameters": {
-        "label": "string — variable name to hide"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "UpdateScoreEvent",
-      "category": "values",
-      "parameters": {
-        "scoreChange": "float — value to apply",
-        "op": "int — omit=set, 1=add, 2=sub, 3=mul, 4=div"
-      },
-      "gotchas": ["Omit 'op' entirely to SET the value. Include op for math operations."]
-    },
-    {
-      "$type": "UpdateScoreEventString",
-      "category": "values",
-      "parameters": {
-        "targetText": "string — text value to set",
-        "label": "string — variable name"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "FunctionEffector",
-      "category": "logic",
-      "parameters": {
-        "V": "string — NCalc expression"
-      },
-      "gotchas": [
-        "Task names OMIT numbered prefix: quest Name='0_redteam' but NCalc uses 'redteam'",
-        "All numeric values MUST use decimals (0.0 not 0)",
-        "Strings use single quotes ('Active' not \"Active\")"
-      ]
-    },
-    {
-      "$type": "RunTriggersFromEffector",
-      "category": "logic",
-      "parameters": {
-        "linkedTasks": "array — [{Trigger:{}, Id, TargetState, Name, TaskTriggerId},...] state changes to fire",
-        "useRandom": "bool — randomly pick one linkedTask instead of firing all"
-      },
-      "gotchas": [
-        "TargetState uses encoded values: 101=any>NotActive, 151=any>Active, 141=any>Completed, 111=NotActive>Active, 121=Active>Completed, 171=Completed>NotActive",
-        "Trigger:{} = immediate. Trigger:{Delay:1.0} = delay in seconds"
-      ]
-    },
-    {
-      "$type": "ResetAllTasks",
-      "category": "logic",
-      "parameters": {},
-      "gotchas": []
-    },
-    {
-      "$type": "StartTimerEffect",
-      "category": "timers",
-      "parameters": {
-        "tn": "string — timer name",
-        "ci": "string — custom identifier (usually empty)",
-        "showTimerUI": "bool — display timer on screen"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "StopTimerEffect",
-      "category": "timers",
-      "parameters": {
-        "tn": "string — timer name",
-        "ci": "string — custom identifier (usually empty)"
-      },
-      "gotchas": ["Fires OnTimerStopped trigger"]
-    },
-    {
-      "$type": "CancelTimerEffect",
-      "category": "timers",
-      "parameters": {
-        "tn": "string — timer name"
-      },
-      "gotchas": ["Does NOT fire OnTimerStopped — cancels silently"]
-    },
-    {
-      "$type": "PostScoreToLeaderboard",
-      "category": "leaderboard",
-      "parameters": {
-        "label": "string — variable name to post"
-      },
-      "gotchas": ["Only for numeric values, not timers directly"]
-    },
-    {
-      "$type": "ClearLeaderboard",
-      "category": "leaderboard",
-      "parameters": {
-        "label": "string — leaderboard name"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "OpenLeaderboardEffect",
-      "category": "leaderboard",
-      "parameters": {
-        "lb": "string — leaderboard name"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "PlaySoundOnce",
-      "category": "audio",
-      "parameters": {
-        "Url": "string — MP3 URL (capital U!)",
-        "Dist": "float — audible distance (capital D!)"
-      },
-      "gotchas": ["Field names use CAPITAL 'Url' and 'Dist' — not lowercase"]
-    },
-    {
-      "$type": "PlaySoundInALoop",
-      "category": "audio",
-      "parameters": {
-        "Url": "string — MP3 URL (capital U!)",
-        "Dist": "float — audible distance (-1=global, capital D!)",
-        "Preload": "bool — preload audio"
-      },
-      "gotchas": ["Field names use CAPITAL 'Url' and 'Dist' — not lowercase"]
-    },
-    {
-      "$type": "StopSound",
-      "category": "audio",
-      "parameters": {
-        "url": "string — MP3 URL (lowercase u!)",
-        "fadeOut": "float — fade out duration seconds"
-      },
-      "gotchas": ["Uses LOWERCASE 'url' — opposite of PlaySoundOnce/PlaySoundInALoop"]
-    },
-    {
-      "$type": "ChangeAudiusEffect",
-      "category": "audio",
-      "parameters": {
-        "ap": "string — Audius playlist name"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "ChangeBloom",
-      "category": "environment",
-      "parameters": {
-        "Intensity": "float — bloom intensity",
-        "Clamp": "float — bloom clamp",
-        "Diffusion": "float — bloom diffusion"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "ChangeTimeOfDay",
-      "category": "environment",
-      "parameters": {},
-      "gotchas": []
-    },
-    {
-      "$type": "RotateSkybox",
-      "category": "environment",
-      "parameters": {
-        "rotation": "float — degrees",
-        "duration": "float — seconds"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "ChangeFog",
-      "category": "environment",
-      "parameters": {
-        "color": "string — hex color",
-        "distance": "float — fog distance"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "SendMessageToIframes",
-      "category": "communication",
-      "parameters": {
-        "iframeMsg": "string — message text"
-      },
-      "gotchas": ["Supports |variable| interpolation (|username|, |position|, player vars). Legacy — prefer native displayHtml() for new custom UI (docs://logic/js-display-html)."]
-    },
-    {
-      "$type": "ChangeVoiceGroup",
-      "category": "communication",
-      "parameters": {
-        "group": "string — voice group name"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "IframeEvent",
-      "category": "communication",
-      "parameters": {
-        "url": "string — iframe URL (supports ?maximized=true, ?noCloseBtn=true)"
-      },
-      "gotchas": ["Legacy — prefer native displayHtml() for custom UI/HUDs (docs://logic/js-display-html)"]
-    },
-    {
-      "$type": "IframeStopEvent",
-      "category": "communication",
-      "parameters": {
-        "iframeUrl": "string — URL must match the opened iframe"
-      },
-      "gotchas": ["URL must exactly match the IframeEvent url to close it. Legacy — prefer native displayHtml() for custom UI/HUDs (docs://logic/js-display-html)"]
-    },
-    {
-      "$type": "NPCMessageEvent",
-      "category": "npc",
-      "parameters": {
-        "n": "string — NPC name",
-        "m": "string — message text",
-        "r": "bool"
-      },
-      "gotchas": ["GLBNPC only"]
-    },
-    {
-      "$type": "WalkNpcToSpot",
-      "category": "npc",
-      "parameters": {
-        "walkSpeed": "float — walk speed",
-        "endPosition": "array — [x,y,z] destination",
-        "endRotation": "array — [qx,qy,qz,qw] final rotation"
-      },
-      "gotchas": ["GLBNPC only. endPosition/endRotation are arrays, not objects."]
-    },
-    {
-      "$type": "NpcAnimation",
-      "category": "npc",
-      "parameters": {
-        "animationName": "string — Sitting, Can Can, Wave, Salute, Jive, Salsa, Shuffling, Chicken, Slide n Jive, Robot"
-      },
-      "gotchas": ["GLBNPC only"]
-    },
-    {
-      "$type": "NpcCopyPlayerPath",
-      "category": "npc",
-      "parameters": {
-        "positions": "array — [[x,y,z],...] world-space waypoints, one per recorded sample",
-        "rotations": "array — [[qx,qy,qz,qw],...] quaternion rotation at each point, same length as positions",
-        "animatorParameterDatas": "array — movement animation state per point. Each entry: {g: bool (grounded), s: bool (sprint, omit if false), o: string ('0.0'=idle, '1.0'=moving), m: string ('0.0'=idle, '0.5'=walk, '1.0'=jog, '1.5'=sprint), d/a/v/i/r: string (typically '0.0')}",
-        "shouldLoop": "bool — true=loop continuously, omit/false=play once"
-      },
-      "gotchas": ["GLBNPC only", "All three arrays (positions, rotations, animatorParameterDatas) must be the same length", "Sprint requires both s:true AND m:'1.5'"]
-    },
-    {
-      "$type": "NpcCopyPlayerPathStop",
-      "category": "npc",
-      "parameters": {
-        "RP": "bool — true=reset to original position"
-      },
-      "gotchas": ["GLBNPC only"]
-    },
-    {
-      "$type": "TurnToPlayer",
-      "category": "npc",
-      "parameters": {},
-      "gotchas": ["GLBNPC only"]
-    },
-    {
-      "$type": "StartSpeaking",
-      "category": "npc",
-      "parameters": {},
-      "gotchas": ["GLBNPC only"]
-    },
-    {
-      "$type": "StopSpeaking",
-      "category": "npc",
-      "parameters": {},
-      "gotchas": ["GLBNPC only"]
-    },
-    {
-      "$type": "EquipGunEffect",
-      "category": "gun",
-      "parameters": {},
-      "gotchas": ["Gun/Shotgun only"]
-    },
-    {
-      "$type": "TossGunEffect",
-      "category": "gun",
-      "parameters": {},
-      "gotchas": ["Gun/Shotgun only"]
-    },
-    {
-      "$type": "ResetGunEffect",
-      "category": "gun",
-      "parameters": {},
-      "gotchas": ["Gun/Shotgun only"]
-    },
-    {
-      "$type": "ReviveEnemy",
-      "category": "enemy",
-      "parameters": {},
-      "gotchas": ["EnemyNPC only"]
-    },
-    {
-      "$type": "ResetEnemy",
-      "category": "enemy",
-      "parameters": {},
-      "gotchas": ["EnemyNPC only — resets to full health at origin"]
-    },
-    {
-      "$type": "AttackPlayer",
-      "category": "enemy",
-      "parameters": {},
-      "gotchas": ["EnemyNPC only — forces attack on nearest player"]
-    },
-    {
-      "$type": "ChangeEnemyHealth",
-      "category": "enemy",
-      "parameters": {
-        "op": "int — 1=add, 2=subtract",
-        "healthChange": "int — HP amount"
-      },
-      "gotchas": ["EnemyNPC only"]
-    },
-    {
-      "$type": "DuplicateEnemy",
-      "category": "enemy",
-      "parameters": {
-        "spawnName": "string — SpawnPoint name",
-        "count": "int — number of copies",
-        "randomRadius": "float — spawn spread radius"
-      },
-      "gotchas": ["EnemyNPC only — spawns at named SpawnPoint"]
-    },
-    {
-      "$type": "EnterVehicle",
-      "category": "vehicle",
-      "parameters": {},
-      "gotchas": ["Vehicle only"]
-    },
-    {
-      "$type": "ExitVehicle",
-      "category": "vehicle",
-      "parameters": {},
-      "gotchas": ["Vehicle only"]
-    },
-    {
-      "$type": "VehicleBoost",
-      "category": "vehicle",
-      "parameters": {
-        "duration": "float — boost duration seconds",
-        "speedOfBoost": "float — boost speed",
-        "rampUpTime": "float — ramp up seconds",
-        "rampDownTime": "float — ramp down seconds"
-      },
-      "gotchas": ["Vehicle only"]
-    },
-    {
-      "$type": "ActivateTriggerZoneEffect",
-      "category": "trigger-zone",
-      "parameters": {},
-      "gotchas": ["Trigger only — re-enables a deactivated zone"]
-    },
-    {
-      "$type": "DeactivateTriggerZoneEffect",
-      "category": "trigger-zone",
-      "parameters": {},
-      "gotchas": ["Trigger only"]
-    },
-    {
-      "$type": "RespawnDestructible",
-      "category": "destructible",
-      "parameters": {},
-      "gotchas": ["Destructible only"]
-    },
-    {
-      "$type": "PlayAnimationOnce",
-      "category": "glb-animation",
-      "parameters": {
-        "speed": "float — playback speed (negative=reverse)"
-      },
-      "gotchas": ["Plays embedded GLB animation once"]
-    },
-    {
-      "$type": "StopAnimationEvt",
-      "category": "glb-animation",
-      "parameters": {
-        "stop": "float — normalized time 0.0(start) to 1.0(end)"
-      },
-      "gotchas": ["Freezes GLB animation at specified frame. Common pattern: OnPlayerLoggedIn > stop:0.0 to freeze, then PlayAnimationOnce on trigger."]
-    },
-    {
-      "$type": "DisplaySellSwap",
-      "category": "other",
-      "parameters": {
-        "id": "string — swap config ID",
-        "typ": "int — swap type"
-      },
-      "gotchas": []
-    },
-    {
-      "$type": "HideSellSwap",
-      "category": "other",
-      "parameters": {},
-      "gotchas": []
-    },
-    {
-      "$type": "DialogEffectorDisplay",
-      "category": "other",
-      "parameters": {
-        "tasksN": "array — [{N: '-0_task_name'},...] ordered task refs",
-        "GN": "string — character name",
-        "S": "string — story UUID prefixed with _",
-        "Audio": "bool — enable audio",
-        "HF": "bool — hide on finish",
-        "R": "bool — allow repeat",
-        "DV": "string — voice ID (empty=no TTS)",
-        "GB": "string — goodbye action ('leave'=close)",
-        "Story": "string — same as S",
-        "tasksSorM": "object — {taskName: {completed: quest, inProgress: quest},...}"
-      },
-      "gotchas": ["Most complex effect — embeds inline quest entries per dialogue node. See docs://reference/interactions for full schema."]
-    },
-    {
-      "$type": "RefreshUserInventory",
-      "category": "other",
-      "parameters": {},
-      "gotchas": []
-    }
-  ]
-}
+{
+  "version": "0.1.0",
+  "description": "Compact lookup of all Portals effects. Wrap in TaskEffectorSubscription (quest-driven) or DirectEffector (basic interaction).",
+  "effects": [
+    {
+      "$type": "ShowObjectEvent",
+      "category": "visibility",
+      "parameters": {},
+      "gotchas": []
+    },
+    {
+      "$type": "HideObjectEvent",
+      "category": "visibility",
+      "parameters": {},
+      "gotchas": ["Hidden items lose collider too — players pass through them"]
+    },
+    {
+      "$type": "ShowOutline",
+      "category": "visibility",
+      "parameters": {},
+      "gotchas": []
+    },
+    {
+      "$type": "HideOutline",
+      "category": "visibility",
+      "parameters": {},
+      "gotchas": []
+    },
+    {
+      "$type": "MoveToSpot",
+      "category": "movement",
+      "parameters": {
+        "_transformState": "object — {position:[x,y,z], rotation:[qx,qy,qz,qw], scale:[x,y,z], duration:float}",
+        "relative": "bool — false(default)=absolute world coords, true=offset from current transform"
+      },
+      "gotchas": [
+        "All values ABSOLUTE by default — position is world coords, not offset",
+        "relative:true makes values accumulate per trigger (3 clicks = 3x offset)",
+        "Scale in relative mode is ADDITIVE (scale [1,1,1] adds 1 to each axis per trigger)"
+      ]
+    },
+    {
+      "$type": "PortalsAnimation",
+      "category": "movement",
+      "parameters": {
+        "_transformStates": "array — [{position:[x,y,z], rotation:[qx,qy,qz,qw], scale:[x,y,z]},...] quaternion-based keyframes. Drives POSITION and SCALE only; the rotation quaternion is not animated at runtime.",
+        "states": "array — [{x,y,z,rx,ry,rz,sx,sy,sz,duration},...] euler-based keyframes. DRIVES ROTATION via rx/ry/rz (degrees per axis) and provides per-keyframe duration in seconds.",
+        "stateEvents": "array — MUST be flat [] for basic animations. NOT a parallel array — never use [[], []] matching keyframe count, as this silently breaks the animation",
+        "loopAnimation": "bool — loop continuously",
+        "seamless": "bool — smooth loop transition",
+        "fixedUpdate": "bool — optimize for collision detection"
+      },
+      "gotchas": [
+        "_transformStates and states arrays must have same length",
+        "Rotation comes from states[].rx/ry/rz (Euler degrees), NOT from _transformStates[].rotation (the quaternion is not animated at runtime). Include rx/ry/rz on every states entry, even when 0.",
+        "Multi-turn rotation REQUIRES Euler. Quaternions are modulo 360° — to spin through several full turns, keep rx/ry/rz monotonically increasing across keyframes (e.g. 0, 360, 720, 1080).",
+        "First keyframe IS the starting pose — the animation snaps to it on trigger. For a smooth start, make the first keyframe a near-zero-duration copy of the item's current transform.",
+        "Children of a rotating parent need a local rotation matching their angular offset around the rotation axis, otherwise their faces don't follow as the parent spins.",
+        "Does NOT support relative mode — always absolute",
+        "Each keyframe in states has its own duration",
+        "stateEvents must be a flat array [] for basic animations — do NOT create a parallel array like [[], []] matching the keyframe count, as this silently breaks the animation"
+      ]
+    },
+    {
+      "$type": "DuplicateItem",
+      "category": "movement",
+      "parameters": {
+        "TS": "object — {position:[x,y,z], rotation:[qx,qy,qz,qw], scale:[x,y,z]}",
+        "destroyAfterTime": "float — seconds before auto-destroy (0=permanent)"
+      },
+      "gotchas": ["Uses 'TS' not '_transformState' for transform"]
+    },
+    {
+      "$type": "MoveItemToPlayer",
+      "category": "movement",
+      "parameters": {},
+      "gotchas": []
+    },
+    {
+      "$type": "AddVelocityToPlayer",
+      "category": "player",
+      "parameters": {
+        "vel": "array — [x,y,z] velocity vector",
+        "local": "bool — true=relative to player facing, false=world"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "TeleportEvent",
+      "category": "player",
+      "parameters": {
+        "id": "string — destination room ID",
+        "sn": "string — spawn name",
+        "sr": "float — spawn radius (meters). Random scatter distance from spawn point. NOT rotation. Default 0. Typically 0–5."
+      },
+      "gotchas": ["sr is spawn RADIUS in meters (random scatter distance), NOT rotation in degrees. Values like 90 or 180 will scatter players 90–180m away. Use 0 for exact spawn placement, or 1–5 for small spread."]
+    },
+    {
+      "$type": "ChangePlayerHealth",
+      "category": "player",
+      "parameters": {
+        "healthChange": "int — amount to heal/damage",
+        "op": "int — omit=heal, 2=damage"
+      },
+      "gotchas": ["Omit 'op' for healing. Set op:2 for damage."]
+    },
+    {
+      "$type": "DamageOverTime",
+      "category": "player",
+      "parameters": {},
+      "gotchas": ["Continuous damage on contact — use with trigger zones"]
+    },
+    {
+      "$type": "LockMovement",
+      "category": "player",
+      "parameters": {},
+      "gotchas": []
+    },
+    {
+      "$type": "UnlockMovement",
+      "category": "player",
+      "parameters": {},
+      "gotchas": []
+    },
+    {
+      "$type": "StartAutoRun",
+      "category": "player",
+      "parameters": {},
+      "gotchas": []
+    },
+    {
+      "$type": "StopAutoRun",
+      "category": "player",
+      "parameters": {},
+      "gotchas": []
+    },
+    {
+      "$type": "PlayerEmote",
+      "category": "player",
+      "parameters": {
+        "animationName": "string — Sitting, Can Can, Wave, Salute, Jive, Salsa, Shuffling, Chicken, Slide n Jive, Robot"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "MutePlayer",
+      "category": "player",
+      "parameters": {},
+      "gotchas": []
+    },
+    {
+      "$type": "HideAllPlayersEvent",
+      "category": "player",
+      "parameters": {},
+      "gotchas": []
+    },
+    {
+      "$type": "LockAvatarChange",
+      "category": "player",
+      "parameters": {},
+      "gotchas": []
+    },
+    {
+      "$type": "UnlockAvatarChange",
+      "category": "player",
+      "parameters": {},
+      "gotchas": []
+    },
+    {
+      "$type": "DisplayAvatarScreen",
+      "category": "player",
+      "parameters": {},
+      "gotchas": []
+    },
+    {
+      "$type": "ChangeAvatarEffector",
+      "category": "player",
+      "parameters": {
+        "Url": "string — GLB model URL",
+        "Persistent": "bool — persist across sessions"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "ChangeMovementProfile",
+      "category": "player",
+      "parameters": {
+        "mvmtProfile": "string — movement profile name"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "ChangeRoundyWearableEffector",
+      "category": "player",
+      "parameters": {
+        "ItemID": "string — wearable item ID"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "LockCamera",
+      "category": "camera",
+      "parameters": {},
+      "gotchas": []
+    },
+    {
+      "$type": "UnlockCamera",
+      "category": "camera",
+      "parameters": {},
+      "gotchas": []
+    },
+    {
+      "$type": "ChangeCameraZoom",
+      "category": "camera",
+      "parameters": {
+        "zoomAmount": "float — zoom level",
+        "lockZoom": "bool — prevent player zoom adjustment"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "ToggleFreeCam",
+      "category": "camera",
+      "parameters": {
+        "enterFreeCam": "bool (optional) — true=enter, false=exit. Omit all params to toggle.",
+        "x": "float (optional) — camera X position",
+        "y": "float (optional) — camera Y position",
+        "z": "float (optional) — camera Z position",
+        "lookAtPlayer": "bool (optional) — camera looks at player"
+      },
+      "gotchas": ["No params = toggle. With params = explicit control with optional position and orientation."]
+    },
+    {
+      "$type": "ChangeCamState",
+      "category": "camera",
+      "parameters": {
+        "camState": "string — camera state name (matches CameraObject sn)",
+        "transitionSpeed": "float — transition speed"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "SetCameraFilter",
+      "category": "camera",
+      "parameters": {
+        "url": "string — image overlay URL",
+        "alpha": "float — overlay opacity"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "ToggleLockCursor",
+      "category": "camera",
+      "parameters": {
+        "lockCursor": "bool (optional) — true=lock, false=unlock. Omit to toggle."
+      },
+      "gotchas": ["No params = toggle. With lockCursor = explicit lock/unlock."]
+    },
+    {
+      "$type": "NotificationPillEvent",
+      "category": "ui",
+      "parameters": {
+        "nt": "string — notification text",
+        "c": "string — hex color",
+        "hideBackground": "bool — transparent background"
+      },
+      "gotchas": ["Supports |varName| pipe syntax for inline variable display"]
+    },
+    {
+      "$type": "DisplayValueEvent",
+      "category": "values",
+      "parameters": {
+        "label": "string — variable name to display",
+        "color": "string — hex color"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "HideValueEvent",
+      "category": "values",
+      "parameters": {
+        "label": "string — variable name to hide"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "UpdateScoreEvent",
+      "category": "values",
+      "parameters": {
+        "scoreChange": "float — value to apply",
+        "op": "int — omit=set, 1=add, 2=sub, 3=mul, 4=div"
+      },
+      "gotchas": ["Omit 'op' entirely to SET the value. Include op for math operations."]
+    },
+    {
+      "$type": "UpdateScoreEventString",
+      "category": "values",
+      "parameters": {
+        "targetText": "string — text value to set",
+        "label": "string — variable name"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "FunctionEffector",
+      "category": "logic",
+      "parameters": {
+        "V": "string — NCalc expression"
+      },
+      "gotchas": [
+        "Task names OMIT numbered prefix: quest Name='0_redteam' but NCalc uses 'redteam'",
+        "All numeric values MUST use decimals (0.0 not 0)",
+        "Strings use single quotes ('Active' not \"Active\")"
+      ]
+    },
+    {
+      "$type": "RunTriggersFromEffector",
+      "category": "logic",
+      "parameters": {
+        "linkedTasks": "array — [{Trigger:{}, Id, TargetState, Name, TaskTriggerId},...] state changes to fire",
+        "useRandom": "bool — randomly pick one linkedTask instead of firing all"
+      },
+      "gotchas": [
+        "TargetState uses encoded values: 101=any>NotActive, 151=any>Active, 141=any>Completed, 111=NotActive>Active, 121=Active>Completed, 171=Completed>NotActive",
+        "Trigger:{} = immediate. Trigger:{Delay:1.0} = delay in seconds"
+      ]
+    },
+    {
+      "$type": "ResetAllTasks",
+      "category": "logic",
+      "parameters": {},
+      "gotchas": []
+    },
+    {
+      "$type": "StartTimerEffect",
+      "category": "timers",
+      "parameters": {
+        "tn": "string — timer name",
+        "ci": "string — custom identifier (usually empty)",
+        "showTimerUI": "bool — display timer on screen"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "StopTimerEffect",
+      "category": "timers",
+      "parameters": {
+        "tn": "string — timer name",
+        "ci": "string — custom identifier (usually empty)"
+      },
+      "gotchas": ["Fires OnTimerStopped trigger"]
+    },
+    {
+      "$type": "CancelTimerEffect",
+      "category": "timers",
+      "parameters": {
+        "tn": "string — timer name"
+      },
+      "gotchas": ["Does NOT fire OnTimerStopped — cancels silently"]
+    },
+    {
+      "$type": "PostScoreToLeaderboard",
+      "category": "leaderboard",
+      "parameters": {
+        "label": "string — variable name to post"
+      },
+      "gotchas": ["Only for numeric values, not timers directly"]
+    },
+    {
+      "$type": "ClearLeaderboard",
+      "category": "leaderboard",
+      "parameters": {
+        "label": "string — leaderboard name"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "OpenLeaderboardEffect",
+      "category": "leaderboard",
+      "parameters": {
+        "lb": "string — leaderboard name"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "PlaySoundOnce",
+      "category": "audio",
+      "parameters": {
+        "Url": "string — MP3 URL (capital U!)",
+        "Dist": "float — audible distance (capital D!)"
+      },
+      "gotchas": ["Field names use CAPITAL 'Url' and 'Dist' — not lowercase"]
+    },
+    {
+      "$type": "PlaySoundInALoop",
+      "category": "audio",
+      "parameters": {
+        "Url": "string — MP3 URL (capital U!)",
+        "Dist": "float — audible distance (-1=global, capital D!)",
+        "Preload": "bool — preload audio"
+      },
+      "gotchas": ["Field names use CAPITAL 'Url' and 'Dist' — not lowercase"]
+    },
+    {
+      "$type": "StopSound",
+      "category": "audio",
+      "parameters": {
+        "url": "string — MP3 URL (lowercase u!)",
+        "fadeOut": "float — fade out duration seconds"
+      },
+      "gotchas": ["Uses LOWERCASE 'url' — opposite of PlaySoundOnce/PlaySoundInALoop"]
+    },
+    {
+      "$type": "ChangeAudiusEffect",
+      "category": "audio",
+      "parameters": {
+        "ap": "string — Audius playlist name"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "ChangeBloom",
+      "category": "environment",
+      "parameters": {
+        "Intensity": "float — bloom intensity",
+        "Clamp": "float — bloom clamp",
+        "Diffusion": "float — bloom diffusion"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "ChangeTimeOfDay",
+      "category": "environment",
+      "parameters": {},
+      "gotchas": []
+    },
+    {
+      "$type": "RotateSkybox",
+      "category": "environment",
+      "parameters": {
+        "rotation": "float — degrees",
+        "duration": "float — seconds"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "ChangeFog",
+      "category": "environment",
+      "parameters": {
+        "color": "string — hex color",
+        "distance": "float — fog distance"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "SendMessageToIframes",
+      "category": "communication",
+      "parameters": {
+        "iframeMsg": "string — message text"
+      },
+      "gotchas": ["Supports |variable| interpolation (|username|, |position|, player vars). Legacy — prefer native displayHtml() for new custom UI (docs://logic/js-display-html)."]
+    },
+    {
+      "$type": "ChangeVoiceGroup",
+      "category": "communication",
+      "parameters": {
+        "group": "string — voice group name"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "IframeEvent",
+      "category": "communication",
+      "parameters": {
+        "url": "string — iframe URL (supports ?maximized=true, ?noCloseBtn=true)"
+      },
+      "gotchas": ["Legacy — prefer native displayHtml() for custom UI/HUDs (docs://logic/js-display-html)"]
+    },
+    {
+      "$type": "IframeStopEvent",
+      "category": "communication",
+      "parameters": {
+        "iframeUrl": "string — URL must match the opened iframe"
+      },
+      "gotchas": ["URL must exactly match the IframeEvent url to close it. Legacy — prefer native displayHtml() for custom UI/HUDs (docs://logic/js-display-html)"]
+    },
+    {
+      "$type": "NPCMessageEvent",
+      "category": "npc",
+      "parameters": {
+        "n": "string — NPC name",
+        "m": "string — message text",
+        "r": "bool"
+      },
+      "gotchas": ["GLBNPC only"]
+    },
+    {
+      "$type": "WalkNpcToSpot",
+      "category": "npc",
+      "parameters": {
+        "walkSpeed": "float — walk speed",
+        "endPosition": "array — [x,y,z] destination",
+        "endRotation": "array — [qx,qy,qz,qw] final rotation"
+      },
+      "gotchas": ["GLBNPC only. endPosition/endRotation are arrays, not objects."]
+    },
+    {
+      "$type": "NpcAnimation",
+      "category": "npc",
+      "parameters": {
+        "animationName": "string — Sitting, Can Can, Wave, Salute, Jive, Salsa, Shuffling, Chicken, Slide n Jive, Robot"
+      },
+      "gotchas": ["GLBNPC only"]
+    },
+    {
+      "$type": "NpcCopyPlayerPath",
+      "category": "npc",
+      "parameters": {
+        "positions": "array — [[x,y,z],...] world-space waypoints, one per recorded sample",
+        "rotations": "array — [[qx,qy,qz,qw],...] quaternion rotation at each point, same length as positions",
+        "animatorParameterDatas": "array — movement animation state per point. Each entry: {g: bool (grounded), s: bool (sprint, omit if false), o: string ('0.0'=idle, '1.0'=moving), m: string ('0.0'=idle, '0.5'=walk, '1.0'=jog, '1.5'=sprint), d/a/v/i/r: string (typically '0.0')}",
+        "shouldLoop": "bool — true=loop continuously, omit/false=play once"
+      },
+      "gotchas": ["GLBNPC only", "All three arrays (positions, rotations, animatorParameterDatas) must be the same length", "Sprint requires both s:true AND m:'1.5'"]
+    },
+    {
+      "$type": "NpcCopyPlayerPathStop",
+      "category": "npc",
+      "parameters": {
+        "RP": "bool — true=reset to original position"
+      },
+      "gotchas": ["GLBNPC only"]
+    },
+    {
+      "$type": "TurnToPlayer",
+      "category": "npc",
+      "parameters": {},
+      "gotchas": ["GLBNPC only"]
+    },
+    {
+      "$type": "StartSpeaking",
+      "category": "npc",
+      "parameters": {},
+      "gotchas": ["GLBNPC only"]
+    },
+    {
+      "$type": "StopSpeaking",
+      "category": "npc",
+      "parameters": {},
+      "gotchas": ["GLBNPC only"]
+    },
+    {
+      "$type": "EquipGunEffect",
+      "category": "gun",
+      "parameters": {},
+      "gotchas": ["Gun/Shotgun only"]
+    },
+    {
+      "$type": "TossGunEffect",
+      "category": "gun",
+      "parameters": {},
+      "gotchas": ["Gun/Shotgun only"]
+    },
+    {
+      "$type": "ResetGunEffect",
+      "category": "gun",
+      "parameters": {},
+      "gotchas": ["Gun/Shotgun only"]
+    },
+    {
+      "$type": "ReviveEnemy",
+      "category": "enemy",
+      "parameters": {},
+      "gotchas": ["EnemyNPC only"]
+    },
+    {
+      "$type": "ResetEnemy",
+      "category": "enemy",
+      "parameters": {},
+      "gotchas": ["EnemyNPC only — resets to full health at origin"]
+    },
+    {
+      "$type": "AttackPlayer",
+      "category": "enemy",
+      "parameters": {},
+      "gotchas": ["EnemyNPC only — forces attack on nearest player"]
+    },
+    {
+      "$type": "ChangeEnemyHealth",
+      "category": "enemy",
+      "parameters": {
+        "op": "int — 1=add, 2=subtract",
+        "healthChange": "int — HP amount"
+      },
+      "gotchas": ["EnemyNPC only"]
+    },
+    {
+      "$type": "DuplicateEnemy",
+      "category": "enemy",
+      "parameters": {
+        "spawnName": "string — SpawnPoint name",
+        "count": "int — number of copies",
+        "randomRadius": "float — spawn spread radius"
+      },
+      "gotchas": ["EnemyNPC only — spawns at named SpawnPoint"]
+    },
+    {
+      "$type": "EnterVehicle",
+      "category": "vehicle",
+      "parameters": {},
+      "gotchas": ["Vehicle only"]
+    },
+    {
+      "$type": "ExitVehicle",
+      "category": "vehicle",
+      "parameters": {},
+      "gotchas": ["Vehicle only"]
+    },
+    {
+      "$type": "VehicleBoost",
+      "category": "vehicle",
+      "parameters": {
+        "duration": "float — boost duration seconds",
+        "speedOfBoost": "float — boost speed",
+        "rampUpTime": "float — ramp up seconds",
+        "rampDownTime": "float — ramp down seconds"
+      },
+      "gotchas": ["Vehicle only"]
+    },
+    {
+      "$type": "ActivateTriggerZoneEffect",
+      "category": "trigger-zone",
+      "parameters": {},
+      "gotchas": ["Trigger only — re-enables a deactivated zone"]
+    },
+    {
+      "$type": "DeactivateTriggerZoneEffect",
+      "category": "trigger-zone",
+      "parameters": {},
+      "gotchas": ["Trigger only"]
+    },
+    {
+      "$type": "RespawnDestructible",
+      "category": "destructible",
+      "parameters": {},
+      "gotchas": ["Destructible only"]
+    },
+    {
+      "$type": "PlayAnimationOnce",
+      "category": "glb-animation",
+      "parameters": {
+        "speed": "float — playback speed (negative=reverse)"
+      },
+      "gotchas": ["Plays embedded GLB animation once"]
+    },
+    {
+      "$type": "StopAnimationEvt",
+      "category": "glb-animation",
+      "parameters": {
+        "stop": "float — normalized time 0.0(start) to 1.0(end)"
+      },
+      "gotchas": ["Freezes GLB animation at specified frame. Common pattern: OnPlayerLoggedIn > stop:0.0 to freeze, then PlayAnimationOnce on trigger."]
+    },
+    {
+      "$type": "DisplaySellSwap",
+      "category": "other",
+      "parameters": {
+        "id": "string — swap config ID",
+        "typ": "int — swap type"
+      },
+      "gotchas": []
+    },
+    {
+      "$type": "HideSellSwap",
+      "category": "other",
+      "parameters": {},
+      "gotchas": []
+    },
+    {
+      "$type": "DialogEffectorDisplay",
+      "category": "other",
+      "parameters": {
+        "tasksN": "array — [{N: '-0_task_name'},...] ordered task refs",
+        "GN": "string — character name",
+        "S": "string — story UUID prefixed with _",
+        "Audio": "bool — enable audio",
+        "HF": "bool — hide on finish",
+        "R": "bool — allow repeat",
+        "DV": "string — voice ID (empty=no TTS)",
+        "GB": "string — goodbye action ('leave'=close)",
+        "Story": "string — same as S",
+        "tasksSorM": "object — {taskName: {completed: quest, inProgress: quest},...}"
+      },
+      "gotchas": ["Most complex effect — embeds inline quest entries per dialogue node. See docs://reference/interactions for full schema."]
+    },
+    {
+      "$type": "RefreshUserInventory",
+      "category": "other",
+      "parameters": {},
+      "gotchas": []
+    }
+  ]
+}