portals-mcp 1.3.1 → 1.3.2

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/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

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

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

@@ -0,0 +1,293 @@
+"""
+Portals trigger-zone press-to-activate auditing and simulation helpers.
+
+Mirrors Core/Assets/Core/Scripts/MultiplayerBridgeTrigger.cs:
+- On enter, Trigger zones fire OnEnterEvent immediately unless pressBtn is true.
+- With pressBtn true, the player must be inside the zone and press keyCode.
+- Empty keyCode falls back to X in the client.
+- OnExitEvent still fires when the player exits the zone.
+"""
+
+from typing import Any, Dict, Iterable, List, Optional, Set, Tuple
+
+from portals_key_input import (
+    VALID_KEY_CODES,
+    VALID_KEY_CODE_SET,
+    canonical_key_code,
+    load_snapshot_logic,
+    validate_key_code,
+)
+
+
+ENTER_TRIGGER_TYPES = {"OnEnterEvent"}
+EXIT_TRIGGER_TYPES = {"OnExitEvent", "UserExitTrigger"}
+
+
+def _task_summary(item_id: str, task_index: int, task: Dict[str, Any], trigger: Dict[str, Any]) -> Dict[str, Any]:
+    direct = task.get("DirectEffector")
+    effector = direct.get("Effector") if isinstance(direct, dict) else None
+    return {
+        "item_id": item_id,
+        "task_index": task_index,
+        "task_id": task.get("Id"),
+        "task_name": task.get("Name", ""),
+        "task_trigger_id": task.get("TaskTriggerId"),
+        "target_state": task.get("TargetState"),
+        "trigger": trigger,
+        "direct_effector_id": direct.get("Id") if isinstance(direct, dict) else None,
+        "direct_effector_type": effector.get("$type") if isinstance(effector, dict) else None,
+    }
+
+
+def _collect_zone_tasks(item_id: str, entry: Dict[str, Any], trigger_types: Set[str]) -> List[Dict[str, Any]]:
+    tasks = entry.get("Tasks", [])
+    if not isinstance(tasks, list):
+        return []
+
+    matches: List[Dict[str, Any]] = []
+    for task_index, task in enumerate(tasks):
+        if not isinstance(task, dict) or task.get("$type") != "TaskTriggerSubscription":
+            continue
+        trigger = task.get("Trigger")
+        if not isinstance(trigger, dict):
+            continue
+        if trigger.get("$type") in trigger_types:
+            matches.append(_task_summary(item_id, task_index, task, trigger))
+    return matches
+
+
+def _collect_global_key_tasks(item_id: str, entry: Dict[str, Any]) -> List[Dict[str, Any]]:
+    tasks = entry.get("Tasks", [])
+    if not isinstance(tasks, list):
+        return []
+
+    matches: List[Dict[str, Any]] = []
+    for task_index, task in enumerate(tasks):
+        if not isinstance(task, dict) or task.get("$type") != "TaskTriggerSubscription":
+            continue
+        trigger = task.get("Trigger")
+        if not isinstance(trigger, dict):
+            continue
+        if trigger.get("$type") in ("OnKeyPressedEvent", "OnKeyReleasedEvent"):
+            matches.append(_task_summary(item_id, task_index, task, trigger))
+    return matches
+
+
+def collect_trigger_zone_audit(
+    room_items: Dict[str, Any],
+    logic: Dict[str, Dict[str, Any]],
+) -> Dict[str, Any]:
+    """Collect Trigger-zone pressBtn/keyCode configuration and static warnings."""
+    zones: List[Dict[str, Any]] = []
+    warnings: List[str] = []
+
+    for item_id, item in room_items.items():
+        if not isinstance(item, dict) or item.get("prefabName") != "Trigger":
+            continue
+
+        item_key = str(item_id)
+        entry = logic.get(item_key, {})
+        if not isinstance(entry, dict):
+            entry = {}
+
+        press_button_raw = entry.get("pressBtn", False)
+        press_button = press_button_raw is True
+        key_code_raw = entry.get("keyCode")
+        key_code = "" if key_code_raw is None else str(key_code_raw)
+        effective_key_code = "X" if key_code == "" else key_code
+        activation_tasks = _collect_zone_tasks(item_key, entry, ENTER_TRIGGER_TYPES)
+        exit_tasks = _collect_zone_tasks(item_key, entry, EXIT_TRIGGER_TYPES)
+        global_key_tasks = _collect_global_key_tasks(item_key, entry)
+        legacy_events = entry.get("events", [])
+        legacy_event_count = len(legacy_events) if isinstance(legacy_events, list) else 0
+
+        zone_warnings: List[str] = []
+        key_valid = True
+        if "pressBtn" in entry and not isinstance(press_button_raw, bool):
+            zone_warnings.append(f'pressBtn must be a boolean, got {type(press_button_raw).__name__}.')
+
+        if key_code_raw is None:
+            key_valid = False
+            zone_warnings.append('Trigger extraData missing required "keyCode"; upload validation rejects this.')
+        elif not isinstance(key_code_raw, str):
+            key_valid = False
+            zone_warnings.append(f'keyCode must be a string key-code name, got {type(key_code_raw).__name__}.')
+        elif key_code and key_code not in VALID_KEY_CODE_SET:
+            key_valid = False
+            suggestion = canonical_key_code(key_code)
+            suffix = f' Did you mean "{suggestion}"?' if suggestion != key_code and suggestion in VALID_KEY_CODE_SET else ""
+            zone_warnings.append(f'keyCode "{key_code}" is not in InputHandler.keyCodeMap.{suffix}')
+
+        if press_button:
+            if not activation_tasks and legacy_event_count == 0:
+                zone_warnings.append("pressBtn is true but the Trigger has no OnEnterEvent tasks or legacy events to activate.")
+            if global_key_tasks:
+                zone_warnings.append(
+                    "This Trigger also has OnKeyPressedEvent/OnKeyReleasedEvent tasks. Those are global key subscriptions, "
+                    "not zone-gated; use pressBtn + OnEnterEvent for press-inside-zone behavior."
+                )
+        elif key_code not in ("", "X") and key_valid:
+            zone_warnings.append('keyCode is ignored while pressBtn is false; OnEnterEvent fires immediately on zone entry.')
+
+        zone = {
+            "item_id": item_key,
+            "title": entry.get("title", ""),
+            "press_button": press_button,
+            "key_code": key_code,
+            "effective_key_code": effective_key_code,
+            "key_valid": key_valid,
+            "message": entry.get("cm", ""),
+            "behavior": "press_key_while_inside" if press_button else "auto_on_enter",
+            "activation_tasks": activation_tasks,
+            "activation_task_count": len(activation_tasks),
+            "exit_tasks": exit_tasks,
+            "exit_task_count": len(exit_tasks),
+            "legacy_event_count": legacy_event_count,
+            "global_key_tasks": global_key_tasks,
+            "global_key_task_count": len(global_key_tasks),
+            "warnings": zone_warnings,
+        }
+        zones.append(zone)
+        for warning in zone_warnings:
+            warnings.append(f"item {item_key}, Trigger: {warning}")
+
+    return {
+        "zones": zones,
+        "warnings": warnings,
+        "valid_key_codes": list(VALID_KEY_CODES),
+        "semantics": {
+            "auto_on_enter": "pressBtn false or omitted: entering the Trigger calls OnEnterEvent tasks immediately.",
+            "press_key_while_inside": "pressBtn true: entering only arms the zone; pressing keyCode while still inside calls OnEnterEvent tasks.",
+            "exit": "OnExitEvent tasks fire on exit even when pressBtn is true.",
+            "not_global_key": "pressBtn does not create OnKeyPressedEvent subscriptions; OnKeyPressedEvent remains global and is not zone-gated.",
+        },
+    }
+
+
+def _normalize_zone_action(action: Any) -> Dict[str, str]:
+    if isinstance(action, str):
+        if ":" not in action:
+            raise ValueError(f'Action string "{action}" must be "enter:<itemId>", "exit:<itemId>", "press:<key>", or "release:<key>"')
+        action_type, value = action.split(":", 1)
+        key = "key" if action_type.lower() in ("press", "release") else "itemId"
+        action = {"type": action_type, key: value}
+    if not isinstance(action, dict):
+        raise ValueError(f"Action must be a dict or action string, got {type(action).__name__}")
+
+    action_type = str(action.get("type", "")).lower()
+    if action_type in ("enter", "exit"):
+        item_id = action.get("itemId", action.get("item_id", action.get("id", "")))
+        if item_id in (None, ""):
+            raise ValueError(f'{action_type} action requires "itemId"')
+        return {"type": action_type, "item_id": str(item_id)}
+    if action_type in ("press", "release"):
+        key = validate_key_code(str(action.get("key", "")), "action.key")
+        return {"type": action_type, "key": key}
+
+    raise ValueError(f'Action type must be "enter", "exit", "press", or "release", got "{action_type}"')
+
+
+def simulate_trigger_zone_sequence(
+    room_items: Dict[str, Any],
+    logic: Dict[str, Dict[str, Any]],
+    actions: Iterable[Any],
+) -> Dict[str, Any]:
+    """Simulate zone enter/exit plus key frames and report matching OnEnter/OnExit tasks."""
+    audit = collect_trigger_zone_audit(room_items, logic)
+    zones_by_id = {zone["item_id"]: zone for zone in audit["zones"]}
+    normalized_actions = [_normalize_zone_action(action) for action in actions]
+
+    inside: Set[str] = set()
+    armed: Set[str] = set()
+    held: Set[str] = set()
+    frames: List[Dict[str, Any]] = []
+
+    for index, action in enumerate(normalized_actions):
+        fired: List[Dict[str, Any]] = []
+        prompts: List[Dict[str, Any]] = []
+        ignored: List[str] = []
+        key_down: Set[str] = set()
+        key_up: Set[str] = set()
+
+        action_type = action["type"]
+        if action_type == "enter":
+            item_id = action["item_id"]
+            zone = zones_by_id.get(item_id)
+            if not zone:
+                ignored.append(f'item "{item_id}" is not a Trigger zone in this snapshot')
+            else:
+                inside.add(item_id)
+                if zone["press_button"]:
+                    armed.add(item_id)
+                    prompts.append({
+                        "item_id": item_id,
+                        "message": zone["message"],
+                        "key": zone["effective_key_code"],
+                    })
+                else:
+                    fired.extend(zone["activation_tasks"])
+        elif action_type == "exit":
+            item_id = action["item_id"]
+            zone = zones_by_id.get(item_id)
+            if not zone:
+                ignored.append(f'item "{item_id}" is not a Trigger zone in this snapshot')
+            elif item_id not in inside:
+                ignored.append(f'item "{item_id}" exit ignored because the simulated player is not inside it')
+            else:
+                fired.extend(zone["exit_tasks"])
+                inside.remove(item_id)
+                armed.discard(item_id)
+        elif action_type == "press":
+            key = action["key"]
+            if key not in held:
+                held.add(key)
+                key_down.add(key)
+                for item_id in sorted(armed):
+                    zone = zones_by_id[item_id]
+                    if not zone["key_valid"]:
+                        continue
+                    if zone["effective_key_code"] == key:
+                        fired.extend(zone["activation_tasks"])
+                        armed.remove(item_id)
+            else:
+                ignored.append(f'key "{key}" is already held; Unity GetKeyDown would be false')
+        elif action_type == "release":
+            key = action["key"]
+            if key in held:
+                held.remove(key)
+                key_up.add(key)
+            else:
+                ignored.append(f'key "{key}" was not held; Unity GetKeyUp would be false')
+
+        frames.append({
+            "index": index,
+            "action": action,
+            "key_down": sorted(key_down),
+            "key_up": sorted(key_up),
+            "held_after": sorted(held),
+            "inside_after": sorted(inside),
+            "armed_after": sorted(armed),
+            "prompts": prompts,
+            "fired": fired,
+            "ignored": ignored,
+        })
+
+    fired_count = sum(len(frame["fired"]) for frame in frames)
+    return {
+        **audit,
+        "simulation": {
+            "actions": normalized_actions,
+            "frames": frames,
+            "fired_count": fired_count,
+        },
+    }
+
+
+def audit_snapshot_trigger_zones(snapshot_path: str, actions: Optional[Iterable[Any]] = None) -> Dict[str, Any]:
+    room_items, logic = load_snapshot_logic(snapshot_path)
+    if actions is None:
+        return {
+            **collect_trigger_zone_audit(room_items, logic),
+            "simulation": None,
+        }
+    return simulate_trigger_zone_sequence(room_items, logic, actions)

package/dist/resources/python/tools/simulate_trigger_zone_input.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""
+simulate_trigger_zone_input.py - Audit and simulate Trigger pressBtn/keyCode behavior.
+
+Usage:
+    python3 simulate_trigger_zone_input.py snapshot.json
+    python3 simulate_trigger_zone_input.py snapshot.json --action enter:12 --action press:X --action exit:12
+    python3 simulate_trigger_zone_input.py snapshot.json --actions actions.json
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, List
+
+PROJECT_ROOT = Path(__file__).parent.parent
+sys.path.insert(0, str(PROJECT_ROOT / "lib"))
+
+from portals_key_input import VALID_KEY_CODES
+from portals_trigger_zone_input import audit_snapshot_trigger_zones
+
+
+def _load_actions(path: str) -> List[Any]:
+    with open(path, "r", encoding="utf-8") as f:
+        actions = json.load(f)
+    if not isinstance(actions, list):
+        raise ValueError("--actions file must contain a JSON array")
+    return actions
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Audit Portals Trigger pressBtn/keyCode behavior and simulate enter/exit/key input.",
+    )
+    parser.add_argument("snapshot", nargs="?", help="Path to snapshot.json")
+    parser.add_argument(
+        "--action",
+        action="append",
+        default=[],
+        help='Action to simulate, e.g. "enter:12", "press:X", "release:X", or "exit:12". May be repeated.',
+    )
+    parser.add_argument(
+        "--actions",
+        help='Path to a JSON array of actions, e.g. [{"type":"enter","itemId":"12"},{"type":"press","key":"X"}].',
+    )
+    parser.add_argument("--pretty", action="store_true", help="Pretty-print JSON output.")
+    parser.add_argument("--list-keys", action="store_true", help="List valid key-code strings and exit.")
+
+    args = parser.parse_args()
+
+    if args.list_keys:
+        print(json.dumps({"ok": True, "valid_key_codes": list(VALID_KEY_CODES)}, indent=2 if args.pretty else None))
+        return
+
+    if not args.snapshot:
+        print(json.dumps({"ok": False, "error": "snapshot path is required unless --list-keys is used"}))
+        sys.exit(1)
+
+    if not Path(args.snapshot).is_file():
+        print(json.dumps({"ok": False, "error": f"Snapshot file not found: {args.snapshot}"}))
+        sys.exit(1)
+
+    try:
+        actions = None
+        if args.actions:
+            actions = _load_actions(args.actions)
+        if args.action:
+            actions = (actions or []) + args.action
+
+        result = audit_snapshot_trigger_zones(args.snapshot, actions)
+        result["ok"] = True
+        result["snapshot"] = str(Path(args.snapshot).resolve())
+        print(json.dumps(result, indent=2 if args.pretty else None))
+    except Exception as exc:
+        print(json.dumps({"ok": False, "error": str(exc)}))
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/dist/resources/python/tools/validate_room.py

@@ -24,7 +24,7 @@ sys.path.insert(0, str(PROJECT_ROOT / "lib"))
 
 from portals_utils import validate_quest_name, validate_color, parse_extra_data, normalize_snapshot
 from portals_effects import EFFECT_TYPES, TRIGGER_TYPES
-from portals_key_input import VALID_KEY_CODE_SET
+from portals_key_input import VALID_KEY_CODE_SET, canonical_key_code
 
 
 # ============================================================================
@@ -573,6 +573,19 @@ def validate_item_extra_data(item_key: str, prefab: str, extra: dict, content_st
             if key not in extra:
                 errors.append(fmt(section, f'extraData missing required key "{key}"'))
 
+    if prefab == "Trigger":
+        if "pressBtn" in extra and not isinstance(extra["pressBtn"], bool):
+            errors.append(fmt(section, f'extraData "pressBtn" must be a boolean, got {type(extra["pressBtn"]).__name__}'))
+
+        key_code = extra.get("keyCode")
+        if key_code is not None:
+            if not isinstance(key_code, str):
+                errors.append(fmt(section, f'extraData "keyCode" must be a string InputHandler key-code name, got {type(key_code).__name__}'))
+            elif key_code and key_code not in VALID_KEY_CODE_SET:
+                suggestion = canonical_key_code(key_code)
+                suffix = f' Did you mean "{suggestion}"?' if suggestion != key_code and suggestion in VALID_KEY_CODE_SET else ""
+                errors.append(fmt(section, f'extraData "keyCode" "{key_code}" is not in InputHandler.keyCodeMap.{suffix}'))
+
     # Addressable VFX validation
     if prefab == "Addressable":
         if not content_string:

package/dist/resources/ref/items/trigger-zone.json

@@ -1,56 +1,59 @@
-{
-  "id": "item:trigger-zone",
-  "name": "Trigger Zone",
-  "prefabName": "Trigger",
-  "category": "gameplay",
-  "description": "Invisible zone that activates events when players enter, exit, or press a key while inside. Invisible during play -- visible only in build mode.",
-  "placement": {
-    "default_y": 0.5,
-    "notes": "Same placement as cubes. y=0.5 for a 1x1x1 trigger on the ground. Scale to cover the desired area."
-  },
-  "fields": {
-    "pos": { "type": "Vector3", "desc": "World position", "default": {"x": 0, "y": 0.5, "z": 0} },
-    "rot": { "type": "Quaternion", "desc": "Rotation quaternion", "default": {"x": 0, "y": 0, "z": 0, "w": 1} },
-    "scale": { "type": "Vector3", "desc": "Zone dimensions. Scale up for larger detection area.", "default": {"x": 1, "y": 1, "z": 1} }
-  },
-  "extra_data_fields": {
-    "events": { "type": "array", "desc": "Array of events. Usually [] when using Tasks.", "default": [] },
-    "pressBtn": { "type": "bool", "desc": "true = require key press while inside. Omit for auto-trigger on enter.", "default": false },
-    "keyCode": { "type": "string", "desc": "Key to press (e.g. 'X', 'H', 'E'). Only used when pressBtn is true.", "default": "X" },
-    "cm": { "type": "string", "desc": "Custom message. Shows 'Press [key] to [message]'.", "default": "" },
-    "opacity": { "type": "float", "desc": "Visual opacity in editor only (0.0-1.0). Does NOT affect gameplay -- triggers are always invisible during play.", "default": null }
-  },
-  "valid_triggers": [
-    "OnEnterEvent",
-    "OnExitEvent",
-    "OnPlayerLoggedIn",
-    "OnKeyPressedEvent",
-    "OnKeyReleasedEvent"
-  ],
-  "gotchas": [
-    "NEVER use OnClickEvent, OnHoverStartEvent, or OnHoverEndEvent -- trigger zones are INVISIBLE during play, so players cannot click or hover over them.",
-    "OnEnterEvent and OnExitEvent ONLY work on Trigger items. They do NOT work on ResizableCubes, GLBs, or other item types.",
-    "Use ActivateTriggerZoneEffect / DeactivateTriggerZoneEffect to enable/disable the zone dynamically.",
-    "For click/hover interactions, use a visible item (ResizableCube, GLB) instead."
-  ],
-  "keyword_map": {
-    "_doc": "Mapping from extraData field names to apply_operations Python keywords",
-    "pressBtn": "press_button",
-    "keyCode": "key_code",
-    "cm": "message"
-  },
-  "create_example": "create_trigger(pos=(0, 0.5, 0), scale=(3, 2, 3), press_button=True, key_code='X', message='activate switch')",
-  "json_example": {
-    "prefabName": "Trigger",
-    "pos": {"x": 0, "y": 0.5, "z": 0},
-    "rot": {"x": 0, "y": 0, "z": 0, "w": 1},
-    "scale": {"x": 3, "y": 2, "z": 3},
-    "extraData": "{\"events\":[],\"pressBtn\":true,\"cm\":\"activate\",\"keyCode\":\"X\",\"Tasks\":[],\"ViewNodes\":[]}",
-    "placed": true
-  },
-  "see_also": [
-    "docs://ref/items/cube",
-    "docs://ref/interactions/basic",
-    "docs://ref/interactions/quest-driven"
-  ]
-}
+{
+  "id": "item:trigger-zone",
+  "name": "Trigger Zone",
+  "prefabName": "Trigger",
+  "category": "gameplay",
+  "description": "Invisible zone that activates OnEnterEvent tasks immediately on entry, or with pressBtn:true after the player enters and presses keyCode. Invisible during play -- visible only in build mode.",
+  "placement": {
+    "default_y": 0.5,
+    "notes": "Same placement as cubes. y=0.5 for a 1x1x1 trigger on the ground. Scale to cover the desired area."
+  },
+  "fields": {
+    "pos": { "type": "Vector3", "desc": "World position", "default": {"x": 0, "y": 0.5, "z": 0} },
+    "rot": { "type": "Quaternion", "desc": "Rotation quaternion", "default": {"x": 0, "y": 0, "z": 0, "w": 1} },
+    "scale": { "type": "Vector3", "desc": "Zone dimensions. Scale up for larger detection area.", "default": {"x": 1, "y": 1, "z": 1} }
+  },
+  "extra_data_fields": {
+    "events": { "type": "array", "desc": "Array of events. Usually [] when using Tasks.", "default": [] },
+    "pressBtn": { "type": "bool", "desc": "true = arm OnEnterEvent on zone entry and fire it only when the player presses keyCode while still inside. Omit/false for immediate OnEnterEvent on entry.", "default": false },
+    "keyCode": { "type": "string", "desc": "InputHandler key-code string to press (e.g. 'X', 'H', 'E', 'Alpha1'). Only used when pressBtn is true; empty falls back to X in the client.", "default": "X" },
+    "cm": { "type": "string", "desc": "Custom message. Shows 'Press [key] to [message]'.", "default": "" },
+    "opacity": { "type": "float", "desc": "Visual opacity in editor only (0.0-1.0). Does NOT affect gameplay -- triggers are always invisible during play.", "default": null }
+  },
+  "valid_triggers": [
+    "OnEnterEvent",
+    "OnExitEvent",
+    "OnPlayerLoggedIn",
+    "OnKeyPressedEvent",
+    "OnKeyReleasedEvent"
+  ],
+  "gotchas": [
+    "NEVER use OnClickEvent, OnHoverStartEvent, or OnHoverEndEvent -- trigger zones are INVISIBLE during play, so players cannot click or hover over them.",
+    "OnEnterEvent and OnExitEvent ONLY work on Trigger items. They do NOT work on ResizableCubes, GLBs, or other item types.",
+    "pressBtn:true gates the Trigger's OnEnterEvent tasks; it is NOT the same as adding an OnKeyPressedEvent task, which is a global key subscription.",
+    "With pressBtn:true, holding the key before entering does not activate the zone; the key must go down while the player is inside.",
+    "OnExitEvent still fires on exit when pressBtn is true.",
+    "Use ActivateTriggerZoneEffect / DeactivateTriggerZoneEffect to enable/disable the zone dynamically.",
+    "For click/hover interactions, use a visible item (ResizableCube, GLB) instead."
+  ],
+  "keyword_map": {
+    "_doc": "Mapping from extraData field names to apply_operations Python keywords",
+    "pressBtn": "press_button",
+    "keyCode": "key_code",
+    "cm": "message"
+  },
+  "create_example": "create_trigger(pos=(0, 0.5, 0), scale=(3, 2, 3), press_button=True, key_code='X', message='activate switch')",
+  "json_example": {
+    "prefabName": "Trigger",
+    "pos": {"x": 0, "y": 0.5, "z": 0},
+    "rot": {"x": 0, "y": 0, "z": 0, "w": 1},
+    "scale": {"x": 3, "y": 2, "z": 3},
+    "extraData": "{\"events\":[],\"pressBtn\":true,\"cm\":\"activate\",\"keyCode\":\"X\",\"Tasks\":[],\"ViewNodes\":[]}",
+    "placed": true
+  },
+  "see_also": [
+    "docs://ref/items/cube",
+    "docs://ref/interactions/basic",
+    "docs://ref/interactions/quest-driven"
+  ]
+}

package/dist/resources/ref/pitfalls.json

@@ -98,6 +98,11 @@
             "title": "OnEnterEvent/OnExitEvent only on Trigger cubes",
             "detail": "OnEnterEvent and OnExitEvent ONLY work on Trigger cubes (prefabName: 'Trigger'). They do NOT work on ResizableCubes, GLBs, or other item types."
         },
+        {
+            "category": "triggers",
+            "title": "Trigger pressBtn gates OnEnterEvent",
+            "detail": "Trigger pressBtn:true means entering the zone arms the Trigger and pressing keyCode while still inside runs the Trigger's OnEnterEvent tasks. It is not the same as OnKeyPressedEvent, which is global and not zone-gated."
+        },
         {
             "category": "glb",
             "title": "External texture references",