More level object documentation

* Collision
* Door
* Doorway
* Location
* Room

documentation/levels/level_objects/README.md

@@ -16,7 +16,7 @@ scripts in `tools/level_scripts/`, initiated by `export_level.lua`. The way the
 level exporter knows how to properly populate these definitions is by using
 object names. Every object in a level's `.blend` file has a name of the form:
 ```
-@type [arg1] [arg2] ... [argN]
+@type [arg...]
 ```
 
 That is, an `@`-prefixed type name followed by 0 or more space-separated
@@ -32,5 +32,10 @@ See the pages below for details on specific level objects.
 
 * [@button](./button.md)
 * [@clock](./clock.md)
+* [@collision](./collision.md)
+* [@door](./door.md)
+* [@doorway](./doorway.md)
+* [@location](./location.md)
+* [@room](./room.md)
 * [@switch](./switch.md)
 * More... (TODO)

documentation/levels/level_objects/collision.md

@@ -0,0 +1,64 @@
+# @collision
+
+Static level collision geometry. Must be a quad.
+
+## Name structure
+
+```
+@collision [transparent] [thickness depth] [CL_X...]
+```
+
+## Arguments
+
+| Name                       | Description                                                                              |
+| -------------------------- | ---------------------------------------------------------------------------------------- |
+| `transparent` (optional)   | If `transparent` is specified, the `TRANSPARENT` collision layer will be added           |
+| `thickness num` (optional) | If `thickness` is specified, the quad's thickness will be set to `depth`                 |
+| `CL_X` (optional)          | Space-separated list of colllision layer names. Only those prefixed with `CL_` are used. |
+
+## Notes
+
+Game objects in the same [room](./room.md) and on the same collision layer can
+collide. Some layers are also used for certain checks by the game.
+
+If no collision layers are specified, the defaults are `STATIC`, `TANGIBLE`, and
+`BLOCK_BALL`. The possible layers and their uses are as follows.
+
+* `STATIC`: Used for portal raycasts, and by:
+    * Doors
+    * Elevators
+* `TRANSPARENT`: Unused
+* `TANGIBLE`: Used to check grabbing and walking, and by:
+    * Ball catchers
+    * Ball launchers
+    * [Button](./button.md)s
+    * Decor
+    * [Door](./door.md)s (when open)
+    * Dynamic boxes
+    * Elevators
+    * Player
+    * Portals
+    * Security cameras
+    * Switches
+    * Triggers
+* `GRABBABLE`: Used to check grabbing, and by:
+    * Decor
+    * Security cameras (when detached)
+* `FIZZLER`: Used to block portal raycasts, and by:
+    * Decor
+    * Fizzlers
+    * Player
+    * Security cameras
+* `BLOCK_PORTAL`: Used for portal raycasts, and by:
+    * Fizzlers
+* `BLOCK_BALL`: Used by:
+    * Energy balls
+    * Ball launchers
+    * Dynamic boxes
+    * Elevators
+    * Player
+
+## TODO
+
+* Page on collision detection
+* Link to level object pages when created

documentation/levels/level_objects/door.md

@@ -0,0 +1,22 @@
+# @door
+
+A sliding door which can open or close in response to a [signal](../signals.md).
+
+## Name structure
+
+```
+@door open_signal_name [type]
+```
+
+## Arguments
+
+| Name                     | Description                                                                        |
+| -------------------------| ---------------------------------------------------------------------------------- |
+| `open_signal_name`       | The name of the signal to which will open the door when set                        |
+| `type` (optional)        | The type of door. `02` for vertical sliding hatches, otherwise circular exit door. |
+
+## Notes
+
+At level export time, if a [doorway](./doorway.md) is found on a door (coplanar
+and at the same position on that plane), the two are linked and the doorway will
+open and close with the door.

documentation/levels/level_objects/doorway.md

@@ -0,0 +1,21 @@
+# @doorway
+
+A connection between two [room](./room.md)s. Used for broad phase collision and
+culling purposes, to determine room visibility and movement of dynamic objects
+from one room to another.
+
+## Name structure
+
+```
+@doorway
+```
+
+## Notes
+
+Doorways connect their nearest two rooms, and can be open or closed (i.e., when
+associated with a [door](./door.md)). If a doorway is closed, its rooms are not
+considered connected at that point (other open doorways count).
+
+Doorways do not need to be linked to a physical door in the world. For example,
+a doorway can be placed over a window so that the room on the other side is
+not processed when out of the player's view.

documentation/levels/level_objects/location.md

@@ -0,0 +1,25 @@
+# @location
+
+A point in the world, used for level spawn points and can be referenced in
+cutscenes.
+
+## Name structure
+
+```
+@location name
+```
+
+## Arguments
+
+| Name   | Description              |
+| ------ | ------------------------ |
+| `name` | The name of the location |
+
+## Notes
+
+Locations can be referenced in cutscenes. See [Cutscenes](../cutscenes.md) for
+more information.
+
+Each level must have a location named "start". This is used to place the player
+when loading levels without a transition from a previous one (e.g., from the
+main menu).

documentation/levels/level_objects/room.md

@@ -0,0 +1,26 @@
+# @room
+
+A box which groups objects in a level. Used for broad phase collision and
+culling.
+
+## Name structure
+
+```
+@room index
+```
+
+## Arguments
+
+| Name    | Description                                  |
+| ------- | -------------------------------------------- |
+| `index` | The index number of the room the box defines |
+
+## Notes
+
+At level export time, room regions with the same index are merged to define the
+bounds of one logical room. Game objects within a room (including the player)
+know their room index.
+
+For performance reasons, only objects in the current room and rooms connected
+via open [doorway](./doorway.md)s are considered for rendering and collision
+detection.