GraalJS Scripts

GraalJS scripts are not Java plugins. They run only when a Java plugin explicitly invokes them, and they receive a limited bridge rather than the Java SDK.

Package a script

A script package uses a script.json descriptor with schema version 2 and language set to js. The descriptor identifies the script entry with entry, identifies the source with sourceSha256, and declares requested permissions. Keep the descriptor and source together as the Java plugin that uses them expects.

{
  "schemaVersion": 2,
  "id": "dev.example.script.hello",
  "name": "Hello Script",
  "version": "0.1.0",
  "language": "js",
  "entry": "main.js",
  "sourceSha256": "<SHA-256 of the source>",
  "permissions": []
}

Only schemaVersion 2 is accepted, and js is currently the only supported script language.

This is a field-level outline, not a complete permission catalogue. Use only permissions supported by the build you are targeting; availability and exact semantics remain capability-sensitive.

Discovery is not execution

Making a script discoverable does not run it. A Java plugin must explicitly obtain scripts through PluginContext.scripts() and explicitly invoke one with ScriptService.run. There is no automatic discovery-and-execution lifecycle, and a script cannot substitute for a Java plugin’s manifest, lifecycle, permissions, or services.

Execution boundary

Scripts run in a restricted JavaScript environment with only the values and operations their Java caller supplies. They receive a limited Cubism bridge rather than the complete Java SDK. Treat bridge operations, resource limits, and available permissions as build-specific; they may constrain what a script can read, change, or request. Design scripts to handle unavailable operations and execution failure without assuming ambient host access.

Use the Java path for a process-resident plugin with SDK lifecycle and services. Use MCP when an external client needs authenticated loopback Streamable HTTP. ACP, used only with fx internally, is not a scripting or extension path.

Current status

Script execution is capability-sensitive: exposed bridge operations, resource limits, and the exact permission set can differ by build. Design scripts to handle an unavailable operation or a failed run without assuming ambient host access.