Save files and export results

Save page results as files or return them to Blender, using the correct interface for each task.

Saving to disk and writing back to Blender are separate

Saving outputs text, images, or data to a user-selected destination. Blender writeback passes results to add-on logic to update images, materials, or other data. A visible canvas effect or saved file does not prove Blender nodes changed.

Start with a text file

First follow File helper loading order Load Resource IO. Put this function in an external script and call it from a user button. output is an existing status element.

Complete text-save handler

javascript

async function saveNotes(output) {
  try {
    const webui = window.acquireNexusWebUI();
    const bytes = new TextEncoder().encode("我的创作记录");
    const result = await webui.resourceIO.saveFile(bytes, {
      name: "notes.txt", mime: "text/plain"
    });
    output.textContent = result.cancelled ? "已取消保存。"
      : result.ok ? `已保存：${result.fileName}`
      : `保存失败：${result.message || "请检查保存位置。"}`;
  } catch (error) {
    output.textContent = `保存请求失败：${error.message || String(error)}`;
  }
}

Images, data, and batch saves

Result	Tools
Plain text	saveText, or encode and use saveFile.
Structured data	saveJSON; data must remain JSON-compatible.
Canvas image	saveCanvas; ensure rendering is complete and exportable.
Multiple files	saveFiles returns per-item results. Count success, cancellation, and failure separately.
Ordinary download link	Load nexus-download-takeover.js to handle links with the download attribute.

Do not declare batch success from the first item. Reuse directories through the public directory picker and destination references, not guessed local paths.

Name conflicts do not automatically confirm overwrite

Save results may contain name_conflict. Currently both confirm and error fail on conflicts without an extra host overwrite dialog. Ask users to overwrite, rename, or cancel, then use the public conflict option. Never silently overwrite existing files.

Cancelling returns a cancelled result; application failures may return ok:false normally. catch alone does not handle these outcomes.

When writing back to the scene

Send processed content as an attachment to a registered action.
Receive the one-time resource in Python and validate format and target.
Invoke existing image or scene-write logic and return the actual result.
Invalidate affected state and show application results, not merely upload completion.

For temporary-file lifetimes, see Returning resources. The website's texture studio remains a simulation; verify real writeback in Blender.

Open actual exported files before delivery

Verify filename, type, content, and size.
Cancellation neither reports success nor discards current work.
Name conflicts, read-only destinations, and per-item failures show accurate results.
Verify actual scene objects and nodes separately; saved files are not a substitute.

Based on file-interaction guidance and public save types.

Back to User guide · All topics