214 lines
11 KiB
Markdown
214 lines
11 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
|
|
|
|
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.
|