Skip to content

Commit

Permalink
Adds missing queue template docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@JujuAdams
JujuAdams committed Dec 18, 2024
1 parent 466da87 commit 73ab114
Show file tree
Hide file tree
Showing 3 changed files with 98 additions and 22 deletions.
16 changes: 16 additions & 0 deletions docs/6.1/Config-JSON.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,22 @@ If the `emitter` parameter is defined, Vinyl will attempt to play sounds defined

 

## Queue Template

|Property |Datatype |Default |Notes |
|---------------|---------------|-----------------------|-----------------------------------------------------------------------------------------------|
|`queueTemplate`|string |N/A |**Required.** Name of the queue template |
|`sounds` |array |N/A |**Required.** Sounds to populate the queue with |
|`behavior` |integer |`VINYL_QUEUE.DONT_LOOP`| |
|`loopQueue` |boolean |`false` | |
|`emitter` |string |`undefined` |Name of a registered emitter to play sounds on by default |

Sets up a queue template that can be used to create a queue at runtime using the `VinylQueueCreateFromTemplate()` function (which effectively calls `VinylQueueCreate()` for you using parameters defined in the template).

If the `emitter` parameter is defined, Vinyl will attempt to play sounds in the queue on the specified emitter. You can register an emitter with `VinylRegisterEmitter()`.

 

## Mixes

?> Mixes cannot be children of other mixes i.e. there are no hierarchical mixes.
Expand Down
42 changes: 35 additions & 7 deletions docs/6.1/Functions-Queue.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

## `VinylQueueCreate`

`VinylQueueCreate(behaviour, loopQueue, [gain=1])`
`VinylQueueCreate(behaviour, loopQueue, [gain=1], [emitter])`

<!-- tabs:start -->

Expand All @@ -18,15 +18,15 @@
|`loopQueue`|boolean |Whether to loop the queue by pushing stopping sounds to the bottom of the queue|
|`[gain]` |number |Local gain to set for the queue |

Create a new sound queue. A sound queue is used to play audio in a particular sequence which is useful to set up dynamix soundtracks, in-game radio stations etc. This function returns a queue index which can be used like the voice index returned by `VinylPlay()`. This means you can call `VinylFadeOut()`, `VinylPause()`, `VinylSetGain()` etc. targeting a queue and the queue will behave appropriately.
Create a new sound queue. A sound queue is used to play audio in a particular sequence which is useful to set up dynamic soundtracks, in-game radio stations etc. This function returns a queue index which can be used like the voice index returned by `VinylPlay()`. This means you can call `VinylFadeOut()`, `VinylPause()`, `VinylSetGain()` etc. targeting a queue and the queue will behave appropriately.

There are three behaviours that a sound queue can use, found in `VINYL_QUEUE` enum:

|Enum Member |Behaviour |
|---------------|-----------------------------------------------------------------------|
|`.DONT_LOOP` |Play each sound in the queue once |
|`.LOOP_ON_LAST`|Play each sound in the queue once until the last sound, which is looped|
|`.LOOP_EACH` |Loop each sound |
|Enum Member |Value|Behaviour |
|---------------|-----|-----------------------------------------------------------------------|
|`.DONT_LOOP` |`0` |Play each sound in the queue once |
|`.LOOP_ON_LAST`|`1` |Play each sound in the queue once until the last sound, which is looped|
|`.LOOP_EACH` |`2` |Loop each sound |

The currently playing sound can be manually set to loop or not loop by calling `VinylSetLoop()` targeting the queue. If a sound is not looping and completes playing then the next sound in the queue will be played.

Expand All @@ -44,6 +44,34 @@ No example provided.

&nbsp;

## `VinylQueueCreateFromTemplate`

`VinylQueueCreateFromTemplate(queueTemplateName, [gain=1], [emitter], [fadeInRate=infinity])`

<!-- tabs:start -->

#### **Description**

*Returns:* Queue voice

|Name |Datatype |Purpose |
|-------------------|-----------------|-------------------------------------------------------------------------------|
|`queueTemplateName`|string |Name of the template to use |
|`[gain]` |number |Local gain to set for the queue |
|`[emitter]` |GameMaker emitter|GameMaker emitter to play sounds on |

Create a new sound queue using parameters previously defined by a queue template, either in the [Config JSON](Config-JSON?id=queue-template) or by using the `VinylSetupQueueTemplate()` function. The `emitter` parameter for this function, if specified, will override the emitter defined in the queue template.

#### **Example**

```gml
No example provided.
```

<!-- tabs:end -->

&nbsp;

## `VinylQueueSetBehaviour`

`VinylQueueSetBehaviour(voice, behaviour, [setForPlaying=true])`
Expand Down
62 changes: 47 additions & 15 deletions docs/6.1/Functions-Runtime-Setup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,42 @@ No example provided.

&nbsp;

## `VinylSetupHLT`

`VinylSetupHLT(patternName, [soundHead], soundLoop, [soundTail], [gain=1], [mix=VINYL_DEFAULT_MIX], [duckerName], [duckPriority=0], [emitterAlias], [metadata])`

<!-- tabs:start -->

#### **Description**

*Returns:* N/A (`undefined`)

|Name |Datatype|Purpose |
|----------------|--------|--------------------------------------------------------------------------------------------|
|`patternName` |string |Name of the pattern |
|`[soundHead]` |sound |Optional. Sound to play first |
|`soundLoop` |sound |Sound to loop on |
|`[soundTail]` |sound |Optional. Sound to play last |
|`[mix]` |string |Optional, defaults to `VINYL_DEFAULT_MIX`. Which mix to play sounds on |
|`[duckerName]` |string |Optional. Which ducker to play sounds on |
|`[duckPriority]`|number |Optional, defaults to 0. What ducker priority to play sounds with |
|`[emitterAlias]`|string |Optional, defaults to `undefined`. Name of a registered emitter to play sounds on by default|
|`[metadata]` |any |Optional. Metadata to attach to the pattern |

Sets up a head-loop-tail pattern for playback with Vinyl. When played, an HLT pattern will first play the "head" sound. Once that sound has finished, the loop sound will be played. If `VinylSetLoop()` is called on the HLT voice to stop looping then the tail sound will be played after the loop sound has finished.

If the `emitterAlias` parameter is defined, Vinyl will attempt to play the sound on the specified emitter when playing the pattern using `VinylPlay()`. You can register an emitter with `VinylRegisterEmitter()`.

#### **Example**

```gml
No example provided.
```

<!-- tabs:end -->

&nbsp;

## `VinylSetupBlend`

`VinylSetupBlend(patternName, soundArray, [loop], [gain=1], [animCurve], [mix=VINYL_DEFAULT_MIX], [duckerName], [duckPriority=0], [emitterAlias], [metadata])`
Expand Down Expand Up @@ -122,31 +158,27 @@ No example provided.

&nbsp;

## `VinylSetupHLT`
## `VinylSetupQueueTemplate`

`VinylSetupHLT(patternName, [soundHead], soundLoop, [soundTail], [gain=1], [mix=VINYL_DEFAULT_MIX], [duckerName], [duckPriority=0], [emitterAlias], [metadata])`
`VinylSetupQueueTemplate(queueTemplateName, soundArray, behaviour, loopQueue, [emitterAlias])`

<!-- tabs:start -->

#### **Description**

*Returns:* N/A (`undefined`)

|Name |Datatype|Purpose |
|----------------|--------|--------------------------------------------------------------------------------------------|
|`patternName` |string |Name of the pattern |
|`[soundHead]` |sound |Optional. Sound to play first |
|`soundLoop` |sound |Sound to loop on |
|`[soundTail]` |sound |Optional. Sound to play last |
|`[mix]` |string |Optional, defaults to `VINYL_DEFAULT_MIX`. Which mix to play sounds on |
|`[duckerName]` |string |Optional. Which ducker to play sounds on |
|`[duckPriority]`|number |Optional, defaults to 0. What ducker priority to play sounds with |
|`[emitterAlias]`|string |Optional, defaults to `undefined`. Name of a registered emitter to play sounds on by default|
|`[metadata]` |any |Optional. Metadata to attach to the pattern |
|Name |Datatype |Purpose |
|-------------------|------------------|---------------------------------------------------------------------------------------------------|
|`queueTemplateName`|string |Name of the queue template |
|`soundArray` |array of sounds |Array of sounds to play in queue when using this template |
|`behaviour` |`VINYL_QUEUE` enum|Behaviour to use for the queue. See [`VinylQueueCreate`](Functions-Queue?id=vinylqueuecreate) |
|`loopQueue` |boolean |Whether to loop the queue by pushing stopping sounds to the bottom of the queue |
|`[emitterAlias]` |string |Optional, defaults to `undefined`. Name of a registered emitter to play sounds on by default |

Sets up a head-loop-tail pattern for playback with Vinyl. When played, an HLT pattern will first play the "head" sound. Once that sound has finished, the loop sound will be played. If `VinylSetLoop()` is called on the HLT voice to stop looping then the tail sound will be played after the loop sound has finished.
Sets up a queue template that can be used to create a queue at runtime using the `VinylQueueCreateFromTemplate()` function (which effectively calls `VinylQueueCreate()` for you using parameters defined in the template).

If the `emitterAlias` parameter is defined, Vinyl will attempt to play the sound on the specified emitter when playing the pattern using `VinylPlay()`. You can register an emitter with `VinylRegisterEmitter()`.
If the `emitterAlias` parameter is defined, Vinyl will attempt to play sounds in the queue on the specified emitter. You can register an emitter with `VinylRegisterEmitter()`.

#### **Example**

Expand Down

0 comments on commit 73ab114

Please sign in to comment.