enter hook

docs/script-api.md

@@ -65,6 +65,27 @@ fn bump(me, dir) {
 }
 ```
 
+### `fn enter(me, dir)`
+
+The **non-solid** counterpart to `bump`. Called when a solid — the player, another object, or a
+**crate** being pushed/shifted — relocates *onto* this object's cell. Only makes sense on a non-solid
+object (a trigger, or a decorative `solid = false` object); a solid object blocks the entrant instead
+of being entered, so its `bump` fires rather than `enter`.
+
+- `dir` is the [`Direction`] the entrant **came from** — the same convention as `bump`. For a one-cell
+  move or push it is exactly the opposite of the entrant's travel direction. For a `teleport` or `shift`
+  that jumps a solid an arbitrary distance it is **best-effort**: the dominant axis of the displacement
+  (a longer horizontal jump reads as East/West, a longer vertical one as North/South).
+- Fires for *every* solid that lands on the cell: a player/object step, and each crate a push or shift
+  moved onto it.
+
+```rhai
+fn enter(me, dir) {
+    say("Who goes there?");
+    log(`something stepped on me from the ${dir}`);
+}
+```
+
 ### `fn grab(me, state)`
 
 Called when the **player walks onto** this object and the object is a *grab* thing (gems, hearts —