[han4wluc]

Why

A story stopped with this error when a line's BGM action named a transition audio effect and the same track was already playing:

[story.scenes["…"].sections["…"].lines["…"].actions.bgm.audioEffects] [resources.audioEffects.<id>] Audio effect resource "<id>" has type "transition", but the BGM action only updates a retained sound. Use an update resource.

This happens on the next line of the same section. It also happens after a section transition or a reset story at section into a line that plays the same track.

resolveAudioEffect threw whenever a transition met a sound that kept its source but changed its mix. The mix almost always changes there, because the transition's final next values are written into the line's persistent BGM mix. Whether a line keeps a sound depends on how the player reached it, so the same line can start the music on one path and keep it on another. An author or an editor cannot know this in general, so the data could not be changed to avoid the error.

What changed

• Kept sounds play no transition. In resolveAudioEffect, a transition on a sound that keeps its source returns no effect instead of throwing. The sound keeps playing and takes the line's mix at once, as it does for a BGM action without audioEffects.
• The persistent mix is unchanged. The transition's final next values still set the line's BGM mix on every path, so the line ends with the same mix whether it started the music or kept it.
• Invalid data still throws. When every sound keeps playing, resolveAudioEffects still resolves one kept sound, paired by id. An unknown resource, an unsupported effect type, or a bad playback speed still throws on that path. The old search for a changed kept sound only chose which sound to reject, so it is removed, together with the two helpers it used.
• Docs. The Audio Channels section of docs/RouteEngine.md and the description in audioEffectResource.yaml now state the rule.
• Sound beginEffect and endEffect already require an update resource on every path and are unchanged. Voice and SFX actions have no top-level audio effects.

Testing

• spec/resolveAudioEffects.test.js:
  • A transition on a sound that keeps its source returns null from resolveAudioEffect and [] from resolveAudioEffects.
  • A transition on two BGM sounds that both keep their source, one with a changed mix, returns [].
  • An unknown resource, an unsupported type and a playback speed of 0 still throw on a kept sound.
  • The topology test no longer expects a transition on a kept sound to throw.
• spec/RouteEngine.audioEffects.test.js, new describe block:
  • The next line of the same section keeps the music with a transition: no error, no audioEffects, the same bgm:main sound and source, and the volume at the transition's final value.
  • The same after sectionTransition and after resetStoryAtSection into a line that keeps the music.
  • The same destination line still plays the transition's incoming track when the music was stopped before the section transition.
  • The three invalid selections still throw when the line keeps the music.
  • The existing "recovers after a rejected line batch" test used the old error as its rejection. It now uses an unknown resource.
• vt/specs/audioChannels/audio-effects-transition-kept-music.yaml (assertions only, no screenshots): the next line, and then a section transition, keep the music with a transition. It checks the source, the new volume and that no audio effect is emitted. Run in the pinned VT container, it passes with this change and fails on main with expected 100, got 70, because the line is never entered.
• With the source files reverted, 5 of the 12 new tests fail. The other 7 cover the start path and invalid data, which behave the same before and after.
• bun run test (101 files, 2468 tests) and bun run lint pass.

Not tested: listening to the result through Route Graphics on an audio device, and a client app using this engine version. All audioChannels VT specs were run in the VT container. All pass except audio-effects-initial-entry.yaml, which fails the same way on main (expected 70, got 100). This change does not touch it.

Risks

• On a path that keeps the music, such a line now changes the mix at once. If the transition's final next volume differs from the track's current volume, the volume jumps to it. On a path that starts the music, the transition fades to the same value.
• A transition on a line that always keeps the music no longer raises an error. It is skipped without a warning.
• A transition resource with an invalid final keyframe is still reported only on paths where the music starts, stops or changes source. Before this change, it was also not reported on a kept sound whose mix did not change.