redoing bump

docs/script-api.md

@@ -48,17 +48,20 @@ fn tick(me, state, dt) {
 }
 ```
 
-### `fn bump(me, state, id)`
+### `fn bump(me, dir)`
 
-Called when another entity walks into this object's cell.
+Called when a solid presses into this object's cell — the player, another object, or a **crate** being
+pushed into it (the push chain is walked through to reach the object it presses against).
 
-- `id` is the bumper's `ObjectId` (an `i64`).
-- `id == -1` means the **player** bumped this object.
+- `dir` is the [`Direction`] the bump **came from**: it points from this object toward the bumper, so
+  the bumper occupies the cell at `(me.x + dir.dx, me.y + dir.dy)`.
+- Compare it against the `North`/`South`/`East`/`West` constants.
+- The hook can no longer tell *who* did the bumping (there is no id) — a crate bumps just like the player.
 
 ```rhai
-fn bump(me, state, id) {
-    if id == -1 { say("Hey! Watch it."); }
-    else        { log(`object ${id} bumped me`); }
+fn bump(me, dir) {
+    if dir == West { say("Something shoved me from the west."); }
+    else           { log(`bumped from ${dir}`); }
 }
 ```
 
@@ -297,7 +300,7 @@ function call named `choice_key` (see [custom handler functions](#custom-handler
 arity rules — a choice handler is called with no `arg`).
 
 ```rhai
-fn bump(me, state, id) {
+fn bump(me, dir) {
     scroll([
         "The muffin looks delicious.",
         "",
@@ -358,7 +361,7 @@ crash the game. A script that throws during `tick` logs the error and resumes on
 ## Full example
 
 ```rhai
-// A guard that patrols east/west and greets the player when bumped.
+// A guard that patrols east/west and greets whatever bumps into it.
 
 fn init(me, state) {
     set_tile(2);
@@ -371,9 +374,8 @@ fn tick(me, state, dt) {
     else if !me.blocked(West) { move(West); }
 }
 
-fn bump(me, state, id) {
-    if id == -1 { say("Halt! Who goes there?"); now(); }
-    else        { say("Watch it!");             now(); }
+fn bump(me, dir) {
+    say(`Halt! Who approaches from the ${dir}?`); now();
 }
 ```