Launch the JavaFX 2 project shell on Java 25 with an interactive viewport, managed Play lifecycle and project mutation guards. Preserve headless/MCP and save compatibility, and qualify exact runtime executable bundles. Separate unit JaCoCo gates from opt-in integration suites and use the internal Pong fixture for the headless visual pilot. Move maintenance and native conformance tools into tooling; retain the VS Code extension and update current navigation links. Validation: tooling make verify passed, including 1064 Studio unit tests, JaCoCo thresholds and 22 headless integration tests.
150 lines
8.5 KiB
Markdown
150 lines
8.5 KiB
Markdown
# 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 [Studio README](../../../README.md).
|
||
|
||
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.
|