Document more cutscene steps

* set_signal
* clear_signal
* wait_for_signal
* teleport_player
* load_level
* label
* goto
* start_cutscene
* stop_cutscene
* wait_for_cutscene

documentation/levels/cutscenes/README.md

@@ -50,16 +50,16 @@ See the pages below for details on specific cutscene steps.
 * [delay](./delay.md)
 * [open_portal](./open_portal.md)
 * [close_portal](./close_portal.md)
-* set_signal (TODO)
+* [set_signal](./set_signal.md)
-* clear_signal (TODO)
+* [clear_signal](./clear_signal.md)
-* wait_for_signal (TODO)
+* [wait_for_signal](./wait_for_signal.md)
-* teleport_player (TODO)
+* [teleport_player](./teleport_player.md)
-* load_level (TODO)
+* [load_level](./load_level.md)
-* label (TODO)
+* [label](./label.md)
-* goto (TODO)
+* [goto](./goto.md)
-* start_cutscene (TODO)
+* [start_cutscene](./start_cutscene.md)
-* stop_cutscene (TODO)
+* [stop_cutscene](./stop_cutscene.md)
-* wait_for_cutscene (TODO)
+* [wait_for_cutscene](./wait_for_cutscene.md)
 * hide_pedestal (TODO)
 * point_pedestal (TODO)
 * play_animation (TODO)

documentation/levels/cutscenes/clear_signal.md

@@ -0,0 +1,21 @@
+# clear_signal
+
+Configures a signal to be unset by default.
+
+## Syntax
+
+```
+set_signal SIGNAL_NAME
+```
+
+## Arguments
+
+| Name          | Description                                           |
+| ------------- | ----------------------------------------------------- |
+| `SIGNAL_NAME` | The name of the signal to change the default state of |
+
+## Notes
+
+Signal-emitting sources such as level objects and operators work by inverting
+the default state. That is, emitting a signal which is set by default will
+result in it being read as unset.

documentation/levels/cutscenes/goto.md

@@ -0,0 +1,15 @@
+# goto
+
+Jumps cutscene execution to a specified [label](./label.md).
+
+## Syntax
+
+```
+goto LABEL_NAME
+```
+
+## Arguments
+
+| Name         | Description                      |
+| ------------ | -------------------------------- |
+| `LABEL_NAME` | The name of the label to jump to |

documentation/levels/cutscenes/label.md

@@ -0,0 +1,19 @@
+# label
+
+A marker to jump to using the [goto](./goto.md) cutscene step.
+
+## Syntax
+
+```
+label LABEL_NAME
+```
+
+## Arguments
+
+| Name         | Description           |
+| ------------ | --------------------- |
+| `LABEL_NAME` | The name of the label |
+
+## Notes
+
+Labels have no effect on their own. They exist to enable control flow via gotos.

documentation/levels/cutscenes/load_level.md

@@ -0,0 +1,15 @@
+# load_level
+
+Loads the next level.
+
+## Syntax
+
+```
+load_level SOURCE_LOCATION_NAME
+```
+
+## Arguments
+
+| Name                   | Description                                                                                                                                                                                                 |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SOURCE_LOCATION_NAME` | The [location](../level_objects/location.md) the player is being teleported from. When the next level is loaded, they are positioned with the same relative position and rotation they had from the source. |

documentation/levels/cutscenes/set_signal.md

@@ -0,0 +1,21 @@
+# set_signal
+
+Configures a signal to be set by default.
+
+## Syntax
+
+```
+set_signal SIGNAL_NAME
+```
+
+## Arguments
+
+| Name          | Description                                           |
+| ------------- | ----------------------------------------------------- |
+| `SIGNAL_NAME` | The name of the signal to change the default state of |
+
+## Notes
+
+Signal-emitting sources such as level objects and operators work by inverting
+the default state. That is, emitting a signal which is set by default will
+result in it being read as unset.

documentation/levels/cutscenes/start_cutscene.md

@@ -0,0 +1,19 @@
+# start_cutscene
+
+Starts execution of a specified cutscene.
+
+## Syntax
+
+```
+start_cutscene CUTSCENE_NAME
+```
+
+## Arguments
+
+| Name            | Description                       |
+| --------------- | --------------------------------- |
+| `CUTSCENE_NAME` | The name of the cutscene to start |
+
+## Notes
+
+The same cutscene can have multiple instances running at once.

documentation/levels/cutscenes/stop_cutscene.md

@@ -0,0 +1,19 @@
+# stop_cutscene
+
+Stops execution of a specified cutscene.
+
+## Syntax
+
+```
+stop_cutscene CUTSCENE_NAME
+```
+
+## Arguments
+
+| Name            | Description                      |
+| --------------- | -------------------------------- |
+| `CUTSCENE_NAME` | The name of the cutscene to stop |
+
+## Notes
+
+Nothing is done if the specified cutscene is not running.

documentation/levels/cutscenes/teleport_player.md

@@ -0,0 +1,16 @@
+# teleport_player
+
+Moves the player to a specified [location](../level_objects/location.md).
+
+## Syntax
+
+```
+teleport_player SOURCE_LOCATION_NAME TARGET_LOCATION_NAME
+```
+
+## Arguments
+
+| Name                   | Description                                                                                                                        |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `SOURCE_LOCATION_NAME` | The location the player is being teleported from. Used to calculate relative position and rotation for the destination.            |
+| `TARGET_LOCATION_NAME` | The location to teleport the player to. They are positioned with the same relative position and rotation they had from the source. |

documentation/levels/cutscenes/wait_for_cutscene.md

@@ -0,0 +1,15 @@
+# wait_for_cutscene
+
+Blocks until a specified cutscene is complete.
+
+## Syntax
+
+```
+wait_for_cutscene CUTSCENE_NAME
+```
+
+## Arguments
+
+| Name            | Description                          |
+| --------------- | ------------------------------------ |
+| `CUTSCENE_NAME` | The name of the cutscene to wait for |

documentation/levels/cutscenes/wait_for_signal.md

@@ -0,0 +1,21 @@
+# wait_for_signal
+
+Blocks until a specified signal is set.
+
+## Syntax
+
+```
+wait_for_signal SIGNAL_NAME [REQUIRED_FRAMES]
+```
+
+## Arguments
+
+| Name                         | Description                                                                                                                |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `SIGNAL_NAME`                | The name of the signal to wait for                                                                                         |
+| `REQUIRED_FRAMES` (optional) | The number of frames the signal must have been previously set for. Useful for debouncing or adding delays. Defaults to 0.  |
+
+## Notes
+
+If using the `REQUIRED_FRAMES` argument, note that cutscenes are updated at 30
+FPS on NTSC/MPAL consoles and 25 FPS on PAL consoles.

documentation/levels/level_objects/ball_catcher.md

@@ -1,7 +1,7 @@
 # @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 launcher](./ball_launcher.md). Emits a [signal](../signals.md) when a
 ball is caught.
 
 ## Name structure

documentation/levels/level_objects/elevator.md

@@ -20,8 +20,9 @@ The start/end of level elevator that takes the player between test chambers.
 End of level elevators open when the player is near and lock once they step
 inside. Then, after some time, the screen shake animation and movement sound
 are played. Finally, the player's portals are closed and they are teleported to
-the destination elevator at the same relative position as in the starting
+the destination elevator at the same relative position and rotation as in the
-elevator to create the illusion that it is the same. It does not actually move.
+starting elevator to create the illusion that it is the same. It does not
+actually move.
 
 If a GLaDOS voice line is playing, the last elevator in a map will not start to
 transition the player to the next one until the line finishes.

documentation/levels/signals.md

@@ -1,12 +1,14 @@
 # Level Signals
 
 Signals are a way to indicate that something is happening in a level. They can
-be emitted by:
+be controlled by:
 * Level objects
 * Triggers
 * Cutscenes
 * Signal operators
 
+Emitting a signal sets its state to the inverse of its default state.
+
 Other parts of the level can listen for signals in order to perform some sort of
 action. The possible listeners are:
 * Level objects
@@ -22,10 +24,7 @@ engine uses this to wire up the various emitters and listeners.
 ## Level objects
 
 Level objects which send or receive signals have the relevant signal name as
-part of their object name in the level's `.blend` file using the format:
+part of their object name in the level's `.blend` file.
-```
-@object_type SIGNAL_NAME
-```
 
 For example, consider the following object names:
 * `@ball_catcher exit_activate`
@@ -37,12 +36,12 @@ reaches the ball catcher.
 
 There are various other level objects that can send and receive signals,
 including those that the player cannot directly interact with such as the
-indicator light strips (they are materials). Some other special cases, such as
+indicator light strips. Some other special cases, such as buttons, can set
-buttons, can set multiple signals. The exact name structure differs per object.
+multiple signals. The exact name structure differs per object. See
-See [Level Objects](./level_objects/README.md) for more details.
+[Level Objects](./level_objects/README.md) for more details.
 
-Objects which can be deactivated will clear their associated signal when that
+Objects which can be deactivated will stop emitting their associated signal when
-occurs.
+that occurs.
 
 ## Triggers
 
@@ -53,26 +52,27 @@ names are of the form:
 ```
 @trigger PLAYER_CUTSCENE_NAME PLAYER_SIGNAL_NAME CUBE_CUTSCENE_NAME CUBE_SIGNAL_NAME
 ```
-`PLAYER_SIGNAL_NAME` is set/unset when the player enters/leaves the trigger and
+`PLAYER_SIGNAL_NAME` is emitted while the player is inside the trigger and
-`CUBE_SIGNAL_NAME` is set/unset when a cube enters/leaves the trigger.
+`CUBE_SIGNAL_NAME` is emitted while a cube is inside the trigger.
 
 ## Cutscenes
 
-[Cutscenes](./cutscenes/README.md) can set and clear signals using the
+[Cutscenes](./cutscenes/README.md) can change the default state of signals using
-`set_signal` and `clear_signal` steps, respectively. For example:
+the [set_signal](./cutscenes/set_signal.md) and
+[clear_signal](./cutscenes/clear_signal.md) steps, respectively. For example:
 ```
 set_signal door_activate
 [...]
 clear_signal door_activate
 ```
 
-The way this works internally is by altering the default state of the signal. In
+In between `set_signal` and `clear_signal`, the `door_activate` signal will be
-the above example, in between `set_signal` and `clear_signal`, other signal
+read as set. Since emitting a signal inverts the default state, signal emitters
-emitters such as buttons would clear the signal when activated.
+such as buttons will change the state to unset when activated.
 
-Cutscenes can also wait for a particular signal to occur using the
+Cutscenes can also wait for a particular signal to become set using the
-`wait_for_signal` step. A number of frames the signal must be set for can
+[wait_for_signal](./cutscenes/wait_for_signal.md) step. A number of frames the
-optionally be specified. For example:
+signal must be set for can optionally be specified. For example:
 ```
 [...]
 wait_for_signal player_in_trigger