portals-mcp 1.3.0 → 1.3.2

package/README.md

@@ -52,6 +52,8 @@ npx portals-mcp@latest
 | `duplicate_room` | Clone a room with all data |
 | `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/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/triggers.json

@@ -1,210 +1,217 @@
-{
-  "version": "0.1.0",
-  "description": "Compact lookup of all Portals triggers. applicable_items='any' means general trigger; specific prefabNames means item-specific.",
-  "triggers": [
-    {
-      "$type": "OnClickEvent",
-      "description": "Player clicks item",
-      "applicable_items": "any",
-      "gotchas": ["Requires VISIBLE item — NEVER use on Trigger cubes (invisible)"]
-    },
-    {
-      "$type": "OnEnterEvent",
-      "description": "Player enters trigger zone",
-      "applicable_items": ["Trigger"],
-      "gotchas": ["ONLY works on Trigger cubes, not ResizableCubes or GLBs"]
-    },
-    {
-      "$type": "OnExitEvent",
-      "description": "Player exits trigger zone",
-      "applicable_items": ["Trigger"],
-      "gotchas": ["ONLY works on Trigger cubes, not ResizableCubes or GLBs"]
-    },
-    {
-      "$type": "OnCollideEvent",
-      "description": "Player collides with item",
-      "applicable_items": "any",
-      "gotchas": []
-    },
-    {
-      "$type": "OnCollisionStoppedEvent",
-      "description": "Player stops colliding with item",
-      "applicable_items": "any",
-      "gotchas": []
-    },
-    {
-      "$type": "OnHoverStartEvent",
-      "description": "Cursor enters item",
-      "applicable_items": "any",
-      "gotchas": ["Requires VISIBLE item — NEVER use on Trigger cubes (invisible)"]
-    },
-    {
-      "$type": "OnHoverEndEvent",
-      "description": "Cursor leaves item",
-      "applicable_items": "any",
-      "gotchas": ["Requires VISIBLE item — NEVER use on Trigger cubes (invisible)"]
-    },
-    {
-      "$type": "OnKeyPressedEvent",
-      "description": "Keyboard key pressed down",
-      "applicable_items": "any",
-      "gotchas": []
-    },
-    {
-      "$type": "OnKeyReleasedEvent",
-      "description": "Keyboard key released",
-      "applicable_items": "any",
-      "gotchas": []
-    },
-    {
-      "$type": "ScoreTrigger",
-      "description": "Variable value changes",
-      "applicable_items": "any",
-      "gotchas": ["Fires on ANY variable change — use FunctionEffector to filter by specific variable"]
-    },
-    {
-      "$type": "OnItemCollectedEvent",
-      "description": "Collectible item picked up",
-      "applicable_items": ["GlbCollectable"],
-      "gotchas": []
-    },
-    {
-      "$type": "OnPlayerLoggedIn",
-      "description": "Player joins room — primary 'game start' trigger",
-      "applicable_items": "any",
-      "gotchas": ["Fires once per player per room join. Use for init: variables, sounds, hide/show, equip."]
-    },
-    {
-      "$type": "OnPlayerDied",
-      "description": "Player health reaches 0",
-      "applicable_items": "any",
-      "gotchas": []
-    },
-    {
-      "$type": "OnPlayerRevived",
-      "description": "Player revives after death",
-      "applicable_items": "any",
-      "gotchas": []
-    },
-    {
-      "$type": "OnPlayerMove",
-      "description": "Player starts moving",
-      "applicable_items": "any",
-      "gotchas": []
-    },
-    {
-      "$type": "OnPlayerStoppedMoving",
-      "description": "Player stops moving",
-      "applicable_items": "any",
-      "gotchas": []
-    },
-    {
-      "$type": "PlayerLeave",
-      "description": "Player leaves room",
-      "applicable_items": "any",
-      "gotchas": []
-    },
-    {
-      "$type": "OnMicrophoneUnmuted",
-      "description": "Player unmutes microphone",
-      "applicable_items": "any",
-      "gotchas": []
-    },
-    {
-      "$type": "OnTimerStopped",
-      "description": "Named timer stopped via StopTimerEffect",
-      "applicable_items": "any",
-      "gotchas": ["Only fires when StopTimerEffect is used, not CancelTimerEffect"]
-    },
-    {
-      "$type": "OnCountdownTimerFinished",
-      "description": "Countdown timer reaches 0",
-      "applicable_items": "any",
-      "gotchas": []
-    },
-    {
-      "$type": "OnAnimationStoppedEvent",
-      "description": "PortalsAnimation finishes playing",
-      "applicable_items": "any",
-      "gotchas": ["Fires when a PortalsAnimation completes, not GLB embedded animations"]
-    },
-    {
-      "$type": "OnItemClickEvent",
-      "description": "Backpack/inventory item activated",
-      "applicable_items": "any",
-      "gotchas": []
-    },
-    {
-      "$type": "SwapVolume",
-      "description": "Swap volume trigger",
-      "applicable_items": "any",
-      "gotchas": []
-    },
-    {
-      "$type": "OnDestroyedEvent",
-      "description": "Destructible item destroyed",
-      "applicable_items": ["Destructible"],
-      "gotchas": []
-    },
-    {
-      "$type": "OnGunEquippedTrigger",
-      "description": "Player equips a gun",
-      "applicable_items": ["Gun", "Shotgun"],
-      "gotchas": []
-    },
-    {
-      "$type": "ShotHitTrigger",
-      "description": "Bullet hits a target",
-      "applicable_items": ["Gun", "Shotgun"],
-      "gotchas": []
-    },
-    {
-      "$type": "GotKillTrigger",
-      "description": "Player gets a kill with gun",
-      "applicable_items": ["Gun", "Shotgun"],
-      "gotchas": []
-    },
-    {
-      "$type": "StartedAimingTrigger",
-      "description": "Player aims down sights",
-      "applicable_items": ["Gun", "Shotgun"],
-      "gotchas": []
-    },
-    {
-      "$type": "StoppedAimingTrigger",
-      "description": "Player stops aiming",
-      "applicable_items": ["Gun", "Shotgun"],
-      "gotchas": []
-    },
-    {
-      "$type": "OnGunTossedTrigger",
-      "description": "Player drops/tosses gun",
-      "applicable_items": ["Gun", "Shotgun"],
-      "gotchas": []
-    },
-    {
-      "$type": "OnVehicleEntered",
-      "description": "Player enters vehicle",
-      "applicable_items": ["Vehicle"],
-      "gotchas": []
-    },
-    {
-      "$type": "OnVehicleExited",
-      "description": "Player exits vehicle",
-      "applicable_items": ["Vehicle"],
-      "gotchas": []
-    },
-    {
-      "$type": "OnEnemyDied",
-      "description": "Enemy NPC killed",
-      "applicable_items": ["EnemyNPC"],
-      "gotchas": []
-    },
-    {
-      "$type": "OnTakeDamageTrigger",
-      "description": "Enemy NPC took damage",
-      "applicable_items": ["EnemyNPC"],
-      "gotchas": []
-    }
-  ]
-}
+{
+  "version": "0.1.0",
+  "description": "Compact lookup of all Portals triggers. applicable_items='any' means general trigger; specific prefabNames means item-specific.",
+  "triggers": [
+    {
+      "$type": "OnClickEvent",
+      "description": "Player clicks item",
+      "applicable_items": "any",
+      "gotchas": ["Requires VISIBLE item — NEVER use on Trigger cubes (invisible)"]
+    },
+    {
+      "$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.",
+      "applicable_items": ["Trigger"],
+      "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",
+      "description": "Player exits trigger zone",
+      "applicable_items": ["Trigger"],
+      "gotchas": ["ONLY works on Trigger cubes, not ResizableCubes or GLBs"]
+    },
+    {
+      "$type": "OnCollideEvent",
+      "description": "Player collides with item",
+      "applicable_items": "any",
+      "gotchas": []
+    },
+    {
+      "$type": "OnCollisionStoppedEvent",
+      "description": "Player stops colliding with item",
+      "applicable_items": "any",
+      "gotchas": []
+    },
+    {
+      "$type": "OnHoverStartEvent",
+      "description": "Cursor enters item",
+      "applicable_items": "any",
+      "gotchas": ["Requires VISIBLE item — NEVER use on Trigger cubes (invisible)"]
+    },
+    {
+      "$type": "OnHoverEndEvent",
+      "description": "Cursor leaves item",
+      "applicable_items": "any",
+      "gotchas": ["Requires VISIBLE item — NEVER use on Trigger cubes (invisible)"]
+    },
+    {
+      "$type": "OnKeyPressedEvent",
+      "description": "Keyboard key pressed down",
+      "applicable_items": "any",
+      "params": {
+        "key": "required InputHandler key-code string, e.g. Alpha1, Space, Return, LeftShift",
+        "key2": "optional second key-code string for combinations; fires when either configured key goes down while the other is held"
+      },
+      "gotchas": ["Requires key. Use Unity/Portals key names, not DOM names: Alpha1 not 1/Digit1, Return not Enter, LeftArrow not ArrowLeft."]
+    },
+    {
+      "$type": "OnKeyReleasedEvent",
+      "description": "Keyboard key released",
+      "applicable_items": "any",
+      "params": {
+        "key": "required InputHandler key-code string, e.g. Alpha1, Space, Return, LeftShift"
+      },
+      "gotchas": ["Requires key. key2 combinations are only supported by OnKeyPressedEvent, not OnKeyReleasedEvent."]
+    },
+    {
+      "$type": "ScoreTrigger",
+      "description": "Variable value changes",
+      "applicable_items": "any",
+      "gotchas": ["Fires on ANY variable change — use FunctionEffector to filter by specific variable"]
+    },
+    {
+      "$type": "OnItemCollectedEvent",
+      "description": "Collectible item picked up",
+      "applicable_items": ["GlbCollectable"],
+      "gotchas": []
+    },
+    {
+      "$type": "OnPlayerLoggedIn",
+      "description": "Player joins room — primary 'game start' trigger",
+      "applicable_items": "any",
+      "gotchas": ["Fires once per player per room join. Use for init: variables, sounds, hide/show, equip."]
+    },
+    {
+      "$type": "OnPlayerDied",
+      "description": "Player health reaches 0",
+      "applicable_items": "any",
+      "gotchas": []
+    },
+    {
+      "$type": "OnPlayerRevived",
+      "description": "Player revives after death",
+      "applicable_items": "any",
+      "gotchas": []
+    },
+    {
+      "$type": "OnPlayerMove",
+      "description": "Player starts moving",
+      "applicable_items": "any",
+      "gotchas": []
+    },
+    {
+      "$type": "OnPlayerStoppedMoving",
+      "description": "Player stops moving",
+      "applicable_items": "any",
+      "gotchas": []
+    },
+    {
+      "$type": "PlayerLeave",
+      "description": "Player leaves room",
+      "applicable_items": "any",
+      "gotchas": []
+    },
+    {
+      "$type": "OnMicrophoneUnmuted",
+      "description": "Player unmutes microphone",
+      "applicable_items": "any",
+      "gotchas": []
+    },
+    {
+      "$type": "OnTimerStopped",
+      "description": "Named timer stopped via StopTimerEffect",
+      "applicable_items": "any",
+      "gotchas": ["Only fires when StopTimerEffect is used, not CancelTimerEffect"]
+    },
+    {
+      "$type": "OnCountdownTimerFinished",
+      "description": "Countdown timer reaches 0",
+      "applicable_items": "any",
+      "gotchas": []
+    },
+    {
+      "$type": "OnAnimationStoppedEvent",
+      "description": "PortalsAnimation finishes playing",
+      "applicable_items": "any",
+      "gotchas": ["Fires when a PortalsAnimation completes, not GLB embedded animations"]
+    },
+    {
+      "$type": "OnItemClickEvent",
+      "description": "Backpack/inventory item activated",
+      "applicable_items": "any",
+      "gotchas": []
+    },
+    {
+      "$type": "SwapVolume",
+      "description": "Swap volume trigger",
+      "applicable_items": "any",
+      "gotchas": []
+    },
+    {
+      "$type": "OnDestroyedEvent",
+      "description": "Destructible item destroyed",
+      "applicable_items": ["Destructible"],
+      "gotchas": []
+    },
+    {
+      "$type": "OnGunEquippedTrigger",
+      "description": "Player equips a gun",
+      "applicable_items": ["Gun", "Shotgun"],
+      "gotchas": []
+    },
+    {
+      "$type": "ShotHitTrigger",
+      "description": "Bullet hits a target",
+      "applicable_items": ["Gun", "Shotgun"],
+      "gotchas": []
+    },
+    {
+      "$type": "GotKillTrigger",
+      "description": "Player gets a kill with gun",
+      "applicable_items": ["Gun", "Shotgun"],
+      "gotchas": []
+    },
+    {
+      "$type": "StartedAimingTrigger",
+      "description": "Player aims down sights",
+      "applicable_items": ["Gun", "Shotgun"],
+      "gotchas": []
+    },
+    {
+      "$type": "StoppedAimingTrigger",
+      "description": "Player stops aiming",
+      "applicable_items": ["Gun", "Shotgun"],
+      "gotchas": []
+    },
+    {
+      "$type": "OnGunTossedTrigger",
+      "description": "Player drops/tosses gun",
+      "applicable_items": ["Gun", "Shotgun"],
+      "gotchas": []
+    },
+    {
+      "$type": "OnVehicleEntered",
+      "description": "Player enters vehicle",
+      "applicable_items": ["Vehicle"],
+      "gotchas": []
+    },
+    {
+      "$type": "OnVehicleExited",
+      "description": "Player exits vehicle",
+      "applicable_items": ["Vehicle"],
+      "gotchas": []
+    },
+    {
+      "$type": "OnEnemyDied",
+      "description": "Enemy NPC killed",
+      "applicable_items": ["EnemyNPC"],
+      "gotchas": []
+    },
+    {
+      "$type": "OnTakeDamageTrigger",
+      "description": "Enemy NPC took damage",
+      "applicable_items": ["EnemyNPC"],
+      "gotchas": []
+    }
+  ]
+}

package/dist/resources/python/README.md

@@ -1,50 +1,68 @@
-# Portals Python Toolkit
-
-The Python toolkit provides validation, room analysis, and query tools. It is bundled inside the MCP server.
-
-## How Tools Run
-
-**Automatic** — these run without you calling them:
-- `validate_room.py` runs automatically before every `apply_operations` and `set_room_data` push. If validation fails, the push is blocked.
-- `index_room.py` runs automatically after every `get_room_data` pull. The index file path is returned alongside the data file.
-
-**Via dedicated MCP tools**:
-- `query_room` — search items by type, position, triggers, text, parent, or quest reference
-- `apply_operations` — add, modify, remove items/logic/quests (auto-pulls fresh data, auto-validates)
-- `get_room_data` — download room data with auto-generated index
-
-## Building Rooms
-
-Use `apply_operations` for all room building — from simple edits to complex 200+ item builds. Key operations:
-
-- **`add_item`** — place a single item
-- **`add_item_with_logic`** — place an item AND attach trigger/effect logic in one step
-- **`modify_item`** / **`remove_item`** — edit or delete existing items
-- **`add_logic_task`** / **`clear_logic_tasks`** — wire interactions onto existing items
-- **`add_quest`** / **`remove_quest`** — manage quests
-- **`add_component`** — use pre-built component patterns (use `lookup("components")` to discover available components)
-
-**Cross-item references**: Use `"__ref:N"` to reference items created earlier in the same batch. Example: `[{op:"add_item", type:"ResizableCube", pos:[0,1,0]}, {op:"add_logic_task", id:"__ref:0", task:{...}}]`
-
-For bulk builds, pass hundreds of operations in a single `apply_operations` call.
-
-## Querying Room Data
-
-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")
-```
-
-## Scripts (manual / Blender)
-| Script | Purpose | Usage |
-|--------|---------|-------|
-| `blender_to_portals.py` | Headless Blender export | `blender --background <file> --python tools/blender_to_portals.py -- <output>` |
-| `extract_glb_metadata.py` | Extract GLB dimensions/thumbnails (needs numpy, trimesh) | `python tools/extract_glb_metadata.py <glbs> <room-id>` |
-| `classify_modular_edges.py` | Classify modular kit edges (needs numpy, trimesh) | After extract |
-| `manifest_to_room_data.py` | Convert Blender manifest to snapshot | `python tools/manifest_to_room_data.py <export-dir> --cdn-urls <urls.json>` |
-| `search_recipes.py` | Search recipes (use MCP `search_recipes` tool instead) | — |
-| `build_recipe_manifest.py` | Regenerate recipe manifest | After adding/editing recipes |
-| `parse_cdn_upload.py` | Parse CDN upload results | After batch upload |
+# Portals Python Toolkit
+
+The Python toolkit provides validation, room analysis, and query tools. It is bundled inside the MCP server.
+
+## How Tools Run
+
+**Automatic** — these run without you calling them:
+- `validate_room.py` runs automatically before every `apply_operations` and `set_room_data` push. If validation fails, the push is blocked.
+- `index_room.py` runs automatically after every `get_room_data` pull. The index file path is returned alongside the data file.
+
+**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
+
+## Building Rooms
+
+Use `apply_operations` for all room building — from simple edits to complex 200+ item builds. Key operations:
+
+- **`add_item`** — place a single item
+- **`add_item_with_logic`** — place an item AND attach trigger/effect logic in one step
+- **`modify_item`** / **`remove_item`** — edit or delete existing items
+- **`add_logic_task`** / **`clear_logic_tasks`** — wire interactions onto existing items
+- **`add_quest`** / **`remove_quest`** — manage quests
+- **`add_component`** — use pre-built component patterns (use `lookup("components")` to discover available components)
+
+**Cross-item references**: Use `"__ref:N"` to reference items created earlier in the same batch. Example: `[{op:"add_item", type:"ResizableCube", pos:[0,1,0]}, {op:"add_logic_task", id:"__ref:0", task:{...}}]`
+
+For bulk builds, pass hundreds of operations in a single `apply_operations` call.
+
+## Querying Room Data
+
+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
+
+Use `simulate_key_input` before live testing `OnKeyPressedEvent` / `OnKeyReleasedEvent` logic:
+```
+simulate_key_input(filePath: ".../snapshot.json", actions: [{type: "press", key: "Alpha1"}])
+simulate_key_input(filePath: ".../snapshot.json", actions: [{type: "press", key: "LeftShift"}, {type: "press", key: "Alpha1"}])
+```
+
+Keyboard trigger keys must use Portals/Unity key-code names such as `Alpha1`, `Space`, `Return`, `LeftShift`, and `LeftArrow`.
+
+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)
+| Script | Purpose | Usage |
+|--------|---------|-------|
+| `blender_to_portals.py` | Headless Blender export | `blender --background <file> --python tools/blender_to_portals.py -- <output>` |
+| `extract_glb_metadata.py` | Extract GLB dimensions/thumbnails (needs numpy, trimesh) | `python tools/extract_glb_metadata.py <glbs> <room-id>` |
+| `classify_modular_edges.py` | Classify modular kit edges (needs numpy, trimesh) | After extract |
+| `manifest_to_room_data.py` | Convert Blender manifest to snapshot | `python tools/manifest_to_room_data.py <export-dir> --cdn-urls <urls.json>` |
+| `search_recipes.py` | Search recipes (use MCP `search_recipes` tool instead) | — |
+| `build_recipe_manifest.py` | Regenerate recipe manifest | After adding/editing recipes |
+| `parse_cdn_upload.py` | Parse CDN upload results | After batch upload |

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": []
     }