materialcraft

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MaterialCraft

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.
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
https://github.com/storytold/materialcraft/blob/main/docs/
when needed. The document lists key commands, not the full library of 227 nodes: discover node definitions and parameters at runtime with
library.list
/
command.list
instead of inventing IDs.
在构造调用前,阅读 references/control-protocol.md 的相关章节。这是下载的上游协议,捕获于 2026-11-03。
有用的章节包括:Methods 表(说明哪些方法仅支持 headless、哪些仅支持 app)、Key commands、Function graphs 和 Portable materials (TextureCraft)。下载文档中的相对链接指向上游文档;需要时,可基于
https://github.com/storytold/materialcraft/blob/main/docs/
解析。该文档仅列出关键命令,并非完整的 227 个节点库:请在运行时通过
library.list
/
command.list
发现节点定义和参数,不要臆造 ID。

Locate the executables

定位可执行文件

materialcraft
and
materialcraft-cli
may not be on
PATH
even when MaterialCraft is installed. Discover them before assuming anything is missing, and never invent a path — search for it:
  1. PATH:
    command -v materialcraft materialcraft-cli
    (POSIX) or
    where materialcraft materialcraft-cli
    (Windows).
  2. macOS: look for
    MaterialCraft.app
    in
    /Applications
    and
    ~/Applications
    , or run
    mdfind -name MaterialCraft.app
    ; the binary inside
    Contents/MacOS/
    is the desktop app.
  3. Linux: AppImage, Flatpak, deb/rpm, or tarball installs; the CLI may be a separate download.
  4. Built from source:
    cargo run --release -p materialcraft
    and
    cargo run --release -p materialcraft-cli -- …
    .
即使已安装 MaterialCraft,
materialcraft
和
materialcraft-cli
也可能不在
PATH
中。不要在假定文件缺失前先进行发现,也绝不要臆造路径——请搜索:
  1. PATH:
    command -v materialcraft materialcraft-cli
    (POSIX)或
    where materialcraft materialcraft-cli
    (Windows)。
  2. macOS: 在
    /Applications
    和
    ~/Applications
    中查找
    MaterialCraft.app
    ,或运行
    mdfind -name MaterialCraft.app
    ;桌面应用的可执行文件位于
    Contents/MacOS/
    中。
  3. Linux: 可能是 AppImage、Flatpak、deb/rpm 或 tarball 安装;CLI 也可能是单独下载的。
  4. 从源代码构建:
    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 (
    materialcraft-cli mcp --bridge <port>
    ) or the app's control channel (
    materialcraft --control <port>
    ). A headless session has its own in-process workspace and cannot edit the user's live window.
  • For unattended file processing, use headless MCP (
    materialcraft-cli mcp --read-root DIR --write-root DIR
    ) or the JSON-lines server (
    materialcraft-cli serve
    ), on stdio or
    127.0.0.1:<port>
    behind a token.
  • 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
auth
request first on every connection: token from
MATERIALCRAFT_CONTROL_TOKEN
or the file
<temp>/materialcraft-control-<port>.token
. Then one JSON object per line,
{"id", "method", "params"}
; match replies by
id
and check
ok
. Set
MATERIALCRAFT_NO_PREFS=1
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.
  • 对于用户已打开的 package 或当前可见的应用,使用 MaterialCraft MCP bridge(
    materialcraft-cli mcp --bridge <port>
    )或应用的 control channel(
    materialcraft --control <port>
    )。headless session 拥有自己的进程内工作区,无法编辑用户当前可见的窗口。
  • 对于无人值守的文件处理,使用 headless MCP(
    materialcraft-cli mcp --read-root DIR --write-root DIR
    )或 JSON-lines server(
    materialcraft-cli serve
    ),可通过 stdio 或带 token 的
    127.0.0.1:<port>
    运行。
  • 首先发现可用的 MaterialCraft 工具和已安装的可执行文件。如果缺少必要的连接或可执行文件,请报告具体前置条件;创建此 skill 不会安装 MaterialCraft,也不会注册 MCP server。
control channel 要求每次连接时首先发送
auth
请求:token 来自
MATERIALCRAFT_CONTROL_TOKEN
或文件
<temp>/materialcraft-control-<port>.token
。随后每行传输一个 JSON 对象,格式为
{"id", "method", "params"}
;通过
id
匹配响应,并检查
ok
。对于脚本化运行,请设置
MATERIALCRAFT_NO_PREFS=1
,以避免更改用户的布局。TCP 应仅绑定 loopback,凭据应保存在私有 token 文件中;不要打印、提交或在命令参数中暴露 token。

Inspect, edit, and verify

检查、编辑和验证

Inspect before editing:
session.inspect
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,
ui.inspect
adds the graph view rectangle, per-node screen rectangles, and per-port screen positions. Discover command and node IDs with
command.list {filter?}
and
library.list {filter?, category?}
.
Build graphs with
file.new {template?, name?, size?}
(templates:
empty
,
pbr
,
bricks
,
stone_tiles
,
wood
,
rusty_metal
,
fabric
,
ground
),
graph.node.add {def, at?, params?, connectFrom?, label?}
,
graph.connect
/
graph.disconnect
, and
graph.node.param {id?, param, value}
. Parameter values are typed: numbers,
[x, y]
,
"#rrggbb"
, enum index, curve
[[x, y], …]
, gradient
[[pos, color], …]
, or
{"t": "function", "v": {...}}
for a function graph driving a parameter (dynamic parameter; remove with
{param, remove: true}
). Set per-node cook settings with
graph.node.base {sizeMode?, size?, format?, seed?, tiling?}
.
Commands run programmatically and never open dialogs. Use
ui.menu.invoke
only when interactive menu behavior is intended. For UI gestures,
ui.input {events}
applies synthetic events one frame at a time using window points taken from
ui.inspect
(
nodes
,
ports
):
move
,
down
,
up
,
click
,
doubleClick
,
drag
,
scroll
,
key
(egui key names),
text
.
Verify visually and structurally: re-run
session.inspect
and check each node's cook error and mean output; render with
view.screenshot {view: "3d"|"2d"}
(app) or
render {…}
(headless, PNG base64 —
hq: true
gives the beauty render with displacement, ray-traced AO and a shadowed key light). Use
view.2d
/
view.3d
commands to point the views at a specific node, channel, or scene;
view.3d.loadMesh {path}
shows an OBJ/glTF/GLB mesh (scene
custom
).
编辑前先检查:
session.inspect
返回 package、graphs、当前打开图中的 nodes(def、params、bindings、base、ports、cook error/size/mean/ms)、wires、frames、exposed inputs、views 和 history。在应用中,
ui.inspect
还会提供图视图矩形、各节点的屏幕矩形以及各端口的屏幕位置。通过
command.list {filter?}
和
library.list {filter?, category?}
发现 command 和 node ID。
使用
file.new {template?, name?, size?}
构建图(模板:
empty
、
pbr
、
bricks
、
stone_tiles
、
wood
、
rusty_metal
、
fabric
、
ground
)、
graph.node.add {def, at?, params?, connectFrom?, label?}
、
graph.connect
/
graph.disconnect
以及
graph.node.param {id?, param, value}
。参数值具有明确类型:number(数字)、
[x, y]
、
"#rrggbb"
、enum index(枚举索引)、curve(曲线)
[[x, y], …]
、gradient(渐变)
[[pos, color], …]
,或用于驱动参数的 function graph(函数图)
{"t": "function", "v": {...}}
(dynamic parameter;使用
{param, remove: true}
移除)。使用
graph.node.base {sizeMode?, size?, format?, seed?, tiling?}
设置各节点的 cook 配置。
Command 均以编程方式运行,不会打开对话框。仅当需要交互式菜单行为时,才使用
ui.menu.invoke
。对于 UI 操作,
ui.input {events}
使用从
ui.inspect
(
nodes
、
ports
)获取的 window points,逐帧应用合成事件:
move
、
down
、
up
、
click
、
doubleClick
、
drag
、
scroll
、
key
(egui key 名称)、
text
。
从视觉和结构两方面进行验证:重新运行
session.inspect
,并检查每个节点的 cook error 和 mean output;使用
view.screenshot {view: "3d"|"2d"}
(app)或
render {…}
(headless,PNG base64——
hq: true
会生成包含 displacement、ray-traced AO 和 shadowed key light 的 beauty render)进行渲染。使用
view.2d
/
view.3d
command 将视图指向特定 node、channel 或 scene;
view.3d.loadMesh {path}
可显示 OBJ/glTF/GLB mesh(scene 为
custom
)。

File access and output

文件访问和输出

Headless file access is workspace-scoped by launch-time roots (
--read-root
/
--write-root
); use task-scoped roots and forward-slash relative paths within them. Do not bypass rejected paths by switching to ambient filesystem commands.
  • Packages:
    package.open {path}
    /
    package.save {path?}
    (headless); the app saves through its own menus.
    .mcmat
    files open too (their source package, on its graph).
  • Bitmaps:
    bitmap.import {path, name?}
    embeds an image as a resource.
  • Texture maps:
    outputs.export {dir, format?, pattern?, depth?, graph?}
    cooks at full size and writes every output — PNG, JPEG, TGA, TIFF, BMP, WEBP, EXR or HDR at 8, 16 or 32 bits.
  • Portable materials:
    file.exportMaterial {path, graph?, size?, values?, inputs?}
    writes a
    .mcmat
    for TextureCraft;
    file.sendToTextureCraft {graph?}
    exports into TextureCraft's library folder. In the workspace sandbox, exporting a
    .mcmat
    is CLI-only:
    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(
--read-root
/
--write-root
)限制,并限定在 workspace 范围内;请使用 task-scoped roots,以及其中使用 forward slash 的相对路径。不要改用常规文件系统命令来绕过被拒绝的路径。
  • Packages:
    package.open {path}
    /
    package.save {path?}
    (headless);app 通过自身的菜单保存。
    .mcmat
    文件也可以打开(打开其 source package 及其 graph)。
  • Bitmaps:
    bitmap.import {path, name?}
    将图像作为 resource 嵌入。
  • Texture maps:
    outputs.export {dir, format?, pattern?, depth?, graph?}
    会按完整尺寸进行 cook,并写入全部输出——PNG、JPEG、TGA、TIFF、BMP、WEBP、EXR 或 HDR,支持 8、16 或 32 位。
  • Portable materials:
    file.exportMaterial {path, graph?, size?, values?, inputs?}
    会写入供 TextureCraft 使用的
    .mcmat
    ;
    file.sendToTextureCraft {graph?}
    会将其导出到 TextureCraft 的 library 文件夹。在 workspace sandbox 中,导出
    .mcmat
    只能通过 CLI 完成:
    materialcraft-cli run package.mcraft file.exportMaterial '{"path": "out.mcmat", "size": 2048}'
    。
  • 报告成功保存和导出的结果时,必须给出准确的输出路径和格式。除非用户明确要求,否则不要覆盖用户的 source package;应在新名称下保存副本。

Batches and uncertain outcomes

批处理和不确定结果

Use
command.batch {steps}
(headless) for known sequences; it stops at the first error. Batches are not transactions: earlier steps persist on failure, so inspect per-step results.
After a disconnect or any other unclear failure, run
session.inspect
before retrying a mutation — the command may already have completed. Stop and report unresolved state if inspection cannot determine whether replay is safe.
对于已知操作序列,使用
command.batch {steps}
(headless);遇到第一个错误时即会停止。批处理不是 transaction:失败时,之前执行的步骤仍会保留,因此需要检查每一步的结果。
连接断开或发生其他不明确故障后,重试 mutation 前请先运行
session.inspect
——该 command 可能已经执行完成。如果通过检查仍无法确定是否可以安全重放,请停止操作并报告未解决的状态。