From 528dc7fd5d585f36692f83aea22dd42d53851c15 Mon Sep 17 00:00:00 2001 From: MelekTaus Date: Tue, 6 Oct 2026 17:38:56 +0200 Subject: [PATCH] Play and stop a song from a behavior in the game (#336) Songs gets a section on playing one in a game. Patterns and Behaviors name Play song and Stop song. --- Behaviors.md | 4 +++- Patterns.md | 8 ++++---- Songs.md | 41 +++++++++++++++++++++++++++++++++++++---- 3 files changed, 44 insertions(+), 9 deletions(-) diff --git a/Behaviors.md b/Behaviors.md index 51117ec..1ba1dea 100644 --- a/Behaviors.md +++ b/Behaviors.md @@ -261,7 +261,9 @@ the inspector). behavior that started it unless `detached` says otherwise), `Play note` (one note of an instrument, its parameters from an `Instrument parameters` node, see [Instruments](Instruments)), `Play pattern` / `Stop pattern` (a whole pattern through its instrument, looped or once, owned - like a sound, see [Patterns](Patterns#playing-one-in-a-game)), + like a sound, see [Patterns](Patterns#playing-one-in-a-game)), `Play song` / `Stop song` (a song + at its tempo, an intro once and then round its loop, faded in and out, see + [Songs](Songs#playing-one-in-a-game)), `Load scene` (swaps the running scene once the frame is over — see [Scenes](Scenes)), `Log`, `Stop game`, `Restart game`, `Pause game`, `Resume game`, `Set time scale` with the data nodes `Is game paused` and `Time scale` (see [Concepts](Concepts), *The game pauses itself*), `Apply force`, `Apply impulse`, `Set velocity`, `Set angular velocity`, `Set gravity` (see [Physics](Physics)), diff --git a/Patterns.md b/Patterns.md index 7991f6a..0f274f7 100644 --- a/Patterns.md +++ b/Patterns.md @@ -115,15 +115,15 @@ no notes. Firing it twice plays the pattern twice, overlapping. Its files are lo first note may come a moment later, but always in time with the ones after it. **Stop pattern** stops every playing of the pattern it names, and every pattern where it names -none (sounds play on). With `playback` connected it stops only that one, and nothing where it is 0. +none (songs and sounds play on). With `playback` connected it stops only that one, and nothing where it is 0. Its notes fade out in 10 ms; with **Let ring** a note of an instrument with an [Envelope](Instruments#envelopes) falls away in its release. `Stop sound` reaches patterns as well: naming no sound it stops everything, patterns included, and its `voice` takes a `playback`. The end of the run stops every pattern. -This is a step ahead of songs in a game: a [song](Songs) plays several patterns on tracks in the -editor, and a game will play a song (#336). A pattern has no tempo input in the game yet, and nothing tells a graph that a -pattern played once has ended. +To play several patterns and sounds together, lay them out in a [song](Songs) and play that with +[Play song](Songs#playing-one-in-a-game). A pattern has no tempo input in the game yet, and nothing +tells a graph that a pattern played once has ended. Measured (2026-10-06, e2e 64): a bar of quarters at 150 BPM played by `Play pattern` in a game was planned 0.4 s apart, round and round, owned by the behavior; stopping the game ended it, and played diff --git a/Songs.md b/Songs.md index 39f0344..04261c1 100644 --- a/Songs.md +++ b/Songs.md @@ -114,10 +114,43 @@ pattern at bar 3 on the third, at 120 BPM, were planned 4 s apart, the pattern's each on the bus of its track; a track turned down to -6 dB was set to 0.501 on its bus, and muting a track while the song played set its bus to 0. +## Playing one in a game + +**Play song** plays a song at its tempo, its tracks with the volume, pan, mute and solo they have, +on the same scheduler as the tab. + +| Input | | +|---|---| +| `song` | The song asset. | +| `volume` | 0 to 1, the level of the whole song. | +| `fade in` | Seconds it rises from silence to `volume`, from its first note on. 0 starts it at once. | +| `loop` | On (the default): it plays from its start, and once it gets to the end of the loop on its ruler it goes round that loop until it is stopped. So an intro before the loop is heard once. With no loop set the whole song is the loop. Off: once to its end, and it is over by itself. | +| `detached` | As for a sound: off (the default), the song belongs to the object of the behavior and stops when that object is destroyed, which a `Load scene` does unless the object is kept; on, it outlives it. | + +It gives out `playback`, the number of this playing, and 0 where the song has nothing on its +tracks. Firing it twice plays the song twice, side by side: to swap one song for another, stop the +first. Its files are loaded first, so the first note may come a moment later, but always in time +with the ones after it. The loop of the ruler is the one the game plays: one set for editing a few +bars is heard in the game too. + +**Stop song** stops every playing of the song it names, and every song where it names none +(patterns and sounds play on). With `playback` connected it stops only that one, and nothing where +it is 0. `fade out` is the seconds it falls silent over first; it plays on meanwhile. `Stop sound` +naming no sound stops songs too, and the end of the run stops every song. + +Each playing is heard through a level of its own, which the fades move, with a bus inside it for +each track. `Pause game` leaves the music playing, and `Set time scale` does not slow it; the pause +in the toolbar holds it where it is, as it holds every sound. + +Measured (2026-10-06, e2e 65): a sound clip on the first bar and a pattern on the second, looped +there, played by `Play song` at 120 BPM: the clip once, the pattern's notes 2 s after it and every +2 s from then on. The playing's level stood at its volume of 0.8, a track at -6 dB and panned half +left sat inside it at 0.501 and -0.5. The toolbar's pause held the clock, and `Stop song` with a +fade of 1 s ended it, its buses with it. + ## Not yet -A game cannot play a song yet: that is #336 (a pattern it can, see -[Playing one in a game](Patterns#playing-one-in-a-game)). No automation (#337), no markers in the -ruler (with game sync, #338), no effects on a track (#325), no song inside a song, no held note -(drone) as an item. A pattern item cannot be made into a pattern of its own (*make unique*); for a +Nothing tells a graph that a song played once has ended, and there is no node that changes the +volume of a playing song. No start at a marker (#338), no automation (#337), no effects on a track +(#325), no song inside a song, no held note (drone) as an item. A pattern item cannot be made into a pattern of its own (*make unique*); for a variation, duplicate the pattern in the Assets panel and pick it on the item.