OPAL · Config
Read and change the settings of every open app from OPAL Tasks
Config OPAL reference
The config.* tasks read and change the settings of every open app. They use
the same validation and the same undo history as the settings window, so the
window shows a change from a task at once, and you can undo a change that a
plan or a language model made.
For the window itself see Settings.
Schemas
A schema is every setting of one app. An app adds its schema when it
starts, and every task names it in the schema parameter. config.schemas
lists the schemas that are open now. A call on a schema that is not open
fails, and the message lists the open ones.
| Schema | App | Levels |
|---|---|---|
construct |
Construct | app, scene, camera, renderjob |
Construct's levels are explained in
Where Construct settings live. The
app level is the one the settings window calls New scenes.
Permission scopes
| Kind | Tasks | Tier | Scope |
|---|---|---|---|
| Read | schemas, list, describe, get, export, window.open |
identified |
config.read |
| Write | set, set-bulk, reset, revert, import, undo, redo |
operational |
config.write |
identified needs an unlocked Sentient session. operational needs an
unlocked session on an active node. Two rules raise the tier of a write:
- A secret setting needs
secured, an unlocked password-protected session. A task never returns the value of a secret setting:config.get,config.listandconfig.exportshow(set)or(not set). - A schema can name a higher tier for all its writes.
Every failure message ends with State: no change., and a failed task changes
nothing. Every write records one step in the history of its level, so
Undo in the settings window, or config.undo, takes it back.
Common parameters
| Name | Meaning |
|---|---|
schema |
The schema id, as config.schemas lists it. Required by every task except config.schemas |
id |
A setting id, as the Id column of the window shows it, for example bloomThreshold |
level |
A level id or label, for example scene or Scene. Empty: the level chosen in Write to of the settings window, which is scene when Construct starts. Name the level when it matters |
context |
Which part of the app the call acts on, for a schema whose levels follow a document. An object, or its JSON text |
category |
A category path, for example hdr. A child category is hdr/<child> |
Construct's context. Construct reads one key, camera_id:
context |
The call acts on |
|---|---|
Absent, or no camera_id |
The open document, and the camera the viewport looks through |
{"camera_id": "<uuid>"} |
The open document, and that camera. A camera that is not in the open document fails the call |
The tasks act on the open document only. In free-orbit editor mode there is
no viewport camera, so a write at camera without a camera_id fails.
Values go in as a number, true or false, a string, or JSON text for a
vector or a color. They come back as compact JSON text, so a string keeps its
quotes: "agx".
config.schemas
Lists every open schema.
Parameters: none.
Output keys: schemas, a JSON array with one object per schema: id,
title, levels and settings, the number of settings.
{"task": "config.schemas"}
config.list
Lists the settings of a schema as rows. The filter is the filter of the settings window, with the advanced settings included.
Parameters:
| Name | Required | Default | Description |
|---|---|---|---|
schema |
yes | — | The schema id |
category |
no | — | Only settings at or below this category |
filter |
no | — | Words that every listed setting holds, as in the window's filter field |
changed-only |
no | false |
Only settings that differ from their default |
limit |
no | 100 |
At most this many rows, 1 to 1000 |
offset |
no | 0 |
Skip this many matches first |
context |
no | — | See Common parameters |
Output keys:
| Key | Type | Meaning |
|---|---|---|
rows |
JSON array | One object per setting: id, label, kind, value, default, source (a level id), flags |
total |
integer | The number of matches, before limit and offset |
offset |
integer | The offset that was used |
A kind is one of bool, int, float, vec2, vec3, vec4, color,
enum, string, path, key-sequence, action, status and custom. A
flag is one of no-reset, restart-required, advanced, read-only and
secret.
An action row, such as Construct's regenerateThumbnails, holds no value.
No task of this family calls an action.
{"task": "config.list", "args": {"schema": "construct", "filter": "bloom"}}
config.describe
Returns the full declaration of one setting.
Parameters: schema and id, both required.
Output keys: declaration, a JSON object with id, label,
description, category, kind, default, levels (the levels that can
hold the setting), flags and help. A number adds minimum, maximum
and unit where it has them. A list adds choices, each with value and
label.
{"task": "config.describe", "args": {"schema": "construct", "id": "toneMapping"}}
config.get
Returns the value of one setting and where it comes from.
Parameters:
| Name | Required | Default | Description |
|---|---|---|---|
schema |
yes | — | The schema id |
id |
yes | — | The setting id |
level |
no | — | The value as seen from this level. Empty: the value the app uses now, through every level |
context |
no | — | See Common parameters |
Output keys:
| Key | Type | Meaning |
|---|---|---|
value |
JSON text | The value |
from |
string | The id of the level the value comes from, or default |
overridden |
true or false |
Whether the value overrides a value at a lower level |
{"task": "config.get", "args": {"schema": "construct", "id": "exposure", "level": "scene"}}
config.set
Writes one value at a level, with the validation of the settings window.
Parameters:
| Name | Required | Default | Description |
|---|---|---|---|
schema |
yes | — | The schema id |
id |
yes | — | The setting id |
value |
yes | — | The new value |
level |
no | The window's Write to | The level to write at |
context |
no | — | See Common parameters |
Output keys: value, the value now set at the level, and level.
Fails when the value is not valid, when the level cannot hold the setting, and when the setting is read-only. The message gives the reason.
{"task": "config.set", "args": {"schema": "construct", "id": "bloomThreshold", "value": 0.8, "level": "scene"}}
config.set-bulk
Writes many values at one level as one step. All or nothing: if one value is refused, the call fails and writes none.
Parameters:
| Name | Required | Default | Description |
|---|---|---|---|
schema |
yes | — | The schema id |
values |
yes | — | An object of setting id to value, or its JSON text |
level |
no | The window's Write to | The level to write at |
context |
no | — | See Common parameters |
Output keys: count, the number of values, and level.
{"task": "config.set-bulk", "args": {"schema": "construct", "level": "scene",
"values": {"ptMaxSamples": 1024, "ptMaxBounces": 6}}}
config.reset
Writes the declared default of one setting, or of every setting at or below a category, at a level. One step.
Parameters: schema, then id or category (one of the two, not both),
then level and context as in Common parameters.
Output keys: count, the number of settings reset.
A setting with the flag no-reset refuses a reset by id. A reset by
category leaves out the settings that have no reset, that are read-only, or
that the level cannot hold.
{"task": "config.reset", "args": {"schema": "construct", "category": "hdr", "level": "camera"}}
config.revert
Removes the value of one setting, or of every setting at or below a category, at a level, so the level below shows through. One step.
Parameters: schema, then id or category (one of the two, not both),
then level and context as in Common parameters.
Output keys: count, the number of settings reverted.
Reset and revert differ: see Reset, revert and undo.
{"task": "config.revert", "args": {"schema": "construct", "id": "exposure", "level": "camera"}}
config.export
Returns the values set at one level, as the settings file that Export… writes.
Parameters: schema, level and context. Only schema is required.
Output keys: json, the file as compact JSON text: schema, level and
values.
{"task": "config.export", "args": {"schema": "construct", "level": "app"}}
config.import
Writes the values of a settings file at a level, as one step. It writes every value it can, and reports the others by name.
Parameters:
| Name | Required | Default | Description |
|---|---|---|---|
schema |
yes | — | The schema id |
json |
yes | — | The file, as config.export returns it: an object or its JSON text |
level |
no | The window's Write to | The level to write at. The level named in the file is not used |
context |
no | — | See Common parameters |
Output keys:
| Key | Type | Meaning |
|---|---|---|
written |
integer | The number of values written |
unknown |
string | The ids that are not settings of the schema, as a comma list |
invalid |
string | One line per refused value, with the reason |
A file of another schema fails the call, and nothing is written. A value whose
tier the caller does not have is reported in invalid and not written.
{"task": "config.import", "args": {"schema": "construct", "level": "app",
"json": {"schema": "construct", "values": {"bloomThreshold": 0.5}}}}
config.window.open
Opens the settings window of the app, on a category.
Parameters:
| Name | Required | Default | Description |
|---|---|---|---|
schema |
yes | — | The schema id |
category |
no | — | The category to show, for example pathTracing |
Output keys: none.
Fails on a node with no screen.
{"task": "config.window.open", "args": {"schema": "construct", "category": "pathTracing"}}
config.undo
Takes back the last step in the history of a level. Fails with
nothing to undo on an empty history.
Parameters: schema, level and context. Only schema is required.
Output keys: none.
In Construct the history of scene and camera is the document's own undo
history. So config.undo at those levels takes back the last step of the
document, which can be an edit of the scene and not a setting.
{"task": "config.undo", "args": {"schema": "construct", "level": "app"}}
config.redo
Takes back the last undo in the history of a level. Fails with
nothing to redo when there is none.
Parameters: schema, level and context. Only schema is required.
Output keys: none.
Construct categories
The category of a Construct setting is one of these ids:
| Category | In the window |
|---|---|
quality |
Quality |
pathTracing |
Path tracing |
shading |
Shading |
environment |
Environment |
hdr |
HDR. Each tone mapper with parameters adds hdr/<tone mapper id> |
editorCamera |
Editor camera |
newCameras |
New cameras |
thisMachine |
This machine |
sceneDefaults |
Scene defaults |
thumbnails |
Thumbnails |
To find the id of a setting, use config.list with a filter, or show the
Id column in the settings window.