Skip to content

Commit

Permalink
Adds 6.1 docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@JujuAdams
JujuAdams committed Sep 10, 2024
1 parent 010dc62 commit 2f8a7f5
Show file tree
Hide file tree
Showing 5 changed files with 90 additions and 30 deletions.
21 changes: 12 additions & 9 deletions docs/6.1/Config-JSON.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,18 +65,21 @@ In this JSON we see four Vinyl definitions: three sounds and one mix. Two of the

## Sounds

|Property |Datatype |Default |Notes |
|----------|----------------|-----------|-----------------------------------------------------------------------------------------------------------|
|`sound` |string or sound |N/A |**Required.** Should be a sound resource, or the name of a sound resource as a string |
|`gain` |number |`1` | |
|`pitch` |number |`1` | |
|`loop` |boolean |`undefined`|Can inherit from a mix if set to `undefined` and the mix has `.membersLoop` set to either `true` or `false`|
|`duckOn` |string |`undefined`|[Ducker](Ducker) to push voices to |
|`duckPrio`|number |`0` |Priority for voices when pushed to the ducker above |
|`metadata`|any |`undefined`|Returned by `VinylGetMetadata()` |
|Property |Datatype |Default |Notes |
|--------------|----------------|-----------|-----------------------------------------------------------------------------------------------------------|
|`sound` |string or sound |N/A |**Required.** Should be a sound resource, or the name of a sound resource as a string |
|`gain` |number |`1` | |
|`pitch` |number |`1` | |
|`loop` |boolean |`undefined`|Can inherit from a mix if set to `undefined` and the mix has `.membersLoop` set to either `true` or `false`|
|`duckOn` |string |`undefined`|[Ducker](Ducker) to push voices to |
|`duckPrio` |number |`0` |Priority for voices when pushed to the ducker above |
|`emitterAlias`|string |`undefined`|Name of a registered emitter to play the sound on by default |
|`metadata` |any |`undefined`|Returned by `VinylGetMetadata()` |

Sets up a sound asset for playback with Vinyl. Any sound asset without a Vinyl definition will be played at a gain of 1, without any pitch shifting, and on the default mix.

If the `emitterAlias` property is defined, Vinyl will attempt to play the sound on the specified emitter. You can register an emitter with `VinylRegisterEmitter()`.

 

## Shuffle
Expand Down
5 changes: 3 additions & 2 deletions docs/6.1/Functions-Mix.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ No example provided.

## `VinylMixVoicesFadeOut`

`VinylMixVoicesFadeOut(mixName, [rateOfChange])`
`VinylMixVoicesFadeOut(mixName, [rateOfChange], [pause=false])`

<!-- tabs:start -->

Expand All @@ -69,8 +69,9 @@ No example provided.
|----------------|--------|-------------------------------------------------------------------------------------------------------------------|
|`mixName` |string |Name of the mix to target |
|`[rateOfChange]`|number |Optional, defaults to `VINYL_DEFAULT_FADE_OUT_RATE`. How fast to reach zero gain, measured in gain units per second|
|`[pause]` |boolean |Optional, defaults to `false`. Whether mix voices should pause when faded out |

Fades out all voices currently playing in a given mix. Once a voice is set to fade out, it cannot be stopped. The rate of change for this function is measured in "gain units per second".
Fades out all voices currently playing in a given mix. Once a voice is set to fade out, it cannot be stopped. The rate of change for this function is measured in "gain units per second". If the optional `pause` parameter is set to `false` (the default) then mix voices will stop once faded out. If the `pause` parameter is set to `true` then mix voices will be paused instead and can be unpaused using the `VinylMixVoicesSetPause()` or `VinylSetPause()` functions. When resuming playback of mix voices, it will *not* fade in.

#### **Example**

Expand Down
79 changes: 66 additions & 13 deletions docs/6.1/Functions-Runtime-Setup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,19 +20,22 @@

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

|Name |Datatype|Purpose |
|----------------|--------|-------------------------------------------------------------------------|
|`sound` |sound |Sound asset to target |
|`[gain]` |number |Optional, defaults to 1. Gain for the sound |
|`[pitch]` |number |Optional, defaults to 1. Pitch multiplier for the sound |
|`[loop]` |boolean |Optional. Whether the sound loops |
|`[mix]` |string |Optional, defaults to `VINYL_DEFAULT_MIX`. Which mix to play the sound on|
|`[duckerName]` |string |Optional. Which ducker to play the sound on |
|`[duckPriority]`|number |Optional, defaults to 0. What ducker priority to play the sound with |
|`[metadata]` |any |Optional. Metadata to attach to the sound |
|Name |Datatype|Purpose |
|----------------|--------|-----------------------------------------------------------------------------------------------|
|`sound` |sound |Sound asset to target |
|`[gain]` |number |Optional, defaults to 1. Gain for the sound |
|`[pitch]` |number |Optional, defaults to 1. Pitch multiplier for the sound |
|`[loop]` |boolean |Optional. Whether the sound loops |
|`[mix]` |string |Optional, defaults to `VINYL_DEFAULT_MIX`. Which mix to play the sound on |
|`[duckerName]` |string |Optional. Which ducker to play the sound on |
|`[duckPriority]`|number |Optional, defaults to 0. What ducker priority to play the sound with |
|`emitterAlias` |string |Optional, defaults to `undefined`. Name of a registered emitter to play the sound on by default|
|`[metadata]` |any |Optional. Metadata to attach to the sound |

Sets up a sound asset for playback with Vinyl. This is an optional function and any sound asset without a Vinyl definition will be played at a gain of 1, without any pitch shifting, and on the default mix.

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

#### **Example**

```gml
Expand Down Expand Up @@ -320,7 +323,7 @@ No example provided.

Imports a JSON that contains definitions for mixes, sounds, and patterns. This is sometimes more convenient than writing lines of code.

?> You can read more about [configuration JSON here](https://www.jujuadams.com/Vinyl/#/6.0/Config-JSON).
?> You can read more about [configuration JSON here](Config-JSON).

#### **Example**

Expand Down Expand Up @@ -348,12 +351,62 @@ No example provided.

Exports the current Vinyl setup as JSON. The root node of this JSON is always an array. JSON can be used to communicate the Vinyl setup to other tools or can be saved to disk for reference later.

?> You can read more about [configuration JSON here](https://www.jujuadams.com/Vinyl/#/6.0/Config-JSON).
?> You can read more about [configuration JSON here](Config-JSON).

#### **Example**

```gml
No example provided.
```

<!-- tabs:end -->

&nbsp;

## `VinylRegisterEmitter`

`VinylPatternExists(semitter, alias)`

<!-- tabs:start -->

#### **Description**

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

|Name |Datatype|Purpose |
|---------|--------|-------------------------------------------|
|`emitter`|emitter |Emitter to register |
|`alias` |string |Name of the emitter for use when setting up|

Registers an emitter for use with the `emitter` property on patterns. You should call this function once, ideally on boot. This emitter should further exist for the lifetime of the game and is intended for use with audio effect buses.

#### **Example**

```gml
No example provided.
```

<!-- tabs:end -->
&nbsp;

## `VinylPatternExists`

`VinylPatternExists(sound/pattern, [explicit=false])`

<!-- tabs:start -->

#### **Description**

*Returns:* Boolean, whether the sound asset or pattern exists

|Name |Datatype |Purpose |
|---------------|-------------|----------------------------------------------------------------------------------------|
|`sound/pattern`|sound/pattern|Sound asset or pattern to target |
|`[explicit]` |boolean |Whether sound assets require an explicit pattern definition to be considering "existing"|

Returns whether a pattern exists i.e. has been defined by a `VinylSetup*()` function (including JSON variants). If the `explicit` parameter is set to `false` (the default) then this function will always return `true` if a sound asset is passed as the parameter for this function regardless of whether a pattern has explicitly been created for the sound asset or not.

#### **Example**

```gml
No example provided.
```
2 changes: 2 additions & 0 deletions docs/6.1/Pausing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,8 @@ No example provided.

Returns whether the target voice is paused or unpaused.

!> This function only works with **voices** and will not work with patterns or sound assets.

#### **Example**

```gml
Expand Down
13 changes: 7 additions & 6 deletions docs/6.1/Stopping-Audio.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,20 +56,21 @@ No example provided.

## `VinylFadeOut`

`VinylFadeOut(voice, [rateOfChange])`
`VinylFadeOut(voice, [rateOfChange], [pause=false])`

<!-- tabs:start -->

#### **Description**

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

|Name |Datatype|Purpose |
|----------------|--------|------------------------------------------------------------------------------------------|
|`voice` |voice |Voice to target |
|`[rateOfChange]`|number |Optional, defaults to 1. How fast to fade out the voice, measured in gain units per second|
|Name |Datatype|Purpose |
|----------------|--------|--------------------------------------------------------------------------------------------|
|`voice` |voice |Voice to target |
|`[rateOfChange]`|number |Optional, defaults to `1`. How fast to fade out the voice, measured in gain units per second|
|`[pause]` |boolean |Optional, defaults to `false`. Whether the voice should pause when faded out |

Fades out out a voice. Once a voice is set to fade out, it cannot be stopped.
Fades out out a voice. Once a voice is set to fade out, it cannot be stopped. The rate of change for this function is measured in "gain units per second". If the optional `pause` parameter is set to `false` (the default) then the voice will stop once faded out. If the `pause` parameter is set to `true` then the voice will be paused instead and can be unpaused using the `VinylSetPause()` function. When resuming playback of the voice, it will *not* fade in.

#### **Example**

Expand Down

0 comments on commit 2f8a7f5

Please sign in to comment.