Files
materialcraft/docs/architecture.md
T
bflatasticandClaude Opus 5.5 53ab0f2d6a Cross-app materials: .mcmat portable materials for TextureCraft
- formats: .mcmat (zip: material.json manifest, maps/<usage>.png, source.mcraft) with
  read/write and caps; color usages 8-bit sRGB, data maps 16-bit linear
- engine: file.exportMaterial {path, size?, values?, inputs?}, file.sendToTextureCraft
  (TextureCraft's library folder), graph.input.bind/unbind; file.open reads .mcmat
- core/eval: Graph::input_images preview images for input nodes (mesh maps from
  TextureCraft); caller images win; grayscale inputs convert to gray
- ui: File > Export material..., File > Send to TextureCraft, Open accepts .mcmat,
  input previews in the graph properties
- docs: control protocol (portable materials), file formats, gaps, parity ≈ 67%,
  roadmap, architecture, AGENTS convention for shared formats

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 12:06:09 +07:00

85 lines
5.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Architecture
> **Last reviewed:** 2026-11-02 · **Last updated:** 2026-11-02 · **Change:** minor (portable materials and TextureCraft) · **Target:** the professional node-based material workflow
MaterialCraft is a Cargo workspace of small crates in strict layers (`cargo xtask layers` enforces
them). Everything below the UI is plain Rust with no UI toolkit and builds for
`wasm32-unknown-unknown`.
```text
L0 core document model: Package → Graph → Node / Connection / Frame / Comment / Pin / ExposedParam;
Value (float, vectors, int, bool, color, enum, text, curve, gradient, function graph)
L0 image Image: grayscale or RGBA f32 planes behind an Arc (copy-on-write, free to share);
wrap/clamp sampling, bilinear, box/bilinear resampling, sRGB, 8-bit display
L0 geom meshes, primitives (rounded cube, sphere, cylinder, plane, torus, material ball), BVH, camera
L1 nodes the node library: NodeDef (ports, parameters, category, cook fn) for 227 nodes, the
tileable noise primitives, shared image ops (blur, EDT, HSL, blend modes) and the
function-graph compiler/evaluator for pixel and value processors
L2 eval cooking: topological order, output sizes (relative to input / parent, absolute, preview
cap), parameter resolution (defaults, overrides, bindings to exposed inputs), the
content-addressed LRU cache, graph instances (sub-graphs, recursion-guarded)
L2 formats .mcraft packages (zip: package.json + resources/), .mcmat portable materials, bitmap
decode, texture encode (PNG/JPEG/TGA/TIFF/BMP/WEBP/EXR/HDR at 8/16/32 bits), atomic writes
L3 engine Session (package, open graph, selection, 2D/3D view state, snapshot undo, cache),
the command registry, inspect, sample materials and graph templates
L3 render the 3D view: BVH ray casts, parallax occlusion from the height output, GGX PBR with
prefiltered IBL + SH diffuse, ACES tone mapping; procedural environments
L4 automation MCP server (rmcp), JSON-lines RPC (stdio/TCP with token), bridge client, workspace sandbox
L5 ui-egui the egui shell: docking (craft-ui), graph editor, library, properties, 2D/3D views,
dialogs, menus, control channel with synthetic input
apps materialcraft (desktop), materialcraft-cli, materialcraft-web
```
## Cooking
A node's cook is a pure function `fn(&Ctx) -> Result<Vec<Image>, String>`: `Ctx` carries the output
size, the seed, tiling, the inputs (by port order, `None` when unconnected), the resolved parameters,
a resource decoder and the graph's exposed values. `eval::cook` walks the graph in dependency order.
For each node it hashes the definition id, resolved parameters, size, seed, tiling, the keys of its
input images, resource bytes and (for instances) the sub-graph: equal keys hit the cache, so an edit
re-cooks only the nodes downstream of it, and undo finds earlier results again. A failing node shows
a magenta image and its error; nodes after it still cook.
Sizes: generators take the graph ("parent") size; filters take their main input's size; both can be
offset by powers of two or set absolutely. While editing, outputs are capped at the preview size
(512 px by default), with pixel-based parameters scaled by `w / 256` so previews and full-size
exports look the same. Exports cook at full size through the same cache.
The desktop UI cooks on a worker thread (`ui-egui/src/cook.rs`) from a snapshot of the package and
keeps drawing the last results; the browser cooks on the UI thread.
## Commands and automation
Every user-visible action is a `CommandSpec` (`engine/src/*_cmds.rs`): id, label, menu, shortcut,
params doc, `enabled`, `run`. The UI calls them through `MaterialCraftApp::run`; the CLI, the JSON
control channel and MCP dispatch the same ids. `Session::edit` snapshots the package before running
an edit and restores it on error; `edit_merged` folds repeated edits with the same key (a slider
drag) into one undo step. See [control-protocol.md](control-protocol.md).
## The UI
`MaterialCraftApp` owns the session and `UiState` (serde, persisted by eframe, readable and writable
through `ui.inspect` / `ui.set`). The dock (craft-ui) hosts eight panels around the protected graph
panel. The graph editor lays nodes out in graph space, draws cards with thumbnails from the cook
results (uploaded once per cache key), wires as cubic beziers between typed ports, and turns
gestures into commands only when they complete. The 3D view renders with `materialcraft-render`
on the CPU: half resolution while the camera moves, 2×2 supersampled when it rests.
`crates/ui-egui/tests/snapshot.rs` renders the real UI offscreen with egui_kittest + wgpu for visual
checks and README screenshots.
## Files
A `.mcraft` package is a zip: `package.json` (the serde `Package`, format version 1) and
`resources/<name>` for embedded bitmaps. Node parameters are stored only where they differ from the
catalog defaults, so new defaults reach old files and files stay small.
## Other apps
A `.mcmat` portable material (`formats/src/material.rs`, `engine/src/material_cmds.rs`) holds a
graph's cooked maps, its portable exposed inputs, presets and input nodes, and the source package.
TextureCraft paints with it and re-cooks it by running `materialcraft-cli run <package>
file.exportMaterial {path, size, values, inputs}`: the apps share the file format and the command
line, never code. Graphs keep preview images for their input nodes (`Graph::input_images`, mesh
maps from TextureCraft); `eval::cook` feeds them to the top-level graph, and a caller's images win.