update dcs

data-structure-block-coding.md

@@ -58,13 +58,15 @@ A script's head block can be one of two kinds:
 |---|---|---|
 | `kind` | `"scene"` | Discriminant identifying this as a scene-event trigger |
 | `id` | `string` | Unique block identifier |
-| `event` | `"clicked" \| "proximity_enter" \| "proximity_exit" \| "looked_at"` | The interaction event to watch for |
+| `event` | `"clicked" \| "proximity_enter" \| "proximity_exit" \| "looked_at" \| "in_area"` | The interaction event to watch for |
 | `sourceItemId` | `number \| null` | Scene item ID to watch (`null` = no item selected yet) |
 | `radius` | `number` | Proximity enter radius in metres (only used when `event` is `"proximity_enter"`) |
 | `exitRadius` | `number` | Proximity exit radius in metres (only used when `event` is `"proximity_exit"`) |
 
 `"looked_at"` fires when a visitor looks directly at `sourceItemId` — it reuses `sourceItemId` like `"clicked"` and does not use `radius`/`exitRadius`. There is no user-configurable cooldown field anymore; the panel no longer exposes it and a fixed ~100ms minimum delay between firings is assumed for when the runtime is implemented.
 
+`"in_area"` ("When in area") fires when a visitor enters/leaves the footprint of an Area Collider item (Creator type `Area`, see [Database data structure](./data-structure-database.md#logic)) referenced by `sourceItemId`. It does not use `radius`/`exitRadius` — the area's own footprint (`scale.x`/`scale.z`) defines the trigger zone. The block coding panel's item picker restricts the choices to `Area`-type items when this event is selected, but `sourceItemId` is a plain item ID like any other trigger — the data shape itself does not enforce the item's type.
+
 Effect blocks in a script headed by a `"looked_at"` trigger — and only those with `effectProp: "visibility"` — additionally show Toggle mode (normally hidden for `"visibility"`); see `EffectBlock.toggle` below.
 
 ---
@@ -170,6 +172,7 @@ All fields are always present regardless of `effectProp`. Fields that are irrele
 - Hidden whenever the parent script's `trigger.kind` is `"source"` with `mode: "value"` (the effect is driven by the incoming value instead).
 - Hidden whenever the parent script has a non-null `loop` — in that case `toggle` is forced to `true` on every effect in the script instead of being user-controlled.
 - For `"proximity_enter"`/`"proximity_exit"` triggers, Toggle mode is shown with a mode-specific meaning (activates on enter/deactivates on leave, or vice versa) rather than the generic "alternate on each firing" explanation.
+- For `"in_area"` triggers, Toggle mode is shown with the meaning: the effect activates when the visitor enters the area, and deactivates when they leave it.
 
 `EffectBlock` has no field referencing a source — the binding is implicit via the parent script's head block. There is no per-effect opt-in; if a script's head is a `SourceBlock` in `"value"` mode, **every** effect in that script is driven by the incoming value. For multi-field effects (`position`, `rotation`, `glow`) only the single "value" field is replaced by the incoming value — the axis selector (`positionAxis`/`rotationAxis`) and the glow color (`targetGlowColor`) stay static/manually set.
 
@@ -296,6 +299,49 @@ A "When entering proximity" trigger whose glow effect repeats every 500ms for 10
 }
 ```
 
+### Area trigger
+
+A "When in area" trigger that reveals an item (visibility effect) while a visitor is standing inside Area Collider item `5`, using Toggle mode so it hides again on exit:
+
+```json
+{
+  "scripts": [
+    {
+      "id": "bl-15-1700000000015",
+      "trigger": {
+        "kind": "scene",
+        "id": "bl-16-1700000000016",
+        "event": "in_area",
+        "sourceItemId": 5,
+        "radius": 5,
+        "exitRadius": 5
+      },
+      "loop": null,
+      "effects": [
+        {
+          "id": "bl-17-1700000000017",
+          "effectProp": "visibility",
+          "targetObjectType": "item",
+          "targetItemId": 9,
+          "targetColor": "#ffffff",
+          "positionAxis": "x",
+          "targetPositionValue": 0,
+          "rotationAxis": "x",
+          "targetRotationValue": 0,
+          "targetScale": 1,
+          "targetVisibility": true,
+          "targetGlowColor": "#ffffff",
+          "targetGlowIntensity": 1,
+          "toggle": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+`radius`/`exitRadius` are stored (every `SceneTriggerBlock` always carries all fields, same convention as `EffectBlock`) but ignored for `"in_area"` — the Area item's own footprint is what defines the zone.
+
 ### REST API source — trigger mode
 
 Fires the script's effects whenever the endpoint reports a value greater than `20`: