Opal Assistant

Open Agent in the editor toolbar, Ask Assistant in Script Studio or Behavior, or Ask Assistant beside a Problems entry. It is also in Help and the command palette. The panel can be moved between the left, right and bottom docks.

Ask mode inspects and explains; the host prevents it from proposing edits. Edit mode prepares changes for your review. Both modes can search the current project's scripts/assets and current-scene objects, read source and working drafts, inspect component settings, project input bindings, engine physics configuration and Flow graphs, and consult installed engine APIs and component field/action schemas. Project references in replies open the matching editor selection, script or asset. When a design choice is missing, short questions offer clickable answers; you can always type your own.

For movement and jumping questions, the assistant can read the current project's normalized input contexts, action names and IDs, bindings, processors and interactions. Engine gravity, physics scale, solver iterations and fixed timestep are labeled separately from per-object body/controller settings. These reads describe authoring configuration; they do not claim to observe live key presses or grounding. Reviewed proposals can add or update actions in existing contexts; manual editing remains available in Settings → Project Input and the Input shelf.

The Changes view shows script diffs and before/after object fields, with checks, Apply changes, Revise, and Dismiss. A proposal can combine up to three typed OpalScript changes with settings on up to 16 existing objects: names, positions, sizes, rotation, opacity, flips, declared component fields, and new component attachments. It can also create primitive sprite objects, configure their components and references, and add or update project input actions in the same proposal. These use one scene-editor undo entry. Property defaults and values already authored on instances are treated separately. Existing script ownership and public APIs are preserved. The actual compiler and field/reference validators check the proposal before review and again before applying it.

Try Move and jump in an empty project. The starter fills the message box for you to edit and send. The installed reference includes a complete player, floor, input and script example sized to the current stage. Existing objects and actions should be inspected and reused where appropriate. The example uses one flat floor; for slopes, coyote time and jump buffering, prefer the built-in Platformer Controller unless you need a custom script. Test movement, jumping and landing in Play.

Review shows each new object's position, size, artwork and components, readable input bindings, then script diffs. Rectangles, rounded rectangles, ellipses and circles bake through the normal primitive-art tool only after Apply, with PNGs in the project's Art folder. Undo restores scene objects, scripts and controls together; generated artwork stays reusable in the library, like imported art. Redo reuses the same object and artwork identities. Save/reopen and game exports include the objects, controls, source and referenced PNGs.

Script diffs keep separate edits separate, show before/after line numbers and accurate added/removed counts, and collapse unchanged sections. Code regions support keyboard scrolling, with the exact full proposed source available below. Revise adds revision context to your existing draft without deleting its text or selection. Stop and Escape return keyboard focus to the draft.

Open a Behavior asset to edit its current working draft. The assistant can add or update states, transitions, trees, nodes and memory using stable identities and real component actions. Behavior changes have their own review, save and native Behavior undo step; they are not grouped with scene/script changes. Save a Behavior before switching away if you want to keep subsequent manual edits. Shared Behavior assets affect every object using that asset.

Pre-existing script drafts retain a separate undo entry. Changed source, project bindings, target objects or Behavior revisions prevent stale proposals from overwriting newer work. Play, transitions and prefab editing also block applying. If a proposal inspected project input settings, those settings are checked again before applying; unrelated proposals do not acquire that dependency. Applied · Saved appears only after the owner's save completes. If saving fails, changes remain in the editor with Retry save, which never adds another edit; an undone change cannot be reapplied by retrying a save.

This release focuses on editor authoring. It cannot generate arbitrary illustrations or audio, edit Flow graphs, delete files, publish games, or operate a live Play debugger. Compilation and schema checks do not prove gameplay correctness; test the result in Play.

Personal connections (the default)

Open Agent and select the model button at the top of the panel (or Choose model), then choose a provider, enter your key where needed, and pick a model. Load models reads the provider's model catalog; you can also enter an exact model id. Test connection sends a small automatic tool-call probe without project data. It may use billable tokens. A successful probe establishes connectivity and basic tool support, not the quality of game edits. Meta only supports automatic tool selection; the probe checks that it actually returns the requested tool call. Its short reasoning setting applies only to the test, not to editor authoring. See Meta's tool-calling constraints.

Connection	API base	Format
OpenRouter	https://openrouter.ai/api/v1	Chat Completions
OpenAI	https://api.openai.com/v1	Responses
Meta · Muse Spark	https://api.meta.ai/v1	Responses
Ollama · local	http://localhost:11434/v1	Chat Completions
LM Studio · local	http://localhost:1234/v1	Chat Completions
Custom compatible API	Your base URL	Chat Completions or Responses

Advanced configures the output-token limit (256–262,144, default 32,768) and per-call timeout (10–1,800 seconds, default 600). Thinking, the visible answer and tool calls share the output budget. The limit is a ceiling, not a target; models can finish earlier and may enforce a lower maximum. The connection test uses the selected budget too. Existing saved limits stay unchanged; Use default limits updates them without changing the model or key. Longer reasoning and local models can need more time. See Meta's reasoning guide and OpenAI's reasoning guidance. Custom APIs must expose /chat/completions or /responses below their base URL; model discovery additionally needs /models. Streaming SSE and ordinary JSON responses are supported. URLs must use HTTPS, except literal loopback HTTP hosts (localhost, 127.0.0.1, ::1). No credentials belong in the URL.

“OpenAI-compatible” is not a guarantee: the selected model/API must support function tools, the chosen protocol and its request parameters. OpenRouter models that explicitly omit tools are filtered out of discovery; local catalogs may not advertise capability, so use the test. Context capacity, tool reliability and code quality vary. All providers still use Opal's inspection, validation, review and undo controls. See the official OpenRouter tool guide, Ollama compatibility reference, and LM Studio tools guide.

Personal requests go directly from the user's browser to their provider. Opal Desktop uses a bounded native assistant bridge with the same adapters, without loosening the editor's Content Security Policy. Personal connections never fall back to an Opal server key. Users pay their own provider account; locally served models use their machine. No Opal server configuration is needed for personal connections, including static and desktop editions.

Provider/model preferences stay on this device, separate from project records and exports. Remember key on this device is checked for new connections and saves the key in a separate endpoint-bound localStorage record when you choose Use connection. It survives reloads, new tabs and browser restarts. This is unencrypted browser storage, readable by code running on the same Opal origin. Uncheck it for memory-only use until reload. Forget key removes the saved key. Keys never enter project files, conversations or Opal's server. Switching endpoints removes the previous key instead of forwarding it. Old tab-only keys are loaded into memory once; saving with Remember key checked moves them to device storage. Local and hosted Opal origins keep separate settings and keys.

Connecting a local model from a browser

Start the model server with a tool-capable model. localhost means the user's computer, not the machine hosting opal-engine.com. The browser may request local network permission, and its security settings can block the connection.

• Ollama: add the exact editor origin to OLLAMA_ORIGINS and restart Ollama. For the production site, that origin is https://opal-engine.com; local development usually uses http://127.0.0.1:5173. Follow the OS-specific Ollama environment setup.
• LM Studio: start its server and enable CORS in server settings.
• Other APIs: the provider must allow the editor's origin and required headers through CORS. An API working in curl does not prove browser access.
• Opal Desktop: the native bridge avoids browser CORS and mixed-content restrictions. Keep local model servers bound to loopback; they do not need to be exposed to the public internet.

Optional server-funded connection

Leave OPAL_ASSISTANT_ENABLED=false and the server API key blank unless you want to pay for a hosted option. A user must explicitly choose Provided by this Opal server to use it. Personal connections do not consume this allowance.

Obtain a key from the Meta Model API dashboard. Set these in the server's .env and restart the server:

OPAL_ASSISTANT_ENABLED=true
OPAL_ASSISTANT_API_KEY=your-server-key
OPAL_ASSISTANT_MODEL=muse-spark-1.3-contributor

The supported alternative is muse-spark-1.3. The provider URL is fixed to https://api.meta.ai/v1/responses; clients cannot choose arbitrary endpoints, models or tools on this route. Production requires Opal authentication. Auth-free development is limited to a loopback host and peer. Static and desktop editors use personal connections. No model or GPU needs to run on the Opal server.

All optional controls, including defaults, are documented in .env.example:

• OPAL_ASSISTANT_USER_DAILY_CALLS: 80 per user per UTC day.
• OPAL_ASSISTANT_DAILY_BUDGET_USD: estimated $5 server-wide per UTC day.
• OPAL_ASSISTANT_MAX_OUTPUT_TOKENS: 32768, including reasoning (up to 262144).
• OPAL_ASSISTANT_TIMEOUT_MS: 600000 per provider call (up to 1800000).

Tasks have no fixed model-call cutoff. The assistant keeps inspecting and repairing proposals until it has a checked result, asks a question, explains a blocker, or you press Stop. Older complete tool exchanges are condensed into task notes as the context fills; the request and available inspection results remain. A provider interruption offers Retry request with the existing inspections, reasoning and validation feedback, without repeating the developer's request. An empty provider reply offers the same retry path; earlier progress text cannot be mistaken for a completed answer. Retry checks for changed scripts, inspected objects, Flow and Behavior drafts. Changing scenes, projects, modes, sharing or connections discards the retry state. Per-call settings and the provider's own limits still apply.

Answering a question continues the same investigation with its tool results and provider reasoning intact. Both suggested choices and free-text answers work. If the selection, open script, scene object list, scripts, inspected objects, Flow or the Behavior draft changed before the answer, the assistant captures fresh context and inspects current data again. Answered or retired choices disappear; a choice clicked while you have a draft adds the answer to that draft for you to send, without discarding or sending your unfinished text.

Activity shows real tool outcomes: inspected object/script names, successful checks, and compiler or validation feedback returned for correction. It does not display private model reasoning. Current activity, elapsed time and provider request counts appear above the composer while working. Request counts are not token usage or cost estimates. You can draft the next message during a request; it sends only when you press Send after the current request finishes. Completion, retry and Stop preserve that draft and do not move keyboard focus away from your work. Scrolling up keeps your reading position, including when a proposal arrives; Jump to latest returns to the newest reply.

A ready proposal opens Changes automatically when you have left the request to finish. If you draft a follow-up, navigate the panel or interact with the conversation while it works, completion keeps your place. Open the proposal through its conversation review button or Changes when you are ready. An older proposal you choose to inspect stays selected through unrelated updates; its status still shows when it has been replaced by a newer proposal.

For the optional hosted connection, one call per user and four users can be active at once. The single-process server reserves conservative token costs before calling Meta, refunds unused reservations only with complete usage, and retains reservations on cancellation or uncertain failure. Counts and estimates persist in OPAL_DATA/assistant-usage.json; it contains no prompts or project content. This is an application budget estimate using the published model rates, not a billing guarantee. Configure a provider spending limit too. Multiple server processes would require a shared transactional ledger before enabling this route.

Data sharing

Before sending, users acknowledge the destination and configured model's data policy for that project. Acceptance is remembered on this device for that exact project and provider/model policy. Data sharing lives in the model connection screen, together with the project-sharing options. Once accepted, its checkbox disappears and the section collapses. Open the model selector and expand Data sharing to review it or Revoke consent; it does not occupy the chat. The disclosure follows the provider/model being configured. Cancelling a draft connection keeps the active connection and its acknowledgement unchanged. Changing the destination, model or policy requires a new acknowledgement. Changing connection settings clears the chat; adjusting limits keeps consent. Other providers apply their own policies and account settings; Opal does not promise zero retention. Contributor permits Meta to use prompts and completions to train future models. The standard tier says it does not use them for training. See Meta's pricing and data-use distinction. Changing the model requires a new acknowledgement.

With project sharing enabled, each task sends a bounded index of scripts and current-scene objects, selected object, and recent errors. Source (including an open draft), component fields, variables, Flow graphs, the open Behavior draft and typed project bindings are read on demand. Asset names and ids are fetched only when the agent searches the project. Art/audio bytes, account information and other projects are excluded. Project sharing can be disabled for engine-reference questions; doing so clears the conversation so previous project context cannot be resent.

Conversation text and proposals stay in memory in the current tab. New chat, project switching and reload clear them. Scene switching stops pending work and retires proposals. store: false disables provider conversation storage for the Responses protocol; it does not opt Contributor out of its training policy.

Verification and limitations

npm test includes server authentication, origin validation, persistent limits, stream cancellation, the tool/compile/repair/review loop, draft protection, combined script/object/input changes and primitive creation, Behavior draft edits, save-failure recovery, apply/undo/persistence/player tests, Chat/Responses stream parsing and tool replay, credential isolation, no hosted fallback, and dark/light browser checks for connection setup, model discovery, probes, tabs, navigation, choices, cancellation and review. npm run test:desktop also exercises the real native assistant bridge against a temporary local API while the renderer's network is blocked. The mechanic browser acceptance also builds a real standalone player and checks rendered movement, jump, landing and repeat input using generated PNGs. Provider responses in automated tests are deterministic fixtures: live model quality requires a configured key and separate evaluation on disposable projects.

The agent never executes arbitrary JavaScript or shell commands. Its only write capability is a proposal, and model text is rendered as text rather than HTML. Unsupported edits require the developer to use the corresponding editor tools.