111 lines
4.2 KiB
Markdown
111 lines
4.2 KiB
Markdown
---
|
|
id: PLN-0140
|
|
ticket: foreground-stack-game-pause-shell-vm-backed
|
|
title: Deliver Game Pause Resume and Suspension
|
|
status: open
|
|
created: 2026-07-03
|
|
ref_decisions: [DEC-0037]
|
|
tags: [runtime, os, vm, lifecycle, pause, suspension]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
`DEC-0037` separates Game-visible `Paused` from OS-owned `Suspended`. When Home
|
|
is requested during Game execution, SystemOS must notify the Game, give it a
|
|
short bounded budget, then suspend the VM even if the Game does not cooperate.
|
|
When returning, SystemOS must reactivate the VM and send a resume or
|
|
foreground-restore notification before the visual owner returns to Game.
|
|
|
|
This plan implements the pause/resume and suspension mechanics after the
|
|
foreground state model exists.
|
|
|
|
## Decisions of Origin
|
|
|
|
- `DEC-0037` - Foreground Stack and Game Pause Contract.
|
|
|
|
## Target
|
|
|
|
Add Game pause/resume lifecycle delivery and OS-enforced VM suspension for the
|
|
same resident Game.
|
|
|
|
## Scope
|
|
|
|
- Add a Game lifecycle event model for pause and resume/foreground-restore.
|
|
- Add a bounded pause reaction budget owned by SystemOS.
|
|
- Suspend the Game VM after the budget even if the Game does not cooperate.
|
|
- Ensure a suspended Game receives no normal gameplay ticks.
|
|
- Reactivate the VM and deliver resume/foreground-restore before Game visual
|
|
foreground restoration.
|
|
- Integrate with `GameRunningStep` and VM runtime tick control.
|
|
|
|
## Out of Scope
|
|
|
|
- No render first-valid-frame gating; that is in `PLN-0141`.
|
|
- No host keyboard routing; that is in `PLN-0136`.
|
|
- No new guest syscall.
|
|
- No background execution.
|
|
- No Game-to-Game switching.
|
|
|
|
## Execution Plan
|
|
|
|
1. Add lifecycle event representation.
|
|
Define pause/resume events in the most local runtime lifecycle module,
|
|
likely under `crates/console/prometeu-system/src/os/lifecycle.rs` or a new
|
|
SystemOS lifecycle submodule. Events must be observable by the VM/runtime
|
|
path without giving the Game authority over suspension.
|
|
|
|
2. Add pause transition state.
|
|
Extend the foreground state from `PLN-0137` with a `PauseRequested` or
|
|
equivalent transition state that records the target Game task and the
|
|
remaining pause budget.
|
|
|
|
3. Gate VM ticks.
|
|
Update `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`
|
|
and `crates/console/prometeu-system/src/services/vm_runtime/tick.rs` so a
|
|
suspended Game does not receive normal ticks, normal input, or frame pacing.
|
|
|
|
4. Deliver pause notification.
|
|
Add the mechanism that makes the pause event visible to the running Game
|
|
before suspension. Use an existing VM event channel if present; otherwise add
|
|
a narrow lifecycle-event queue owned by SystemOS/VM runtime.
|
|
|
|
5. Enforce the budget.
|
|
Advance the pause budget on firmware ticks. When it expires, transition the
|
|
Game task/process to suspended through SystemOS lifecycle regardless of Game
|
|
cooperation.
|
|
|
|
6. Deliver resume notification.
|
|
On return to the resident Game, transition from suspended to resume-requested,
|
|
reactivate VM execution, deliver resume/foreground-restore, and leave visual
|
|
restoration to the render boundary plan.
|
|
|
|
7. Add tests.
|
|
Cover cooperative pause, non-cooperative forced suspension, no tick while
|
|
suspended, resume notification delivery, and no Game-owned ability to cancel
|
|
OS suspension.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Game receives pause before suspension.
|
|
- SystemOS suspends after a bounded budget even if the Game does not cooperate.
|
|
- Suspended Game does not receive normal gameplay ticks.
|
|
- Resume/foreground-restore is delivered before visual return to Game.
|
|
- Game cannot prevent OS suspension through guest-visible behavior.
|
|
- Existing debugger pause behavior remains distinct from lifecycle suspension.
|
|
|
|
## Tests / Validation
|
|
|
|
- Add unit tests in `prometeu-system` for lifecycle transition state.
|
|
- Add firmware tests around `GameRunningStep` pause request and suspension.
|
|
- Add VM runtime tests proving suspended state suppresses normal ticks.
|
|
- Run `cargo test -p prometeu-system`.
|
|
- Run `cargo test -p prometeu-firmware`.
|
|
- Run `discussion validate`.
|
|
|
|
## Risks
|
|
|
|
- Debugger pause already exists in VM runtime. Keep debug pause separate from
|
|
lifecycle pause/suspend.
|
|
- A lifecycle event queue could become a general app event system. Keep this
|
|
plan limited to pause/resume required by `DEC-0037`.
|