Files
materialcraft/docs/architecture.md
T

8.4 KiB
Raw Blame History

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.

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   .sbs packages (the main format, sbs.rs), .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, the height output displacing a subdivided mesh, GGX PBR with
              prefiltered IBL + SH diffuse, alpha transparency (layered ray compositing) and an
              alpha channel view, 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 2D toolbar and the 3D view's Display menu expose the shared preview limit (256, 512, 1024, 2048 or 4096 px, or Full size). This is a cap, so a 4K preview requires a graph/node configured for 4096 px or larger. Both controls run view.previewSize and persist the choice in preferences; control-channel calls to the same command also retain their size across UI frames. The 3D view uses those cooked maps, while its rendered frame follows the panel's physical pixel dimensions. If the device supports smaller textures than the cooked image, the 2D view reduces only the uploaded texture to that limit; source pixels, readout and screenshots retain the cooked size.

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.

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 (hit-tested against the curve, so wires can be selected, deleted, swapped or split with a reroute dot), and turns gestures into commands only when they complete. See wires-and-alpha.md. 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.

The properties panel builds every parameter editor from the node catalog; the Levels node adds a histogram editor with range handles on top of its sliders (levels-editor.md).

Function math includes pow2 (2 raised to each input component), log2 (base-2 logarithm per component), and cartesian (scalar radius, then angle in radians, returning [radius * cos(angle), radius * sin(angle)]). They are entries in function::FN_OPS, so the function editor and the existing graph.node.param / graph.node.function commands use the same CPU evaluator. Nonpositive logarithm inputs and nonfinite results return zero; Cartesian returns zero for nonfinite inputs. These primitives extend the native function library; importing SBS function graphs remains a separate gap.

Files

SBS (.sbs, formats/src/sbs.rs) is the main project format: XML with the package's graphs, nodes, wires, parameters, graph inputs and outputs, frames and comments, and bitmaps embedded as zlib/base64 data. MaterialCraft writes the SBS data plus, in a trailing XML comment, its own exact copy of the package with a hash of the <content> it belongs to; reading uses the exact copy while the hash matches (so nothing MaterialCraft-specific is lost) and the SBS data otherwise. Reading never fails on what MaterialCraft lacks: atomic filters map to atomic nodes, library nodes map by name, instances of graphs in the same file become graph instances, and anything else becomes a missing_node placeholder (core::MISSING_NODE) that keeps its ports, wires and raw SBS parameters, cooks to a soft error, and is written back unchanged. Every gap is a warning in Session::load_warnings, the Console (Session::warn) and session.inspect (package.warnings). Bitmaps an SBS file keeps next to it load from its folder only (file_cmds::linked_files).

A .mcraft package (the older format, still read and written: packages opened from a .mcraft save back to it) 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.