IlluGen

Adds a comment to the node graph: a framed group around nodes, or a free text note. Annotations only document the graph; they do not change the rendered result. Writes the project file in place. Returns {"group": index} or {"note": index}, the index to pass to annotation_remove.

Deletes one group or note annotation from the node graph. The indexes of later annotations of the same kind shift down by one: re-read project_summary before removing another. Fails if the index does not exist. Writes the project file in place. Returns {"ok": true}.

Replaces all the keys of a node's curve (remap curves, custom oscillator waveforms...). The previous keys are discarded. Writes the project file in place. Returns: curve (name written) and keys (number of keys).

Describes one node type: its parameters, curves and typed input/output pins. Call it before node_add or node_set to get valid parameter names, value kinds, defaults, enum values and UI ranges, and before link_add to get pin names and the data kind each pin carries. Offline and read-only. Pin kinds: Grayscale, Color, UV, Normal, Islands, GeometryBuffer...; 'Inherit' takes the kind of whatever is connected; 'Signal' is a modulator (Oscillator, Cycle, Constant...). Returns: type, category, params {name: {kind, default, values for enums, min/max, label, modulatable}}, curves, pins {inputs, outputs, optional_inputs} and parameter_pins {pin name: parameter it drives when a Signal is linked to it, e.g. 'Scale', 'Seed'}. An unknown type fails with close-match suggestions.

Replaces a node's color gradient (Color Ramp, Color Interpolate, Geometry Combine Color...). The previous stops are discarded. Fails if the node has no gradient. Writes the project file in place. Returns: stops (number written) and color_space.

Reports whether IlluGen is installed and which node catalog this server uses. Call it first when an engine tool (project_render, project_validate with engine=true, project_screenshot, project_normalize) fails, or to find the folder of the shipped presets. Takes no arguments, does not start IlluGen and changes nothing. Returns: exe (path used, set with the ILLUGEN_EXE variable), installed (bool), running_instances (IlluGen processes currently open, GUI ones included), catalog_illugen_version and node_types (IlluGen version and node count of the bundled catalog), presets_dir.

Connects an output pin of one node to an input pin of another. Any existing connection into that input is replaced. Pin data kinds are checked (Grayscale, Color, UV...) and a mismatch fails with an explanation. Parameter pins (e.g. 'Scale', 'Seed') let a Signal node (Oscillator, Cycle, Constant...) drive a parameter; optional inputs (e.g. Levels 'In Low mod') are exposed automatically. Subgraph pins are the labels of the subgraph's inner Node_Input/Node_Output nodes. Writes the project file in place. Returns: link {from_node, from_pin, to_node, to_pin} and warnings if any.

Disconnects an input pin: removes the link(s) arriving at `to_pin` of `to_node`. Writes the project file in place. If the pin drove a parameter, the parameter gets a fixed value again (its default if it had none). Removing nothing is not an error. node_get lists a node's incoming links. Returns: removed, the number of links deleted (0 if the pin was not connected).

Lists the IlluGen node types this server can create, grouped by category. Use it to find a type name for node_add, then describe_node_type for that type's parameters and pins. Offline (IlluGen not needed) and read-only. Returns {category: [type names]}, e.g. {"Grayscale": ["Node_Grayscale_Noise", ...]}; an empty object means nothing matched the filters.

Lists the example projects shipped with IlluGen, usable as starting points. Pass a returned name to project_new(from_preset=...) to get an editable copy; the presets themselves are never modified. Read-only; reads the presets folder of the installed IlluGen. Returns [{name, path}], sorted by name. The list is empty when nothing matches or when IlluGen is not found (check illugen_status).

Adds a node to the graph with IlluGen's default values, optionally setting some parameters. Writes the project file in place. Parameter values are checked: an unknown name or invalid enum value fails with suggestions and nothing is saved; a value outside the UI range is kept and reported in warnings. Connect the new node with link_add afterwards. Returns: id (string id of the new node), type, and warnings if any.

Returns every detail of one node: parameter values, curves, gradients, spline points, pins and links. Use it before node_set, curve_set, gradient_set, spline_set or node_set_data to see current values and exact names; use project_summary for the whole graph. Offline and read-only. Returns: id, type, label, pos, disabled, params {name: value} ('<driven by link>' when a Signal drives it), curves {name: [[position, value], ...]}, gradients, spline_points, subgraph pins for subgraphs, parameter_pins, outgoing and incoming links, known_inputs and known_outputs.

Deletes a node from the graph, with its outgoing links and every link from other nodes into it. Writes the project file in place and cannot be undone: copy the file first if you may need the node back. To bypass a node without losing it, use node_set(disabled=true) instead. Returns: removed_links, the number of links from other nodes that pointed to the deleted node.

Changes an existing node's parameter values, label, position or disabled flag. Only what you pass changes. Writes the project file in place; values are checked like in node_add. For curves, gradients and spline points use curve_set, gradient_set and spline_set. Returns: changed {name: new value} and warnings (value outside the UI range, or parameter currently driven by a link, in which case the value only applies once unlinked).

Low-level escape hatch: overwrites one raw field of a node's internal data block. Use it only for fields that node_set, curve_set, gradient_set and spline_set do not cover. The value is written without type checking, so run project_validate(engine=true) afterwards. Writes the project file in place. Returns {"ok": true}.

Creates a new .illugen project file, blank or copied from a preset or another project. Start every new graph here, then add nodes with node_add. Writes only the file at `path`; the copied preset or project is left untouched, and a copied preset is made editable. Returns the new file's path plus its summary (same shape as project_summary).

Loads the project in a private, invisible IlluGen and saves it back in place, the way IlluGen writes it. Fills in every default value, applies IlluGen's own fixes and refreshes the embedded thumbnail. Use it before sharing a project built with this server, or to update a project made with an older IlluGen. Overwrites the project file; a copy of the original is kept as <name>.illugen.bak (replacing any previous one). Needs IlluGen installed. Returns: path, backup (path of the .bak copy), log_issues from IlluGen and node_count.

Renders the project with the real IlluGen: runs the export of every enabled Node_Export_* node. IlluGen runs as a private, invisible instance (an IlluGen open on screen is not affected). The project file itself is not modified; image files are written to output_dir or to the export nodes' folders, overwriting files with the same names. Needs IlluGen installed and at least one enabled export node. Run project_validate first when the graph is new. Returns: a result {ok, items_written, seconds, files (written paths), exports (settings of each export node), log_issues} followed by a preview image. On failure: {ok: false, error, log_issues, hint} plus screenshots of IlluGen's error dialogs.

Opens the project in a private, invisible IlluGen and returns a screenshot of its window. Shows the viewport and the node graph with each node's live preview: use it to check visually what a graph does, or to see why a render fails. Use project_render to produce the actual image files. Works on a temporary copy, so the project file is not modified. Needs IlluGen installed; takes a few seconds. Returns {path} and a PNG image.

Changes project-wide settings: frame rate, animation loop region and default texture size. Only the values you pass change; omitted ones are kept. Applies to the whole project (top-level graph and subgraphs). Writes the project file in place. The resolution of an individual export is set on its export node with node_set. Returns the resulting settings, same shape as project_summary.settings.

Gives an overview of a project: its nodes, links, export settings, annotations and main settings. Use it to get node ids before node_get, node_set or link_add, and to check the graph after edits; use node_get for every value of a single node. Offline and read-only. Returns: path, graph (scope shown), app_version, settings (frames_per_second, loop_region, default texture size...), annotations {groups, notes} in index order, node_count and nodes [{id, type, label, pos, links going out of the node, export settings for Node_Export_* nodes, subgraph_nodes for subgraphs}].

Returns the preview image IlluGen embedded in the project file at its last save. Instant and offline (IlluGen not needed), but it can be outdated or missing for a project edited only through this server: project_normalize refreshes it, project_screenshot and project_render show the current state. Read-only. Returns a JPEG image, or {thumbnail: null, hint} when the file has none.

Checks a project for problems before rendering it. Offline checks: unknown node types, unknown parameters, dangling links, missing export node. `legacy_params` (informational) lists parameters of older project versions, such as the shipped presets, that IlluGen renames or ignores on load. With engine=true, it also loads and re-saves a temporary copy in an invisible IlluGen, runs a trial export, and reports what the real loader dropped (nodes, links), serialization errors from its log and a screenshot of any load-issue dialog. The project file is never modified. Returns: a report {ok, offline_issues, legacy_params, and with engine: dropped_nodes, dropped_links, trial_export, engine_log_issues, load_dialog} followed by any screenshots.

Replaces the control points of a spline, sweep, point-shape or lattice node. Points are chained in order unless `edges` is given. The previous points are discarded. Fails if the node has no spline or lattice points. Writes the project file in place. Returns: points (number written) and edges (number of segments, when applicable).

Shows a parameter of a node inside a subgraph on the subgraph node itself, so it can be tweaked from outside. To build a subgraph: node_add('Subgraph'), then node_add and link_add with graph=<subgraph id> to add a Node_Input (its label becomes an input pin name), the inner nodes and a Node_Output (its label becomes an output pin name). Writes the project file in place. Returns: id of the exposed parameter, node_id, param_name and label.