A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(music): a piece that ends rings out and can fade, and a loop says where it meets itself - loop false keeps what rings past the last bar, fadeIn and fadeOut are its to set, and a loop whose last bar is unlike its first is a warning that names what stops dead
yhh841d49f0da2c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 54c501a99..12481482f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -22,7 +22,7 @@ published separately; it ships inside the editor.- **A flower turns to face the eye.** A flat flower faces the sky, so a field of them is seen edge on from a few metres up and has no colour a field away; tipping each far plant's head at random (`farTilt`) showed half of them from behind. `Foliage.faceEyeNear` and `Foliage.faceEye` turn the head of every mesh plant toward the eye, by the first close to and by the second from half the draw distance away, as a clump of flowers shows its colour from the side. It is done the way a pivot painted into a uv is elsewhere: the copies carry in a second uv where each vertex of a head sits from its plant's axis, and a material's vertex hook now reads a mesh's second uv as `es_vertexUv1` (zero on a mesh with none), beside `es_vertexColor`. At 0 and 0, the default, no channel is added and nothing turns.- **A far field of flowers shows its colour.** A mesh plant kept in a far version grows across the ground to stand for those left out. A flat flower grown that way is a disc facing the sky: from an eye a few metres up it is seen edge on, and a meadow that is all flowers at your feet was plain green a field away. `Foliage.farTilt` tips the top of each far plant over by so many degrees (the last tenth of its height: the flower, not its stem), each plant its own way round, so half the field shows its face. 0, the default, leaves a far plant as it was.- **A layer with a grain is read without repeat and without hexagons.** Near the eye a terrain layer is read in hexagonal cells, each shifted and turned at random, so no tile shows. A layer with a direction to it (sand in ripples, rock in beds) turned cell by cell has its normal map lit cell by cell, and the ground showed a mosaic of light and dark hexagons a metre wide. `u_antiTileTurn` on the Terrain and Terrain Layers materials is how far round a cell may be turned: 1, the default, is any way as before; 0 shifts the cell and does not turn it, which is the setting for a layer with a grain.-- **An AI can make background music.** A sound effect is layers; a piece of music is notes, and writing it as layers would be writing every note as a wave. A piece is now an `.esmusic`: instruments, each the layers of a sound written at the A of 440 Hz and struck at the pitch of every note; patterns of a few bars, each track a line of steps (`1 - - . 5, - 3'`, `[1 3 5]`, `x` for a drum) written as degrees of the key, so a line cannot leave it; chords that a bass or a pad follows, written once and moving with them; and the order the patterns come in, with instruments left out of a part so a piece builds. It makes a `.wav` that runs into itself, what rings past its end added to its start, and with `stems` a file for each instrument that add up to the whole, for music that grows with the game. Whoever writes it cannot hear it, so `music_write`, `music_edit` and `music_read` answer with a picture of the notes, every one a bar in its instrument's colour, and with what can be said of them unheard: two lines crowding one octave, notes outside the key, how loud each instrument is beside the whole. Instruments of layers are made sounds, which suit electronic, retro and ambient music. A piano or strings that pass for real ones are recordings: an instrument may instead have `samples`, a recording in the project for each of a few notes, and every note of the piece is played from the recording nearest it, faster to be higher and slower to be lower; what dies of itself ends with its recording, and what is held goes round the steady middle of it with `loop`. Each recording is listened to: one whose pitch is not the note it is called, or a whole library an octave out because it counts its octaves from another C, is a warning that names the note to set, since nothing in the notes would show an instrument out of tune. The engine ships no recordings of its own: they are the project's.+- **An AI can make background music.** A sound effect is layers; a piece of music is notes, and writing it as layers would be writing every note as a wave. A piece is now an `.esmusic`: instruments, each the layers of a sound written at the A of 440 Hz and struck at the pitch of every note; patterns of a few bars, each track a line of steps (`1 - - . 5, - 3'`, `[1 3 5]`, `x` for a drum) written as degrees of the key, so a line cannot leave it; chords that a bass or a pad follows, written once and moving with them; and the order the patterns come in, with instruments left out of a part so a piece builds. It makes a `.wav` that runs into itself, what rings past its end added to its start, and with `stems` a file for each instrument that add up to the whole, for music that grows with the game. A loop that joins without a click can still be heard to join, where a full last bar runs into a thin first one: the reply says what the last bar and the first hold and warns when they differ. A piece with `loop: false` has an end: it rings out past its last bar, and `fadeIn` and `fadeOut` bring it up and down; a loop has no fade written into it, since the game fades one with `playBGM` and `stopBGM`. Whoever writes it cannot hear it, so `music_write`, `music_edit` and `music_read` answer with a picture of the notes, every one a bar in its instrument's colour, and with what can be said of them unheard: two lines crowding one octave, notes outside the key, how loud each instrument is beside the whole. Instruments of layers are made sounds, which suit electronic, retro and ambient music. A piano or strings that pass for real ones are recordings: an instrument may instead have `samples`, a recording in the project for each of a few notes, and every note of the piece is played from the recording nearest it, faster to be higher and slower to be lower; what dies of itself ends with its recording, and what is held goes round the steady middle of it with `loop`. Each recording is listened to: one whose pitch is not the note it is called, or a whole library an octave out because it counts its octaves from another C, is a warning that names the note to set, since nothing in the notes would show an instrument out of tune. The engine ships no recordings of its own: they are the project's.- **An AI can make a sound effect.** The engine played recordings and nothing here made one: a game built by an agent had pictures and models of its own and no sounds. A sound is now layers, as a picture is: `sound_write` takes a source of tones (sine, triangle, saw, square), noise (white, pink, brown) and `modes`, the tones a struck thing rings with, each placed in time and shaped by a level, a decay, filters whose corner can move, a second tone bending it, drive, pan and repeats, with an echo and a room over the whole, and writes an `.essound` and the `.wav` a scene plays. Whoever writes one cannot hear it, so the reply is a picture: the wave on top and pitch against time under it, a thump a blot low on the left, a hiss a haze across the top, a falling tone a falling line, with the level and the share of the energy that is low, middle and high. `sound_edit` changes a number and makes it again; `loop` runs the end into the start for an engine or a wind. A gunshot, footsteps, breaking glass, a pickup, an explosion, an engine loop and a laser are 150 to 500 bytes of source each and are made in under a tenth of a second. The same source is the same file on every machine. The first sounds made this way were listened to and did not pass: one noise through one filter with one decay is heard at once as a machine. So a layer can now be what a real sound is made of: noise cut to a `band` and brought back to full level, several of which die at different rates behind an `impulse`; a `tail` that lets part of a decay linger; `scatter`, which strikes a layer hundreds of times at random in time, pitch, loudness and side, for glass, gravel and rain; `repeat` with `faster`, for a thing bouncing to rest; a `peak` filter for the note a body adds; and `reverb` as a place, `room` or `open`, made by laying the sound over what that place answers to a click, with distinct first echoes and a wash whose top dies before its bottom. The tool text gives the method and the numbers for a shot, glass, a step and an explosion; the step is a shoe on a floor, measured against a recording: a blow on something that rings briefly, heel then ball of the foot, a scrape, nothing under 110 Hz, and a room round it. A `group` is several layers struck together as one event, so four footsteps are one step with `repeat` (787 bytes of source where it was 24 layers), each striking with its own grit. `variants` makes up to eight files that are the same sound and not the same samples, their pitch, loudness, decay and timing off by `vary`, with a sound event beside them that plays one after another without repeating: a game that plays one file for every shot is heard as a machine however good the file. And `reference` names a recording to be like, which is drawn above the made sound in every reply, the same way and to one scale of time, and measured the same way; `sound_read` reads a recording on its own.- **An AI can draw a surface: a picture that repeats, with what the light does on it.** `image_write` drew one picture, and a picture laid beside itself shows its edges; nor is a wall only its colour. `tile: true` on an image source makes it repeat: a shape, a line or a brush stroke that leaves one edge comes in at the opposite one, a shadow and a blur go round with it, and a noise fill meets itself. `material: { relief, height, roughness, metal }` makes it a surface: each of height, roughness and metal is layers drawn as a grey picture of their own (light is high, rough, metal), or the colour's own lightness stands in for the relief, and a normal map, a map of roughness and metal and an `.esmaterial` are written beside the picture. The reply shows the picture laid beside itself two by two, where a join would run through the middle, and the same under a low light, and gives the fields to put on a mesh. A brick wall, a plank floor and a riveted plate, 256 pixels each, drew in under a third of a second apiece and tiled three across in the engine with no join. A `filter` still stops at the edges, and a noise turned or stretched by `transform` does not come round.- **A model is written once for all its like parts, and a leaf can be a picture.** A model's source was a flat list of steps with plain numbers: a plant of ten fronds wrote out a frond ten times, and every leaf was a thin solid in one colour. Three things change that. `params` names numbers and points, and a value written `"=length * 0.4"` is a sum over them, with points that add and scale, angles in degrees, and makers for what shapes keep asking for: `polar` for a point round the upright axis, `arc` for a line that bends from one lean to another, `part` for a share of a line. `{ op: "repeat", over: [rows], steps: [...] }` runs its steps once for each row, the row's fields being names inside it, and `let` names a value for the steps after it; what is saved and edited is the source as written, so one edit to a name changes every part. The `strip` step carries a band with no thickness along a path, shaped by `widths`, folded by `cup`, with a picture laid along it from root to tip. `material.texture` names that picture, and with `alpha: "cutout"` its alpha is the outline: a leaf with veins and a torn edge, drawn once. `loft` takes an `up` for the way its section stands. The palm that was 386 steps is six steps written in two models of 2.9 and 2.4 KB, and 9,150 triangles where it was 26,814. Drawn in the engine it cost a little more GPU than the solid one all the same (about 1.1 ms against 0.8 for the frame at 1024 by 1024 on an RTX 3060): cut-out leaves draw both sides and test every pixel.diff --git a/desktop b/desktopindex fd5c7d7dd..4bdedda2d 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit fd5c7d7dd7ce297e9caede9e76768d552f58cf64+Subproject commit 4bdedda2d622286c20ce44ce687b5a567d100818diff --git a/pipeline/src/music/musicPicture.ts b/pipeline/src/music/musicPicture.tsindex c06d3b190..baf0fbbab 100644--- a/pipeline/src/music/musicPicture.ts+++ b/pipeline/src/music/musicPicture.ts@@ -50,7 +50,8 @@ export function musicPicture(music: RenderedMusic): MusicPicture {for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) put(x, y, y < waveH ? 22 : 10, y < waveH ? 24 : 10, y < waveH ? 30 : 16);// Loudness: each column from the quietest to the loudest sample it covers.- const frames = music.channels[0]!.length;+ // The bars only: what a piece that ends rings on by is past the right edge.+ const frames = Math.min(music.channels[0]!.length, Math.round(music.seconds * music.rate));for (let x = 0; x < width; x++) {const [from, to] = [Math.floor((x / width) * frames), Math.floor(((x + 1) / width) * frames)];let top = 0;diff --git a/pipeline/src/music/musicRender.ts b/pipeline/src/music/musicRender.tsindex e2b1f3421..312467c36 100644--- a/pipeline/src/music/musicRender.ts+++ b/pipeline/src/music/musicRender.ts@@ -47,6 +47,10 @@ export interface RenderedMusic extends CompiledMusic {channels: Float32Array[];peak: number;rms: number;+ /** For a piece that ends: seconds it rings on after its last bar, which the file is longer by. */+ tailSeconds: number;+ /** For a loop: what sounds in its last bar and in its first, and how loud each is, in decibels beside the whole. Null for a piece that ends. */+ join: { ends: string[]; begins: string[]; endDb: number; startDb: number } | null;/** Each instrument alone, when the source asks for stems: they add up to `channels`. */stems: Record<string, Float32Array[]> | null;/** What each instrument played, and how loud it is beside the whole, in decibels. */@@ -355,17 +359,30 @@ export function renderMusic(source: MusicSource, given: Readonly<Record<string,}const loop = source.loop !== false;+ // A piece that ends rings out: the file runs on past its last bar until what is left cannot be heard. One that fades+ // out is at nothing by the end of the bar, and has nothing to ring.+ let total = count;+ if (!loop && !source.fadeOut) {+ let last = count;+ for (const channel of [...room, ...names.flatMap((name) => buses.get(name)!)]) for (let n = work - 1; n > last; n--) if (Math.abs(channel[n]!) > 2e-4) { last = n; break; }+ total = Math.min(work, last + (last > count ? Math.round(0.05 * rate) : 0));+ }const finish = (channel: Float32Array): Float32Array => {- const out = channel.slice(0, count);+ const out = channel.slice(0, total);if (loop) for (let n = count; n < work; n++) out[(n - count) % count]! += channel[n]!;- else { const fade = Math.min(count, Math.round(0.02 * rate)); for (let n = 0; n < fade; n++) out[count - 1 - n]! *= n / fade; }+ else {+ if (source.fadeIn) { const rise = Math.round(source.fadeIn * rate); for (let n = 0; n < rise && n < total; n++) out[n]! *= (n / rise) ** 2; }+ // Let down over the seconds asked, or over the last fiftieth of one so that it does not stop on a step.+ const fall = Math.min(total, Math.round((source.fadeOut ?? 0.02) * rate));+ for (let n = 0; n < fall; n++) out[total - 1 - n]! *= source.fadeOut ? (n / fall) ** 2 : n / fall;+ }return out;};const stems: Record<string, Float32Array[]> = {};for (const name of names) stems[name] = buses.get(name)!.map(finish);const channels = [0, 1].map((c) => {const sum = finish(room[c]!);- for (const name of names) { const stem = stems[name]![c]!; for (let n = 0; n < count; n++) sum[n]! += stem[n]!; }+ for (const name of names) { const stem = stems[name]![c]!; for (let n = 0; n < total; n++) sum[n]! += stem[n]!; }return sum;});@@ -398,10 +415,31 @@ export function renderMusic(source: MusicSource, given: Readonly<Record<string,const target = source.gain ?? 0.9;const scale = peak > 1e-6 ? target / peak : 1;if (peak <= 1e-6) notes.push('the piece is silent: nothing in it reaches a level that can be heard');- for (const list of [channels, ...Object.values(stems)]) for (const channel of list) for (let n = 0; n < count; n++) channel[n]! *= scale;- const rmsOf = (list: Float32Array[]): number => { let s = 0; for (const channel of list) for (const v of channel) s += v * v; return Math.sqrt(s / (count * list.length)); };+ for (const list of [channels, ...Object.values(stems)]) for (const channel of list) for (let n = 0; n < total; n++) channel[n]! *= scale;+ const rmsOf = (list: Float32Array[], from = 0, to = count): number => { let s = 0; for (const channel of list) for (let n = from; n < to; n++) s += channel[n]! * channel[n]!; return Math.sqrt(s / (Math.max(1, to - from) * list.length)); };const rms = rmsOf(channels);+ // Where a loop meets itself. The samples join without a step whatever is written; what the ear hears as a join is+ // the music changing at once, a full last bar running into a first bar with two instruments in it.+ let join: RenderedMusic['join'] = null;+ if (loop) {+ const bar = Math.min(count, Math.round(compiled.barSeconds * rate));+ const sounding = (from: number, to: number): string[] => {+ // In the bar for more than a twentieth of it: a note let go on the bar line, a few thousandths late, is not in the next bar.+ const least = compiled.barSeconds * 0.05;+ return names.filter((name) => compiled.events.some((e) => e.instrument === name && Math.min(to, e.at + e.seconds) - Math.max(from, e.at) > least));+ };+ const db = (level: number): number => (level > 0 && rms > 0 ? Math.round(20 * Math.log10(level / rms) * 10) / 10 : -120);+ join = {+ ends: sounding(compiled.seconds - compiled.barSeconds, compiled.seconds), begins: sounding(0, compiled.barSeconds),+ endDb: db(rmsOf(channels, count - bar, count)), startDb: db(rmsOf(channels, 0, bar)),+ };+ const [gone, come] = [join.ends.filter((n) => !join!.begins.includes(n)), join.begins.filter((n) => !join!.ends.includes(n))];+ if (count > bar * 2 && (Math.abs(join.endDb - join.startDb) > 6 || gone.length + come.length > Math.max(1, names.length / 3))) {+ notes.push(`where the loop meets itself the music changes at once: its last bar has ${join.ends.join(', ') || 'nothing'} at ${join.endDb} dB and its first has ${join.begins.join(', ') || 'nothing'} at ${join.startDb} dB${gone.length ? `, so ${gone.join(', ')} stop${gone.length === 1 ? 's' : ''} dead` : ''}. A loop is heard as one piece when its end is as full as its start: end on a part like the first (thin the last part with \`without\`, or begin as full as it ends), and put a build that happens once in a piece of its own with loop false`);+ }+ }+const instruments: RenderedMusic['instruments'] = {};for (const name of names) {const mine = compiled.events.filter((e) => e.instrument === name);@@ -413,5 +451,5 @@ export function renderMusic(source: MusicSource, given: Readonly<Record<string,levelDb: level > 0 && rms > 0 ? Math.round(20 * Math.log10(level / rms) * 10) / 10 : -120,};}- return { ...compiled, notes, rate, channels, peak: peak > 1e-6 ? target : 0, rms, stems: source.stems ? stems : null, instruments };+ return { ...compiled, notes, rate, channels, peak: peak > 1e-6 ? target : 0, rms, tailSeconds: (total - count) / rate, join, stems: source.stems ? stems : null, instruments };}diff --git a/pipeline/src/music/musicSource.ts b/pipeline/src/music/musicSource.tsindex ab7086668..ab1d218c5 100644--- a/pipeline/src/music/musicSource.ts+++ b/pipeline/src/music/musicSource.ts@@ -103,8 +103,15 @@ export interface MusicSource {patterns: Readonly<Record<string, MusicPattern>>;/** The patterns in the order they come, each whole, or with some instruments left out or only some kept. */song: readonly SongPart[];- /** What rings past the end comes in at the start, so the piece runs into itself. Default true. */+ /**+ * What rings past the end comes in at the start, so the piece runs into itself. Default true. False is a piece+ * with an end: its last notes and the room ring out after the last bar, and the file is that much longer.+ */loop?: boolean;+ /** Seconds over which it comes up from nothing at its start. A loop comes round to its start again and again, so only a piece that ends has one; a game fades a loop in as it starts it. */+ fadeIn?: number;+ /** Seconds before the end of the last bar over which it goes down to nothing, for a piece that ends and has no ending written. */+ fadeOut?: number;/** Also a file for each instrument, which add up to the whole: a game brings them in and out. */stems?: boolean;/** The room it is all in: `size` 0..1, `mix` 0..1. */@@ -182,7 +189,7 @@ export function parseTrack(text: string, bars: number, stepsToBar: number, wherereturn out;}-const SOURCE_FIELDS = ['version', 'tempo', 'beats', 'key', 'scale', 'swing', 'humanize', 'seed', 'instruments', 'patterns', 'song', 'loop', 'stems', 'reverb', 'gain', 'rate'];+const SOURCE_FIELDS = ['version', 'tempo', 'beats', 'key', 'scale', 'swing', 'humanize', 'seed', 'instruments', 'patterns', 'song', 'loop', 'fadeIn', 'fadeOut', 'stems', 'reverb', 'gain', 'rate'];const INSTRUMENT_FIELDS = ['layers', 'samples', 'attack', 'gain', 'pan', 'octave', 'follow', 'release', 'reverb'];const RECORDING = /\.(wav|ogg|mp3|flac|m4a|aac|webm)$/i;@@ -297,6 +304,11 @@ export function validateMusicSource(raw: unknown): MusicSource {});const source = s as unknown as MusicSource;const seconds = musicSeconds(source);+ for (const key of ['fadeIn', 'fadeOut'] as const) {+ if (s[key] === undefined) continue;+ if (s.loop !== false) throw new Error(`${key} is for a piece that ends (loop: false). A loop comes round to its start with no gap, and a fade written into it would be heard every time round: the game fades it, playBGM(url, { fadeIn }) to start it and stopBGM(seconds) to end it`);+ if (!(isNum(s[key]) && (s[key] as number) > 0 && (s[key] as number) <= seconds)) throw new Error(`${key} must be seconds, above 0 and no longer than the piece (${Math.round(seconds * 10) / 10} s)`);+ }if (seconds > MAX_MUSIC_SECONDS) throw new Error(`the song lasts ${Math.round(seconds)} s; at most ${MAX_MUSIC_SECONDS}`);return source;}diff --git a/pipeline/tests/music.test.ts b/pipeline/tests/music.test.tsindex 88b2eb6db..a631f7998 100644--- a/pipeline/tests/music.test.ts+++ b/pipeline/tests/music.test.ts@@ -92,7 +92,9 @@ describe('music from instruments and patterns', () => {const instruments = { tone: { layers: [{ source: 'sine', freq: 440, length: 0.8, decay: 0.3 }] }, click, low: tone };const open = renderMusic(piece({ tone: last }, { loop: false, instruments }));const round = renderMusic(piece({ tone: last }, { loop: true, instruments }));- expect(round.channels[0]!.length).toBe(open.channels[0]!.length);+ // The one that ends rings on past its last bar; the loop is its bars and no more.+ expect(round.channels[0]!.length).toBe(2 * round.rate);+ expect(open.channels[0]!.length).toBeGreaterThan(round.channels[0]!.length);expect(level(open.channels[0]!, open.rate, 0.05, 0.4)).toBeLessThan(1e-4);expect(level(round.channels[0]!, round.rate, 0.05, 0.4)).toBeGreaterThan(0.05);expect(pitchOf(round.channels[0]!, round.rate, 0.05, 0.4)).toBeCloseTo(440, -1);@@ -328,3 +330,61 @@ describe('an instrument made of recordings', () => {expect(bad({ layers: [{ source: 'noise' }], attack: 0.1 })).toThrow(/attack is for samples/);});});++describe('how a piece begins, ends and meets itself', () => {+ const long = { layers: [{ source: 'sine', freq: 440, length: 0.8, decay: 0.3 }] };+ const last = `${REST.slice(0, -1)}1`;+ const FULL = '1 - - - 1 - - - 1 - - - 1 - - -';++ it('rings out past its last bar when it ends, and the file is that much longer', () => {+ const m = renderMusic(piece({ tone: last }, { instruments: { tone: long, click, low: tone } }));+ // The note starts an eighth of a second before the end and lasts 0.8.+ expect(m.seconds).toBe(2);+ expect(m.tailSeconds).toBeGreaterThan(0.5);+ expect(m.tailSeconds).toBeLessThan(0.8);+ expect(m.channels[0]!.length).toBe(Math.round((2 + m.tailSeconds) * m.rate));+ expect(level(m.channels[0]!, m.rate, 2.05, 2.3)).toBeGreaterThan(0.01);+ // And it ends on nothing.+ expect(Math.abs(m.channels[0]!.at(-1)!)).toBeLessThan(1e-3);+ // A piece with nothing left over is as long as its bars.+ expect(renderMusic(piece({ click: steps('x') })).tailSeconds).toBe(0);+ expect(renderMusic(piece({ tone: last }, { loop: true, instruments: { tone: long, click, low: tone } })).tailSeconds).toBe(0);+ });++ it('comes up from nothing and goes down to nothing over the seconds asked', () => {+ const m = renderMusic(piece({ tone: '1 - - - - - - - - - - - - - - -' }, { fadeIn: 0.5, fadeOut: 0.5 }));+ const c = m.channels[0]!;+ const middle = level(c, m.rate, 0.9, 1.1);+ expect(level(c, m.rate, 0, 0.1)).toBeLessThan(middle * 0.05);+ expect(level(c, m.rate, 0.2, 0.3)).toBeLessThan(middle * 0.5);+ expect(level(c, m.rate, 0.6, 0.8)).toBeCloseTo(middle, 2);+ expect(level(c, m.rate, 1.7, 1.8)).toBeLessThan(middle * 0.5);+ expect(level(c, m.rate, 1.9, 2)).toBeLessThan(middle * 0.05);+ // Faded to nothing by the end of the bar, it has nothing to ring.+ expect(m.tailSeconds).toBe(0);+ expect(c.length).toBe(2 * m.rate);+ });++ it('will not write a fade into a loop, and says who fades one', () => {+ expect(() => piece({ tone: FULL }, { loop: true, fadeIn: 1 })).toThrow(/fadeIn is for a piece that ends \(loop: false\).*playBGM\(url, \{ fadeIn \}\).*stopBGM\(seconds\)/);+ expect(() => validateMusicSource({ tempo: 120, key: 'A', instruments: { tone }, patterns: { a: { bars: 1, tracks: { tone: FULL } } }, song: ['a'], fadeOut: 1 })).toThrow(/fadeOut is for a piece that ends/);+ expect(() => piece({ tone: FULL }, { fadeOut: 3 })).toThrow(/fadeOut must be seconds, above 0 and no longer than the piece \(2 s\)/);+ });++ it('says where a loop meets itself, and when the music changes at once there', () => {+ const instruments = { tone, click, low: tone, pad: tone, bass: tone };+ const thin = { pattern: 'a', only: ['tone'] };+ const tracks = { tone: FULL, pad: FULL.replace(/1/g, '3'), bass: FULL.replace(/1/g, "5,"), click: steps('x', '.', 'x', '.', 'x') };+ const of = (song: unknown[]) => renderMusic(piece(tracks, { loop: true, instruments, song }));+ // Thin first and full last: the join is a drop.+ const drop = of([thin, 'a', 'a']);+ expect(drop.join).toMatchObject({ begins: ['tone'], ends: ['tone', 'click', 'pad', 'bass'] });+ expect(drop.join!.endDb).toBeGreaterThan(drop.join!.startDb + 3);+ expect(drop.notes.join()).toMatch(/where the loop meets itself the music changes at once: its last bar has tone, click, pad, bass at .* and its first has tone at .*, so click, pad, bass stop dead/);+ // As full at its end as at its start, or thin at both: nothing to say.+ expect(of(['a', 'a', 'a']).notes.join()).not.toMatch(/meets itself/);+ expect(of([thin, 'a', thin]).notes.join()).not.toMatch(/meets itself/);+ // A piece that ends has no join.+ expect(renderMusic(piece(tracks, { instruments, song: [thin, 'a'] })).join).toBeNull();+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 2dc23e5f9..70f4e76b2 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -4618,6 +4618,10 @@ export const NOTED = {{"note": "An AI can make background music."},"docs(music): the tool text says the reply listens to each recording and that recordings differ in level":{"note": "An AI can make background music."},+ "feat(music): a piece that ends rings out and can fade, and a loop says where it meets itself - loop false keeps what rings past the last bar, fadeIn and fadeOut are its to set, and a loop whose last bar is unlike its first is a warning that names what stops dead":+ {"note": "An AI can make background music."},+ "feat(music): the reply gives the join of a loop or how long an ending rings, and the tool text says how a loop is written and who fades one":+ {"note": "An AI can make background music."},"feat(sky): a sky of your own shades the ground under its clouds - defineSkyEffect takes groundShadow and a second function, skyShadow(world, sun), what is left of the light at a world position, and the sky pass multiplies every surface it finds by it, as Sky Atmosphere does with its own clouds":{"note": "A sky of your own shades the ground under its clouds."},"fix(terrain): a colour map and an occlusion map lie the way the heightmap does - Terrain.colorMap, Terrain.occlusionMap and Foliage.colorMap were sampled with their rows turned over, so a picture painted to match a heightmap, a splatmap or a density map came out mirrored north to south under them; an image over an area now has its first row along the least z whoever reads it":