Describe sound FX graphs and their parameters

Sounds gets a section on sound FX with its nodes, the preview in the tab and the parameters a Play sound hands in. Concepts, Home and Behaviors point to it.

Behaviors.md

@@ -252,7 +252,7 @@ the inspector).
   `Mouse position`, `Mouse button`, `Is hovered`, `Is touching`, `Layer of` (the collision layer of an object by name and number, see [Colliders](Colliders)), `Render layer of` (the render layer an object is drawn on, inherited or its own, see [Concepts](Concepts)), `Animation playing` (whether an animation runs on an object, its progress and time left) and `Animation length` (see [Animations](Animations)), `Get velocity`, `Joint position` (how far a hinge or a slider stands from how it was placed, see [Physics](Physics#joints)), `Current state` (name and id), `Is in state` (one boolean per state) ·
   actions `Move` (dx, dy, scale, dt — connect an event's dt for per-second movement; in the object's own axes, which a turned parent turns too; with *Collide with solids* it slides along what it hits, less friction, and outputs `blocked x/y`, `hit` and the contact `normal x/y`, see [Colliders](Colliders)), `Move toward` (x, y in world units, speed, dt: steps the object toward that point by at most speed times dt and stops exactly on it, also below a moved or turned parent; with *Collide with solids* it moves the way `Move` does; outputs `arrived`, the `distance` still left and `hit`. The way to walk an enemy to a spot, home or after the player), `Set position`, `Set Z` (the object's own `z`, which is its draw order: higher is in front from the next frame on, see [Scene editing](Scene-editing)), `Spawn`
   (asset input + x/y/z, optional parent → outputs the new object; the asset is picked on the node or arrives over an edge, from an `Asset` node, a variable or a list item. A pick saved while it was still a setting reads as that input's value, so older projects spawn as before; the same holds for the asset of `Is asset`), `Destroy` (removes the object with everything below it; with **keep children** on, only the object goes: its children move up to its parent (top level when it had none) and keep their place, rotation and size in the world, and the output `children` is the list of them, nearest level only. Its behaviors, its rigidbody and its joints go with it either way. In the editor run, children that are content of a placed container move up for the run only: their place belongs to the template, so the scene does not learn it), `Add joint` (ties an object to another while the game runs: the picked Joint asset is placed on *object* at x/y and connected to *connected*, the scene when nothing arrives; outputs the new joint, which `Destroy` lets go again, see [Physics](Physics#joints)), `Emit` (starts a particle source over, see *Particles*),
-  `Play sound` / `Stop sound` (see [Sounds](Sounds): the asset says how loud and whether it loops, the node's
+  `Play sound` / `Stop sound` (see [Sounds](Sounds): the asset says how loud and whether it loops, `fx` sends it through a sound FX, whose parameters a `Sound FX parameters` node sets through `fx params`, the node's
   `volume` multiplies that and its `loop` either leaves it alone or overrules it in either
   direction; every play is a voice of its own, so two in a row overlap, and the voice ends with the
   behavior that started it unless `detached` says otherwise),

Concepts.md

@@ -1,10 +1,10 @@
 | Term | Meaning |
 |---|---|
 | **Account** | Who you are signed in as. The editor asks for a user name and a password before it loads anything, and every project belongs to one account — see [Accounts](Accounts). The **Account** menu is at the far right of the toolbar and holds the name, *Change password* and *Logout*; signing in and out changes what the canvas draws, it never reloads the page. |
-| **Asset** | Named thing with a type (`scene`, `camera`, `clip`, `sprite`, `text`, `behavior`, `collider`, `container`, `texture`, `animation`, `statemachine`, `shader`, `shaderfunction`, `font`, `sound`, `particles`, `variables`) and typed properties. Assets have **no position**. |
+| **Asset** | Named thing with a type (`scene`, `camera`, `clip`, `sprite`, `text`, `behavior`, `collider`, `container`, `texture`, `animation`, `statemachine`, `shader`, `shaderfunction`, `font`, `sound`, `soundfx`, `particles`, `variables`) and typed properties. Assets have **no position**. |
 | **Texture** | An uploaded image. Scenes, textures, animations, state machines, shaders, fonts, sounds and Variables assets are the eight types that cannot be placed: a texture has no position, it is *worn* by a sprite through the ordinary property `texture`. See [Textures](Textures). |
 | **Font** | An uploaded typeface, worn by a text through the ordinary property `font`; no font means the editor's own. Uploaded and picked exactly like a texture, and stored the same way. See [Fonts](Fonts). |
-| **Sound** | An uploaded audio file. Uploaded, picked and stored exactly like a typeface — but nothing *wears* it: it is neither on screen nor in the scene, and a graph plays it with `Play sound`. Its own rows say how loud it is and whether it loops; the node scales the one and can overrule the other either way. See [Sounds](Sounds). |
+| **Sound** | An uploaded audio file. Uploaded, picked and stored exactly like a typeface — but nothing *wears* it: it is neither on screen nor in the scene, and a graph plays it with `Play sound`. Its own rows say how loud it is and whether it loops; the node scales the one and can overrule the other either way. A **sound FX** asset is a graph of effects (gain, pitch, EQ) a `Play sound` can send it through. See [Sounds](Sounds). |
 | **State machine** | A named set of **states**, edited as nodes in its own tab. A behavior puts it into a state with `Set state`, moves it along a named transition with `State transition` and branches on it with `State branch`. Its **Scope** says where the current state lives: **Local** gives every behavior instance one of its own, **Global** keeps a single one for the whole run. See [State machines](State-machines). |
 | **Shader** | A node graph that becomes the GLSL a sprite is drawn with, edited in its own tab. A sprite, a text or a particle source wears it through `shader`; the numbers the graph declares are rows below that dropdown. A **shader function** is a part of such a graph kept on its own and used as a node in other shaders. See [Shaders](Shaders). |
 | **Particles** | A node graph that says what *one* particle is as a function of its age and of a random number drawn once for it — no forces, no simulation. Unlike the other graph assets it **is** placeable: the object made from it is a source, whose rows say how many go out and for how long they live. Because a particle is a formula, the same second always draws the same picture and the tab's slider can jump to any of them exactly. See [Particles](Particles). |

Home.md

@@ -21,7 +21,7 @@ Live: <https://nockal.com/game-maker/> · Widget playground: <https://nockal.com
 | [Vector art](Vector-Art) | The vector art asset, canvas and shapes, the Pen and Select tools, the shape list, how a drawing is worn |
 | [Pixel art](Pixel-Art) | The pixel art asset and its palette, the tools, layers and frames, onion skin and the preview, resizing, how frames are worn and where the pixels are stored |
 | [Fonts](Fonts) | Uploading a typeface, what a text wears, what the editor falls back to |
-| [Sounds](Sounds) | Uploading a sound, what the asset says, `Play sound` and `Stop sound`, what a pause and a stop do to a voice |
+| [Sounds](Sounds) | Uploading a sound, what the asset says, `Play sound` and `Stop sound`, sound FX (gain, pitch, EQ), what a pause and a stop do to a voice |
 | [Animations](Animations) | Animation assets, the Animation tab, how they run |
 | [Curves](Curves) | Easings drawn by hand, the Curve tab, using one on a key or a `Lerp` |
 | [Tiles](Tiles) | The tile asset, plain tiles and the two autotile kinds, the pictures as animation steps, the Tile tab |

Sounds.md

@@ -36,7 +36,7 @@ so what the inspector plays is what the graph will play.
 
 | Node | What it does |
 | --- | --- |
-| **Play sound** | Starts the sound named by its `sound` input. `volume` **multiplies** the asset's own volume (1 leaves it alone), `loop` is a choice of three (*From the asset*, *On*, *Off*), and `detached` says the voice belongs to nobody. |
+| **Play sound** | Starts the sound named by its `sound` input. `volume` **multiplies** the asset's own volume (1 leaves it alone), `loop` is a choice of three (*From the asset*, *On*, *Off*), `detached` says the voice belongs to nobody, `fx` names a [sound FX](#sound-fx) to play it through, and `fx params` takes values for that FX's [parameters](#parameters). |
 | **Stop sound** | Silences every voice of the sound it names, however many plays started it — a loop included. Naming no sound silences everything the run is playing. |
 | **Sound** | A constant sound, for either of the two to work on through an edge. |
 
@@ -88,6 +88,57 @@ any edit, so a loop cannot pile up one voice per keystroke.
 normal speed rather than sounding like a tape being slowed — the global clock scales what the
 world does, not how the device plays back.
 
+## Sound FX
+
+A **sound FX asset** (**+ → Sound FX**) is what a sound is played *through*. It opens in a tab of
+its own with a node graph, like a shader: an **Input** (the sound as `Play sound` starts it), an
+**Output** (what is heard) and effects between them, wired `out` → `in`. The palette offers the
+Input and the Output once each; their pins carry sound and fit nothing but each other.
+
+| Node | What it does |
+| --- | --- |
+| **Gain** | Louder or quieter, in dB (`Gain (dB)`): 0 leaves it alone, -6 is about half as loud, +6 twice. Above 0 the sound can clip. |
+| **Pitch** | Higher or lower, in semitones (12 is an octave). It is the speed the sound is played at, so a higher sound is also shorter, and it applies to the **whole** sound wherever the node sits. |
+| **EQ** | Five bands in dB: 80 Hz and 12 kHz as shelves, 250 Hz, 1 kHz and 4 kHz as peaks. A band at 0 does nothing. |
+
+Every number of these nodes is an **input**: typed in while nothing is connected, or fed from a
+parameter of the Input. Each is held to its range (Gain -60 to +24 dB, Pitch and the EQ bands
+-24 to +24), whichever way the value arrives.
+
+**It is a line, not a mixer.** An input takes one edge, so the way from Input to Output never forks;
+a node hanging off the line is simply not heard. A node on the way with nothing coming in, or a
+graph without an Output, does not compile: the node says why, and the tab's header says it too
+(otherwise it counts the effects on the line).
+
+**Listening in the tab.** The header picks one of the project's sounds and plays it through the
+graph as it stands — the same library as a running game, so it sounds the way the game will.
+`Stop` there ends only what the tab started. Play is offered only while the graph compiles.
+Every parameter has a number field in the header, starting at its default: what Play hands in.
+Those values are the tab's own and never written into the asset.
+
+### Parameters
+
+The **Input** declares parameters in the inspector (**+ Parameter**): a name and a **Default**,
+numbers only. Each one is an output of the Input that can feed any number input of the graph, so
+"how low" or "how loud" is decided when the sound is played, not when the FX is built.
+
+In a behavior, a **Sound FX parameters** node names the FX and picks the parameters it sets, the
+way a `Variables` node picks variables: each picked one is a number input, starting at the
+default the Input gives it. Its `params` output goes into `fx params` of `Play sound`.
+
+- A parameter not picked, or nothing at `fx params`, plays at its **default**.
+- A name the played FX does not know is left out. Where both nodes name their FX in place and the
+  two differ, `Play sound` warns: *The parameters are for another sound FX*.
+- Renaming a parameter at the Input renames it in every Sound FX parameters node naming that FX,
+  edges and typed-in values included. A removed one stays on those nodes in red.
+- **A value counts from the start of a voice.** Changing it later does not change a sound that is
+  already playing.
+
+**In the game** the `fx` input of `Play sound` names the asset. An FX that does not compile, or
+one that was deleted, plays the sound **dry** rather than not at all: a broken effect should not
+silence the game. One asset can serve any number of sounds, so "everything in the cave sounds
+hollow" is one asset and one pick per node.
+
 **Known limits.** There is no `Set volume` on a playing voice, no `Is playing`, no fade and no
 positional audio: a sound is as loud as the asset and the node together say, from the moment it
 starts. There is no mixer and no master volume — the browser's own is the one. And nothing