materialcraft
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseMaterialCraft
MaterialCraft
Operate MaterialCraft through its structured automation interface. Preserve the user's requested material workflow and target graph.
通过结构化的自动化接口操作 MaterialCraft。保留用户指定的材质工作流和目标图。
Protocol reference
协议参考
Read the relevant sections of references/control-protocol.md before constructing calls. This is the downloaded upstream protocol, captured on 2026-11-03.
Source: MaterialCraft control protocol.
Useful sections: the Methods table (which methods are headless-only vs app-only), Key commands, Function graphs, and Portable materials (TextureCraft). Relative links inside the downloaded document refer to upstream documentation; resolve them against when needed. The document lists key commands, not the full library of 227 nodes: discover node definitions and parameters at runtime with / instead of inventing IDs.
https://github.com/storytold/materialcraft/blob/main/docs/library.listcommand.list在构造调用前,阅读 references/control-protocol.md 的相关章节。这是下载的上游协议,捕获于 2026-11-03。
有用的章节包括:Methods 表(说明哪些方法仅支持 headless、哪些仅支持 app)、Key commands、Function graphs 和 Portable materials (TextureCraft)。下载文档中的相对链接指向上游文档;需要时,可基于 解析。该文档仅列出关键命令,并非完整的 227 个节点库:请在运行时通过 / 发现节点定义和参数,不要臆造 ID。
https://github.com/storytold/materialcraft/blob/main/docs/library.listcommand.listLocate the executables
定位可执行文件
materialcraftmaterialcraft-cliPATH- PATH: (POSIX) or
command -v materialcraft materialcraft-cli(Windows).where materialcraft materialcraft-cli - macOS: look for in
MaterialCraft.appand/Applications, or run~/Applications; the binary insidemdfind -name MaterialCraft.appis the desktop app.Contents/MacOS/ - Linux: AppImage, Flatpak, deb/rpm, or tarball installs; the CLI may be a separate download.
- Built from source: and
cargo run --release -p materialcraft.cargo run --release -p materialcraft-cli -- …
即使已安装 MaterialCraft, 和 也可能不在 中。不要在假定文件缺失前先进行发现,也绝不要臆造路径——请搜索:
materialcraftmaterialcraft-cliPATH- PATH: (POSIX)或
command -v materialcraft materialcraft-cli(Windows)。where materialcraft materialcraft-cli - macOS: 在 和
/Applications中查找~/Applications,或运行MaterialCraft.app;桌面应用的可执行文件位于mdfind -name MaterialCraft.app中。Contents/MacOS/ - Linux: 可能是 AppImage、Flatpak、deb/rpm 或 tarball 安装;CLI 也可能是单独下载的。
- 从源代码构建: 和
cargo run --release -p materialcraft。cargo run --release -p materialcraft-cli -- …
Select the session
选择会话
- For a user's open package or visible application, use a MaterialCraft MCP bridge () or the app's control channel (
materialcraft-cli mcp --bridge <port>). A headless session has its own in-process workspace and cannot edit the user's live window.materialcraft --control <port> - For unattended file processing, use headless MCP () or the JSON-lines server (
materialcraft-cli mcp --read-root DIR --write-root DIR), on stdio ormaterialcraft-cli servebehind a token.127.0.0.1:<port> - Discover available MaterialCraft tools and installed executables first. If the required connection or executable is missing, report the concrete prerequisite; creating this skill does not install MaterialCraft or register an MCP server.
The control channel requires an request first on every connection: token from or the file . Then one JSON object per line, ; match replies by and check . Set for scripted runs so the user's layout is left alone. Keep TCP on loopback and credentials in a private token file; do not print, commit, or expose tokens in command arguments.
authMATERIALCRAFT_CONTROL_TOKEN<temp>/materialcraft-control-<port>.token{"id", "method", "params"}idokMATERIALCRAFT_NO_PREFS=1- 对于用户已打开的 package 或当前可见的应用,使用 MaterialCraft MCP bridge()或应用的 control channel(
materialcraft-cli mcp --bridge <port>)。headless session 拥有自己的进程内工作区,无法编辑用户当前可见的窗口。materialcraft --control <port> - 对于无人值守的文件处理,使用 headless MCP()或 JSON-lines server(
materialcraft-cli mcp --read-root DIR --write-root DIR),可通过 stdio 或带 token 的materialcraft-cli serve运行。127.0.0.1:<port> - 首先发现可用的 MaterialCraft 工具和已安装的可执行文件。如果缺少必要的连接或可执行文件,请报告具体前置条件;创建此 skill 不会安装 MaterialCraft,也不会注册 MCP server。
control channel 要求每次连接时首先发送 请求:token 来自 或文件 。随后每行传输一个 JSON 对象,格式为 ;通过 匹配响应,并检查 。对于脚本化运行,请设置 ,以避免更改用户的布局。TCP 应仅绑定 loopback,凭据应保存在私有 token 文件中;不要打印、提交或在命令参数中暴露 token。
authMATERIALCRAFT_CONTROL_TOKEN<temp>/materialcraft-control-<port>.token{"id", "method", "params"}idokMATERIALCRAFT_NO_PREFS=1Inspect, edit, and verify
检查、编辑和验证
Inspect before editing: returns the package, graphs, the open graph's nodes (def, params, bindings, base, ports, cook error/size/mean/ms), wires, frames, exposed inputs, views, and history. In the app, adds the graph view rectangle, per-node screen rectangles, and per-port screen positions. Discover command and node IDs with and .
session.inspectui.inspectcommand.list {filter?}library.list {filter?, category?}Build graphs with (templates: , , , , , , , ), , / , and . Parameter values are typed: numbers, , , enum index, curve , gradient , or for a function graph driving a parameter (dynamic parameter; remove with ). Set per-node cook settings with .
file.new {template?, name?, size?}emptypbrbricksstone_tileswoodrusty_metalfabricgroundgraph.node.add {def, at?, params?, connectFrom?, label?}graph.connectgraph.disconnectgraph.node.param {id?, param, value}[x, y]"#rrggbb"[[x, y], …][[pos, color], …]{"t": "function", "v": {...}}{param, remove: true}graph.node.base {sizeMode?, size?, format?, seed?, tiling?}Commands run programmatically and never open dialogs. Use only when interactive menu behavior is intended. For UI gestures, applies synthetic events one frame at a time using window points taken from (, ): , , , , , , , (egui key names), .
ui.menu.invokeui.input {events}ui.inspectnodesportsmovedownupclickdoubleClickdragscrollkeytextVerify visually and structurally: re-run and check each node's cook error and mean output; render with (app) or (headless, PNG base64 — gives the beauty render with displacement, ray-traced AO and a shadowed key light). Use / commands to point the views at a specific node, channel, or scene; shows an OBJ/glTF/GLB mesh (scene ).
session.inspectview.screenshot {view: "3d"|"2d"}render {…}hq: trueview.2dview.3dview.3d.loadMesh {path}custom编辑前先检查: 返回 package、graphs、当前打开图中的 nodes(def、params、bindings、base、ports、cook error/size/mean/ms)、wires、frames、exposed inputs、views 和 history。在应用中, 还会提供图视图矩形、各节点的屏幕矩形以及各端口的屏幕位置。通过 和 发现 command 和 node ID。
session.inspectui.inspectcommand.list {filter?}library.list {filter?, category?}使用 构建图(模板:、、、、、、、)、、 / 以及 。参数值具有明确类型:number(数字)、、、enum index(枚举索引)、curve(曲线)、gradient(渐变),或用于驱动参数的 function graph(函数图)(dynamic parameter;使用 移除)。使用 设置各节点的 cook 配置。
file.new {template?, name?, size?}emptypbrbricksstone_tileswoodrusty_metalfabricgroundgraph.node.add {def, at?, params?, connectFrom?, label?}graph.connectgraph.disconnectgraph.node.param {id?, param, value}[x, y]"#rrggbb"[[x, y], …][[pos, color], …]{"t": "function", "v": {...}}{param, remove: true}graph.node.base {sizeMode?, size?, format?, seed?, tiling?}Command 均以编程方式运行,不会打开对话框。仅当需要交互式菜单行为时,才使用 。对于 UI 操作, 使用从 (、)获取的 window points,逐帧应用合成事件:、、、、、、、(egui key 名称)、。
ui.menu.invokeui.input {events}ui.inspectnodesportsmovedownupclickdoubleClickdragscrollkeytext从视觉和结构两方面进行验证:重新运行 ,并检查每个节点的 cook error 和 mean output;使用 (app)或 (headless,PNG base64—— 会生成包含 displacement、ray-traced AO 和 shadowed key light 的 beauty render)进行渲染。使用 / command 将视图指向特定 node、channel 或 scene; 可显示 OBJ/glTF/GLB mesh(scene 为 )。
session.inspectview.screenshot {view: "3d"|"2d"}render {…}hq: trueview.2dview.3dview.3d.loadMesh {path}customFile access and output
文件访问和输出
Headless file access is workspace-scoped by launch-time roots ( / ); use task-scoped roots and forward-slash relative paths within them. Do not bypass rejected paths by switching to ambient filesystem commands.
--read-root--write-root- Packages: /
package.open {path}(headless); the app saves through its own menus.package.save {path?}files open too (their source package, on its graph)..mcmat - Bitmaps: embeds an image as a resource.
bitmap.import {path, name?} - Texture maps: cooks at full size and writes every output — PNG, JPEG, TGA, TIFF, BMP, WEBP, EXR or HDR at 8, 16 or 32 bits.
outputs.export {dir, format?, pattern?, depth?, graph?} - Portable materials: writes a
file.exportMaterial {path, graph?, size?, values?, inputs?}for TextureCraft;.mcmatexports into TextureCraft's library folder. In the workspace sandbox, exporting afile.sendToTextureCraft {graph?}is CLI-only:.mcmat.materialcraft-cli run package.mcraft file.exportMaterial '{"path": "out.mcmat", "size": 2048}' - Report successful saves and exports with the exact output path and format. Do not overwrite the user's source package unless asked; save a copy under a new name.
headless 文件访问受启动时指定的 roots( / )限制,并限定在 workspace 范围内;请使用 task-scoped roots,以及其中使用 forward slash 的相对路径。不要改用常规文件系统命令来绕过被拒绝的路径。
--read-root--write-root- Packages:/
package.open {path}(headless);app 通过自身的菜单保存。package.save {path?}文件也可以打开(打开其 source package 及其 graph)。.mcmat - Bitmaps:将图像作为 resource 嵌入。
bitmap.import {path, name?} - Texture maps:会按完整尺寸进行 cook,并写入全部输出——PNG、JPEG、TGA、TIFF、BMP、WEBP、EXR 或 HDR,支持 8、16 或 32 位。
outputs.export {dir, format?, pattern?, depth?, graph?} - Portable materials:会写入供 TextureCraft 使用的
file.exportMaterial {path, graph?, size?, values?, inputs?};.mcmat会将其导出到 TextureCraft 的 library 文件夹。在 workspace sandbox 中,导出file.sendToTextureCraft {graph?}只能通过 CLI 完成:.mcmat。materialcraft-cli run package.mcraft file.exportMaterial '{"path": "out.mcmat", "size": 2048}' - 报告成功保存和导出的结果时,必须给出准确的输出路径和格式。除非用户明确要求,否则不要覆盖用户的 source package;应在新名称下保存副本。
Batches and uncertain outcomes
批处理和不确定结果
Use (headless) for known sequences; it stops at the first error. Batches are not transactions: earlier steps persist on failure, so inspect per-step results.
command.batch {steps}After a disconnect or any other unclear failure, run before retrying a mutation — the command may already have completed. Stop and report unresolved state if inspection cannot determine whether replay is safe.
session.inspect对于已知操作序列,使用 (headless);遇到第一个错误时即会停止。批处理不是 transaction:失败时,之前执行的步骤仍会保留,因此需要检查每一步的结果。
command.batch {steps}连接断开或发生其他不明确故障后,重试 mutation 前请先运行 ——该 command 可能已经执行完成。如果通过检查仍无法确定是否可以安全重放,请停止操作并报告未解决的状态。
session.inspect