feuerwerk/tests/core/buses.test.ts

/**
 * Master and buses (#325): which bus a bus goes into, what the sound library is set up with, and
 * which bus a sound, a note, a pattern or a song is heard on.
 */
import { describe, expect, it } from 'vitest';
import {
  buildAsset,
  CreateAssetCommand,
  CreateSoundCommand,
  SetAssetPropertyCommand,
} from '../../src/core/commands/assetCommands';
import { SetMasterFxCommand, SetMasterVolumeCommand } from '../../src/core/commands/projectCommands';
import type { BehaviorAsset, SoundFxAsset } from '../../src/core/model/Asset';
import { isPlaceableType } from '../../src/core/model/AssetTypes';
import {
  MASTER_MIX,
  type MixBus,
  mixBusName,
  mixOf,
  playedBus,
  reachedBus,
  sameMix,
} from '../../src/core/music/mixer';
import { BUS_INTO_KEY, BUS_KEY, busesInto, busInto, MASTER_BUS } from '../../src/core/properties/buses';
import { schemaForAsset } from '../../src/core/properties/PropertySchema';
import type { FxParams, FxVoice } from '../../src/core/soundfx/nodes';
import { GameRun } from '../../src/runtime/GameRun';
import { SILENT_AUDIO } from '../../src/runtime/systems/Audio';
import { Input } from '../../src/runtime/systems/Input';
import {
  graphEditor,
  makeBehavior,
  makeProject,
  makeSpriteScene,
  place,
  roundTrip,
  startWorld,
} from '../helpers';

const FILE = `${'a1'.repeat(32)}.wav`;

function withBuses(...names: string[]) {
  const f = makeProject();
  const ids = names.map((name) => {
    const command = new CreateAssetCommand('bus', name);
    f.stack.execute(command);
    return command.asset.id;
  });
  const into = (bus: string, target: string) =>
    f.stack.execute(new SetAssetPropertyCommand(bus, BUS_INTO_KEY, target));
  return { ...f, ids, into };
}

/** A sound FX that compiles: Input, a Gain, Output. */
function workingFx(f: ReturnType<typeof makeProject>): string {
  const command = new CreateAssetCommand('soundfx', 'Squash');
  f.stack.execute(command);
  const edit = graphEditor(f, command.asset as SoundFxAsset as unknown as BehaviorAsset);
  const input = edit.addNode('SoundFxInput');
  const gain = edit.addNode('SoundFxGain', { gain: -6 });
  const output = edit.addNode('SoundFxOutput');
  edit.connect(input, 'out', gain, 'in');
  edit.connect(gain, 'out', output, 'in');
  return command.asset.id;
}

describe('the bus asset (#325)', () => {
  it('is not placeable and starts at full volume, without a sound FX, into the master', () => {
    expect(isPlaceableType('bus')).toBe(false);
    const f = withBuses('Music');
    const bus = f.project.assets[0]!;
    expect(buildAsset('bus', 'SFX')).toMatchObject({ type: 'bus', props: { volume: 1, fx: '', into: '' } });
    expect(schemaForAsset(f.project, bus).map((def) => def.key)).toEqual(['volume', 'fx', 'into']);
    expect(roundTrip(f.project)).toEqual(f.project);
  });

  it('names the master as the empty pick of Into and of the Bus of a sound, an instrument, a pattern and a song', () => {
    const f = withBuses('Music');
    const into = schemaForAsset(f.project, f.project.assets[0]!).find((def) => def.key === BUS_INTO_KEY);
    expect(into).toMatchObject({ kind: 'asset', assetTypes: ['bus'], none: 'Master' });
    for (const type of ['sound', 'instrument', 'pattern', 'song'] as const) {
      const command = new CreateAssetCommand(type, type);
      f.stack.execute(command);
      expect(schemaForAsset(f.project, command.asset).find((def) => def.key === BUS_KEY)).toMatchObject({
        none: 'Master',
        assetTypes: ['bus'],
      });
    }
  });

  it('offers as Into neither itself nor a bus that already goes into it', () => {
    const f = withBuses('Master music', 'Music', 'Drums', 'SFX');
    const [top, music, drums, sfx] = f.ids as [string, string, string, string];
    f.into(music, top);
    f.into(drums, music);
    const rows = schemaForAsset(
      f.project,
      f.project.assets.find((a) => a.id === top)!,
    );
    expect(rows.find((d) => d.key === BUS_INTO_KEY)).toMatchObject({ intoFor: top });
    expect(busesInto(f.project, top)).toEqual([top, music, drums]);
    expect(busesInto(f.project, drums)).toEqual([drums]);
    expect(busesInto(f.project, sfx)).toEqual([sfx]);
  });

  it('sends a bus that would come round to itself into the master, whatever the file says', () => {
    const f = withBuses('A', 'B', 'C');
    const [a, b, c] = f.ids as [string, string, string];
    f.into(a, b);
    f.into(b, c);
    f.into(c, b);
    // B and C go round each other: both go into the master. A goes into B, which is no loop.
    expect([busInto(f.project, a), busInto(f.project, b), busInto(f.project, c)]).toEqual([b, '', '']);
    f.into(a, a);
    expect(busInto(f.project, a)).toBe('');
    f.into(a, 'gone');
    expect(busInto(f.project, a)).toBe('');
  });
});

describe('the master (#325)', () => {
  it('is a project setting at full volume without a sound FX, kept through a round trip', () => {
    const f = makeProject();
    expect([f.project.masterVolume, f.project.masterFx]).toEqual([1, '']);
    f.stack.execute(new SetMasterVolumeCommand(2));
    f.stack.execute(new SetMasterFxCommand('fx-1'));
    expect([f.project.masterVolume, f.project.masterFx]).toEqual([1, 'fx-1']);
    f.stack.execute(new SetMasterVolumeCommand(0.4));
    expect(roundTrip(f.project)).toMatchObject({ masterVolume: 0.4, masterFx: 'fx-1' });
    f.stack.undo();
    f.stack.undo();
    expect([f.project.masterVolume, f.project.masterFx]).toEqual([1, '']);
  });

  it('reads as full volume without a sound FX from a project written before there was one', () => {
    const f = makeProject();
    const written = roundTrip(f.project) as unknown as Record<string, unknown>;
    delete written.masterVolume;
    delete written.masterFx;
    expect(roundTrip(written as never)).toMatchObject({ masterVolume: 1, masterFx: '' });
  });
});

describe('the mix (#325)', () => {
  it('is the master first, then every bus into the one it names, with its volume and its sound FX', () => {
    const f = withBuses('Music', 'Drums');
    const [music, drums] = f.ids as [string, string];
    const fx = workingFx(f);
    f.into(drums, music);
    f.stack.execute(new SetAssetPropertyCommand(drums, 'volume', 0.5));
    f.stack.execute(new SetAssetPropertyCommand(music, 'fx', fx));
    f.stack.execute(new SetMasterVolumeCommand(0.8));
    const mix = mixOf(f.project);
    expect(mix.map(({ name, volume, into }) => ({ name, volume, into }))).toEqual([
      { name: MASTER_MIX, volume: 0.8, into: null },
      { name: `mix:${music}`, volume: 1, into: MASTER_MIX },
      { name: `mix:${drums}`, volume: 0.5, into: `mix:${music}` },
    ]);
    expect(mix.map((bus) => bus.fx !== null)).toEqual([false, true, false]);
  });

  it('is the same mix again while nothing of it changed, another once a volume does', () => {
    const f = withBuses('Music');
    const before = mixOf(f.project);
    expect(sameMix(before, mixOf(f.project))).toBe(true);
    f.stack.execute(new SetAssetPropertyCommand(f.ids[0]!, 'volume', 0.2));
    expect(sameMix(before, mixOf(f.project))).toBe(false);
  });

  it('plays on the bus a node picks, else the one its asset names, else the master', () => {
    const f = withBuses('Music', 'SFX');
    const [music, sfx] = f.ids as [string, string];
    expect(playedBus(f.project, '', { bus: music })).toBe(`mix:${music}`);
    expect(playedBus(f.project, sfx, { bus: music })).toBe(`mix:${sfx}`);
    expect(playedBus(f.project, MASTER_BUS, { bus: music })).toBe(MASTER_MIX);
    expect(playedBus(f.project, '', {})).toBe(MASTER_MIX);
    // A bus that was deleted leaves it on the master.
    expect(playedBus(f.project, '', { bus: 'gone' })).toBe(MASTER_MIX);
  });

  it('reaches the master for an empty pick, and no bus for one that is not there', () => {
    const f = withBuses('Music');
    expect(reachedBus(f.project, '')).toBe(MASTER_MIX);
    expect(reachedBus(f.project, MASTER_BUS)).toBe(MASTER_MIX);
    expect(reachedBus(f.project, f.ids[0]!)).toBe(mixBusName(f.ids[0]!));
    expect(reachedBus(f.project, 'gone')).toBeNull();
  });
});

/** What a run asked of the buses, beside the voices it played and on which bus. */
function busSink() {
  const sink = {
    ...SILENT_AUDIO,
    calls: [] as string[],
    play: (file: string, _volume: number, _loop: boolean, _owner: string, _fx?: FxVoice, bus = '') => {
      sink.calls.push(`play ${file} on ${bus}`);
      return 1;
    },
    setMix: (buses: readonly MixBus[]) =>
      void sink.calls.push(`mix ${buses.map((bus) => bus.name).join(' ')}`),
    resetMix: () => void sink.calls.push('reset'),
    setMixVolume: (bus: string, volume: number, time = 0) =>
      void sink.calls.push(`volume ${bus} ${volume} ${time}`),
    mixVolume: (bus: string) => (bus === MASTER_MIX ? 0.7 : 0.2),
    tuneMix: (bus: string, params: FxParams) => void sink.calls.push(`tune ${bus} ${JSON.stringify(params)}`),
  };
  return sink;
}

/** A scene whose behavior runs `type` on its first frame, its result in a variable "Got". */
function runOnStart(type: string, params: Record<string, string | number | boolean>, f = makeSpriteScene()) {
  const behavior = makeBehavior(f, 'Logic', ['Got']);
  place(f, behavior.id, { x: 0, y: 0 });
  const edit = graphEditor(f, behavior);
  const start = edit.addNode('OnStart');
  const node = edit.addNode(type, params);
  edit.connect(start, 'exec', node, 'exec');
  return { ...f, behavior, edit, node };
}

describe('buses in a running game (#325)', () => {
  it('plays a sound on the bus its asset names, or on the one Play sound picks', () => {
    const f = makeSpriteScene();
    const bus = new CreateAssetCommand('bus', 'SFX');
    const sound = new CreateSoundCommand('Jump', FILE);
    f.stack.execute(bus);
    f.stack.execute(sound);
    f.stack.execute(new SetAssetPropertyCommand(sound.asset.id, BUS_KEY, bus.asset.id));
    runOnStart('PlaySound', { sound: sound.asset.id, volume: 1 }, f);
    const asset = busSink();
    startWorld(f, { behaviors: true, audio: asset }).frame();
    expect(asset.calls).toEqual([`play ${FILE} on mix:${bus.asset.id}`]);

    const picked = makeSpriteScene();
    const pickedSound = new CreateSoundCommand('Jump', FILE);
    picked.stack.execute(pickedSound);
    runOnStart('PlaySound', { sound: pickedSound.asset.id, volume: 1, bus: MASTER_BUS }, picked);
    const master = busSink();
    startWorld(picked, { behaviors: true, audio: master }).frame();
    expect(master.calls).toEqual([`play ${FILE} on ${MASTER_MIX}`]);
  });

  it('sets the volume of the master for an empty pick, and of the bus picked, over its time', () => {
    const f = runOnStart('SetBusVolume', { bus: '', volume: 0.25, time: 2 });
    const sink = busSink();
    startWorld(f, { behaviors: true, audio: sink }).frame();
    expect(sink.calls).toEqual([`volume ${MASTER_MIX} 0.25 2`]);

    const gone = runOnStart('SetBusVolume', { bus: 'gone', volume: 0.25 });
    const none = busSink();
    startWorld(gone, { behaviors: true, audio: none }).frame();
    expect(none.calls).toEqual([]);
  });

  it('changes the sound FX of a bus with Set sound FX parameters and no voice', () => {
    const f = runOnStart('SetSoundFxParameters', { voice: 0, bus: MASTER_BUS });
    const sink = busSink();
    startWorld(f, { behaviors: true, audio: sink }).frame();
    expect(sink.calls).toEqual([`tune ${MASTER_MIX} {}`]);
  });

  it('reads the volume a bus is at, the master for an empty pick and 0 for a bus that is not there', () => {
    const f = runOnStart('Log', {});
    const read = f.edit.addNode('BusVolume', { bus: '' });
    f.edit.connect(read, 'volume', f.node, 'message');
    const gone = f.edit.addNode('BusVolume', { bus: 'gone' });
    const second = f.edit.addNode('Log');
    f.edit.connect(f.node, 'exec', second, 'exec');
    f.edit.connect(gone, 'volume', second, 'message');
    const started = startWorld(f, { behaviors: true, audio: busSink() });
    started.frame();
    expect(started.world.log).toEqual(['0.7', '0']);
  });

  it('starts every run with the buses as their assets have them, and ends it so', () => {
    const f = makeSpriteScene();
    f.stack.execute(new CreateAssetCommand('bus', 'Music'));
    const sink = busSink();
    const run = GameRun.start(f.project, f.sceneId, new Input(), {
      audio: sink,
      physics: undefined as never,
      clock: { scale: 1 },
      saves: { read: () => ({}), write: () => {} },
    });
    expect(sink.calls).toEqual(['reset', `mix ${MASTER_MIX} mix:${f.project.assets.at(-1)!.id}`]);
    run.end();
    expect(sink.calls.at(-1)).toBe('reset');
  });
});