Construct document tasks

Construct can hold more than one document. Every construct OPAL task therefore accepts a document argument, and six tasks manage the documents themselves.

This page is the reference. If you only do one thing with it: an agent running a long edit calls construct.document.use first.

The document argument

Every construct.* task takes an optional document.

Value Resolves to
Absent The document this session pinned, or the active tab if none is pinned
A document id That document, or a failure that names it
A name That document, or a failure if the name is ambiguous

A lookup that fails is a task failure. It never falls back to the active document. The fallback would fire in exactly the case where you were being explicit, and it would succeed against the wrong scene, which is worse than a refusal.

Every response names the document it acted on, in document and document_name. Not only failures. Read them: they are how you notice that a call landed somewhere you did not intend.

Why the default is not enough on its own

Defaulting to the active tab is convenient for one call and unsafe for a sequence. The engineer can click another tab while your plan is running, and your next call lands in a different scene. Nothing errors.

So pin the document first:

{"task": "construct.document.use", "args": {"document": "hull"}}

Every following call in your session acts on that document, whichever tab the engineer is looking at. A pinned document that is closed fails your next call rather than quietly redirecting it.

construct.document.use and construct.document.activate are different

They are one word apart and they do different things. Getting them the wrong way round does not raise an error — the call succeeds, against the wrong document.

Task Changes Use it when
construct.document.use Which document your calls act on You are about to run a sequence of edits
construct.document.activate Which tab the engineer sees You were asked to show someone something

activate leaves your pin alone. use leaves the visible tab alone.

The six tasks

construct.document.list

No arguments. Returns one row per open document: id, name, path, modified, active, pinned.

This is the discovery path. Call it to find ids rather than guessing, which is why document does not need to be described on all fifty-odd other tasks.

construct.document.open

Argument Required Default Meaning
path yes — File to open
activate no true Make it the active tab

Returns documentId and name. Opening a file that is already open returns the existing document's id rather than a second copy of it.

It always opens a new tab — even when the scene in front is empty — because you asked for one more document. With activate set to false the file opens beside the engineer's current tab without taking it over. A file saved by a different version of Construct fails with a message saying so, where a person would have been asked whether to load it anyway.

construct.document.close

Argument Required Default Meaning
document yes — Id or name
discardChanges no false Required to close a modified document

Returns closed and hadUnsavedChanges. It refuses a document with unsaved changes unless you pass discardChanges. Save it first, or discard deliberately.

Closing a document takes its errors, its shader reports and its undo history with it. That is deliberate.

construct.document.activate

Argument Required Meaning
document yes Id or name

Returns activeDocument. Changes what the engineer sees. Does not change where your calls land — see the table above.

construct.document.use

Argument Required Default Meaning
document no clears the pin Id or name

Returns pinned. Pins a document for your session. Call with no argument to clear the pin and go back to following the active tab.

construct.document.save

Argument Required Default Meaning
document yes — Id or name
path no its own path Save-as

Returns path and hash. The hash is there so that if you pinned assets against this file elsewhere, you can re-pin without reading it again.

What has no task

  • Nothing resolves a document by position or index. Tab positions change when a tab moves, so an index means something different a second later.
  • Nothing forces a close past unsaved changes without the explicit flag.
  • Nothing sets the modified flag. It follows the undo history.

Opening Construct in the first place

There is no task that creates or opens a scene from nothing. Construct opens through:

{"task": "navigation.goto", "args": {"activity": "ConstructActivity"}}

Send that as a plan on its own and wait for it to finish. The shell finishes loading after the step returns, so an editing plan sent in the same turn arrives before there is anything to edit.

In this section