Document ball launcher and catcher level objects

documentation/levels/level_objects/README.md

@@ -31,6 +31,8 @@ easy.
 See the pages below for details on specific level objects.
 
 * [@anim](./anim.md)
+* [@ball_catcher](./ball_catcher.md)
+* [@ball_launcher](./ball_launcher.md)
 * [@button](./button.md)
 * [@clock](./clock.md)
 * [@collision](./collision.md)

documentation/levels/level_objects/ball_catcher.md

@@ -0,0 +1,24 @@
+# @ball_catcher
+
+A receptacle for a high energy pellet launched by a
+[ball launcher](./ball_launcher.md)). Emits a [signal](../signals.md) when a
+ball is caught.
+
+## Name structure
+
+```
+@ball_catcher CATCH_SIGNAL_NAME
+```
+
+## Arguments
+
+| Name                | Description                                          |
+| ------------------- | ---------------------------------------------------- |
+| `CATCH_SIGNAL_NAME` | The name of the signal to emit when a ball is caught |
+
+## Notes
+
+When a ball collides with a ball catcher, the catcher notifies the associated
+launcher (so it will not update the ball) and emits the specified signal.
+
+Only one ball can be caught.

documentation/levels/level_objects/ball_launcher.md

@@ -0,0 +1,28 @@
+# @ball_launcher
+
+A spawner for high energy pellets, which can be caught by a
+[ball catcher](./ball_catcher.md) to emit a [signal](../signals.md).
+
+## Name structure
+
+```
+@ball_launcher ACTIVE_SIGNAL_NAME [BALL_LIFETIME_SECONDS] [TARGET_BALL_VELOCITY]
+```
+
+## Arguments
+
+| Name                               | Description                                                                                                                                         |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ACTIVE_SIGNAL_NAME`               | The name of the signal which enables the launcher when set                                                                                          |
+| `BALL_LIFETIME_SECONDS` (optional) | The amount of time in seconds it takes for a launched ball to destroy itself. Resets when passing through portals. Defaults to 10 if not specified. |
+| `TARGET_BALL_VELOCITY`  (optional) | The intended velocity of launched balls. Any deviations (e.g., due to collision) will be corrected to this value. Defaults to 3.                    |
+
+## Notes
+
+While activated with its signal, a ball launcher ensures its associated ball has
+been spawned - creating a new one if it doesn't exist. Launched balls have a
+configurable lifetime until they are destroyed and the process is repeated. This
+value constantly counts down and is reset when passing through portals.
+
+Once a launcher's ball has been caught by a ball catcher, the launcher will not
+spawn any more.

documentation/levels/level_objects/collision.md

@@ -29,8 +29,8 @@ If no collision layers are specified, the defaults are `STATIC`, `TANGIBLE`, and
     * Elevators
 * `TRANSPARENT`: Unused
 * `TANGIBLE`: Used to check grabbing and walking, and by:
-    * Ball catchers
-    * Ball launchers
+    * [Ball catchers](./ball_catcher.md)
+    * [Ball launchers](./ball_launcher.md)
     * [Buttons](./button.md)
     * Decor
     * [Doors](./door.md) (when open)
@@ -53,7 +53,7 @@ If no collision layers are specified, the defaults are `STATIC`, `TANGIBLE`, and
     * Fizzlers
 * `BLOCK_BALL`: Used by:
     * Energy balls
-    * Ball launchers
+    * [Ball launchers](./ball_launcher.md)
     * [Dynamic boxes](./dynamic_box.md)
     * Elevators
     * Player