Add descriptions to level object summary page and clarify room/door behavior

documentation/levels/level_objects/README.md

@@ -11,12 +11,13 @@ stops the player from falling through, and so on.
 
 ## Naming convention
 
-At build time, level definition C source files are generated using the Lua
-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:
+At level export time, level definition C source files are generated using the
+Lua scripts in `tools/level_scripts/`, initiated by `export_level.lua`. The way
+the level exporter knows how to properly populate these definitions with objects
+is by using their names. Every object in a level's `.blend` file has a name of
+the form:
 ```
-@type [arg...]
+@TYPE [ARG]...
 ```
 
 That is, an `@`-prefixed type name followed by 0 or more space-separated
@@ -26,30 +27,32 @@ This could have been done with Blender's custom object properties feature, but
 one nice benefit of this approach is that it makes searching for related objects
 easy.
 
-## Object information
+## Object types
 
-See the pages below for details on specific level objects.
+See the linked pages below for details on specific level objects.
 
-* [@ambient](./ambient.md)
-* [@anim](./anim.md)
-* [@ball_catcher](./ball_catcher.md)
-* [@ball_launcher](./ball_launcher.md)
-* [@box_dropper](./box_dropper.md)
-* [@button](./button.md)
-* [@clock](./clock.md)
-* [@collision](./collision.md)
-* [@decor](./decor.md)
-* [@door](./door.md)
-* [@doorway](./doorway.md)
-* [@dynamic_box](./dynamic_box.md)
-* [@elevator](./elevator.md)
-* [@fizzler](./fizzler.md)
-* [@location](./location.md)
-* [@pedestal](./pedestal.md)
-* [@point_light](./point_light.md)
-* [@room](./room.md)
-* [@security_camera](./security_camera.md)
-* [@signage](./signage.md)
-* [@static](./static.md)
-* [@switch](./switch.md)
-* [@trigger](./trigger.md)
+| Type                                     | Description                                          |
+| ---------------------------------------- | ---------------------------------------------------- |
+| [@ambient](./ambient.md)                 | Ambient light source for baked lighting              |
+| [@anim](./anim.md)                       | Animatable armature bone                             |
+| [@ball_catcher](./ball_catcher.md)       | High energy pellet receptacle                        |
+| [@ball_launcher](./ball_launcher.md)     | High energy pellet spawner                           |
+| [@box_dropper](./box_dropper.md)         | Cube spawner                                         |
+| [@button](./button.md)                   | Flat, circular button                                |
+| [@clock](./clock.md)                     | Countdown clock                                      |
+| [@collision](./collision.md)             | Static collision                                     |
+| [@decor](./decor.md)                     | Generic dynamic object                               |
+| [@door](./door.md)                       | Sliding door                                         |
+| [@doorway](./doorway.md)                 | Level segment connection for rendering and collision |
+| [@dynamic_box](./dynamic_box.md)         | Dynamic collision                                    |
+| [@elevator](./elevator.md)               | Level transition elevator                            |
+| [@fizzler](./fizzler.md)                 | Emancipation grill                                   |
+| [@location](./location.md)               | Referenceable point in the world                     |
+| [@pedestal](./pedestal.md)               | Portal gun holder                                    |
+| [@point_light](./point_light.md)         | Omnidirectional light source for baked lighting      |
+| [@room](./room.md)                       | Discrete level segment for rendering and collision   |
+| [@security_camera](./security_camera.md) | Wall-mounted camera                                  |
+| [@signage](./signage.md)                 | Start of level informational sign                    |
+| [@static](./static.md)                   | Static geometry                                      |
+| [@switch](./switch.md)                   | Button on pedestal                                   |
+| [@trigger](./trigger.md)                 | Signal and cutscene activating volume                |

documentation/levels/level_objects/collision.md

@@ -5,7 +5,7 @@ Static level collision geometry. Must be a quad.
 ## Name structure
 
 ```
-@collision [transparent] [thickness DEPTH] [CL_X...]
+@collision [transparent] [thickness DEPTH] [CL_X]...
 ```
 
 ## Arguments

documentation/levels/level_objects/door.md

@@ -18,5 +18,5 @@ A sliding door which can open or close in response to a [signal](../signals.md).
 ## 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.
+and at the same position on that plane), the two are linked and the game will
+open and close the doorway with the door.

documentation/levels/level_objects/doorway.md

@@ -1,7 +1,7 @@
 # @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
+A connection between two [rooms](./room.md). Used for culling and broad phase
+collision purposes, to determine room visibility and movement of dynamic objects
 from one room to another.
 
 ## Name structure
@@ -14,8 +14,13 @@ from one room to another.
 
 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).
+considered connected at that point (other open doorways count). Only the
+player's current room and visible connected rooms are considered for rendering.
+
+Passing through an open doorway updates an object's room index, allowing it to
+collide with other objects in the entered room while ignoring those in the
+exited room.
 
 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.
+not considered for rendering when out of the player's view.

documentation/levels/level_objects/room.md

@@ -1,7 +1,7 @@
 # @room
 
-A 3D box which groups objects in a level. Used for broad phase collision and
-culling.
+A 3D box which defines a portion of a level. Used for culling and broad phase
+collision.
 
 ## Name structure
 
@@ -19,8 +19,9 @@ culling.
 
 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.
+know their room index, which is updated when passing through
+[doorways](./doorway.md).
 
-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.
+For performance reasons, only the player's current room and those visible
+through open doorways are considered for rendering, and only objects in the same
+room can collide with each other.