Files
prometeu-studio/docs/specs/studio/14. Integrated Play Specification.md
T
bquarkz 23522f7589
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/head There was a failure building this commit
docs(studio): keep README focused on project onboarding
2026-11-19 17:58:22 +00:00

150 lines
8.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Integrated Play Specification
Status: Implemented first interactive slice. Owner: `studio`.
## Product and scope
The normal `prometeu-app` launcher and managed installation MUST use
`prometeu-studio-ui-javafx-2`. The standalone foundation shell and gallery remain
development entry points. The previous frontend is retained for existing adapter
qualification; its workspaces are not mounted in the new product.
Startup MUST show known projects and an action to open an existing project
directory. A project MUST be closed before another can open. Closing returns to
the chooser. Startup MUST NOT automatically restore the previous project.
This slice exposes Play, Pause, Resume, Stop, a game viewport, and bounded logs.
It MUST NOT initialize an AI client or editor/LSP infrastructure when opening for
Play. Existing headless, MCP, evidence, tests and agent contracts remain available
through their existing entry points and services. Their preservation takes
precedence over interactive convenience.
Project creation UI, editors, workspaces, AI prompts, tuning during Play,
breakpoints, hot reload, PMC builds and distribution/export are outside this
slice. Future packaging belongs in Studio as a separate action; Play MUST NOT
implicitly package a PMC or a distributable runtime.
## Preparation, process and authority
Play MUST reuse the compiler/Packer/Shipper preparation pipeline to produce the
cartridge directory. Managed asset capacity, input revision and artifact identity
guards MUST remain enforced against the selected runtime installation. A changed
runtime requires a newly qualified capacity profile; the consumer MUST NOT infer
equivalence from its version string or bypass the guard.
Core owns execution orchestration and an exclusive project lease. The lease MUST
cover preparation, connection, running, paused and stopping phases until actual
preparation termination and native process/worker cleanup. Other project writes
MUST be rejected at service admission, including writes initiated outside the UI.
Preparation by the execution owner has a scoped admission path; it MUST NOT grant
an arbitrary caller permission to edit. The frontend MUST disable configuration
through the same ownership interval. A state label alone MUST NOT release ownership.
The application adapter MUST start a direct, owned `prometeu-runtime` child in
interactive `--studio` mode, without a native game window. This does not compile
Rust for the JVM or load native VM code into Java. Wire and process mechanics
belong to `prometeu-app`, behind neutral API/Core ports. UI2 MUST depend only on
Studio API and its presentation toolkit, never Core, concrete providers or the
previous frontend.
Process/control/video/log workers MUST use a per-connection executor independent
of the bounded operation pool. FX code MUST NOT wait for compilation, sockets,
native process exit or worker joins. Native process completion and worker cleanup
are prerequisites for returning project authority. Failed/stale attempts MUST NOT
change a replacement execution's lifecycle.
## Lifecycle and focus
Play prepares, connects, waits for READY, and issues START. Pause freezes logical
game advancement and audio without replacing the machine. Resume continues that
same session. Pause requested during preparation/connection MUST arm a paused
startup; START alone MUST NOT undo it. Stop cancels/waits for preparation or asks
the native host to stop and confirms teardown.
Minimizing or switching focus to another application MUST pause. Returning focus
or restoring the window MUST NOT automatically resume. Windows/popups owned by
Studio MUST be treated as part of Studio. A focus loss during an asynchronous
Resume MUST still result in pause once the runtime becomes running.
Closing a project or Studio MUST stop its game before closing the project session.
A normal Stop or close that is refused by save protection MUST retain the paused
session and its lease, explain the refusal in logs, and allow manual Resume.
Required IPC failure MUST close channels, terminate the owned native process,
retain bounded diagnostics and restore controls after cleanup. There MUST be no
automatic reconnect/restart, process-name-based termination or loss of headless
capabilities as a recovery mechanism. A new Play requires a new explicit action.
## Save media
For a game declaring save slots, the human MUST select an existing development
save image or explicitly select a disposable session. The frontend MUST NOT
silently create, overwrite or discard persistent media. The disposable choice is
per Play and MUST NOT be silently restored as a persistent project preference.
Existing agent/indentation setup fields MUST be preserved when runtime/save paths
are saved.
Normal Stop MUST wait for pending IO or refuse if it cannot finish safely, and
MUST refuse uncommitted persistent data. Disposable Stop may discard only because
that session was explicitly selected. IPC failure is the bounded forced-teardown
exception; it MUST be reported rather than represented as a successful save.
## Presentation and input
The binary [Studio Play protocol](../../../../runtime/docs/specs/runtime/11b-studio-play-protocol.md)
uses independent control/input and video channels, bounded messages, session and
epoch correlation, and one video credit returned after full reception. The native
tick MUST NOT wait for FX or socket writes. Unsent presentation frames may be
replaced by the latest complete publication; partial wire messages MUST finish or
fail. Control messages MUST NOT be dropped as a presentation optimization.
Java reception converts RGBA8 to premultiplied BGRA on an IO worker. Three CPU
buffers have explicit free, receiving, pending and presentation ownership, with
at most one presentation lease. A leased image MUST remain stable until close.
FX polls the latest complete frame on a pulse, copies it to an FX-owned
`WritableImage`, and releases the lease. Reception MUST NOT enqueue one FX task
per frame. Logs and frontend projections MUST remain bounded.
Zoom choices MUST be x1, x2 and x4 with nearest-neighbor presentation. At x1 a
480×270 game occupies 480×270 logical pixels, respecting OS scale; it does not mean
one physical display pixel. Oversized images MUST retain zoom and scroll. The UI
MUST NOT silently fit the image or change zoom.
Input MUST invert the image's scene transform and selected logical zoom. Touch
outside the image MUST release/reject touch rather than clamp to an edge. Keyboard
input belongs to the focused viewport, with modifiers reserved for application
shortcuts. Pad keys are arrows, A/D/W/S for A/B/X/Y, Q/E for L/R, Z for Start and
Shift for Select. Focus loss and lifecycle changes MUST neutralize held input;
native epochs reject input from older execution phases.
## Verification and limits
The product baseline is Java 25, retaining JavaFX 23.0.2. The bundled image uses an
explicit JDK `jmods` module path for jlink. Build logic may target Java 21 bytecode;
that is not the Studio application baseline.
Qualification MUST cover actual installed startup, existing-game image/input,
pause/resume and focus, project close, dirty-save refusal and cross-mode readback,
broken channels, slow presentation/receiver, bounded buffers, repeated sessions,
and preserved headless/MCP/evidence/tests. Codec fixtures alone are insufficient.
`studioPlayDesktopTest` is an opt-in desktop gate. `-PstudioPlayStress=true` adds a
30-second idle-host measurement, deliberate FX suspension and twenty cycles.
Receive-to-copy latency uses `System.nanoTime` in the same JVM; it MUST NOT be
called end-to-end input latency or physical scanout latency. CPU/heap observations
and hardware/OS/build flavor MUST accompany performance claims. A heap-used sample
does not prove retained-memory bounds; ownership and resource tests do.
Executed functional qualification includes macOS ARM64 with Java 25 and the release
umbrella distribution produced by `runtime/scripts/local-dist.sh`, including real
Pong Play and the deterministic headless process. Capacity qualification identifies
the dispatcher and both native backends as one exact bundle; multiple releases may
share an unchanged dispatcher. The explicit qualification command is documented in
the [development guide](../../development.md#native-runtime-installation-and-qualification).
Earlier presentation performance measurements used debug native binaries.
Windows/Linux, release performance, physical HiDPI pixel alignment, and human
listening/IME/accessibility walkthroughs require separate evidence. Diagnostic runs
and failures remain in Work evidence; a later passing run does not establish their
unobserved cause.