feat(audio): add guest voice controls and reliable lifecycle delivery
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

This commit is contained in:
2026-10-14 09:08:27 +01:00
parent 3899b7f12c
commit e0e01ed1de
23 changed files with 1442 additions and 482 deletions
@@ -61,6 +61,30 @@ impl Firmware {
/// This method is called exactly once per Host frame (60Hz).
/// It updates peripheral signals and delegates the logic to the current state.
pub fn tick(&mut self, signals: &InputSignals, platform: &mut dyn RuntimePlatform) {
self.sync_audio(platform);
self.tick_inner(signals, platform);
self.sync_audio(platform);
}
fn sync_audio(&mut self, platform: &mut dyn RuntimePlatform) {
let task = self.os.lifecycle().resident_game_task().map(|task| task.0);
let suspended = matches!(
self.os.lifecycle().resident_game().map(|game| game.state),
Some(ResidentGameState::PausedSuspended)
);
let paused = self.game_lifecycle_audio_paused() || self.os.vm().paused();
platform.audio_mut().set_session(task);
platform.audio_mut().set_paused(paused);
// Without a pause hook the OS can suspend synchronously, bypassing the
// callback runner. Complete the same audio boundary before resuming.
// A real hook already published its prefix; repeating an empty flush is inert.
if suspended && platform.audio().lifecycle_ready() {
platform.audio_mut().begin_lifecycle();
platform.audio_mut().finish_lifecycle(true);
}
}
fn tick_inner(&mut self, signals: &InputSignals, platform: &mut dyn RuntimePlatform) {
self.os.poll_background_io(platform);
if self.os.memcard().host_faulted() {
// Keep the resident VM, snapshots, and worker-owned buffers alive. A
@@ -1858,6 +1882,113 @@ mod tests {
(firmware, platform, task)
}
fn check_audio_lifecycle(partial: bool, hooks: bool) {
use prometeu_bytecode::registry::LifecycleRole;
use prometeu_drivers::AudioCommand;
let mut program = TestProgram::single(
assemble("PUSH_I32 0\nHOSTCALL 0\nPOP_N 1\nFRAME_SYNC\nJMP 0").unwrap(),
int64_signature(0, 0),
0,
8,
);
program.syscalls.push(SyscallDecl {
module: "audio".into(),
name: "stop".into(),
version: 1,
arg_slots: 1,
ret_slots: 1,
});
for (role, voice) in [(LifecycleRole::BeforePause, 1), (LifecycleRole::BeforeResume, 2)] {
if !hooks {
continue;
}
let code = assemble(&format!("PUSH_I32 {voice}\nHOSTCALL 0\nPOP_N 1\nRET")).unwrap();
program.functions.push(FunctionDecl {
lifecycle_role: role,
code_offset: program.code.len() as u32,
code_len: code.len() as u32,
max_stack_slots: 8,
..Default::default()
});
program.code.extend(code);
}
let mut cartridge = valid_cartridge(AppMode::Game);
cartridge.capabilities = caps::AUDIO;
cartridge.program = program.serialize();
let mut fw = Firmware::new(None);
let mut platform = TestPlatform::new();
let signals = InputSignals::default();
fw.load_cartridge(cartridge);
fw.tick(&signals, &mut platform);
if partial {
for _ in 0..2 {
assert!(fw.os.vm().debug_step_active_session(&mut platform).is_none());
}
} else {
fw.tick(&signals, &mut platform);
}
let task = fw.os.lifecycle().resident_game_task().unwrap();
let transport = platform.local_hardware().audio.transport();
assert_eq!(platform.audio().ready(), partial);
fw.os.lifecycle().suspend_task(task).unwrap();
fw.tick(&signals, &mut platform);
let delivery = transport.try_take().unwrap();
assert!(delivery.paused);
if partial {
assert!(delivery.frame.is_none());
} else {
assert!(matches!(delivery.frame.unwrap()[0], AudioCommand::Stop { voice_id: 0 }));
}
let lifecycle = delivery.lifecycle.unwrap_or_default();
assert_eq!(lifecycle.len(), usize::from(partial) + usize::from(hooks));
if partial {
assert!(matches!(lifecycle[0], AudioCommand::Stop { voice_id: 0 }));
}
if hooks {
assert!(matches!(lifecycle[usize::from(partial)], AudioCommand::Stop { voice_id: 1 }));
}
assert!(fw.resume_resident_game_from_home());
fw.tick(&signals, &mut platform);
let delivery = transport.try_take().unwrap();
assert!(!delivery.paused);
if hooks {
assert!(matches!(delivery.lifecycle.unwrap()[0], AudioCommand::Stop { voice_id: 2 }));
} else {
assert!(delivery.lifecycle.is_none());
assert!(delivery.frame.is_none(), "hookless resume completed the prefix-free frame");
}
let epoch = delivery.epoch;
fw.tick(&signals, &mut platform);
if partial && hooks {
assert!(
platform.audio().ready(),
"prefix must not be published again at frame completion"
);
fw.tick(&signals, &mut platform);
}
assert!(!platform.audio().ready());
fw.change_state(FirmwareState::Reset(ResetStep), &signals, &mut platform);
let delivery = transport.try_take().unwrap();
assert!(delivery.epoch > epoch);
assert!(delivery.frame.is_none() && delivery.lifecycle.is_none());
assert!(platform.audio().ready());
}
#[test]
fn audio_lifecycle_publishes_with_pending_frame_and_reset_invalidates_session() {
check_audio_lifecycle(false, true);
}
#[test]
fn audio_lifecycle_publishes_interrupted_frame_prefix_before_hook() {
check_audio_lifecycle(true, true);
}
#[test]
fn audio_lifecycle_flushes_prefix_when_optional_hooks_are_absent() {
check_audio_lifecycle(true, false);
}
#[test]
fn lifecycle_home_resume_callbacks_are_outside_frames_and_preserve_pc() {
let (mut fw, mut platform, task) = load_lifecycle("RET", "RET");
@@ -15,6 +15,8 @@ impl ResetStep {
let _ = ctx.os.lifecycle().terminate_resident_game();
ctx.os.sessions().clear_vm_sessions();
ctx.os.vm().reset_global_runtime_state();
ctx.platform.audio_mut().reset();
ctx.platform.audio_mut().set_session(None);
}
pub fn on_update(&mut self, ctx: &mut PrometeuContext) -> Option<FirmwareState> {
@@ -32,6 +32,7 @@ pub(crate) fn terminate_resident_game(
};
os.memcard().session.end_session();
platform.audio_mut().set_session(None);
os.vm().transition_render_owner(AppMode::Shell, 0);
platform.game2d_frame_composer().unbind_scene();
platform.assets_mut().shutdown();