209 lines
3.6 KiB
Markdown
209 lines
3.6 KiB
Markdown
# SEQUENCE
|
||
|
||
An animation sequence. The `.SEQ` file contains **sequence events** — descriptions of [`ANIMO`](ANIMO.md) animation runs played in sync with accompanying [`SOUND`](SOUND.md) effects. Sequences let you treat picture and audio as a single, script-controlled unit.
|
||
|
||
## Fields
|
||
|
||
### FILENAME
|
||
|
||
```
|
||
STRING FILENAME
|
||
```
|
||
|
||
Path to the `.SEQ` file holding the sequence definition.
|
||
|
||
## Methods
|
||
|
||
### GETEVENTNAME
|
||
|
||
```
|
||
STRING GETEVENTNAME()
|
||
```
|
||
|
||
Returns the name of the sequence event currently being played.
|
||
|
||
**Returns**: event name.
|
||
|
||
**Examples**
|
||
|
||
```
|
||
SEQSFX^GETEVENTNAME();
|
||
```
|
||
|
||
### GETPLAYING
|
||
|
||
```
|
||
STRING GETPLAYING()
|
||
```
|
||
|
||
Returns the name of the [`ANIMO`](ANIMO.md) variable being played as part of the currently active event. If no event is active, an empty string is returned.
|
||
|
||
**Returns**: the animation name or `""`.
|
||
|
||
### HIDE
|
||
|
||
```
|
||
void HIDE()
|
||
```
|
||
|
||
Hides every animation belonging to the sequence.
|
||
|
||
**Examples**
|
||
|
||
```
|
||
SEQJEAN^HIDE();
|
||
SEQKRET^HIDE();
|
||
```
|
||
|
||
### ISPLAYING
|
||
|
||
```
|
||
BOOL ISPLAYING()
|
||
```
|
||
|
||
Checks whether the sequence is currently playing.
|
||
|
||
**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the sequence is in playback.
|
||
|
||
**Examples**
|
||
|
||
```
|
||
SEQBLANK^ISPLAYING();
|
||
SEQMANDOLINA^ISPLAYING();
|
||
```
|
||
|
||
### PAUSE
|
||
|
||
```
|
||
void PAUSE()
|
||
```
|
||
|
||
Pauses the sequence's playback.
|
||
|
||
**Examples**
|
||
|
||
```
|
||
SEQCS^PAUSE();
|
||
```
|
||
|
||
### PLAY
|
||
|
||
```
|
||
void PLAY(STRING eventName)
|
||
```
|
||
|
||
Starts playing the sequence event with the given name. On start, the [`ONSTARTED`](#onstarted) signal is fired with the event name as its argument.
|
||
|
||
**Parameters**
|
||
|
||
- `eventName` — name of the event from the `.SEQ` file.
|
||
|
||
**Examples**
|
||
|
||
```
|
||
GADAJA2^PLAY("KOGF2");
|
||
SEQNARRATOR^PLAY(VARSTRING0);
|
||
SEQLAB^PLAY(["PLAYER"+VARINT0]);
|
||
SEQREKSIO^PLAY($1);
|
||
```
|
||
|
||
### RESUME
|
||
|
||
```
|
||
void RESUME()
|
||
```
|
||
|
||
Resumes a sequence paused with [`PAUSE`](#pause).
|
||
|
||
**Examples**
|
||
|
||
```
|
||
SEQCS^RESUME();
|
||
```
|
||
|
||
### SETFREQ
|
||
|
||
```
|
||
void SETFREQ(INTEGER sampleRate)
|
||
```
|
||
|
||
Sets the sample rate used by the sound attached to the currently active sequence event. Equivalent to calling [`SETFREQ`](SOUND.md#setfreq) on the [`SOUND`](SOUND.md) object of that event.
|
||
|
||
**Parameters**
|
||
|
||
- `sampleRate` — the target sample rate in Hz.
|
||
|
||
### SETPAN
|
||
|
||
```
|
||
void SETPAN(INTEGER pan)
|
||
```
|
||
|
||
Sets the stereo panning (left/right balance) of the active event's sound. A value of `400` corresponds to a centred mix, `0` to fully left, and `800` to fully right.
|
||
|
||
**Parameters**
|
||
|
||
- `pan` — panning value in the `0–800` range.
|
||
|
||
### SETVOLUME
|
||
|
||
```
|
||
void SETVOLUME(INTEGER volume)
|
||
```
|
||
|
||
Sets the active event sound's volume. A value of `1600` corresponds to maximum volume; `0` mutes the sound.
|
||
|
||
**Parameters**
|
||
|
||
- `volume` — volume value in the `0–1600` range.
|
||
|
||
### SHOW
|
||
|
||
```
|
||
void SHOW()
|
||
```
|
||
|
||
Shows every animation belonging to the sequence.
|
||
|
||
### STOP
|
||
|
||
```
|
||
void STOP([BOOL emitSignal])
|
||
```
|
||
|
||
Stops the sequence's playback.
|
||
|
||
**Parameters**
|
||
|
||
- `emitSignal` — (optional) if `FALSE`, the [`ONFINISHED`](#onfinished) signal is suppressed. By default, the signal is fired.
|
||
|
||
**Examples**
|
||
|
||
```
|
||
SEQBLANK^STOP(FALSE);
|
||
SEQMENU^STOP(TRUE);
|
||
SEQZMIANAWAGIREX^STOP();
|
||
```
|
||
|
||
## Signals
|
||
|
||
### ONINIT
|
||
|
||
Fired when the object is initialised.
|
||
|
||
### ONSTARTED
|
||
|
||
Fired when a sequence event starts playing. The argument (`$1`) is the name of the started event.
|
||
|
||
### ONFINISHED
|
||
|
||
Fired when a sequence event finishes (naturally or via a [`STOP`](#stop) call that does not suppress the signal). The argument (`$1`) is the name of the finished event. The signal is [parameterised](../engine/events.md#parameterised-signals) by that name, so a handler can target a specific event:
|
||
|
||
```
|
||
SEQUENCE:ONFINISHED^IDLE=BEHAFTERIDLE
|
||
```
|
||
|
||
### ONSIGNAL
|
||
|
||
Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
|