Archive/portal64-still-alive
1
0
Fork 0
mirror of https://github.com/mwpenny/portal64-still-alive.git synced 2024-10-19 22:27:36 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity

Finish cutscene step documentation

Browse source
This commit is contained in:
Matt Penny 2024-04-13 17:03:54 -04:00
parent 1a91f840c0
commit f4cb8ddd31
22 changed files with 302 additions and 56 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

58
documentation/levels/cutscenes/README.md
View file

@ -43,31 +43,33 @@ after their final step is executed.
See the pages below for details on specific cutscene steps.
* [play_sound](./play_sound.md)
* [start_sound](./start_sound.md)
* [q_sound](./q_sound.md)
* [wait_for_channel](./wait_for_channel.md)
* [delay](./delay.md)
* [open_portal](./open_portal.md)
* [close_portal](./close_portal.md)
* [set_signal](./set_signal.md)
* [clear_signal](./clear_signal.md)
* [wait_for_signal](./wait_for_signal.md)
* [teleport_player](./teleport_player.md)
* [load_level](./load_level.md)
* [label](./label.md)
* [goto](./goto.md)
* [start_cutscene](./start_cutscene.md)
* [stop_cutscene](./stop_cutscene.md)
* [wait_for_cutscene](./wait_for_cutscene.md)
* hide_pedestal (TODO)
* point_pedestal (TODO)
* play_animation (TODO)
* pause_animation (TODO)
* resume_animation (TODO)
* wait_for_animation (TODO)
* save_checkpoint (TODO)
* kill_player (TODO)
* show_prompt (TODO)
* rumble (TODO)
* activate_signage (TODO)
| Type | Description |
| --------------------------------------------- | ------------------------------------------- |
| [play_sound](./play_sound.md) | Plays a sound and waits for completion |
| [start_sound](./start_sound.md) | Plays a sound without waiting |
| [q_sound](./q_sound.md) | Queues a sound to be played on a channel |
| [wait_for_channel](./wait_for_channel.md) | Waits for a sound channel to be available |
| [delay](./delay.md) | Pauses for a specified duration |
| [open_portal](./open_portal.md) | Opens a portal at a location |
| [close_portal](./close_portal.md) | Closes a portal at a location |
| [set_signal](./set_signal.md) | Changes a signal's default state to set |
| [clear_signal](./clear_signal.md) | Changes a signal's default state to unset |
| [wait_for_signal](./wait_for_signal.md) | Waits for a signal to become set |
| [teleport_player](./teleport_player.md) | Moves the player to a location |
| [load_level](./load_level.md) | Loads the next level |
| [label](./label.md) | Marker for goto |
| [goto](./goto.md) | Unconditional jump to a label |
| [start_cutscene](./start_cutscene.md) | Starts a cutscene |
| [stop_cutscene](./stop_cutscene.md) | Stops a cutscene |
| [wait_for_cutscene](./wait_for_cutscene.md) | Waits for a cutscene to end |
| [hide_pedestal](./hide_pedestal.md) | Hides pedestals and grants the portal gun |
| [point_pedestal](./point_pedestal.md) | Points pedestals at a location |
| [play_animation](./play_animation.md) | Plays or updates an armature's animation |
| [pause_animation](./pause_animation.md) | Pauses playback of an armature's animation |
| [resume_animation](./resume_animation.md) | Resumes playback of an armature's animation |
| [wait_for_animation](./wait_for_animation.md) | Waits until an armature is not animated |
| [save_checkpoint](./save_checkpoint.md) | Creates an autosave |
| [kill_player](./kill_player.md) | Kills the player |
| [show_prompt](./show_prompt.md) | Displays an action prompt |
| [rumble](./rumble.md) | Activates the rumble pak |
| [activate_signage](./activate_signage.md) | Turns on test chamber signs |

16
documentation/levels/cutscenes/activate_signage.md Normal file
View file

@ -0,0 +1,16 @@
# activate_signage
Illuminates the [signage](../level_objects/signage.md) at the beginning of a
test chamber, playing its flicker animation.
## Syntax
```
activate_signage TEST_CHAMBER_NUMBER
```
## Arguments
| Name | Description |
| --------------------- | ------------------------------------------------------- |
| `TEST_CHAMBER_NUMBER` | The number of the test chamber to activate the sign for |

18
documentation/levels/cutscenes/hide_pedestal.md Normal file
View file

@ -0,0 +1,18 @@
# hide_pedestal
Lowers [pedestal](../level_objects/pedestal.md) objects into the ground and
gives the player the portal gun.
## Syntax
```
hide_pedestal
```
## Notes
If multiple pedestals exist in the level, all are hidden.
The player is given the blue portal gun if they do not have the portal gun
already. Otherwise, they are given the fully upgraded (blue and orange) portal
gun.

15
documentation/levels/cutscenes/kill_player.md Normal file
View file

@ -0,0 +1,15 @@
# kill_player
Kills the player.
## Syntax
```
kill_player [water]
```
## Arguments
| Name | Description |
| ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `water` | If specified, the player will be killed after 2 seconds to simulate damage from toxic water. The cutscene step will not block. |

24
documentation/levels/cutscenes/pause_animation.md Normal file
View file

@ -0,0 +1,24 @@
# pause_animation
Pauses the current animation of a specified [armature](../level_objects/anim.md).
## Syntax
```
pause_animation ARMATURE_NAME
```
## Arguments
| Name | Description |
| ------------------ | --------------------------------- |
| `ARMATURE_NAME` | The name of the armature to pause |
## Notes
Pausing is equivalent to using the [play_animation](./play_animation.md)
cutscene step with a speed of 0 and the animation name set to the armature's
current animation.
This cutscene step has no effect if the specified armature has no active
animation.

27
documentation/levels/cutscenes/play_animation.md Normal file
View file

@ -0,0 +1,27 @@
# play_animation
Starts or updates a specified animation on a specified
[armature](../level_objects/anim.md).
## Syntax
```
play_animation ARMATURE_NAME ANIMATION_NAME [SPEED]
```
## Arguments
| Name | Description |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `ARMATURE_NAME` | The name of the armature to animate |
| `ANIMATION_NAME` | The name of the animation to play on the armature |
| `SPEED` (optional) | The speed multiplier for playback. 1 is normal speed and negative speeds play the animation in reverse. Defaults to 1. |
## Notes
Only one animation can be played at a time on a single armature. Playing a new
one will stop any in-progress animation. Playing an animation that is already
playing will update its speed. A speed of 0 will pause the animation.
If an armature named `player` is used, control will be taken away from the
player and their view and body will be animated in addition to the armature.

10
documentation/levels/cutscenes/play_sound.md
View file

@ -10,11 +10,11 @@ play_sound SOUND_ID [VOLUME] [SPEED]
## Arguments
| Name | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------- |
| `SOUND_ID` | The ID of the sound to play. `SOUNDS_` prefix can be omitted. |
| `VOLUME` (optional) | The volume to play the sound at. 0 is muted and 1 is normal volume. |
| `SPEED` (optional) | The speed to play the sound at. Effectively a multiplier of the game's output sample rate (44100 Hz). |
| Name | Description |
| ------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `SOUND_ID` | The ID of the sound to play. `SOUNDS_` prefix can be omitted. |
| `VOLUME` (optional) | The volume multiplier for playback. 0 is muted and 1 is normal volume. Defaults to 1. |
| `SPEED` (optional) | The speed to play the sound at. Effectively a multiplier of the game's output sample rate (44100 Hz). Defaults to 1. |
## Notes

22
documentation/levels/cutscenes/point_pedestal.md Normal file
View file

@ -0,0 +1,22 @@
# point_pedestal
Rotates [pedestal](../level_objects/pedestal.md) objects toward a specified
[location](../level_objects/pedestal.md).
## Syntax
```
point_pedestal LOCATION_NAME
```
## Arguments
| Name | Description |
| --------------- | ----------------------------------------- |
| `LOCATION_NAME` | The name of the location to rotate toward |
## Notes
If multiple pedestals exist in the level, all are rotated.
Pedestal rotation only occurs horizontally.

2
documentation/levels/cutscenes/q_sound.md
View file

@ -15,7 +15,7 @@ q_sound SOUND_ID CHANNEL_NAME SUBTITLE_ID [VOLUME]
| `SOUND_ID` | The ID of the sound to queue. `SOUNDS_` prefix can be omitted. |
| `CHANNEL_NAME` | The name of the channel to queue the sound on |
| `SUBTITLE_ID` | The ID of the subtitle to display when playing the sound with subtitles enabled, or `SubtitleKeyNone`. Only shown for `CH_GLADOS` channel. |
| `VOLUME` (optional) | The volume to play the sound at. 0 is muted and 1 is normal volume. |
| `VOLUME` (optional) | The volume multiplier for playback. 0 is muted and 1 is normal volume. Defaults to 1. |
## Notes

25
documentation/levels/cutscenes/resume_animation.md Normal file
View file

@ -0,0 +1,25 @@
# resume_animation
Updates the speed of a specified [armature](../level_objects/anim.md)'s current
animation.
## Syntax
```
resume_animation ARMATURE_NAME
```
## Arguments
| Name | Description |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `ARMATURE_NAME` | The name of the armature to animate |
| `SPEED` (optional) | The speed multiplier for playback. 1 is normal speed and negative speeds play the animation in reverse. Defaults to 1. |
## Notes
Resuming is equivalent to using the [play_animation](./play_animation.md)
cutscene step with the animation name set to the armature's current animation.
This cutscene step has no effect if the specified armature has no active
animation.

15
documentation/levels/cutscenes/rumble.md Normal file
View file

@ -0,0 +1,15 @@
# rumble
Plays a rumble pattern using the rumble pak.
## Syntax
```
rumble PATTERN_INDEX
```
## Arguments
| Name | Description |
| --------------- | ---------------------------------------------------------------- |
| `PATTERN_INDEX` | The type of rumble pattern to play (0: soft, 1: medium, 2: hard) |

9
documentation/levels/cutscenes/save_checkpoint.md Normal file
View file

@ -0,0 +1,9 @@
# save_checkpoint
Saves the game in the autosave slot.
## Syntax
```
save_checkpoint
```

40
documentation/levels/cutscenes/show_prompt.md Normal file
View file

@ -0,0 +1,40 @@
# show_prompt
Displays a button prompt informing the player how to perform an action.
## Syntax
```
show_prompt PROMPT_TYPE
```
## Arguments
| Name | Description |
| ------------- | -------------------------- |
| `PROMPT_TYPE` | The type of prompt to show |
## Notes
The possible prompt types are:
| Type | Description |
| --------------------------- | ----------------------------------------------------------------- |
| `CutscenePromptTypeNone` | Remove the current prompt |
| `CutscenePromptTypePortal0` | Prompt to fire the orange portal |
| `CutscenePromptTypePortal1` | Prompt to fire the blue portal |
| `CutscenePromptTypePickup` | Prompt to pick up item |
| `CutscenePromptTypeDrop` | Prompt to drop item |
| `CutscenePromptTypeUse` | Prompt to use object (e.g., [switch](../level_objects/switch.md)) |
| `CutscenePromptTypeCrouch` | Prompt to crouch |
| `CutscenePromptTypeMove` | Prompt to move |
| `CutscenePromptTypeJump` | Prompt to jump |
When a prompt is shown, the currently mapped button(s) for the action are used.
Performing a prompt's action will remove it if on screen and prevent it from
being shown until either a save file or new level are loaded. This is true even
if the action takes place before the prompt is first displayed.
Only one prompt can be shown at a time. Showing a new one will remove any
currently displayed prompt.

10
documentation/levels/cutscenes/start_sound.md
View file

@ -10,11 +10,11 @@ start_sound SOUND_ID [VOLUME] [SPEED]
## Arguments
| Name | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------- |
| `SOUND_ID` | The ID of the sound to start. `SOUNDS_` prefix can be omitted. |
| `VOLUME` (optional) | The volume to play the sound at. 0 is muted and 1 is normal volume. |
| `SPEED` (optional) | The speed to play the sound at. Effectively a multiplier of the game's output sample rate (44100 Hz). |
| Name | Description |
| ------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `SOUND_ID` | The ID of the sound to start. `SOUNDS_` prefix can be omitted. |
| `VOLUME` (optional) | The volume multiplier for playback. 0 is muted and 1 is normal volume. Defaults to 1. |
| `SPEED` (optional) | The speed to play the sound at. Effectively a multiplier of the game's output sample rate (44100 Hz). Defaults to 1. |
## Notes

2
documentation/levels/cutscenes/stop_cutscene.md
View file

@ -17,3 +17,5 @@ stop_cutscene CUTSCENE_NAME
## Notes
Nothing is done if the specified cutscene is not running.
If multiple instances are running, all are stopped.

21
documentation/levels/cutscenes/wait_for_animation.md Normal file
View file

@ -0,0 +1,21 @@
# wait_for_animation
Blocks until a specified [armature](../level_objects/anim.md) has no in-progress
animation.
## Syntax
```
wait_for_animation ARMATURE_NAME
```
## Arguments
| Name | Description |
| ------------------ | ------------------------------------ |
| `ARMATURE_NAME` | The name of the armature to wait for |
## Notes
The state of the armature's current animation (playing/paused) has no effect.
For this cutscene step to finish, the armature must have no current animation.

5
documentation/levels/cutscenes/wait_for_cutscene.md
View file

@ -13,3 +13,8 @@ wait_for_cutscene CUTSCENE_NAME
| Name | Description |
| --------------- | ------------------------------------ |
| `CUTSCENE_NAME` | The name of the cutscene to wait for |
## Notes
If multiple instances of the cutscene are running, this step will block until
all have ended.

10
documentation/levels/cutscenes/wait_for_signal.md
View file

@ -10,12 +10,12 @@ 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. |
| 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.
FPS on NTSC/PAL-M consoles and 25 FPS on PAL consoles.

1
documentation/levels/level_objects/collision.md
View file

@ -36,6 +36,7 @@ If no collision layers are specified, the defaults are `STATIC`, `TANGIBLE`, and
* [Doors](./door.md) (when open)
* [Dynamic boxes](./dynamic_box.md)
* [Elevators](./elevator.md)
* [Fizzler](./fizzler.md) frames
* Player
* Portals
* [Security cameras](./security_camera.md)

2
documentation/levels/level_objects/fizzler.md
View file

@ -17,4 +17,4 @@ objects and any player-placed portals.
## Notes
The cube signal is only set for the frame that fizzling starts.
The cube signal is only emitted on the frame that fizzling starts.

13
documentation/levels/level_objects/signage.md
View file

@ -10,14 +10,17 @@ The large, illuminated informational sign at the beginning of each test chamber.
## Arguments
| Name | Description |
| --------------------- | ------------------------------------------------------------------------------------------------ |
| `TEST_CHAMBER_NUMBER` | The number of the test chamber to display on the sign, along with its associated warning images. |
| Name | Description |
| --------------------- | ----------------------------------------------------------------------------------------------- |
| `TEST_CHAMBER_NUMBER` | The number of the test chamber to display on the sign, along with its associated warning images |
## Notes
Signage is unlit by default. It can be activated using [cutscenes](../cutscenes/README.md).
Signage is unlit by default. It can be activated using the
[activate_signage](../cutscenes/activate_signage.md)
[cutscene](../cutscenes/README.md) step.
Due to the way they are rendered (by dynamically modifying the model's texture
coordinates), only one unique sign can be drawn - and therefore on screen - at a
time.
time. Placing more than one will cause them both to appear as whichever was
processed last.

13
documentation/levels/signals.md
View file

@ -30,15 +30,16 @@ For example, consider the following object names:
* `@ball_catcher exit_activate`
* `@door exit_activate`
In this example, the ball catcher sets the `exit_activate` signal when
activated. The door listens for that signal, and so it will open when a ball
reaches the ball catcher.
In this example, the [ball catcher](./level_objects/ball_catcher.md) sets the
`exit_activate` signal when activated. The [door](./level_objects/door.md)
listens for that signal, and so it will open when a ball 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. Some other special cases, such as buttons, can set
multiple signals. The exact name structure differs per object. See
[Level Objects](./level_objects/README.md) for more details.
indicator light strips. Some other special cases, like
[buttons](./level_objects/button.md), can set multiple signals. The exact name
structure differs per object. See [Level Objects](./level_objects/README.md) for
more details.
Objects which can be deactivated will stop emitting their associated signal when
that occurs.