portals-mcp 1.3.1 → 1.3.3

package/README.md

@@ -53,6 +53,7 @@ npx portals-mcp@latest
 | `get_room_data` | Download room snapshot to temp JSON |
 | `inspect_room_data` | Summarize room-data counts, item types, variables, triggers/actions, and warnings without dumping full JSON |
 | `simulate_key_input` | Audit and simulate `OnKeyPressedEvent` / `OnKeyReleasedEvent` mappings against a snapshot |
+| `simulate_trigger_zone_input` | Audit and simulate Trigger `pressBtn` / `keyCode` press-inside-zone behavior |
 | `query_room` | Query room data for specific items, logic, or structure |
 | `update_room_settings` | Modify name, description, image, privacy, loading screens |
 

package/dist/resources/index/intents.json

@@ -1,164 +1,164 @@
-{
-  "version": "3.0.0",
-  "description": "Data-driven intent profiles for context recommendation. Used by get_context to assemble inline knowledge.",
-  "base_resources": [
-    { "uri": "docs://ai/bootstrap", "reason": "Execution policy.", "priority": 1 },
-    { "uri": "docs://ai/contracts/tool-output-envelope", "reason": "Tool response schema.", "priority": 1 },
-    { "uri": "docs://usage-rules", "reason": "Read/write conventions.", "priority": 1 },
-    { "uri": "docs://guide/rules-and-conventions", "reason": "Core execution rules.", "priority": 1 },
-    { "uri": "docs://index/knowledge-map", "reason": "Navigate all available content.", "priority": 2 }
-  ],
-  "stage_hints": {
-    "setup": ["setup-auth"],
-    "design": ["create-room", "gameplay-build", "scene-design"],
-    "build": ["gameplay-build", "function-effects"],
-    "logic": ["function-effects", "js-scripting", "logic-board"],
-    "validate": ["validation-publish"],
-    "publish": ["validation-publish"],
-    "assets": ["asset-pipeline"],
-    "settings": ["settings-update"],
-    "scripting": ["local-scripting", "js-scripting"]
-  },
-  "intents": [
-    {
-      "id": "setup-auth",
-      "keywords": ["install", "setup", "auth", "authenticate", "connect", "key", "access", "mcp", "server", "config"],
-      "resources": {
-        "required": [],
-        "recommended": []
-      },
-      "tools": ["authenticate"],
-      "checks": ["Ensure authenticate returns ok=true.", "Persist PORTALS_ACCESS_KEY in MCP config."]
-    },
-    {
-      "id": "create-room",
-      "keywords": ["create", "new", "template", "duplicate", "clone", "start"],
-      "resources": {
-        "required": ["docs://guide/workflow-steps", "docs://workflows/scene-design"],
-        "recommended": ["docs://recipes/manifest", "docs://ref/room-data-skeleton"]
-      },
-      "tools": ["create_room", "duplicate_room", "get_room_data"],
-      "checks": ["Choose template and room type before calling create_room.", "Capture returned roomId."]
-    },
-    {
-      "id": "scene-item",
-      "keywords": ["cube", "spawn", "portal", "npc", "light", "image", "glb", "item", "place", "add", "text", "video", "gun", "vehicle", "trigger", "jump pad", "leaderboard", "camera", "effect", "vfx", "collectible", "destructible", "billboard", "chart", "elemental"],
-      "resources": {
-        "required": ["docs://index/items"],
-        "recommended": ["docs://ref/pitfalls", "docs://ref/interactions/basic", "docs://reference/gotchas"]
-      },
-      "tools": ["lookup", "get_room_data", "apply_operations"],
-      "checks": ["Use lookup tool for specific item specs.", "Read room data before writing."]
-    },
-    {
-      "id": "gameplay-build",
-      "keywords": ["mechanic", "gameplay", "logic", "interaction", "trigger", "effect", "castle", "keypad", "minimap", "leaderboard", "score", "quest", "puzzle", "game", "board game", "hud", "ui", "display", "health bar", "timer"],
-      "resources": {
-        "required": ["docs://recipes/manifest", "docs://ref/systems/function-effector"],
-        "recommended": ["docs://ref/interactions/patterns", "docs://ref/interactions/quest-driven", "docs://ref/systems/quests", "docs://ref/room-data-skeleton", "docs://reference/gotchas", "docs://ref/systems/display-html"]
-      },
-      "tools": ["search_recipes", "lookup", "get_room_data", "apply_operations"],
-      "checks": ["Reuse recipes before custom implementation.", "Verify item/task counts after apply_operations."]
-    },
-    {
-      "id": "function-effects",
-      "keywords": ["functioneffector", "ncalc", "variable", "variables", "settask", "setvariable", "timer", "timers", "multiplayer", "team", "teams", "random", "condition", "conditional", "logic expression"],
-      "resources": {
-        "required": ["docs://ref/systems/function-effector"],
-        "recommended": ["docs://logic/js-function-reference", "docs://logic/js-use-effector", "docs://logic/expression-guide", "docs://logic/multiplayer", "docs://logic/string-variables", "docs://ref/interactions/quest-driven", "docs://ref/systems/quests", "docs://ref/systems/variables", "docs://reference/gotchas"]
-      },
-      "tools": ["search_recipes", "lookup", "get_room_data", "apply_operations"],
-      "checks": ["Decimal literals (0.0, 1.0) in expressions.", "Single quotes for string task states.", "Task names omit numbered prefix in NCalc."]
-    },
-    {
-      "id": "js-scripting",
-      "keywords": ["javascript", "js", "functioneffectorjs", "useeffector", "use effector", "onclick", "on click", "click function", "js function", "script", "hide object", "show object", "move to spot", "play sound", "change movement", "lock movement", "teleport", "change avatar", "change camera", "attach item", "displayhtml", "display html", "html overlay", "custom ui", "hud", "custom hud", "backdrop-filter", "html display", "game ui", "overlay", "html panel"],
-      "resources": {
-        "required": ["docs://logic/js-function-reference", "docs://logic/js-use-effector"],
-        "recommended": ["docs://ref/systems/function-effector", "docs://logic/string-variables", "docs://logic/multiplayer", "docs://reference/gotchas", "docs://logic/js-display-html"]
-      },
-      "tools": ["lookup", "get_room_data", "apply_operations"],
-      "checks": ["S: true REQUIRED with OnPlayerLoggedIn trigger.", "R: true for reactive variable watchers.", "V must be single-line (semicolons, not newlines).", "UseEffector effect names are case-sensitive.", "No PrintString in JS — use browser console.", "Use Number() not parseInt() to avoid octal trap.", "displayHtml: Variable names must be all-lowercase (e.g. 'ballx' not 'bX').", "displayHtml: Code after displayHtml() in same V field executes directly — can manipulate rendered HTML."]
-    },
-    {
-      "id": "logic-board",
-      "keywords": ["logic board", "flowchart", "circuit", "node", "nodes", "pulse", "diagram", "visualize", "visualise", "board"],
-      "resources": {
-        "required": ["docs://recipes/logic-board/implementation"],
-        "recommended": ["docs://ref/systems/function-effector", "docs://ref/interactions/quest-driven"]
-      },
-      "tools": ["get_room_data", "apply_operations"],
-      "checks": ["Keep board visuals and logic on same nodes.", "Verify parent-child links after write."]
-    },
-    {
-      "id": "local-scripting",
-      "keywords": ["python", "room-index", "query_room", "merge_room", "sync_room", "validate_room", "tooling", "helpers", "minimap", "check_storage"],
-      "resources": {
-        "required": ["docs://python/README"],
-        "recommended": ["docs://ref/systems/movement", "docs://ref/room-data-skeleton"]
-      },
-      "tools": ["get_room_data", "apply_operations", "query_room"],
-      "checks": ["Use query_room to search items by type, position, triggers, or text."]
-    },
-    {
-      "id": "validation-publish",
-      "keywords": ["validate", "test", "qa", "verify", "publish", "ship", "regression"],
-      "resources": {
-        "required": ["docs://workflows/quality-review"],
-        "recommended": ["docs://usage-rules"]
-      },
-      "tools": ["get_room_data", "apply_operations"],
-      "checks": ["Resolve all structural errors before publish.", "Keep last-known-good snapshot for rollback."]
-    },
-    {
-      "id": "asset-pipeline",
-      "keywords": ["upload", "asset", "glb", "model", "texture", "image", "png", "jpg", "jpeg", "gif", "cdn", "media"],
-      "resources": {
-        "required": ["docs://reference/glb-asset-catalog"],
-        "recommended": ["docs://ref/items/glb"]
-      },
-      "tools": ["upload_glb", "upload_image"],
-      "checks": ["Capture returned CDN URLs.", "Verify references after mutation."]
-    },
-    {
-      "id": "settings-update",
-      "keywords": ["settings", "name", "description", "cover", "loading", "images", "visibility", "hide", "loader"],
-      "resources": {
-        "required": ["docs://ref/settings"],
-        "recommended": ["docs://usage-rules"]
-      },
-      "tools": ["update_room_settings", "get_room_data"],
-      "checks": ["Provide at least one field besides roomId.", "Verify CustomLoader behavior if loading images changed."]
-    },
-    {
-      "id": "game-design-full",
-      "keywords": ["full build", "complete game", "design game", "new game", "game from scratch", "full game", "build game", "make game", "surprise me"],
-      "resources": {
-        "required": ["docs://guide/workflow-steps", "docs://workflows/scene-design"],
-        "recommended": ["docs://index/knowledge-map", "docs://recipes/manifest", "docs://ref/room-data-skeleton", "docs://ref/systems/display-html"]
-      },
-      "tools": ["search_recipes", "create_room", "get_room_data", "apply_operations", "analyze_scene", "render_scene"],
-      "checks": ["Design before building — write design.md first.", "Search recipes before inventing mechanics.", "Use modular build for 50+ item games.", "Run quality review before pushing."]
-    },
-    {
-      "id": "scene-design",
-      "keywords": ["compose", "composition", "spatial", "layout", "placement", "arrange", "density", "zones", "sightline", "scene design", "furnish", "decorate", "populate", "fill", "detail", "design review", "analyze scene", "scene analysis", "evaluate"],
-      "resources": {
-        "required": ["docs://workflows/scene-design", "docs://workflows/scene-design"],
-        "recommended": ["docs://reference/glb-asset-catalog"]
-      },
-      "tools": ["analyze_scene", "render_scene", "get_room_data", "apply_operations"],
-      "checks": ["Analyze scene before making composition changes.", "Use render_scene for visual verification.", "Compare before/after with compare_scene."]
-    },
-    {
-      "id": "room-targeting",
-      "keywords": ["edit", "existing", "current", "room id", "roomid", "room-id", "open"],
-      "resources": {
-        "required": ["docs://usage-rules"],
-        "recommended": []
-      },
-      "tools": ["get_room_data"],
-      "checks": ["Ask user for roomId if unknown.", "Always read room data before proposing writes."]
-    }
-  ]
-}
+{
+  "version": "3.0.0",
+  "description": "Data-driven intent profiles for context recommendation. Used by get_context to assemble inline knowledge.",
+  "base_resources": [
+    { "uri": "docs://ai/bootstrap", "reason": "Execution policy.", "priority": 1 },
+    { "uri": "docs://ai/contracts/tool-output-envelope", "reason": "Tool response schema.", "priority": 1 },
+    { "uri": "docs://usage-rules", "reason": "Read/write conventions.", "priority": 1 },
+    { "uri": "docs://guide/rules-and-conventions", "reason": "Core execution rules.", "priority": 1 },
+    { "uri": "docs://index/knowledge-map", "reason": "Navigate all available content.", "priority": 2 }
+  ],
+  "stage_hints": {
+    "setup": ["setup-auth"],
+    "design": ["create-room", "gameplay-build", "scene-design"],
+    "build": ["gameplay-build", "function-effects"],
+    "logic": ["function-effects", "js-scripting", "logic-board"],
+    "validate": ["validation-publish"],
+    "publish": ["validation-publish"],
+    "assets": ["asset-pipeline"],
+    "settings": ["settings-update"],
+    "scripting": ["local-scripting", "js-scripting"]
+  },
+  "intents": [
+    {
+      "id": "setup-auth",
+      "keywords": ["install", "setup", "auth", "authenticate", "connect", "key", "access", "mcp", "server", "config"],
+      "resources": {
+        "required": [],
+        "recommended": []
+      },
+      "tools": ["authenticate"],
+      "checks": ["Ensure authenticate returns ok=true.", "Persist PORTALS_ACCESS_KEY in MCP config."]
+    },
+    {
+      "id": "create-room",
+      "keywords": ["create", "new", "template", "duplicate", "clone", "start"],
+      "resources": {
+        "required": ["docs://guide/workflow-steps", "docs://workflows/scene-design"],
+        "recommended": ["docs://recipes/manifest", "docs://ref/room-data-skeleton", "docs://reference/template-layouts"]
+      },
+      "tools": ["create_room", "duplicate_room", "get_room_data"],
+      "checks": ["Choose template and room type before calling create_room.", "Capture returned roomId."]
+    },
+    {
+      "id": "scene-item",
+      "keywords": ["cube", "spawn", "portal", "npc", "light", "image", "glb", "item", "place", "add", "text", "video", "gun", "vehicle", "trigger", "jump pad", "leaderboard", "camera", "effect", "vfx", "collectible", "destructible", "billboard", "chart", "elemental"],
+      "resources": {
+        "required": ["docs://index/items"],
+        "recommended": ["docs://ref/pitfalls", "docs://ref/interactions/basic", "docs://reference/gotchas", "docs://reference/template-layouts"]
+      },
+      "tools": ["lookup", "get_room_data", "apply_operations"],
+      "checks": ["Use lookup tool for specific item specs.", "Read room data before writing."]
+    },
+    {
+      "id": "gameplay-build",
+      "keywords": ["mechanic", "gameplay", "logic", "interaction", "trigger", "effect", "castle", "keypad", "minimap", "leaderboard", "score", "quest", "puzzle", "game", "board game", "hud", "ui", "display", "health bar", "timer"],
+      "resources": {
+        "required": ["docs://recipes/manifest", "docs://ref/systems/function-effector"],
+        "recommended": ["docs://ref/interactions/patterns", "docs://ref/interactions/quest-driven", "docs://ref/systems/quests", "docs://ref/room-data-skeleton", "docs://reference/gotchas", "docs://ref/systems/display-html"]
+      },
+      "tools": ["search_recipes", "lookup", "get_room_data", "apply_operations"],
+      "checks": ["Reuse recipes before custom implementation.", "Verify item/task counts after apply_operations."]
+    },
+    {
+      "id": "function-effects",
+      "keywords": ["functioneffector", "ncalc", "variable", "variables", "settask", "setvariable", "timer", "timers", "multiplayer", "team", "teams", "random", "condition", "conditional", "logic expression"],
+      "resources": {
+        "required": ["docs://ref/systems/function-effector"],
+        "recommended": ["docs://logic/js-function-reference", "docs://logic/js-use-effector", "docs://logic/expression-guide", "docs://logic/multiplayer", "docs://logic/string-variables", "docs://ref/interactions/quest-driven", "docs://ref/systems/quests", "docs://ref/systems/variables", "docs://reference/gotchas"]
+      },
+      "tools": ["search_recipes", "lookup", "get_room_data", "apply_operations"],
+      "checks": ["Decimal literals (0.0, 1.0) in expressions.", "Single quotes for string task states.", "Task names omit numbered prefix in NCalc."]
+    },
+    {
+      "id": "js-scripting",
+      "keywords": ["javascript", "js", "functioneffectorjs", "useeffector", "use effector", "onclick", "on click", "click function", "js function", "script", "hide object", "show object", "move to spot", "play sound", "change movement", "lock movement", "teleport", "change avatar", "change camera", "attach item", "displayhtml", "display html", "html overlay", "custom ui", "hud", "custom hud", "backdrop-filter", "html display", "game ui", "overlay", "html panel"],
+      "resources": {
+        "required": ["docs://logic/js-function-reference", "docs://logic/js-use-effector"],
+        "recommended": ["docs://ref/systems/function-effector", "docs://logic/string-variables", "docs://logic/multiplayer", "docs://reference/gotchas", "docs://logic/js-display-html"]
+      },
+      "tools": ["lookup", "get_room_data", "apply_operations"],
+      "checks": ["S: true REQUIRED with OnPlayerLoggedIn trigger.", "R: true for reactive variable watchers.", "V must be single-line (semicolons, not newlines).", "UseEffector effect names are case-sensitive.", "No PrintString in JS — use browser console.", "Use Number() not parseInt() to avoid octal trap.", "displayHtml: Variable names must be all-lowercase (e.g. 'ballx' not 'bX').", "displayHtml: Code after displayHtml() in same V field executes directly — can manipulate rendered HTML."]
+    },
+    {
+      "id": "logic-board",
+      "keywords": ["logic board", "flowchart", "circuit", "node", "nodes", "pulse", "diagram", "visualize", "visualise", "board"],
+      "resources": {
+        "required": ["docs://recipes/logic-board/implementation"],
+        "recommended": ["docs://ref/systems/function-effector", "docs://ref/interactions/quest-driven"]
+      },
+      "tools": ["get_room_data", "apply_operations"],
+      "checks": ["Keep board visuals and logic on same nodes.", "Verify parent-child links after write."]
+    },
+    {
+      "id": "local-scripting",
+      "keywords": ["python", "room-index", "query_room", "merge_room", "sync_room", "validate_room", "tooling", "helpers", "minimap", "check_storage"],
+      "resources": {
+        "required": ["docs://python/README"],
+        "recommended": ["docs://ref/systems/movement", "docs://ref/room-data-skeleton"]
+      },
+      "tools": ["get_room_data", "apply_operations", "query_room"],
+      "checks": ["Use query_room to search items by type, position, triggers, or text."]
+    },
+    {
+      "id": "validation-publish",
+      "keywords": ["validate", "test", "qa", "verify", "publish", "ship", "regression"],
+      "resources": {
+        "required": ["docs://workflows/quality-review"],
+        "recommended": ["docs://usage-rules"]
+      },
+      "tools": ["get_room_data", "apply_operations"],
+      "checks": ["Resolve all structural errors before publish.", "Keep last-known-good snapshot for rollback."]
+    },
+    {
+      "id": "asset-pipeline",
+      "keywords": ["upload", "asset", "glb", "model", "texture", "image", "png", "jpg", "jpeg", "gif", "cdn", "media"],
+      "resources": {
+        "required": ["docs://reference/glb-asset-catalog"],
+        "recommended": ["docs://ref/items/glb"]
+      },
+      "tools": ["upload_glb", "upload_image"],
+      "checks": ["Capture returned CDN URLs.", "Verify references after mutation."]
+    },
+    {
+      "id": "settings-update",
+      "keywords": ["settings", "name", "description", "cover", "loading", "images", "visibility", "hide", "loader"],
+      "resources": {
+        "required": ["docs://ref/settings"],
+        "recommended": ["docs://usage-rules"]
+      },
+      "tools": ["update_room_settings", "get_room_data"],
+      "checks": ["Provide at least one field besides roomId.", "Verify CustomLoader behavior if loading images changed."]
+    },
+    {
+      "id": "game-design-full",
+      "keywords": ["full build", "complete game", "design game", "new game", "game from scratch", "full game", "build game", "make game", "surprise me"],
+      "resources": {
+        "required": ["docs://guide/workflow-steps", "docs://workflows/scene-design"],
+        "recommended": ["docs://index/knowledge-map", "docs://recipes/manifest", "docs://ref/room-data-skeleton", "docs://ref/systems/display-html", "docs://reference/template-layouts"]
+      },
+      "tools": ["search_recipes", "create_room", "get_room_data", "apply_operations", "analyze_scene", "render_scene"],
+      "checks": ["Design before building — write design.md first.", "Search recipes before inventing mechanics.", "Use modular build for 50+ item games.", "Run quality review before pushing."]
+    },
+    {
+      "id": "scene-design",
+      "keywords": ["compose", "composition", "spatial", "layout", "placement", "arrange", "density", "zones", "sightline", "scene design", "furnish", "decorate", "populate", "fill", "detail", "design review", "analyze scene", "scene analysis", "evaluate"],
+      "resources": {
+        "required": ["docs://workflows/scene-design", "docs://workflows/scene-design"],
+        "recommended": ["docs://reference/glb-asset-catalog", "docs://reference/template-layouts"]
+      },
+      "tools": ["analyze_scene", "render_scene", "get_room_data", "apply_operations"],
+      "checks": ["Analyze scene before making composition changes.", "Use render_scene for visual verification.", "Compare before/after with compare_scene."]
+    },
+    {
+      "id": "room-targeting",
+      "keywords": ["edit", "existing", "current", "room id", "roomid", "room-id", "open"],
+      "resources": {
+        "required": ["docs://usage-rules"],
+        "recommended": []
+      },
+      "tools": ["get_room_data"],
+      "checks": ["Ask user for roomId if unknown.", "Always read room data before proposing writes."]
+    }
+  ]
+}

package/dist/resources/index/items.json

@@ -113,13 +113,13 @@
       "category": "gameplay",
       "key_fields": {
         "events": "array — legacy events (usually [])",
-        "pressBtn": "bool — require key press",
-        "keyCode": "string — key to press (X, H, E)",
+        "pressBtn": "bool — require key press while inside before firing OnEnterEvent tasks",
+        "keyCode": "string — InputHandler key to press (X, H, E, Alpha1)",
         "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.",
+      "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.",
       "spec_uri": "docs://ref/items/trigger-zone"
     },
     {

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

@@ -84,6 +84,13 @@
             "uri": "docs://workflows/scene-design",
             "children": []
           },
+          {
+            "id": "scene.templates",
+            "label": "Template Layouts",
+            "description": "Live-verified operational zones, placement caveats, floor/terrain Y ranges, and QA status for built-in room templates",
+            "uri": "docs://reference/template-layouts",
+            "children": []
+          },
           {
             "id": "scene.assets",
             "label": "Assets",

package/dist/resources/index/triggers.json

@@ -10,9 +10,9 @@
     },
     {
       "$type": "OnEnterEvent",
-      "description": "Player enters trigger zone",
+      "description": "Player enters trigger zone. If the Trigger item has pressBtn:true, this fires only after the player enters and presses the Trigger keyCode.",
       "applicable_items": ["Trigger"],
-      "gotchas": ["ONLY works on Trigger cubes, not ResizableCubes or GLBs"]
+      "gotchas": ["ONLY works on Trigger cubes, not ResizableCubes or GLBs", "pressBtn:true gates this trigger by keyCode while inside the zone; use simulate_trigger_zone_input to audit."]
     },
     {
       "$type": "OnExitEvent",

package/dist/resources/python/README.md

@@ -11,6 +11,7 @@ The Python toolkit provides validation, room analysis, and query tools. It is bu
 **Via dedicated MCP tools**:
 - `query_room` — search items by type, position, triggers, text, parent, or quest reference
 - `simulate_key_input` — audit and simulate keyboard triggers against a snapshot
+- `simulate_trigger_zone_input` — audit and simulate Trigger `pressBtn` / `keyCode` press-inside-zone behavior
 - `apply_operations` — add, modify, remove items/logic/quests (auto-pulls fresh data, auto-validates)
 - `get_room_data` — download room data with auto-generated index
 
@@ -33,6 +34,11 @@ For bulk builds, pass hundreds of operations in a single `apply_operations` call
 
 Use the `query_room` MCP tool to search items without loading the full room JSON:
 ```
+query_room(roomId: "...", types: ["GLB"], hasTriggers: true)
+query_room(roomId: "...", near: {x:10, y:0, z:15}, radius: 5)
+query_room(roomId: "...", search: "door")
+query_room(roomId: "...", parent: "12")
+```
 
 ## Auditing Keyboard Triggers
 
@@ -43,10 +49,11 @@ simulate_key_input(filePath: ".../snapshot.json", actions: [{type: "press", key:
 ```
 
 Keyboard trigger keys must use Portals/Unity key-code names such as `Alpha1`, `Space`, `Return`, `LeftShift`, and `LeftArrow`.
-query_room(roomId: "...", types: ["GLB"], hasTriggers: true)
-query_room(roomId: "...", near: {x:10, y:0, z:15}, radius: 5)
-query_room(roomId: "...", search: "door")
-query_room(roomId: "...", parent: "12")
+
+Use `simulate_trigger_zone_input` for Trigger cube `pressBtn` behavior. This is not a global `OnKeyPressedEvent`; it gates the Trigger's `OnEnterEvent` tasks until the player enters the zone and presses `keyCode`.
+```
+simulate_trigger_zone_input(filePath: ".../snapshot.json", actions: [{type: "enter", itemId: "12"}, {type: "press", key: "X"}])
+simulate_trigger_zone_input(filePath: ".../snapshot.json", actions: [{type: "press", key: "X"}, {type: "enter", itemId: "12"}])
 ```
 
 ## Scripts (manual / Blender)

package/dist/resources/python/lib/portals_core.py

@@ -16,6 +16,8 @@ Usage:
 
 from typing import Dict, Tuple, Optional
 
+from portals_key_input import validate_key_code
+
 
 def create_base_item(
     prefab_name: str,
@@ -350,12 +352,14 @@ def create_trigger(
     Notes:
         - Invisible during play (visible in build mode)
         - Two trigger types: User Enter and User Exit
+        - If press_button=True, OnEnterEvent tasks fire after the player enters
+          the zone and presses key_code; this is separate from OnKeyPressedEvent.
         - Add effects via Tasks array (see portals_effects.py)
     """
     logic = {
         "events": [],
         "cm": message,
-        "keyCode": key_code,
+        "keyCode": validate_key_code(key_code, "key_code"),
         "Tasks": [],
         "ViewNodes": []
     }