279 lines
15 KiB
Markdown
279 lines
15 KiB
Markdown
# Studio Development Guide
|
||
|
||
Run commands from the Studio repository root unless stated otherwise.
|
||
This guide covers installation, native runtime qualification, external tooling
|
||
and opt-in integration checks. See the [project README](../README.md) for the
|
||
application overview and basic build commands.
|
||
|
||
## Native Runtime Installation and Qualification
|
||
|
||
Build the native umbrella distribution with `../runtime/scripts/local-dist.sh`.
|
||
It packages `prometeu`, `prometeu-runtime` (desktop/Studio Play) and
|
||
`prometeu-headless` (deterministic automation). Select the extracted
|
||
`../runtime/dist-staging/stable/prometeu-cli-<target>` directory in Studio.
|
||
An unchanged dispatcher can belong to several releases: Studio selects a profile
|
||
only when all three executable hashes match the same qualified bundle.
|
||
|
||
After changing a native binary, qualify the actual installation before building
|
||
or launching Studio with its updated catalog:
|
||
|
||
```sh
|
||
make -C ../tooling venv
|
||
../tooling/.venv/bin/python ../tooling/scripts/qualify.py \
|
||
--studio . \
|
||
--runtime ../runtime/dist-staging/stable/prometeu-cli-aarch64-apple-darwin
|
||
```
|
||
|
||
This command executes the native glyph/scene 16/17 boundary test afresh, verifies
|
||
the evidence and executable identities, then publishes an exact capacity profile
|
||
under `prometeu-app/src/main/resources/asset-capacity`. Review/include those
|
||
resources when distributing Studio. It neither builds a replacement runtime nor
|
||
relaxes the execution guard. A failed qualification publishes no catalog entry.
|
||
The native build stays independent of the JVM; qualification is an explicit
|
||
consumer verification step, separate from pressing Play.
|
||
|
||
## Installation and IntelliJ Development
|
||
|
||
Build and stage the complete distribution, including its Java runtime:
|
||
|
||
```bash
|
||
./gradlew :prometeu-app:stageStudioInstallation
|
||
```
|
||
|
||
The macOS default is `~/Library/Application Support/Prometeu/Studio/current`.
|
||
Staging validates a new version before atomically changing `current`, retaining
|
||
older versions for rollback and running processes. Native client registration
|
||
uses absolute paths and argument arrays, independent of shell PATH:
|
||
|
||
```text
|
||
command: <installation>/current/runtime/bin/java
|
||
args: ["-cp", "<installation>/current/lib/*", "p.studio.app.StudioLauncher", "mcp", "--project", "<absolute-project-root>"]
|
||
```
|
||
|
||
For development, use an isolated installation:
|
||
|
||
```bash
|
||
./gradlew :prometeu-app:stageStudioInstallation -PstudioInstallationRoot=/absolute/dev-installation
|
||
```
|
||
|
||
In IntelliJ, run/debug `p.studio.app.StudioLauncher` with the `prometeu-app`
|
||
runtime classpath and VM option `-Dstudio.installationRoot=/absolute/dev-installation`.
|
||
The desktop and client-owned connector are separate JVMs. To debug the latter,
|
||
add the development-only VM argument
|
||
`-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=127.0.0.1:5005`
|
||
before `-cp` in the local MCP entry, restart that MCP process, then use IntelliJ's
|
||
**Remote JVM Debug** on localhost:5005. Do not commit this local configuration.
|
||
Because manual edits to the managed entry are protected, restore its original
|
||
content before using preparation again. Regular registration never enables JDWP.
|
||
|
||
## External Coding Agents (MCP)
|
||
|
||
The following authorization workflow belongs to the previous DEV adapter. The new
|
||
Play UI does not yet expose a grant/configuration surface. Headless protocol,
|
||
task authority, MCP tool schemas and the installed stdio connector retain their
|
||
existing entry points.
|
||
|
||
Studio includes its own `mcp --project <absolute-root>` mode. Configure the native
|
||
client once; project grants and desktop restarts no longer require copying ports
|
||
or tokens. The initial integration targets Codex on macOS.
|
||
|
||
1. Install/stage Studio with its bundled Java runtime (see installation above).
|
||
New projects prepare the local client entry during scaffolding. Opening an existing project
|
||
also prepares its enabled integration automatically; Studio starts the shared
|
||
MCP server itself. **DEV → Prepare assistant** retries preparation after resolving
|
||
a reported setup conflict. Opening a project does not grant agent control.
|
||
2. Open the coding client in the project directory. Trust the project and reload
|
||
MCP once if the client requests it. Studio does not alter client approval policy.
|
||
Tools can initialize/list even before the desktop is open or access is granted.
|
||
3. Open the project in Studio and grant control in DEV (save first if prompted).
|
||
Active Debug prevents granting. The connector discovers access automatically.
|
||
4. The agent acquires a task, consults project/language/SDK references, edits saved
|
||
project files with its native tools and validates through LSP/build. SDK and
|
||
external libraries remain read-only.
|
||
5. Recover uncertain operations by operationId/clientRequestId lookup within the
|
||
same task; never replay build/advance blindly. Explicitly release control when
|
||
done. Human reclaim also revokes access; stop direct external file edits separately.
|
||
|
||
The client invokes the same Studio artifact over stdio. It forwards to Studio's
|
||
project-scoped loopback service using protected, transient
|
||
`.studio/mcp/connection.json`. The permanent `.codex/config.toml` entry contains
|
||
installed Java/classpath/root arguments, not credentials. Both local outputs are
|
||
ignored by Git. Unrelated client settings are preserved; tracked or conflicting
|
||
Studio entries require deliberate resolution. `.studio/setup.json` preserves
|
||
neutral integration intent and existing runtime/editor settings.
|
||
|
||
After desktop restart, grant again in DEV. Keep the same client session and
|
||
configuration; old task identities and operation receipts are not restored.
|
||
DEV displays connection separately from project authority. No project-local
|
||
launcher, Python transport script or embedded chat is required.
|
||
|
||
### Reading external source code
|
||
|
||
VS Code F12 opens SDK/core and admitted libraries as read-only documents, with
|
||
hover, continued F12 and syntax highlighting. SDK/core stay bundled; no editorial
|
||
copies are created. After a source revision changes or a session ends, navigate
|
||
again instead of reusing old positions.
|
||
|
||
For MCP, use `studio_language_query` with `operation: "definition"`, then pass a
|
||
returned `prometeu-source:` URI to `operation: "readExternalSource"`. The response
|
||
contains `descriptor` and `text`; hover and definition accept the same URI within
|
||
the owning task. Another task cannot reuse it. MCP does not require VS Code open.
|
||
External or mixed edit proposals are refused in full. Library installation/cache
|
||
management is outside this feature. See the [extension guide](../tools/vscode-extension/README.md).
|
||
|
||
The production tools cover context, references, task control, LSP,
|
||
build/pack, operation lookup/cancellation and headless execution.
|
||
Headless requires a runtime installation configured for the project; missing or
|
||
incompatible installations fail explicitly. DEV is an
|
||
observation panel, not manual Play/input for the agent's session; **Debug** retains
|
||
the human testing workflow. Edits are preserved on cancellation; Git/review/recovery
|
||
remain the developer's responsibility.
|
||
|
||
See the [MCP contract](specs/studio/11.%20MCP%20Tools%20and%20Project%20Knowledge%20Contract.md)
|
||
for schemas, authorization, limits and delivery boundaries.
|
||
|
||
### Troubleshooting automation
|
||
|
||
| Symptom | Action |
|
||
| --- | --- |
|
||
| Waiting for access / desktop restarted | Open the project and grant again in DEV. Keep the existing client configuration. |
|
||
| Stale connection / incompatible catalog | Grant fresh access, or update the installed Studio when versions differ. Do not edit transient credentials. |
|
||
| Preparation conflict | Preserve the existing client settings; resolve a tracked/user-owned/edited Studio table explicitly, then prepare again. |
|
||
| Acquisition rejected or project busy | Grant control in DEV first; stop manual Debug before granting. Query an existing operation instead of starting another; serialize headless calls. |
|
||
| `RUNTIME_UNAVAILABLE` or handshake incompatibility | Check the project's configured runtime installation and its packaged headless command. Studio does not download a substitute. |
|
||
| `NO_FRAME_AVAILABLE` | Advance at least one frame before requesting a capture. |
|
||
| Advance/page limit rejected | Respect advertised limits and use reference pagination. Runtime's default maximum is 600 frames per advance; requests are not silently clamped. |
|
||
| Unknown language or missing reference | Inspect project context and the declared manifest language; use only advertised capabilities/reference IDs. PBS is a creation default, not an unknown-language fallback. |
|
||
| Returning control reports cleanup failure | Stop the external client's direct editing separately, then retry DEV reclaim after owned-process cleanup. Do not bypass the lock or restore stale editor buffers. |
|
||
|
||
Language and SDK references are bundled locally; reading them does not require a
|
||
compiler checkout or network download. SDK/external-library changes remain outside
|
||
the game-authoring task, even when a reference exposes a limitation.
|
||
|
||
## Integration Checks
|
||
|
||
Unit tests run through `./gradlew test`. Process, network, desktop and actual
|
||
application/provider composition checks use separate integration tasks, including
|
||
fixture subprocesses. These suites remain in Studio; `../tooling` prepares their
|
||
environment and orchestrates selected commands.
|
||
Integration checks are excluded from the runtime and Studio pipelines.
|
||
|
||
### Installed Studio Connector
|
||
|
||
```bash
|
||
./gradlew :prometeu-app:installedConnectorTest
|
||
```
|
||
|
||
Checks bundled Java, upgrade/rollback, project paths with spaces, minimal
|
||
environment, scaffolding/preparation and JavaFX startup.
|
||
|
||
### Integrated Play
|
||
|
||
The product starts with a separate project launcher. Add selects a `prometeu.json`
|
||
and remembers the project without opening it; Forget removes only the reference.
|
||
New Project opens a five-step wizard using the language catalogue. Successful
|
||
creation opens the project through the same shield as an existing project. The
|
||
shield follows actual opening steps and remains visible for at least one second,
|
||
counted in parallel with preparation. Opening a project does not compile or start
|
||
the game. Closing its window stops execution and returns to the launcher.
|
||
|
||
The launcher inherits presentation preferences and offers **Prometeu Studio > Preferences**
|
||
instead of permanent appearance selectors. This dialog also sets the machine-local
|
||
runtime default; **Project > Settings** configures an optional override and save
|
||
media. Interactive Play freezes the effective runtime for both asset capacity
|
||
qualification and launch, leaving inherited project configuration null. Headless
|
||
and MCP configuration remains project-specific.
|
||
|
||
The global Play/Stop button and Pause/Resume toggle stay on the right above the
|
||
Gameplay tab, moving together onto a second right-aligned row when navigation
|
||
needs the space. State text
|
||
lives in the project header. The equal-height footer follows the selected tab and
|
||
shows Gameplay's effective scale. Native tabs use stepped upper corners and a flat,
|
||
open base joining the content, without a button's lower bevel. Studio identity
|
||
appears once in the launcher's menu. Gameplay automatically fits the native frame
|
||
to its surface; the optional manual slider
|
||
uses 25–400% scale, with scrolling for oversized images. Window geometry is stored
|
||
in `~/.prometeu-studio/window-state.json`; the runtime default is stored separately
|
||
in `~/.prometeu-studio/runtime-settings.json`. Neither is portable game metadata.
|
||
Closing the launcher exits Studio. `./gradlew run` at the root
|
||
launches only the product; the independent shell/gallery require their explicit
|
||
module commands and do not run after the product closes.
|
||
|
||
The active tab's gold outline encloses its content with an opening below the tab
|
||
header. The product workspace uses a plain surface and equal top/bottom margins;
|
||
there is no additional decorative frame around the tabs. The standalone foundation
|
||
shell retains its panel. Gameplay contains a vertical SplitPane: game/local scale controls above,
|
||
logs below, initially around 80/20. Drag its horizontal divider to prioritize logs
|
||
or game. Automatic fitting follows the resulting render area, including while
|
||
paused; manual mode preserves the chosen scale and uses scrolling. The split stays
|
||
with the open view and is not stored as a project preference. Header/footer stay
|
||
outside the split. The outline decoration does not participate in layout or hit testing.
|
||
|
||
Qualify these windows without a native runtime using disposable projects and
|
||
isolated presentation storage:
|
||
|
||
```bash
|
||
./gradlew :prometeu-app:studioProjectsDesktopTest
|
||
```
|
||
|
||
Scene captures and environment metadata are written to
|
||
`prometeu-app/build/projects-desktop-captures`. This gate covers the catalogue,
|
||
wizard, appearance, geometry, failure feedback and late-session cleanup; the
|
||
separate Play gates below exercise the native process and game lifecycle.
|
||
|
||
Check command position and painting with real Robot mouse events, screen captures
|
||
and a repaint reference across themes, locales and text scales:
|
||
|
||
```bash
|
||
./gradlew :prometeu-app:studioControlsDesktopTest
|
||
```
|
||
|
||
Captures and pixel comparisons are written to
|
||
`prometeu-app/build/controls-desktop-captures`. The diagnostic fixture retains the
|
||
old wrapping layout to measure displacement; the stable-layout gate exercises the
|
||
current execution bar. These checks do not replace human confirmation of a reported
|
||
artifact that cannot be reproduced on the qualification machine.
|
||
|
||
Requires a desktop environment and an installed native runtime:
|
||
|
||
```bash
|
||
./gradlew :prometeu-app:studioPlayProcessTest -PstudioRuntimeInstall=/absolute/runtime-install
|
||
./gradlew :prometeu-app:studioPlayDesktopTest -PstudioRuntimeInstall=/absolute/runtime-install
|
||
```
|
||
|
||
Add `-PstudioPlayStress=true` for the 30-second presentation/FX-delay/20-cycle
|
||
check. Fixtures use a disposable copy of `test-projects/pong`. No external port
|
||
checkout is required. Changed native executables require renewed qualification
|
||
as described above.
|
||
|
||
### Headless Runtime and Application Composition
|
||
|
||
Use an extracted runtime distribution:
|
||
|
||
```bash
|
||
./gradlew :prometeu-app:headlessProcessTest -PstudioRuntimeInstall=/absolute/path/to/runtime
|
||
```
|
||
|
||
Exercises the real runtime, installed PBS examples, canonical PNGs, reset/reboot,
|
||
cancellation and process cleanup, plus saved-file LSP/build corrective loops.
|
||
The task requires the supplied runtime installation.
|
||
|
||
### MCP and DEV Desktop Integration
|
||
|
||
This check exercises the retained DEV adapter. It requires a POSIX desktop and
|
||
free port 7777:
|
||
|
||
```bash
|
||
./gradlew :prometeu-app:headlessMcpDesktopTest -PstudioRuntimeInstall=/absolute/path/to/runtime --max-workers=2
|
||
```
|
||
|
||
The HTTP client drives LSP, build and a fixed input timeline; output and visible
|
||
DEV pixels are compared with a separate direct-JSONL runtime process. Scenarios
|
||
include reset, cancellation, disconnect/reconnect, revocation, project/app closure,
|
||
crash, forced shutdown and return to manual Debug. Only test-owned processes are
|
||
terminated or suspended. After a forced-shutdown error, a second explicit reclaim
|
||
can acknowledge completed cleanup; control stays locked until cleanup is confirmed.
|
||
|
||
These commands describe available checks. Record actual runs, environment,
|
||
results, acceptance evidence and pending investigations in the owning AIE Work.
|