341 lines
21 KiB
Markdown
341 lines
21 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 a separate compact project launcher with known projects and
|
||
actions to add an existing `prometeu.json`, open, forget and create a project.
|
||
Opening MUST hide the launcher and present a separate loading shield; the project
|
||
window MUST appear only after preparation and the minimum shield duration.
|
||
A project MUST be closed before another can open. Closing returns to the
|
||
launcher after execution and session cleanup. Startup MUST NOT automatically
|
||
restore the previous project. Launcher geometry and project-window geometry MUST
|
||
be stored independently through the neutral window-state port. Project keys are
|
||
normalized absolute project paths. Geometry MUST preserve normal position/size
|
||
separately from maximization, survive orderly application restart and leave the
|
||
title bar reachable when monitors change. Available secondary displays, including
|
||
negative coordinates, MUST be considered instead of clamping every window to the
|
||
primary display. Writes MUST be serialized, atomic and off the FX thread; orderly
|
||
close MUST flush pending snapshots. Transient native show/maximization events MUST
|
||
NOT overwrite the saved normal geometry. Legacy geometry remains readable.
|
||
|
||
This slice exposes a global Play/Stop button, a separate Pause/Resume toggle, a
|
||
Gameplay tab with the game viewport, and bounded logs. Execution belongs to the
|
||
project session, independently of tab selection or lifetime. The global toolbar
|
||
MUST remain above the tabs. Starting Play selects Gameplay. Pause selection,
|
||
accessible names and command availability MUST follow observed execution state,
|
||
including automatic pauses and failures. Stop MUST remain Stop until execution
|
||
ownership is actually relinquished, including when paused. Transitioning commands
|
||
MUST NOT be submitted repeatedly.
|
||
|
||
The top row MUST place the golden-square Studio mark and **Prometeu Studio** menu
|
||
on the left, followed by project navigation. The Play/Stop and Pause/Resume pair
|
||
MUST be anchored at the right padding, leaving the intervening space available
|
||
for navigation independently of status text. When navigation and the pair would
|
||
overlap, the pair MUST occupy a second row, also aligned right. Each command MUST
|
||
reserve enough width for all its
|
||
translated labels at the active typeface and text scale. State changes MUST NOT
|
||
move the pair or resize its slots. The pause toggle MUST visibly read **Resume**
|
||
when paused and **Pause** otherwise, consistently with its accessible name and
|
||
tooltip. Keyboard focus MUST remain visible within the control's drawing envelope.
|
||
|
||
A compact project-information header MUST sit below the top area. It contains
|
||
project identity and execution status, including transient/disposable status,
|
||
separate from command layout. A footer MUST remain at the bottom of the window,
|
||
with the same height as the header at the current text scale. It MUST display
|
||
information supplied by the selected tab; unregistered tabs MUST show no inherited
|
||
status. Gameplay supplies the effective scale or a waiting-for-image status.
|
||
Overflowing information MUST ellipsize without displacing commands. At small window
|
||
sizes or large text scales, content MUST remain scrollable while both information
|
||
strips remain outside the scrolling content.
|
||
|
||
The product workspace between header and footer MUST use a plain surface without
|
||
an additional decorative frame around the tabs. Its top and bottom margins MUST
|
||
be equal, initially 18 logical pixels, while retaining the horizontal inset and
|
||
filling the remaining space. This MUST preserve scrolling for constrained windows
|
||
and MUST NOT remove the active tab's gold outline around its own content. The
|
||
standalone foundation shell/gallery retains its decorative panel.
|
||
|
||
Tabs MUST retain native selection, focus and keyboard behavior and the inherited
|
||
Studio typeface. Tabs MUST use stepped upper corners and a flat base without the
|
||
lower bevel or bottom outline of a button. The selected tab MUST join the content
|
||
surface, with a gold accent on its top and sides. Semantic theme colors MUST retain
|
||
distinct selected, hovered, disabled and focused states. This slice MUST NOT add
|
||
placeholder editors or extra tabs.
|
||
|
||
The gold outline MUST continue from the active tab header around its entire content
|
||
area, joining the header's sides without drawing a line across the opening below
|
||
it. The outline MUST follow selection and layout, disappear for empty content and
|
||
remain outside hit testing and layout measurement. It MUST NOT obscure keyboard
|
||
focus or leave the previous tab's outline after selection/removal.
|
||
|
||
Gameplay MUST contain both the game surface/local scale controls and bounded logs,
|
||
with an adjustable horizontal divider between game above and logs below. The
|
||
initial division SHOULD prioritize the game at approximately 80/20. Both regions
|
||
MUST retain usable minimum sizes and scrolling when needed. The divider MUST follow
|
||
the Studio theme and indicate drag affordance. Header/footer and global execution
|
||
controls MUST remain outside that split. Adjusting it MUST NOT change execution
|
||
state or restart the runtime. The split is retained for the open view; it does not
|
||
introduce persisted project settings or a restoration contract across reopening.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
## Project selection, creation and loading
|
||
|
||
The launcher MUST reuse the persisted known-project catalogue, ordered by name,
|
||
and display name, version, language, stdlib and path. Open and Forget MUST require
|
||
a selection; Open MUST also work by double click or Enter. Adding a manifest MUST
|
||
validate, remember and select it without automatically opening. Forget MUST remove
|
||
only the catalogue reference, never files. Cancelled file selection MUST leave the
|
||
catalogue unchanged. Empty and failed states MUST provide visible feedback.
|
||
The launcher MUST contain project selection/management, identity and access to
|
||
Studio preferences, without permanently exposed language, theme, typeface or scale
|
||
selectors. It MUST inherit the existing presentation settings. Closing the
|
||
launcher MUST exit Studio without presenting an empty project/foundation shell.
|
||
Studio identity MUST appear in the Prometeu Studio menu with its icon; the project
|
||
chooser MUST NOT repeat that identity in a separate block below the menu. The
|
||
project-section title, catalogue and commands MUST remain visible.
|
||
The internal project frame MUST grow and shrink with the available launcher width
|
||
and height, allocating additional height to the project list. Smaller viewports or
|
||
larger text scales MUST retain scrolling so project commands remain accessible.
|
||
The chooser MUST use equal 18px outer margins and one 18px panel inset, with 18px
|
||
between title/list/actions and 12px between actions. Empty feedback MUST NOT reserve
|
||
space; visible feedback MUST align with the outer margins without doubled gaps.
|
||
|
||
The creation wizard MUST use UI2 components and preserve five steps: name,
|
||
language/stdlib/source root, indentation/runtime details, parent location and
|
||
confirmation. Options MUST come from `ProjectLanguageCatalog`, with Game as the
|
||
target. Back MUST preserve input. Cancel MUST return to selection; creation and
|
||
persistence MUST execute off the FX thread. Successful creation MUST remember and
|
||
open the project through the common loading flow. A failed opening after creation
|
||
MUST explain that the project exists and can be opened again. Partial creation
|
||
MUST retain diagnostics and identify its location without deleting files as an
|
||
automatic rollback. The catalogue's existing machine-local MCP configuration
|
||
preparation remains available; it does not start an AI client or LSP.
|
||
|
||
The opening coordinator MUST expose real steps for catalogue validation,
|
||
`openForPlay()` session acquisition, known-project persistence and FX view
|
||
composition. The sequence MUST accommodate future steps without enabling them in
|
||
this slice. It MUST NOT initialize the previous workspace initializer merely to
|
||
provide the loading mechanism. Unmeasurable work MUST use indeterminate progress;
|
||
time-driven percentages MUST NOT stand in for actual progress.
|
||
|
||
The shield MUST identify Studio, its version, the project and current phase. It
|
||
MUST use equal 18px outer margins, one 18px panel inset and 18px between content
|
||
groups. Content MUST be centered vertically when space permits, with scrolling for
|
||
constrained space or larger text. These refinements MUST preserve window sizing,
|
||
positioning and opening behavior. It MUST remain visible for at least one second,
|
||
measured with a monotonic clock from
|
||
presentation, in parallel with preparation. The project is ready when validation,
|
||
session acquisition, required persistence and view composition succeed. If ready
|
||
before the minimum, show completion while awaiting the remainder; if slower,
|
||
there MUST be no additional full-second delay. This is independent of native
|
||
runtime READY and first-frame delivery, which belong to Play.
|
||
|
||
Each opening attempt MUST own its pending session, timer and callbacks until
|
||
handoff or cleanup. Failures at every step, including executor admission and FX
|
||
composition, MUST release acquired resources before enabling another opening and
|
||
return to selection with a visible error after the minimum. Cleanup failure MUST
|
||
retain recovery feedback and block new openings until explicitly retried cleanup
|
||
succeeds. There MUST be no automatic opening retry. Application exit MUST cancel
|
||
the cosmetic delay, prevent late presentation and still release late-arriving
|
||
sessions; cancelling a future is not proof of resource release.
|
||
|
||
IO, session teardown and operation waits MUST stay off the FX thread. Window
|
||
transitions MUST NOT accidentally exit JavaFX while all stages are hidden.
|
||
Launcher, wizard, shield and project MUST share UI2 theme, locale, typeface and
|
||
scale, with scrolling as needed to keep commands accessible. The launcher MUST
|
||
request application exit when closed; closing the project window MUST request
|
||
project closure and return to selection under the existing Stop/save rules.
|
||
Timers, views and appearance subscriptions MUST be disposed with their owners.
|
||
|
||
## Preferences and project configuration
|
||
|
||
Prometeu Studio > Preferences MUST open a separate dialog for theme, language, typeface,
|
||
UI text scale and the machine-local default runtime installation. Project >
|
||
Settings MUST open a separate dialog for the optional runtime override and save
|
||
media configuration. Project > Close project retains coordinated teardown.
|
||
Runtime and save fields MUST NOT be mounted permanently in Gameplay. Apply MUST
|
||
validate and publish settings off the FX thread; Cancel MUST leave stored choices
|
||
unchanged. Appearance forms use draft state until Apply. Execution configuration
|
||
MUST remain unavailable while execution ownership is held; appearance preferences
|
||
remain usable. Missing configuration MUST provide an action to open its settings.
|
||
|
||
Interactive Play MUST resolve the project override when present, otherwise the
|
||
Studio default. Inheritance MUST remain null in the persisted project setup; the
|
||
effective installation MUST be frozen in memory for both build capacity admission
|
||
and runtime launch. New global selections affect subsequent starts. An invalid
|
||
explicit override MUST fail visibly rather than silently select another runtime.
|
||
Existing project overrides MUST remain intact. The global installation is stored
|
||
locally, separately from frontend appearance. This rule MUST NOT change the
|
||
existing project-specific headless/MCP configuration contracts.
|
||
|
||
Save media paths remain machine-local project settings. Disposable save MUST be
|
||
an explicit temporary choice for the open project, reset on reopening, and MUST
|
||
be identified in execution status. Missing save media MUST NOT implicitly select
|
||
disposable mode. Existing write exclusion and save protection remain mandatory.
|
||
|
||
## 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.
|
||
|
||
Gameplay MUST default to uniform automatic scaling to the largest image that
|
||
fits the available surface. Window or Gameplay divider resize MUST recompute the scale, preserve aspect ratio
|
||
and center the image with margins when needed, without scrollbars in automatic
|
||
mode. The Gameplay footer's percentage and multiplier MUST describe the effective scale
|
||
relative to native frame dimensions. UI text scale is independent of game scale.
|
||
|
||
A Manual scale checkbox MUST enable a continuous slider from 25% to 400% of
|
||
native dimensions, initially using the current fitted scale clamped to that range.
|
||
Manual images larger than the surface MUST remain accessible by scrolling.
|
||
Disabling manual mode returns to automatic fit; reopening a project resets manual
|
||
mode. Presentation retains nearest-neighbor sampling, including fractional scale.
|
||
Divider movement MUST preserve the chosen manual scale and update the visible
|
||
scroll area. Automatic fitting MUST also respond while paused, without requiring
|
||
a new runtime frame; disabling manual mode fits the current render area.
|
||
This replaces the former discrete x1/x2/x4 and mandatory 1:1 presentation contract.
|
||
|
||
Input MUST invert the image's actual scene transform and displayed dimensions,
|
||
including fractional scale, centering margins and manual scroll. 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.
|
||
|
||
The only native machine output is 640×360 RGBA8888 at 60 Hz. The new JavaFX 2
|
||
viewport obtains dimensions from complete runtime publications; it MUST NOT keep
|
||
an independent fallback resolution. Leaving the image cancels an active contact;
|
||
dragging back while still held MUST NOT recapture without a new press inside.
|
||
Scale and scroll operate in JavaFX logical coordinates, with scene
|
||
transforms accounting for host display scaling. These frontend changes apply to
|
||
the new UI only; the old UI is outside the current graphics migration scope.
|
||
|
||
## 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.
|
||
|
||
`studioProjectsDesktopTest` qualifies real launcher/wizard/shield/project window
|
||
transitions with isolated projects/preferences and filesystem catalogue services.
|
||
It does not require or qualify native execution. Its snapshots include environment
|
||
metadata under `prometeu-app/build/projects-desktop-captures`. Unit tests with a
|
||
controlled clock cover fast/slow loading, failure, cleanup retry and late results.
|
||
|
||
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.
|