README, AGENTS, ATTRIBUTION, roadmap and docs; web app; icons

The README in the Crafting Apps frame with real screenshots and renders made
by MaterialCraft, the agent guide with the asset and clean-room rules, the
attribution list, the parity assessment, gaps, roadmap, architecture,
control protocol, localization and file format docs. Adds the browser build
(trunk), the .ico/.icns icons and centers the 3D camera on the mesh bounds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
bflatasticandClaude Opus 5.5 committed 2026-11-02 04:04:13 +07:00
1 parent 2648fd0334
commit 54fc5b9571
31 files changed
+1434 -5

No files matched your search

+182
View File
@@ -0,0 +1,182 @@
# AGENTS.md: guide for AI agents and contributors
MaterialCraft is an open-source, native **node-based procedural material designer**: a clean-room
implementation of the workflow professional material artists know from industry-standard node
graph tools, written in **Rust only** (no JavaScript or TypeScript). **No Tauri, Electron or
webview shells:** the desktop app is native egui/eframe on wgpu, and the web build is the same Rust
compiled to WebAssembly (trunk + wasm-bindgen). Never add Tauri (or any webview/JS UI framework) as
a dependency, build step or packaging target.
The product name is always written **MaterialCraft** (`{Function}Craft` in PascalCase, like its
siblings PhotoCraft, VectorCraft, FilmCraft, LightCraft, PdfCraft, EffectCraft, DesignCraft,
TextureCraft) in user-facing text: UI, window titles, About, installers, release names, docs prose.
Machine names stay lowercase: crates (`materialcraft-*`), binaries, file names, ids
(`ai.storyteller.materialcraft`), the native package extension `.mcraft`.
Standards and learnings shared across the crafting apps live in `../craftrules` (checked out next
to this repo, or `storytold/craftrules`). Read its `AGENTS.md` at the start of a session, follow its
standards, and contribute reusable learnings back there. Shared code goes only in craft-libs
(`standards/shared-libraries.md`); otherwise copy, don't depend. TextureCraft is the sibling this
repository's infrastructure (xtask, automation, packaging, docking, theme) was copied from.
The goal is full parity with the professional node-based material workflow (the same panels,
menus, node library, parameters, shortcuts and file conventions) with better performance, every
feature drivable by agents, and builds for Windows, macOS, Linux, FreeBSD and the web. Read this
file first, then `docs/`.
## 1. Orientation (5 minutes)
| Read | Why |
|---|---|
| `docs/architecture.md` | Crate map, layers, the CPU cook engine and cache, data flow |
| `docs/control-protocol.md` | The JSON control channel, synthetic input and MCP: how agents drive the app |
| `ROADMAP.md` | Honest parity estimate, milestones, **current focus** |
| `docs/target-app-parity.md` | The parity assessment by area |
| `docs/gaps.md` | Every known shortfall, ranked: the work list |
| `ATTRIBUTION.md` | Every bundled asset with author, source, license |
## 2. Workspace map
```text
crates/
core image geom L0 document model (package, graphs, nodes, values, function graphs); float images; meshes, BVH, camera
nodes L1 the node library: definitions + CPU cooks (atomic nodes, noises, patterns, filters, PBR utilities, function evaluator)
eval formats L2 graph cooking (topological order, sizes, content-addressed cache, sub-graphs); .mcraft packages, bitmaps, texture export
engine render L3 Session + command registry (every action is a command), inspect, samples; the 3D preview renderer (CPU PBR + IBL)
automation L4 MCP server + headless JSON-lines RPC + bridge to the running app
ui-egui L5 egui shell (thin: every edit goes through engine commands)
apps/
materialcraft desktop app (eframe/wgpu), `--control <port>` loopback control server
materialcraft-cli headless CLI (info, run, batch, new, cook, export, render, nodes, commands, mcp, serve)
materialcraft-web the same app in the browser (trunk + wasm-bindgen)
xtask/ cargo xtask layers | wasm | ci | version | ico | icns
```
**Layering is enforced** by `cargo xtask layers`: a crate may depend only on lower layers. Nothing
below `ui-egui` may use egui, eframe, winit or rfd; only `render`, `ui-egui` and the apps may use
wgpu. A new crate must be registered in `xtask/src/layers.rs`.
**The UI crate is swappable.** `materialcraft-ui-egui` holds no document logic: it calls engine
commands (`materialcraft_engine::execute`). Another front end could replace it without touching
the engine.
## 3. Golden rules
### Never name the reference product (absolutely essential)
- The repository never names the commercial product MaterialCraft is modeled on, nor its vendor,
in code, comments, docs, commit messages, test names, file names or UI text. Say "the reference
app", "the professional node-based material workflow" or describe the feature itself.
- Notes that name it may live only in the gitignored `plan/` folder.
### Assets, icons and images (absolutely essential)
- **Never use any icon, image, logo, texture, material, sample graph, preset, environment, font or
other asset from Adobe, Avid, Figma, Autodesk or any other commercial product**, and never copy
files from an installed commercial application (its package files, compiled material archives,
presets, sample graphs, HDR environments, UI icons). Not as reference files in the repo either.
- Every image or icon must be **open source, public domain, Creative Commons (CC0/CC-BY), or
original** (made by a contributor who has the right to license it). Prefer generating content in
code: MaterialCraft's noises, patterns, sample materials, environments, library previews and
template thumbnails are all procedural.
- **Every bundled asset gets a row in [`ATTRIBUTION.md`](ATTRIBUTION.md)** (path, title, author,
source, license) **in the same change that adds it**, plus its license file next to it when the
license requires one. Assets compiled in through dependencies (icon fonts, default fonts) get a
row too. No row, no merge.
- Demo images and README screenshots show MaterialCraft rendering original procedural content
only. Never personal photos.
- The ArtCraft logos in `docs/brand/` are not open source (`docs/brand/LICENSE-brand.txt`).
- Fonts live in [storytold/craft-fonts](https://github.com/storytold/craft-fonts); never commit font
files here.
### Clean room
MaterialCraft is an independent, clean-room implementation of a node-based procedural material
workflow. Work from public documentation, general domain knowledge and public algorithms (Perlin
and simplex gradient noise, Worley/cellular noise, fractal sums, Gaussian and box blurs,
Felzenszwalb–Huttenlocher distance transforms, Sobel/central-difference normals, reoriented normal
mapping, HSL, levels, monotone cubic curves, W3C blend modes, GGX/Smith/Schlick PBR, split-sum IBL,
ACES fitted tone mapping). Never copy proprietary code, shaders, node implementations, presets or
file formats; compatibility with the reference app's package formats is a non-goal. Always describe
MaterialCraft as a clean-room implementation, in code, docs and commits.
### Never crash (outranks feature work)
People trust MaterialCraft with hours of work. A malformed package, a hostile command or MCP
parameter, an odd keystroke or a full disk must produce an error the user or agent can act on,
never a panic. The shared standard is `../craftrules/standards/never-crash.md`.
- Non-test code never panics: no `unwrap()`, `expect()`, `panic!`, `unreachable!`, `todo!` or
`unimplemented!`. Every production crate root carries
`#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]`.
- No `unsafe` (`unsafe_code = "forbid"` for the workspace).
- Input-derived numbers are hostile: `get()` instead of `[i]`, checked/saturating arithmetic, caps
on allocations (image sizes are clamped to 8192, zip entries capped), NaN guards.
- Every crash fix comes with a regression test. The engine's `panic_hunt` test runs every command
with hostile params, and the node library's `every_node_cooks` test cooks every node with no
inputs and with odd-sized inputs; keep both green.
### Architecture rules
1. **Everything is a command.** New user-visible behaviour = a command in the engine
(`crates/engine/src/*_cmds.rs`, registered in `commands.rs`) with id, label, menu path, shortcut,
params doc, `enabled` and `run`, plus tests. The menus, shortcuts, CLI, control channel and MCP
all dispatch commands by id. Menu items come from the catalog in `crates/ui-egui/src/menus.rs`.
2. **Every node is a catalog entry.** A new node is a `NodeDef` (ports, parameters with defaults and
ranges, library category, description) and a pure cook function in `crates/nodes`. It tiles
(whole-number lattice scales), works at any size, scales pixel-based parameters by `w / 256`,
and needs no new UI code: the library, the properties panel and the search pick it up.
3. **Programmatic calls never open dialogs.** A command run through the control channel or MCP runs
with defaults; only `ui.menu.invoke` behaves like a menu click.
4. **Inspect shows the agent's work.** `session.inspect` must reveal every node, parameter, wire,
cook error, size and mean value an agent changed.
5. **CPU oracle first.** Nodes cook on the CPU (rayon) through a content-addressed cache, so every
node is testable and identical in the app, the CLI, MCP and the browser. Any GPU acceleration
must match the CPU cook in parity tests.
6. **Undo is snapshots.** `Session::edit` clones the package and restores it on error, so every
command is atomic; `edit_merged` folds a slider drag into one step.
7. **Never break wasm.** L0–L5 must `cargo check --target wasm32-unknown-unknown`
(`cargo xtask wasm`). File-system code is `cfg(not(target_arch = "wasm32"))` with byte-based
alternatives.
8. **Performance is a feature.** Edits re-cook only what lies downstream (the cache). Cooking runs
on a worker thread; the UI never blocks on it. Benchmark heavy nodes in release.
9. **Verify UI changes visually.** `MC_SNAPSHOT_DIR=<dir> cargo test -p materialcraft-ui-egui
--release --test snapshot -- --ignored` renders the real UI offscreen; look at the PNGs.
## 4. Picking work
1. `ROADMAP.md` → **Current focus** and the parity table.
2. `docs/gaps.md` → the ranked list of shortfalls.
3. Render snapshots of MaterialCraft and fix the biggest visible gaps in the workflow.
4. `log/devlog.md` (local) → the "Still open" bullets of recent entries.
## 5. Before you finish a task
```sh
cargo fmt --all
cargo test -p <crates you touched> --release
cargo clippy --workspace --all-targets -- -D warnings
cargo xtask layers
cargo xtask wasm # if you touched L0–L5
cargo test -p materialcraft-engine --release --test session panic_hunt # if you added/changed commands
```
Then append a terse entry to `log/devlog.md` (what landed, numbers, what's still open). Commit
after every arc of work that builds and passes.
## 6. Parallel agents
- Use your own target dir (`CARGO_TARGET_DIR=target/agent-<name>`) and edit only the files you own.
Shared files (`engine/src/commands.rs`, `nodes/src/catalog.rs`, `ui-egui/src/menus.rs`,
`ui-egui/src/lib.rs`, the root `Cargo.toml`) get small, surgical edits; re-read before editing.
- Put new commands in a **new module** with its own `specs()` registered by one line, and new nodes
in the module of their library category.
- Delete your `target/agent-*` dir when done.
## 7. Where things are tracked
- `ROADMAP.md`: milestones, parity estimate and remaining effort.
- `docs/target-app-parity.md` and `docs/gaps.md`: the assessment and the work list.
- `docs/releasing.md` and `../craftrules/release/playbook.md`: release builds and signing.
- `plan/` (local, gitignored): execution plan and notes.
- `log/` (local, gitignored): the dev log.
+43
View File
@@ -0,0 +1,43 @@
# Attribution
Every bundled non-code asset in this repository, with its author, source and license. The rule:
**each asset gets a row here in the same change that adds it.** MaterialCraft's own code and
original assets are MIT OR Apache-2.0 (see [`LICENSE-MIT`](LICENSE-MIT),
[`LICENSE-APACHE`](LICENSE-APACHE) and [`NOTICE`](NOTICE)); third-party assets must be permissively
licensed and keep their license file next to them. No asset from any commercial product (icons,
images, materials, sample graphs, presets, environments) may ever be added.
| Path | Title | Author | Source | License |
|---|---|---|---|---|
| `assets/app-icon/materialcraft.svg` | App icon (material sphere fed by a node), master vector | MaterialCraft contributors | Original placeholder drawn for MaterialCraft | MIT OR Apache-2.0 (`assets/app-icon/LICENSE.txt`) |
| `assets/app-icon/materialcraft-small.svg` | App icon, small-size vector (copy of the master) | MaterialCraft contributors | Original placeholder drawn for MaterialCraft | MIT OR Apache-2.0 (`assets/app-icon/LICENSE.txt`) |
| `assets/app-icon/materialcraft.ico` | App icon, Windows (16–256 px) | MaterialCraft contributors | Rendered from the PNGs by `cargo xtask ico` | MIT OR Apache-2.0 (`assets/app-icon/LICENSE.txt`) |
| `assets/app-icon/materialcraft.icns` | App icon, macOS (16–1024 px) | MaterialCraft contributors | Rendered from the PNGs by `cargo xtask icns` | MIT OR Apache-2.0 (`assets/app-icon/LICENSE.txt`) |
| `assets/app-icon/hicolor/{16x16,24x24,32x32,48x48,64x64,128x128,256x256,512x512,1024x1024}/apps/ai.storyteller.materialcraft.png` | App icon, hicolor theme PNGs | MaterialCraft contributors | Drawn in code (Pillow) from the same design as the SVG | MIT OR Apache-2.0 (`assets/app-icon/LICENSE.txt`) |
| `assets/app-icon/hicolor/scalable/apps/ai.storyteller.materialcraft.svg` | App icon, hicolor scalable (copy of the master) | MaterialCraft contributors | Original placeholder drawn for MaterialCraft | MIT OR Apache-2.0 (`assets/app-icon/LICENSE.txt`) |
| `assets/app-icon/LICENSE.txt` | App icon licence | MaterialCraft contributors | original | MIT OR Apache-2.0 |
| `docs/images/materialcraft-workspace.png` | README screenshot: the workspace with the brick wall sample | MaterialCraft contributors | Offscreen render of MaterialCraft's UI (`crates/ui-egui/tests/snapshot.rs`) | MIT OR Apache-2.0 |
| `docs/images/materialcraft-wood.png` | README screenshot: the wood planks template | MaterialCraft contributors | Offscreen render of MaterialCraft's UI | MIT OR Apache-2.0 |
| `docs/images/materialcraft-fabric.png` | README screenshot: the woven fabric template | MaterialCraft contributors | Offscreen render of MaterialCraft's UI | MIT OR Apache-2.0 |
| `docs/images/materialcraft-new-graph.png` | README screenshot: the New graph dialog | MaterialCraft contributors | Offscreen render of MaterialCraft's UI | MIT OR Apache-2.0 |
| `docs/images/materialcraft-materials.png` | README render: six sample materials on the material ball | MaterialCraft contributors | `materialcraft-cli render --scene material_ball --full`, six renders side by side | MIT OR Apache-2.0 |
| `docs/brand/artcraft-*.svg`, `docs/brand/artcraft-*.png` | ArtCraft logo and mark | ArtCraft Team | storytold/craftrules `assets/brand/` | ArtCraft brand terms, not open source ([`docs/brand/LICENSE-brand.txt`](docs/brand/LICENSE-brand.txt)) |
## Third-party assets compiled into the binary
These come from Rust crate dependencies (not files in this repository) and keep their licenses.
| Asset | Used for | Author | Source | License |
|---|---|---|---|---|
| Phosphor Icons (regular), via the `egui-phosphor` crate (vendored in `vendor/egui-phosphor` for egui 0.37) | Every UI icon (toolbars, panels, node quick-insert buttons) | Phosphor Icons (Helena Zhang, Tobias Fried) | https://phosphoricons.com, https://github.com/amPerl/egui-phosphor | MIT (icons); crate MIT OR Apache-2.0 |
| egui default fonts (Ubuntu-Light, Hack, Noto Emoji, emoji-icon-font), via `epaint_default_fonts` | UI text | Canonical / Source Foundry / Google / Jessie Jung | https://github.com/emilk/egui | Ubuntu Font Licence 1.0, MIT + Bitstream Vera License, OFL 1.1, MIT |
## Procedural content (no asset files)
The node library's noises and patterns (`crates/nodes`), the sample materials and graph templates
(`crates/engine/src/samples.rs`), the 3D view's environments (`crates/render/src/ibl.rs`, procedural
HDR skies and soft boxes), the built-in meshes (`crates/geom/src/primitives.rs`), the library's node
previews (`crates/ui-egui/src/thumbs.rs`, each node cooked on sample noise) and the New graph
dialog's template spheres (`crates/ui-egui/src/windows.rs`) are generated in code by MaterialCraft
contributors (MIT OR Apache-2.0). None of them is derived from another product's presets,
shaders, materials, sample graphs or images.
Generated
+14
View File
@@ -2394,6 +2394,20 @@ dependencies = [
"serde_json",
]
[[package]]
name = "materialcraft-web"
version = "0.1.0"
dependencies = [
"eframe",
"js-sys",
"log",
"materialcraft-engine",
"materialcraft-ui-egui",
"wasm-bindgen",
"wasm-bindgen-futures",
"web-sys",
]
[[package]]
name = "maybe-owned"
version = "0.3.4"
+32 -1
View File
@@ -1,7 +1,38 @@
[workspace]
resolver = "3"
members = ["crates/core", "crates/image", "crates/geom", "crates/nodes", "crates/eval", "crates/formats", "crates/engine", "crates/render", "crates/automation", "apps/materialcraft-cli", "crates/ui-egui", "apps/materialcraft", "xtask"]
members = [
"crates/core",
"crates/image",
"crates/geom",
"crates/nodes",
"crates/eval",
"crates/formats",
"crates/engine",
"crates/render",
"crates/automation",
"crates/ui-egui",
"apps/materialcraft",
"apps/materialcraft-cli",
"apps/materialcraft-web",
"xtask",
]
exclude = ["vendor"]
# The web app only builds for wasm32 (trunk); everything else is the default.
default-members = [
"crates/core",
"crates/image",
"crates/geom",
"crates/nodes",
"crates/eval",
"crates/formats",
"crates/engine",
"crates/render",
"crates/automation",
"crates/ui-egui",
"apps/materialcraft",
"apps/materialcraft-cli",
"xtask",
]
[workspace.package]
version = "0.1.0"
+299
View File
@@ -0,0 +1,299 @@
<p align="center">
<a href="https://getartcraft.com/">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/brand/artcraft-logo-white.svg">
<img alt="ArtCraft" src="docs/brand/artcraft-logo.svg" width="200">
</picture>
</a>
</p>
<h1 align="center">MaterialCraft</h1>
<p align="center">
<b>Procedural materials; an open-source, node-based material designer, built in pure Rust.</b>
</p>
<p align="center">
Build tileable PBR materials from noises, patterns and filters in a node graph, watch them
update live in 2D and on a 3D model, and export the maps for any engine. It runs natively on
macOS, Windows, Linux and FreeBSD, and in the browser via WebAssembly. Built by the ArtCraft team.
</p>
<p align="center">
<img alt="Status: in active development" src="https://img.shields.io/badge/status-in%20active%20development-1ea7c4?style=flat-square">
<img alt="Written in pure Rust" src="https://img.shields.io/badge/pure-Rust-b83a24?style=flat-square&logo=rust&logoColor=white">
<img alt="Runs on macOS, Windows, Linux, FreeBSD and the web" src="https://img.shields.io/badge/runs%20on-macOS%20%C2%B7%20Windows%20%C2%B7%20Linux%20%C2%B7%20FreeBSD%20%C2%B7%20Web-555555?style=flat-square">
<img alt="MCP server for agents" src="https://img.shields.io/badge/agents-MCP%20server-555555?style=flat-square">
<img alt="License: MIT OR Apache-2.0" src="https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-555555?style=flat-square">
</p>
<p align="center">
<a href="https://discord.gg/artcraft"><img alt="Join the ArtCraft community on Discord" src="https://img.shields.io/badge/Join%20us%20on%20Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" height="40"></a>
</p>
<p align="center">
<a href="https://getartcraft.com/apps/materialcraft"><b>MaterialCraft on getartcraft.com</b></a> ·
<a href="https://getartcraft.com/">ArtCraft</a> ·
<a href="https://getartcraft.com/apps">All Crafting Apps</a>
</p>
<br>
<p align="center">
<img src="docs/images/materialcraft-workspace.png" alt="The MaterialCraft workspace: the explorer and node library on the left; a brick wall material as a node graph with live thumbnails in the middle, over a 3D view of a rounded cube in red brick and a 2D view of the base color; the brick generator's parameters on the right" width="100%">
<br><sub><b>The workspace</b>: explorer, library, node graph, 3D view, 2D view and properties</sub>
</p>
> [!NOTE]
> **ArtCraft is a community of artists from all walks of life.** Painters, sculptors, game
> artists, material and texture artists, photographers, filmmakers, illustrators, designers,
> hobbyists, and people who picked up a stylus last week. If you make things, you belong here.
> **[Come say hi on Discord](https://discord.gg/artcraft).**
<p align="center">
<a href="#a-look-around">A look around</a> ·
<a href="#made-in-materialcraft">Made in MaterialCraft</a> ·
<a href="#why-materialcraft">Why MaterialCraft</a> ·
<a href="#quick-start">Quick start</a> ·
<a href="#status">Status</a> ·
<a href="#downloads">Downloads</a> ·
<a href="#the-crafting-apps">The Crafting Apps</a> ·
<a href="#license-and-credits">License</a>
</p>
## A look around
<table>
<tr>
<td width="50%" valign="top">
<img src="docs/images/materialcraft-wood.png" alt="A wood planks graph: anisotropic noise warped by Perlin noise and multiplied over a plank pattern, shown on the rounded cube and in the 2D view" width="100%">
<p align="center"><sub><b>Wood planks</b>: anisotropic grain, warped and laid over planks</sub></p>
</td>
<td width="50%" valign="top">
<img src="docs/images/materialcraft-fabric.png" alt="A woven fabric graph: a weave pattern with soft fuzz, as a blue cloth on the rounded cube and in the 2D view" width="100%">
<p align="center"><sub><b>Woven fabric</b>: a weave pattern with fuzz and a color ramp</sub></p>
</td>
</tr>
<tr>
<td width="50%" valign="top">
<img src="docs/images/materialcraft-new-graph.png" alt="The New graph dialog: template spheres for empty, PBR, brick wall, stone tiles, wood planks, rusty metal, woven fabric and stone ground, with the graph name and size" width="100%">
<p align="center"><sub><b>New graph</b>: start from a PBR template or a sample material</sub></p>
</td>
<td width="50%" valign="top">
<img src="docs/images/materialcraft-materials.png" alt="Six material balls rendered by MaterialCraft: red brick, wood planks, rusty metal, stone tiles, blue woven fabric and stone ground" width="100%">
<p align="center"><sub><b>Six sample materials</b> on the material ball, rendered by <code>materialcraft-cli render</code></sub></p>
</td>
</tr>
</table>
## Made in MaterialCraft
Every material below is a node graph that ships with MaterialCraft as a template, built only from
its own procedural nodes (no photos, scans or textures from anywhere else) and rendered by
`materialcraft-cli render --scene material_ball --full`.
<p align="center">
<img src="docs/images/materialcraft-materials.png" alt="Brick, wood planks, rusty metal, stone tiles, woven fabric and stone ground on material balls" width="100%">
</p>
## Why MaterialCraft
- **Familiar.** The layout, panels, menus and gestures material artists already know: a package
explorer, a library of nodes with previews, the node graph with live thumbnails, a 3D view, a 2D
view and a properties panel with base and specific parameters. Space opens the node search.
- **Fast.** Every node cooks on every CPU core, and a content-addressed cache means an edit
re-cooks only what lies downstream: the brick wall sample cooks in about 40 ms at preview size.
Cooking runs on a worker thread, so the UI never waits.
- **Tileable by design.** Noises and patterns live on whole-number lattices, so everything tiles
seamlessly at any resolution, from 16 px to 8K.
- **Robust.** No panics in shipped code, every command tested with hostile input, every node cooked
with odd inputs in tests, unlimited undo from snapshots, and lossless `.mcraft` packages.
- **Open.** Export base color, normal, roughness, metallic, height and ambient occlusion as PNG,
JPEG, TGA, TIFF, BMP, WEBP, EXR or HDR at 8, 16 or 32 bits, with your own file name pattern.
- **Agent-native.** Every menu item and edit is a command you can drive from the CLI, a JSON
control channel (including synthetic mouse and keyboard input) or an **MCP server**, so Claude
and other agents can build materials the way a person does.
- **Everywhere.** One codebase for the desktop apps and the same UI in the browser.
## Quick start
```sh
git clone https://github.com/storytold/materialcraft
cd materialcraft
cargo run --release -p materialcraft # desktop app (opens the brick wall sample)
cargo run --release -p materialcraft -- package.mcraft # open a package
cargo run --release -p materialcraft -- --control 7878 # + JSON control channel
cargo run --release -p materialcraft-cli -- mcp # MCP server (stdio)
cargo run --release -p materialcraft-cli -- new wood wood.mcraft
cargo run --release -p materialcraft-cli -- render wood.mcraft wood.png --scene material_ball --full
cargo run --release -p materialcraft-cli -- export wood.mcraft textures --format png --depth 16
cd apps/materialcraft-web && trunk serve # web build
cargo xtask ci # fmt, clippy, tests, layering, wasm
```
You need Rust 1.95 or newer. The app opens with the brick wall sample; **File ▸ New ▸ Graph...**
starts from a PBR template or one of the sample materials.
### Use it from Claude Code and other agents
Register the MCP server with Claude Code, giving it the folders it may read and write:
```sh
claude mcp add materialcraft -- /path/to/materialcraft-cli mcp --read-root /work/materials --write-root /work/materials
```
To drive the running app instead, start it with `--control 7878` and bridge to it:
```sh
claude mcp add materialcraft-app -- /path/to/materialcraft-cli mcp --bridge 7878
```
The details are in [`docs/control-protocol.md`](docs/control-protocol.md).
## Status
MaterialCraft is under active development. [**ROADMAP.md**](ROADMAP.md) has the parity estimate by
area, the remaining work and what's next.
**Where we are (2026-11-02):** the node engine, about 120 nodes (the atomic nodes, noises,
patterns, adjustments, blurs, effects, normal map tools, tiling, transforms and PBR utilities),
pixel and value processors driven by function graphs, sub-graphs with exposed parameters, the full
editor (graph, library, properties, 2D and 3D views), `.mcraft` packages, texture export, the CLI,
the control channel and the MCP server all work today. We estimate about half (≈ 51%) of a material
artist's daily workflow works end to end; [docs/target-app-parity.md](docs/target-app-parity.md)
has the breakdown.
**What's missing:** a visual function-graph editor (functions are edited as JSON for now), the
rest of the node library, FX-maps, text and vector shapes, a GPU cook path, mesh-based nodes,
browser file I/O, translations and the first signed release. The ranked list is in
[`docs/gaps.md`](docs/gaps.md).
**Workspace:** `crates/{core, image, geom, nodes, eval, formats, engine, render, automation, ui-egui}`
and `apps/{materialcraft, materialcraft-cli, materialcraft-web}`. The egui frontend is its own
crate, so the UI can be swapped without touching the engine; [`docs/architecture.md`](docs/architecture.md)
explains how it fits together.
Agent and contributor rules (clean room, the asset policy, no panics in shipped code, quality gates)
are in [`AGENTS.md`](AGENTS.md). Every bundled asset is listed with its licence in
[`ATTRIBUTION.md`](ATTRIBUTION.md).
## Downloads
**New to MaterialCraft?** Download it from the [MaterialCraft page on getartcraft.com](https://getartcraft.com/apps/materialcraft). That's the easiest way to install it.
**Want a specific build or format?** On GitHub, the [latest release](https://github.com/storytold/materialcraft/releases/latest) has every build listed below, and [all releases](https://github.com/storytold/materialcraft/releases) has earlier versions and their notes. `<ver>` in the file names is the version number, and `SHA256SUMS.txt` lists a checksum for every file.
### Windows
| Build | Installer | Portable |
|---|---|---|
| x64 (64-bit Intel/AMD) | `materialcraft-<ver>-windows-x64.msi` | `materialcraft-<ver>-windows-x64-portable.zip` |
| arm64 (Snapdragon and other ARM PCs) | `materialcraft-<ver>-windows-arm64.msi` | `materialcraft-<ver>-windows-arm64-portable.zip` |
| x86 (32-bit) | `materialcraft-<ver>-windows-x86.msi` | `materialcraft-<ver>-windows-x86-portable.zip` |
### macOS
| Build | File | Notes |
|---|---|---|
| App, universal (Apple silicon + Intel) | `materialcraft-<ver>-macos-universal.dmg` | Signed and notarized |
| Command-line tool, universal | `materialcraft-cli-<ver>-macos-universal.zip` | Signed and notarized |
### Linux
| Format | x86_64 | aarch64 (ARM64) | Notes |
|---|---|---|---|
| AppImage | `materialcraft-<ver>-linux-x86_64.AppImage` | `materialcraft-<ver>-linux-aarch64.AppImage` | Runs anywhere; updates itself with [AppImageUpdate](https://github.com/AppImageCommunity/AppImageUpdate) (`.zsync` files) |
| Flatpak | `materialcraft-<ver>-linux-x86_64.flatpak` | `materialcraft-<ver>-linux-aarch64.flatpak` | Sandboxed; `flatpak install --user <file>` |
| Debian/Ubuntu | `materialcraft-<ver>-linux-x86_64.deb` | `materialcraft-<ver>-linux-aarch64.deb` | |
| Fedora/RHEL/openSUSE | `materialcraft-<ver>-linux-x86_64.rpm` | `materialcraft-<ver>-linux-aarch64.rpm` | |
| Tarball | `materialcraft-<ver>-linux-x86_64.tar.gz` | `materialcraft-<ver>-linux-aarch64.tar.gz` | Unpack anywhere |
### FreeBSD
| Build | File |
|---|---|
| x86_64 | `materialcraft-<ver>-freebsd-x86_64.tar.gz` |
### Web (WebAssembly)
| Build | File | Notes |
|---|---|---|
| Static site | `materialcraft-web-<ver>.zip` | Runs in a modern browser; host it on any static server |
## The Crafting Apps
MaterialCraft is one of the **Crafting Apps**: free, open-source creative tools from the
[ArtCraft](https://getartcraft.com/) team, each written from scratch in Rust and each able to
stand on its own.
| | App | What it's for | Code | Learn more |
|:-:|---|---|---|---|
| <img src="https://raw.githubusercontent.com/storytold/photocraft/main/assets/app-icon/hicolor/64x64/apps/ai.storyteller.photocraft.png" alt="" width="32" height="32"> | **PhotoCraft** | Image editing: layers, masks, type and real PSD files | [GitHub](https://github.com/storytold/photocraft) | [Website](https://getartcraft.com/apps/photocraft) |
| <img src="https://raw.githubusercontent.com/storytold/vectorcraft/main/assets/app-icon/hicolor/64x64/apps/ai.storyteller.vectorcraft.png" alt="" width="32" height="32"> | **VectorCraft** | Vector illustration | [GitHub](https://github.com/storytold/vectorcraft) | [Website](https://getartcraft.com/apps/vectorcraft) |
| <img src="https://raw.githubusercontent.com/storytold/texturecraft/main/assets/app-icon/hicolor/64x64/apps/ai.storyteller.texturecraft.png" alt="" width="32" height="32"> | **TextureCraft** | 3D texture painting | [GitHub](https://github.com/storytold/texturecraft) | [Website](https://getartcraft.com/apps/texturecraft) |
| <img src="https://raw.githubusercontent.com/storytold/materialcraft/main/assets/app-icon/hicolor/64x64/apps/ai.storyteller.materialcraft.png" alt="" width="32" height="32"> | **MaterialCraft** | **Procedural materials with node graphs · you are here** | [GitHub](https://github.com/storytold/materialcraft) | [Website](https://getartcraft.com/apps/materialcraft) |
| <img src="https://raw.githubusercontent.com/storytold/filmcraft/main/assets/app-icon/hicolor/64x64/apps/ai.storyteller.filmcraft.png" alt="" width="32" height="32"> | **FilmCraft** | Video editing, color and sound | [GitHub](https://github.com/storytold/filmcraft) | [Website](https://getartcraft.com/apps/filmcraft) |
| <img src="https://raw.githubusercontent.com/storytold/lightcraft/main/assets/app-icon/hicolor/64x64/apps/ai.storyteller.lightcraft.png" alt="" width="32" height="32"> | **LightCraft** | Photo library and raw development | [GitHub](https://github.com/storytold/lightcraft) | [Website](https://getartcraft.com/apps/lightcraft) |
| <img src="https://raw.githubusercontent.com/storytold/pdfcraft/main/assets/app-icon/hicolor/64x64/apps/ai.storyteller.pdfcraft.png" alt="" width="32" height="32"> | **PdfCraft** | Reading, organizing and protecting PDFs | [GitHub](https://github.com/storytold/pdfcraft) | [Website](https://getartcraft.com/apps/pdfcraft) |
| <img src="https://raw.githubusercontent.com/storytold/effectcraft/main/assets/app-icon/hicolor/64x64/apps/ai.storyteller.effectcraft.png" alt="" width="32" height="32"> | **EffectCraft** | Motion graphics and visual effects | [GitHub](https://github.com/storytold/effectcraft) | [Website](https://getartcraft.com/apps/effectcraft) |
| <img src="https://raw.githubusercontent.com/storytold/designcraft/main/assets/app-icon/hicolor/64x64/apps/ai.storyteller.designcraft.png" alt="" width="32" height="32"> | **DesignCraft** | Page layout and publishing | [GitHub](https://github.com/storytold/designcraft) | [Website](https://getartcraft.com/apps/designcraft) |
| <img src="https://raw.githubusercontent.com/storytold/gridcraft/main/assets/app-icon/hicolor/64x64/apps/ai.storyteller.gridcraft.png" alt="" width="32" height="32"> | **GridCraft** | Spreadsheets and data | [GitHub](https://github.com/storytold/gridcraft) | [Website](https://getartcraft.com/apps/gridcraft) |
And [**ArtCraft**](https://getartcraft.com/) itself, our AI image and video studio for artists who want real control.
<br>
<p align="center">
<a href="https://discord.gg/artcraft"><img alt="Join the ArtCraft community on Discord" src="https://img.shields.io/badge/Join%20us%20on%20Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" height="40"></a>
</p>
<h3 align="center">Come make things with us</h3>
<p align="center">
Our Discord is where artists of every kind hang out: people who paint, sculpt, model, build
materials, shoot, draw, cut film, set type, and people still figuring out what they like to make.
Share what you're working on, ask for help, tell us what's broken, or tell us what you wish these
tools could do. Whatever your medium and however long you've been at it, you're welcome here.
</p>
<p align="center">
<a href="https://discord.gg/artcraft"><b>discord.gg/artcraft</b></a> ·
<a href="https://getartcraft.com/">getartcraft.com</a> ·
<a href="https://getartcraft.com/apps">The Crafting Apps</a> ·
<a href="https://getartcraft.com/apps/materialcraft">MaterialCraft</a>
</p>
## Star history
[![Star History Chart](https://api.star-history.com/svg?repos=storytold/materialcraft&type=Date&legend=top-left)](https://www.star-history.com/?repos=storytold%2Fmaterialcraft&type=date&legend=top-left)
## License and credits
MaterialCraft is dual-licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE), at your option.
Copyright (c) 2026 ArtCraft Team and the MaterialCraft contributors. Required notices are in [NOTICE](NOTICE).
Bundled icons, images and other assets keep their own open licenses; each one is listed with its
author, source and license in [ATTRIBUTION.md](ATTRIBUTION.md).
Every material, noise, pattern, environment, library preview and mesh shown is generated
procedurally by MaterialCraft itself; no third-party textures, scans or models appear in the
screenshots. MaterialCraft is an independent, clean-room implementation of a node-based procedural
material workflow and is not affiliated with any other software vendor.
The app icon (a material sphere fed by a node, on MaterialCraft cyan `#1ea7c4`) is an original
placeholder drawn in code for this project; its files are in [`assets/app-icon/`](assets/app-icon/).
The ArtCraft name, wordmark and logos in [`docs/brand/`](docs/brand/) are trademarks of the
ArtCraft Team and are not covered by this license. They may be used only unmodified, and only as
part of this repository and MaterialCraft, under [`docs/brand/LICENSE-brand.txt`](docs/brand/LICENSE-brand.txt).
Forks and modified versions must remove them.
<p align="center">
<a href="https://discord.gg/artcraft"><img alt="Join the ArtCraft community on Discord" src="https://img.shields.io/badge/Join%20us%20on%20Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" height="40"></a>
</p>
<p align="center">
<a href="https://getartcraft.com/"><img alt="ArtCraft" src="docs/brand/artcraft-mark.svg" width="28"></a><br>
<sub>Made by the <a href="https://getartcraft.com/">ArtCraft</a> team and community.</sub>
</p>
+56
View File
@@ -0,0 +1,56 @@
# MaterialCraft roadmap
> **Last reviewed:** 2026-11-02 · **Last updated:** 2026-11-02 · **Change:** major (first version) · **Target:** the professional node-based material workflow
**Stage:** alpha (in active development). MaterialCraft aims for full parity with the professional
node-based procedural material workflow, with better performance, every feature drivable by agents
(MCP, CLI, control channel), and builds for Windows, macOS, Linux, FreeBSD and the web.
## Headline numbers
- **Parity: ≈ 51%** of a material artist's daily workflow works end to end
([docs/target-app-parity.md](docs/target-app-parity.md)).
- **Remaining: ≈ 120 Opus 5.5 agent hours** ([docs/roadmap.md](docs/roadmap.md)).
- **Nodes:** ~120 (all tileable), cooked on every CPU core through a content-addressed cache; the
brick wall sample cooks in about 40 ms at preview size.
## By area
| Area | Weight | Done |
|---|---:|---:|
| Graph editing | 15 | 75% |
| Atomic nodes | 12 | 80% |
| Node library | 20 | 25% |
| Function graphs | 10 | 35% |
| Graph parameters and instances | 8 | 50% |
| 2D view | 5 | 70% |
| 3D view | 10 | 45% |
| Files | 8 | 50% |
| UI and UX | 8 | 55% |
| Platforms | 4 | 40% |
| **Total** | **100** | **≈ 51%** |
## What's next
1. The visual function-graph editor and dynamic parameters.
2. More of the node library: flood fill, shape splatter, 3D noises, grunge maps, whole-material
blending.
3. FX-Map lite, Text and SVG nodes.
4. A GPU 3D view with tessellation and lights; mesh import.
5. Browser file I/O and the first release on every platform.
The ranked work list is [docs/gaps.md](docs/gaps.md); file formats are in
[docs/file-format-parity.md](docs/file-format-parity.md) and languages in
[docs/localization-parity.md](docs/localization-parity.md).
## Progress log
| Date | What landed |
|---|---|
| 2026-11-02 | First day: engine, ~120 nodes, cooking cache, packages, export, the full editor UI, 3D preview, CLI, control channel with synthetic input, MCP server, wasm builds |
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-11-02 | major | First version |
+27
View File
@@ -0,0 +1,27 @@
[package]
name = "materialcraft-web"
description = "MaterialCraft in the browser (eframe web runner, WebGPU with WebGL2 fallback)"
version.workspace = true
edition.workspace = true
license.workspace = true
publish = false
[lints]
workspace = true
[[bin]]
name = "materialcraft-web"
path = "src/main.rs"
[dependencies]
materialcraft-engine = { workspace = true }
materialcraft-ui-egui = { workspace = true }
log = { workspace = true }
[target.'cfg(target_arch = "wasm32")'.dependencies]
# `wgpu` pulls egui-wgpu's defaults: WebGPU plus the WebGL2 fallback.
eframe = { workspace = true, features = ["default_fonts", "wgpu", "accesskit", "persistence"] }
wasm-bindgen = "0.2"
wasm-bindgen-futures = "0.4"
js-sys = "0.3"
web-sys = { version = "0.3", features = ["Window", "Document", "Element", "HtmlCanvasElement", "Location", "KeyboardEvent", "EventTarget", "AddEventListenerOptions"] }
+10
View File
@@ -0,0 +1,10 @@
# Build with: trunk build --release (from apps/materialcraft-web; packaging/web/package.sh)
[build]
target = "index.html"
dist = "../../dist/web"
public_url = "./"
filehash = true
[serve]
addresses = ["127.0.0.1"]
port = 8765
+49
View File
@@ -0,0 +1,49 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
<meta name="color-scheme" content="dark">
<title>MaterialCraft</title>
<link data-trunk rel="rust" data-bin="materialcraft-web" data-cargo-profile="wasm-release" data-wasm-opt="z" data-weak-refs />
<style>
html, body { margin: 0; padding: 0; width: 100%; height: 100%; overflow: hidden; overscroll-behavior: none; background: #1c1c1c; }
/* Touch and pen strokes paint and orbit; the browser must not scroll, zoom or select. */
#materialcraft_canvas { position: absolute; inset: 0; width: 100%; height: 100%; display: block; outline: none;
touch-action: none; user-select: none; -webkit-user-select: none; -webkit-touch-callout: none; }
#materialcraft_loading { position: absolute; inset: 0; display: flex; flex-direction: column; align-items: center; justify-content: center;
gap: 12px; padding: 0 16px; text-align: center; color: #b8b8b8; font: 14px system-ui, sans-serif; pointer-events: none; background: #1c1c1c; }
#materialcraft_loading h1 { margin: 0; color: #f2f2f2; font-size: 20px; font-weight: 600; letter-spacing: 0.02em; }
#materialcraft_loading p { margin: 0; max-width: 420px; line-height: 1.5; }
#materialcraft_loading a { color: #e0e0e0; pointer-events: auto; }
/* Indeterminate while the WebAssembly downloads (the page has no script to measure it); the
app sets its value through the startup steps once it runs. */
#materialcraft_progress { width: min(280px, 70vw); height: 4px; border: 0; border-radius: 2px; background: #333; color: #1ea7c4; accent-color: #1ea7c4; }
#materialcraft_progress::-webkit-progress-bar { background: #333; border-radius: 2px; }
#materialcraft_progress::-webkit-progress-value { background: #1ea7c4; border-radius: 2px; }
#materialcraft_progress::-moz-progress-bar { background: #1ea7c4; border-radius: 2px; }
/* Styled progress bars lose the native "busy" animation: a sweep stands in while downloading. */
#materialcraft_progress:indeterminate { background: linear-gradient(90deg, #333 0%, #1ea7c4 50%, #333 100%) 0 0 / 300% 100%;
animation: materialcraft-busy 1.4s linear infinite; }
#materialcraft_progress:indeterminate::-webkit-progress-bar { background: transparent; }
#materialcraft_progress:indeterminate::-moz-progress-bar { background: transparent; }
@keyframes materialcraft-busy { from { background-position: 100% 0; } to { background-position: -50% 0; } }
#materialcraft_status { font-size: 12px; color: #969696; }
/* The app removes this element once it runs. If the WebAssembly never downloads or doesn't match
this page, no Rust runs to say so, so the page itself shows what to do after a while. */
#materialcraft_stalled { color: #8c8c8c; visibility: hidden; animation: materialcraft-stalled 0s 30s forwards; }
@keyframes materialcraft-stalled { to { visibility: visible; } }
</style>
</head>
<body>
<canvas id="materialcraft_canvas"></canvas>
<div id="materialcraft_loading" role="status" aria-live="polite">
<h1>MaterialCraft</h1>
<progress id="materialcraft_progress" max="1" aria-label="Loading MaterialCraft"></progress>
<p id="materialcraft_status">Downloading&hellip;</p>
<p id="materialcraft_stalled">This is taking longer than usual. If MaterialCraft doesn't start, its files may have failed to
download or come from a different version of this page. <a href="">Reload</a> to try again; the browser
console lists what failed.</p>
</div>
</body>
</html>
+41
View File
@@ -0,0 +1,41 @@
//! MaterialCraft in the browser.
//!
//! Runs the same [`materialcraft_ui_egui::MaterialCraftApp`] as the desktop app through eframe's web
//! runner (wgpu: WebGPU where available, WebGL2 otherwise). Build with `trunk build --release`
//! from this directory (`packaging/web/package.sh` zips the result).
//!
//! Differences from the desktop app: no control server (browsers can't listen on sockets), and
//! file I/O in the browser is still to come (see ROADMAP.md).
//!
//! URL query flag: `?webgl` forces the WebGL2 backend instead of WebGPU.
#![forbid(unsafe_code)]
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
#[cfg(target_arch = "wasm32")]
mod web;
#[cfg(target_arch = "wasm32")]
fn main() {
web::start();
}
#[cfg(not(target_arch = "wasm32"))]
fn main() {
eprintln!("materialcraft-web only runs in the browser: build it with `trunk build --release` in apps/materialcraft-web");
}
#[cfg(test)]
mod tests {
/// A WebAssembly module that never downloads runs no Rust, so the page itself replaces the
/// endless "Loading" with a way to retry, without a hand-written script.
#[test]
fn loading_page_offers_a_reload_when_startup_stalls() {
let html = include_str!("../index.html");
let (_, hint) = html.split_once("<p id=\"materialcraft_stalled\">").expect("stalled-startup hint in the loading element");
assert!(hint.contains("failed to") && hint.contains("<a href=\"\">Reload</a>"), "{hint}");
assert!(html.contains("animation: materialcraft-stalled"), "the hint appears after a delay");
assert!(html.contains("id=\"materialcraft_canvas\"") && html.contains("data-cargo-profile=\"wasm-release\""));
assert!(!html.contains("<script"), "trunk injects the generated loader; the page has no script of its own");
}
}
+110
View File
@@ -0,0 +1,110 @@
//! The eframe web runner: canvas lookup, backend selection, the loading screen's startup steps,
//! browser shortcuts the app takes over, and startup errors shown in the page.
use materialcraft_ui_egui::MaterialCraftApp;
use wasm_bindgen::JsCast as _;
use wasm_bindgen::closure::Closure;
const CANVAS_ID: &str = "materialcraft_canvas";
const LOADING_ID: &str = "materialcraft_loading";
const STATUS_ID: &str = "materialcraft_status";
const PROGRESS_ID: &str = "materialcraft_progress";
pub fn start() {
eframe::WebLogger::init(log::LevelFilter::Info).ok();
capture_app_shortcuts();
wasm_bindgen_futures::spawn_local(async {
let Some(document) = web_sys::window().and_then(|w| w.document()) else {
log::error!("no document");
return;
};
let result = match document.get_element_by_id(CANVAS_ID).and_then(|e| e.dyn_into::<web_sys::HtmlCanvasElement>().ok()) {
Some(canvas) => run(canvas).await,
None => Err(format!("the page has no <canvas id=\"{CANVAS_ID}\">")),
};
if let Some(el) = document.get_element_by_id(LOADING_ID) {
match result {
Ok(()) => el.remove(),
Err(e) => {
log::error!("MaterialCraft failed to start: {e}");
el.set_text_content(Some(&format!(
"MaterialCraft failed to start: {e}. It needs a browser with WebGPU (current Chrome, Edge or Safari) or at least WebGL2."
)));
}
}
}
});
}
async fn run(canvas: web_sys::HtmlCanvasElement) -> Result<(), String> {
// The WebAssembly has downloaded and compiled when this runs.
step(0.5, "Preparing the sample package…").await;
let session = materialcraft_engine::sample_session();
step(0.8, "Starting the renderer…").await;
let mut options = eframe::WebOptions::default();
if query().contains("webgl")
&& let eframe::egui_wgpu::WgpuSetup::CreateNew(create) = &mut options.wgpu_options.wgpu_setup
{
create.instance_descriptor.backends = eframe::wgpu::Backends::GL;
}
eframe::WebRunner::new()
.start(
canvas,
options,
Box::new(|cc| {
let mut app = MaterialCraftApp::new(cc, session);
// One thread cooks in the browser: keep previews small.
app.ui.prefs.preview_size = app.ui.prefs.preview_size.clamp(128, 256);
Ok(Box::new(app))
}),
)
.await
.map_err(|e| e.as_string().unwrap_or_else(|| format!("{e:?}")))
}
/// Show a startup step on the loading screen and let the browser paint it before the next
/// (blocking) step runs.
async fn step(progress: f32, status: &str) {
let Some(document) = web_sys::window().and_then(|w| w.document()) else { return };
if let Some(el) = document.get_element_by_id(STATUS_ID) {
el.set_text_content(Some(status));
}
if let Some(el) = document.get_element_by_id(PROGRESS_ID) {
let _ = el.set_attribute("value", &progress.to_string());
}
// A timer longer than a frame lets the browser paint the step before work resumes. Not
// `requestAnimationFrame`: it never fires in a background tab, which would stall startup.
let promise = js_sys::Promise::new(&mut |resolve, _| {
if let Some(w) = web_sys::window() {
let _ = w.set_timeout_with_callback_and_timeout_and_arguments_0(&resolve, 20);
}
});
let _ = wasm_bindgen_futures::JsFuture::from(promise).await;
}
/// The app's shortcuts (Ctrl+S, Ctrl+O, Ctrl+D, F5…) would also trigger the browser's own
/// actions; take them first. Copy, cut and paste stay with the browser, which turns them into
/// the clipboard events egui reads. Shortcuts the browser reserves (Ctrl+N, Ctrl+T, Ctrl+W)
/// never reach the page.
fn capture_app_shortcuts() {
let Some(window) = web_sys::window() else { return };
let on_key = Closure::<dyn FnMut(web_sys::KeyboardEvent)>::new(|e: web_sys::KeyboardEvent| {
let ctrl = e.ctrl_key() || e.meta_key();
let k = e.key().to_ascii_lowercase();
let taken = (ctrl && ["s", "o", "d", "a", "z", "y", "e"].contains(&k.as_str())) || k == "f5" || (k == " " && !ctrl);
if taken {
e.prevent_default();
}
});
let options = web_sys::AddEventListenerOptions::new();
options.set_capture(true);
if let Err(e) = window.add_event_listener_with_callback_and_add_event_listener_options("keydown", on_key.as_ref().unchecked_ref(), &options) {
log::warn!("couldn't take over the browser's shortcuts: {e:?}");
}
// The listener lives as long as the page.
on_key.forget();
}
fn query() -> String {
web_sys::window().and_then(|w| w.location().search().ok()).unwrap_or_default()
}
+13
View File
@@ -0,0 +1,13 @@
MaterialCraft app icon (materialcraft.svg, materialcraft-small.svg and every file derived from them in
this directory: materialcraft.icns, materialcraft.ico, hicolor/).
An original placeholder made for this project in code by the MaterialCraft contributors (no
third-party material), until the owner's mascot artwork replaces it. Licensed like the rest of
MaterialCraft, under either of
* Apache License, Version 2.0 (https://www.apache.org/licenses/LICENSE-2.0)
* MIT license (https://opensource.org/licenses/MIT)
at your option.
Regenerate the derived files with packaging/icons.sh.
@@ -0,0 +1,24 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
<!-- MaterialCraft placeholder icon: an engraved material sphere fed by a node. Original work,
CC0 (see ATTRIBUTION.md). Three colours: ink #0b0b0c, paper #efe9dc, MaterialCraft cyan #1ea7c4. -->
<defs>
<clipPath id="ball"><circle cx="290" cy="236" r="150"/></clipPath>
</defs>
<rect width="512" height="512" rx="112" fill="#1ea7c4"/>
<!-- wire from the node into the sphere -->
<path d="M 128 388 C 190 388, 170 300, 232 300" fill="none" stroke="#0b0b0c" stroke-width="22" stroke-linecap="round"/>
<path d="M 128 388 C 190 388, 170 300, 232 300" fill="none" stroke="#efe9dc" stroke-width="10" stroke-linecap="round"/>
<!-- node card -->
<rect x="58" y="338" width="100" height="100" rx="18" fill="#efe9dc" stroke="#0b0b0c" stroke-width="10"/>
<rect x="58" y="338" width="100" height="26" rx="12" fill="#0b0b0c"/>
<!-- sphere with engraved shading -->
<circle cx="290" cy="236" r="150" fill="#efe9dc"/>
<g clip-path="url(#ball)" stroke="#0b0b0c" stroke-width="7" fill="none" stroke-linecap="round">
<path d="M 200 386 A 170 170 0 0 0 440 250"/>
<path d="M 222 396 A 150 150 0 0 0 446 290"/>
<path d="M 250 404 A 130 130 0 0 0 448 326"/>
<path d="M 284 408 A 110 110 0 0 0 446 360"/>
</g>
<circle cx="290" cy="236" r="150" fill="none" stroke="#0b0b0c" stroke-width="12"/>
<ellipse cx="238" cy="176" rx="34" ry="22" fill="#ffffff" transform="rotate(-30 238 176)"/>
</svg>

After

Width:  |  Height:  |  Size: 1.5 KiB

+24
View File
@@ -0,0 +1,24 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
<!-- MaterialCraft placeholder icon: an engraved material sphere fed by a node. Original work,
CC0 (see ATTRIBUTION.md). Three colours: ink #0b0b0c, paper #efe9dc, MaterialCraft cyan #1ea7c4. -->
<defs>
<clipPath id="ball"><circle cx="290" cy="236" r="150"/></clipPath>
</defs>
<rect width="512" height="512" rx="112" fill="#1ea7c4"/>
<!-- wire from the node into the sphere -->
<path d="M 128 388 C 190 388, 170 300, 232 300" fill="none" stroke="#0b0b0c" stroke-width="22" stroke-linecap="round"/>
<path d="M 128 388 C 190 388, 170 300, 232 300" fill="none" stroke="#efe9dc" stroke-width="10" stroke-linecap="round"/>
<!-- node card -->
<rect x="58" y="338" width="100" height="100" rx="18" fill="#efe9dc" stroke="#0b0b0c" stroke-width="10"/>
<rect x="58" y="338" width="100" height="26" rx="12" fill="#0b0b0c"/>
<!-- sphere with engraved shading -->
<circle cx="290" cy="236" r="150" fill="#efe9dc"/>
<g clip-path="url(#ball)" stroke="#0b0b0c" stroke-width="7" fill="none" stroke-linecap="round">
<path d="M 200 386 A 170 170 0 0 0 440 250"/>
<path d="M 222 396 A 150 150 0 0 0 446 290"/>
<path d="M 250 404 A 130 130 0 0 0 448 326"/>
<path d="M 284 408 A 110 110 0 0 0 446 360"/>
</g>
<circle cx="290" cy="236" r="150" fill="none" stroke="#0b0b0c" stroke-width="12"/>
<ellipse cx="238" cy="176" rx="34" ry="22" fill="#ffffff" transform="rotate(-30 238 176)"/>
</svg>

After

Width:  |  Height:  |  Size: 1.5 KiB

Binary file not shown.
Binary file not shown.

After

Width:  |  Height:  |  Size: 49 KiB

+7 -3
View File
@@ -54,6 +54,8 @@ pub struct Scene {
pub mesh: Arc<Mesh>,
pub bvh: Arc<Bvh>,
pub radius: f32,
/// Center of the mesh bounds (the camera orbits it).
pub center: Vec3,
}
impl Scene {
@@ -65,8 +67,10 @@ impl Scene {
mesh.compute_tangents();
}
let bvh = Bvh::new(&mesh);
let radius = mesh.radius().max(1e-3);
Scene { mesh: Arc::new(mesh), bvh: Arc::new(bvh), radius }
let (lo, hi) = mesh.bounds();
let center = (lo + hi) * 0.5;
let radius = ((hi - lo).length() * 0.5).max(1e-3);
Scene { mesh: Arc::new(mesh), bvh: Arc::new(bvh), radius, center }
}
/// A built-in scene (`rounded_cube`, `sphere`, …); unknown ids give the rounded cube.
@@ -141,7 +145,7 @@ impl Default for Settings {
/// The orbit camera for `s` around `scene`.
pub fn camera(scene: &Scene, s: &Settings) -> OrbitCamera {
OrbitCamera {
target: Vec3::ZERO,
target: scene.center,
yaw: s.yaw.to_radians(),
pitch: s.pitch.clamp(-89.0, 89.0).to_radians(),
distance: s.distance.clamp(1.05, 50.0) * scene.radius,
+2 -1
View File
@@ -78,7 +78,8 @@ pub fn show(app: &mut MaterialCraftApp, ui: &mut Ui) {
return;
};
let key = app.session.cooked.nodes.get(&id).map_or(0, |r| r.key)
^ (app.session.view2d.port as u64).wrapping_mul(0x9e37) ^ (app.session.view2d.channel.len() as u64 * 31)
^ (app.session.view2d.port as u64).wrapping_mul(0x9e37)
^ (app.session.view2d.channel.len() as u64 * 31)
^ app.session.view2d.channel.bytes().next().unwrap_or(0) as u64;
if app.view2d.tex.as_ref().is_none_or(|(k, _)| *k != key) {
let px = rgba8(&img, &app.session.view2d.channel);
+75
View File
@@ -0,0 +1,75 @@
# Architecture
> **Last reviewed:** 2026-11-02 · **Last updated:** 2026-11-02 · **Change:** major (first version) · **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 ~120 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/), 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.
+88
View File
@@ -0,0 +1,88 @@
# Control protocol and MCP
> **Last reviewed:** 2026-11-02 · **Last updated:** 2026-11-02 · **Change:** major (first version) · **Target:** the professional node-based material workflow
Agents drive MaterialCraft three ways, all dispatching the same engine commands:
1. **MCP** (`materialcraft-cli mcp`): headless (an in-process session, files only below
`--read-root` / `--write-root`) or bridged to the running app (`--bridge <port>`).
2. **JSON lines** (`materialcraft-cli serve`): the same methods on stdio, or on `127.0.0.1:<port>`
behind a token.
3. **The app's control channel** (`materialcraft --control <port>`): one JSON request per line,
`{"id", "method", "params"}` → `{"id", "ok": true, "result"}` or `{"id", "ok": false, "error"}`.
The first request must be `{"method":"auth","params":{"token":"…"}}` with the token from
`MATERIALCRAFT_CONTROL_TOKEN` or the file `<temp>/materialcraft-control-<port>.token`.
Set `MATERIALCRAFT_NO_PREFS=1` for scripted runs so the user's layout is left alone.
## Methods
| Method | Where | What |
|---|---|---|
| `ping` | all | `"pong"` |
| `command.list {filter?}` | all | every command: id, label, menu, shortcut, params doc, enabled |
| `command.run {id, params?}` | all | run one command (programmatic: never opens a dialog) |
| `command.batch {steps}` | headless | run `[{id, params}]` in order, stop at the first error |
| `session.inspect` | all | package, graphs, the open graph's nodes (def, params, bindings, base, ports, cook error/size/mean/ms), wires, frames, comments, pins, exposed inputs, views, history |
| `package.open {path}` / `package.save {path?}` | headless | workspace-scoped package I/O |
| `bitmap.import {path, name?}` | headless | embed an image as a resource |
| `outputs.export {dir, format?, pattern?, depth?, graph?}` | headless | cook at full size and write every output |
| `render {view?, width?, height?, yaw?, pitch?, scene?, node?, port?, full?}` | headless | PNG (base64) of the 3D view or of one node |
| `ui.inspect` | app | UI state, the graph view rectangle, every node's screen rectangle, every port's screen position, fps, toasts |
| `ui.menu.list` / `ui.menu.invoke {id}` | app | the menu catalog; behave like a click |
| `ui.set {...}` | app | merge fields into the UI state |
| `ui.input {events}` | app | synthetic input, below |
| `view.screenshot {view?: "3d"\|"2d"}` | app | PNG of the 3D or 2D view |
| `ui.screenshot` | app | PNG of the whole window |
| `ui.resize {width, height}` | app | window size in points |
### Synthetic input (`ui.input`)
Events are applied one frame at a time, so egui sees real presses, drags and releases. Positions are
window points (take them from `ui.inspect`'s `nodes` and `ports`).
```json
{"method": "ui.input", "params": {"events": [
{"type": "drag", "from": [512, 140], "to": [600, 220], "steps": 12},
{"type": "click", "pos": [700, 300], "button": "left", "modifiers": ["ctrl"]},
{"type": "doubleClick", "pos": [640, 180]},
{"type": "scroll", "pos": [640, 300], "delta": [0, -120]},
{"type": "key", "key": "Space"},
{"type": "text", "text": "perlin"},
{"type": "key", "key": "Enter"}
]}}
```
Types: `move`, `down`, `up`, `click`, `doubleClick`, `drag`, `scroll`, `key` (egui key names:
`A`, `Enter`, `Space`, `Delete`, `F5`, …), `text`. Buttons: `left`, `right`, `middle`.
## Key commands
| Command | Params |
|---|---|
| `file.new` | `{template?, name?, size?}`; templates from `graph.templates` (`empty`, `pbr`, `bricks`, `stone_tiles`, `wood`, `rusty_metal`, `fabric`, `ground`) |
| `graph.node.add` | `{def, at?, params?, connectFrom?: {node, port?}, label?}` |
| `graph.connect` / `graph.disconnect` | `{from, fromPort?, to, toPort?}` / `{to, toPort}` |
| `graph.node.param` | `{id?, param, value}`: numbers, `[x, y]`, `"#rrggbb"`, enum index, curve `[[x, y], …]`, gradient `[[pos, color], …]`, or a typed value `{"t": "function", "v": {...}}` |
| `graph.node.base` | `{id?, sizeMode?, size?, format?, seed?, tiling?}` |
| `graph.exposed.add` / `graph.exposed.set` | `{id, label?, default?, bind?: {node, param}}` / `{id, value}` |
| `graph.createFromSelection` | `{name?, ids?}`: move nodes into a sub-graph and replace them with an instance |
| `view.2d` / `view.3d` | which node the 2D view shows; scene, environment, camera, tiling, parallax depth |
| `library.list` | `{filter?, category?}`: every node with ports and parameters |
## Function graphs
Pixel and value processors carry a `function` parameter: `{"nodes": [{"id", "op", "inputs": [ids],
"value"?}], "output": id}`. Ops: constants (`const_float`, `const_float2/3/4`, `const_int`,
`const_bool`), variables (`get_pos` = normalized pixel position, `get_size`, `get_var` with
`value` = an exposed input id), samplers (`sample_gray`, `sample_color` with `value` = input index
0–3, input = a float2 position), vectors (`vec2/3/4`, `swizzle` with `value` = `"xy"` etc.),
casts, arithmetic (`add sub mul div mod neg dot`), logic and comparison (`and or not gt ge lt le eq
ne`), functions (`abs floor ceil frac sqrt exp log sin cos tan atan2 pow min max clamp lerp length
normalize rand noise`) and `if_else`. Values are 4-wide; scalars broadcast.
## MCP tools
`session_inspect`, `command_list`, `command_run`, `command_batch`, `library_list`, `graph_new`,
`node_add`, `node_connect`, `node_param`, `package_open`, `package_save`, `bitmap_import`,
`outputs_export`, `view_render` (headless) and, bridged to the app, `view_screenshot`,
`ui_screenshot`, `ui_inspect`, `ui_menu_invoke`, `ui_input`.
+31
View File
@@ -0,0 +1,31 @@
# File format parity
> **Last reviewed:** 2026-11-02 · **Last updated:** 2026-11-02 · **Change:** major (first version) · **Target:** the professional node-based material workflow
MaterialCraft does not read or write the reference app's proprietary package or archive formats
(a non-goal of the clean room). It has its own package format and reads and writes the open image
formats material artists exchange.
| Format | Read | Write | Fidelity | Tests |
|---|---|---|---|---|
| `.mcraft` package (zip: `package.json` + `resources/`) | Yes | Yes | Lossless (graphs, parameters, frames, comments, pins, exposed inputs, embedded bitmaps) | `formats::tests::package_round_trip`, engine `package_save_and_open_round_trip` |
| PNG | Yes (8/16-bit, gray and color) | Yes (8/16-bit) | 16-bit gray round-trips within 1/65535 | `formats::tests::export_every_format` |
| JPEG | Yes | Yes (8-bit) | Lossy | same |
| TGA | Yes | Yes (8-bit) | Lossless | same |
| TIFF | Yes | Yes (8/16-bit) | Lossless | same |
| BMP | Yes | Yes (8-bit) | Lossless | same |
| WEBP | Yes | Yes (8-bit lossless) | Lossless | same |
| OpenEXR | Yes | Yes (32-bit float RGB) | Float | same |
| Radiance HDR | Yes | Yes | Float (RGBE) | same |
| SVG, fonts (resources) | No | — | — | gap |
| Meshes for the 3D view (OBJ, glTF, FBX) | No | — | — | gap |
| Published material archives | — | No | — | gap |
Exports write base color, emissive and specular through the sRGB curve and data maps (normal,
roughness, metallic, height, ambient occlusion, opacity) linear.
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-11-02 | major | First version |
+28
View File
@@ -0,0 +1,28 @@
# Gaps
> **Last reviewed:** 2026-11-02 · **Last updated:** 2026-11-02 · **Change:** major (first list) · **Target:** the professional node-based material workflow
Every known shortfall, most important first. Pick from the top.
| # | Gap | Evidence | Impact | Estimate | Parity doc |
|---:|---|---|---|---:|---|
| 1 | Visual function-graph editor | Pixel/value processor functions are edited as JSON in Properties | Function graphs are a core power-user feature | 10 h | target-app-parity (Function graphs) |
| 2 | Node library breadth | ~120 nodes vs. ~400 in the reference library | Many recipes need nodes we lack (flood fill, shape splatter, 3D noises, material blends) | 40 h | target-app-parity (Node library) |
| 3 | FX-Map, Text and SVG atomic nodes | Not in the catalog | Hand-placed patterns and lettering | 12 h | target-app-parity (Atomic nodes) |
| 4 | Dynamic parameters | Only exposed-input bindings, no per-parameter functions | Procedural parameter logic | 6 h | target-app-parity (Function graphs) |
| 5 | GPU 3D view with tessellation and lights | CPU renderer with parallax only | Displacement previews, light setups | 12 h | target-app-parity (3D view) |
| 6 | Mesh-based generators and bakers | None | Workflows that start from a mesh | 15 h | target-app-parity (Node library) |
| 7 | Published material archives | Only `.mcraft` sources | Sharing cooked materials with other tools | 6 h | target-app-parity (Files) |
| 8 | Browser file I/O | The web build shows a notice for open/save/import | Web users cannot keep their work | 3 h | target-app-parity (Platforms) |
| 9 | `ui.screenshot` times out on this test machine | The window-capture callback never fires here; `view.screenshot` and the offscreen snapshot test work | Agents bridged to the app see views but not the whole window | 1 h | — |
| 10 | Accessible names for custom widgets | egui_kittest's accessibility check finds 12 unnamed widgets (canvas, tiles) | Screen readers; the snapshot test disables the check | 2 h | target-app-parity (UI and UX) |
| 11 | Presets and parameter groups | Not implemented | Organizing large graphs' inputs | 4 h | target-app-parity (Graph parameters) |
| 12 | Translations and keymap editor | English only, fixed shortcuts | Non-English users; custom shortcuts | 8 h | localization-parity |
| 13 | Owner's mascot app icon | A placeholder drawn in code | Brand consistency with the other Crafting Apps | owner | — |
| 14 | First signed release | Workflows copied, not run | Downloads | 3 h | target-app-parity (Platforms) |
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-11-02 | major | First list |
Binary file not shown.

After

Width:  |  Height:  |  Size: 461 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1020 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 425 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 366 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 435 KiB

+18
View File
@@ -0,0 +1,18 @@
# Localization parity
> **Last reviewed:** 2026-11-02 · **Last updated:** 2026-11-02 · **Change:** major (first version) · **Target:** the professional node-based material workflow
Every interface string goes through `crate::i18n::tr` (or is marked with `n_` where it is stored),
so catalogs can be added without touching callers. Today only English ships.
| Language | Code | Status | Notes |
|---|---|---|---|
| English | `en` | Complete | Source language |
| French, German, Spanish, Portuguese (Brazil), Italian | `fr`, `de`, `es`, `pt-br`, `it` | Not started | Planned with the shared craft-i18n catalogs |
| Japanese, Chinese (Simplified), Korean | `ja`, `zh-hans`, `ko` | Not started | Needs the craft-fonts CJK faces (`CRAFT_FONTS_DIR`), as in TextureCraft |
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-11-02 | major | First version |
+177
View File
@@ -0,0 +1,177 @@
# Releasing MaterialCraft
The recipe is craftrules' [release playbook](release-playbook.md); this page covers what is
specific to MaterialCraft. The pipeline is [`.github/workflows/release.yml`](../.github/workflows/release.yml).
## Release manager checklist
The steps below are the release manager's; agents never create the `release` branch, tags or
GitHub Releases. The shared runbook with copy-paste `gh` commands is craftrules
`release/cut-a-release.md`.
### 1. One-time repository setup (org admin)
Status on 2026-10-23: `storytold/materialcraft` has the `release` environment (deployable from
`release` only) and the `release` ruleset (steps 1 and 2 below). Still to do before the first run:
the secrets (step 3) and the runner group (step 4); the `release` branch is created by the first
release push. An org admin runs craftrules `release/signing-setup.md` steps 1-2 for this repo:
1. Create the **`release` environment**, with deployment branches limited to `release`.
2. Add the **ruleset on `refs/heads/release`** (restrict creations, updates and deletions, block
force pushes; bypass: the `release-managers` team and the Organization admin role).
3. Set these **environment secrets** on `release` (`gh secret set <NAME> --env release -R
storytold/materialcraft`). Never as org- or repo-level Actions secrets: only the `release`
environment keeps them away from other branches.
| Secret | Read by |
|---|---|
| `APPLE_CERTIFICATE`, `APPLE_CERTIFICATE_PASSWORD`, `KEYCHAIN_PASSWORD` | macOS: Developer ID certificate into a temporary keychain |
| `APPLE_ID`, `APPLE_PASSWORD`, `APPLE_TEAM_ID` | macOS: notarization (`notarytool`) and its verification |
| `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_SIGNING_ENDPOINT`, `AZURE_SIGNING_ACCOUNT`, `AZURE_CERT_PROFILE` | Windows: Azure Trusted Signing (the org's method) |
| `WINDOWS_CERTIFICATE`, `WINDOWS_CERTIFICATE_PASSWORD` | Windows: a `.pfx` instead of Azure; takes precedence when set. Leave unset |
Those twelve (`APPLE_*` and `KEYCHAIN_PASSWORD`, `AZURE_*`) are all a signed release needs;
`GITHUB_TOKEN` is provided by Actions.
4. Add the repo to the org's **Default runner group** (Settings → Actions → Runner groups). The
macOS job (`macos-15-xlarge`) and the FreeBSD job (`github-ubuntu-16core`) run on larger runners,
which only serve repos in that group; outside it they wait for a runner forever, with no error.
### 2. Set the version
On `main`:
```sh
cargo xtask version # prints the current version
cargo xtask version set 0.2.0 # or 0.2.0-rc.1 for a pre-release
```
`set` rewrites `[workspace.package] version` in the root `Cargo.toml` (the single source of truth)
and refreshes `Cargo.lock`. Commit, push, and wait for CI on `main` to pass.
### 3. Cut the release
Fast-forward `release` to `main` and push it (only the `release-managers` team and org admins can):
```sh
git fetch origin
git push origin origin/main:refs/heads/release
```
That push runs `release.yml`, and also `freebsd.yml` and `windows-arm64.yml` (build, test, install
checks). A version with a hyphen becomes a pre-release. To test without bumping, dispatch
`release.yml` on `release` with `version` set (e.g. `0.2.0-rc.1`); a dispatch on any other branch
is a dry run (Linux, Flatpak, FreeBSD and web build; the signing jobs are refused by the
environment, so no draft is made).
### 4. Wait for green and verify
```sh
RID=$(gh run list -R storytold/materialcraft -w release.yml -L1 --json databaseId --jq '.[0].databaseId')
gh run watch $RID -R storytold/materialcraft
gh run view $RID -R storytold/materialcraft --log | grep -E "status: Accepted|staple and validate action worked|::warning"
```
- Every job is green, and no `::warning::` names a missing secret (that platform shipped unsigned:
fix the secret and re-run, don't publish).
- macOS: two `The staple and validate action worked!` lines (app and DMG) and `status: Accepted`.
- The draft `MaterialCraft v<version>` exists, targets the commit you pushed, and carries every
file in the table below plus `SHA256SUMS.txt`.
- Download, check and launch at least one artifact per platform:
- Windows: `signtool verify /pa /v materialcraft-<v>-windows-x64.msi` succeeds and names the
org's publisher; install, open a `.mcraft` by double-click, `materialcraft-cli --version` from the
install dir, uninstall.
- macOS: `spctl -a -vvv -t install materialcraft-<v>-macos-universal.dmg` says *Notarized
Developer ID*; the app opens with no Gatekeeper prompt.
- Linux: `sha256sum -c SHA256SUMS.txt --ignore-missing`, then run the AppImage and install the
`.deb` or `.rpm`; `materialcraft --version`, `materialcraft-cli --version`.
- Web: unzip `materialcraft-web-<v>.zip`, serve it (`python3 -m http.server`), open it in a
WebGPU browser.
### 5. Publish
Review the generated notes, then publish the draft (`gh release edit v<version> -R
storytold/materialcraft --draft=false --latest`, or `--prerelease` for an rc). A draft is updated in
place by a re-run; a published release is never overwritten, so bump the version before building
again.
## What gets built
All file names are `materialcraft-<version>-<platform>-<arch>.<ext>`, written to `dist/release/`.
| Platform | Artifacts | Script |
|---|---|---|
| macOS universal (`macos-15-xlarge`) | `-macos-universal.dmg` (`MaterialCraft.app`), `materialcraft-cli-<version>-macos-universal.zip` | `packaging/macos/package.sh`, `verify.sh` |
| Windows x64, x86, arm64 | `-windows-<arch>.msi`, `-windows-<arch>-portable.zip` | `packaging/windows/package.ps1` |
| Linux x86_64, aarch64 (Ubuntu 22.04, glibc 2.35) | `.AppImage` + `.AppImage.zsync`, `.deb`, `.rpm`, `.tar.gz` | `packaging/linux/package.sh` |
| Flatpak x86_64, aarch64 | `-linux-<arch>.flatpak`, repackaged from the Linux tarball | `packaging/linux/flatpak-bundle.sh` |
| FreeBSD x86_64 (14.3 VM on `github-ubuntu-16core`) | `-freebsd-x86_64.tar.gz` | `packaging/freebsd/package.sh` |
| Web | `materialcraft-web-<version>.zip` (trunk, `wasm-release` profile; hosting notes in `packaging/web/README.md`) | `packaging/web/package.sh` |
Every desktop package ships both binaries, `materialcraft` and `materialcraft-cli` (on macOS the CLI
is its own zip next to the DMG). Release builds pass the craft-fonts reference (`CRAFT_FONTS_REF` in `release.yml`); MaterialCraft
does not embed CJK fonts yet (see docs/localization-parity.md). The packaging
scripts smoke-test `materialcraft-cli --version`, and the Linux job also runs the AppImage with
`--version`, so both binaries must print their version and exit without opening a window.
## MaterialCraft-specific values
| What | Value |
|---|---|
| Bundle / app id | `ai.storyteller.materialcraft` |
| Package format | `.mcraft`, MIME `application/x-materialcraft`, UTI `ai.storyteller.materialcraft.package` (owned). Declared in `materialcraft.wxs`, `Info.plist.in`, the `.desktop` file, `mime.xml` and the AppStream metainfo: keep all five in step |
| WiX UpgradeCode | `89DE105E-B6C8-4261-ADBE-25BCFA3A0C91`, never change it |
| Flathub manifest | `packaging/linux/flatpak/ai.storyteller.MaterialCraft.yml` (release bundle: `…MaterialCraft.bundle.yml`) |
| macOS minimum | 11.0 (`LSMinimumSystemVersion`, `MACOSX_DEPLOYMENT_TARGET`) |
## Version and build info in the binaries
`apps/materialcraft/build.rs` (also `include!`d by `apps/materialcraft-cli/build.rs`) sets, for
`env!`:
- `MATERIALCRAFT_BUILD_SHA`: the full commit. CI sets it to `github.sha`; `packaging/env.sh` sets
it from git; otherwise build.rs asks git itself; empty when unknown.
- `MATERIALCRAFT_BUILD_DATE`: `YYYY-MM-DD` (UTC). CI sets it once per run; otherwise today's date,
or `SOURCE_DATE_EPOCH`'s for reproducible builds.
On Windows targets it also embeds `assets/app-icon/materialcraft.ico` and VERSIONINFO
(ProductName MaterialCraft); `package.ps1` sets `MATERIALCRAFT_REQUIRE_WINRES=1` so a release can't
ship an exe without them. The version itself is `CARGO_PKG_VERSION`.
Other environment variables the scripts read: `MATERIALCRAFT_VERSION` (override the version),
`DIST`, `CARGO_TARGET_DIR`, `MATERIALCRAFT_MAINTAINER` (deb/rpm maintainer),
`MATERIALCRAFT_WASM_MAX_BYTES` (web size gate, default 24 MiB), and at run time
`MATERIALCRAFT_NO_DESKTOP_INTEGRATION=1` (the AppImage's AppRun skips installing its `.desktop`
entry and icons).
## Signing
Secrets live only in the `release` environment and are all optional: a missing one gives an
unsigned artifact and a `::warning::`, never a failed build.
- macOS: `APPLE_CERTIFICATE`, `APPLE_CERTIFICATE_PASSWORD`, `KEYCHAIN_PASSWORD` (import into a
temporary keychain, `packaging/macos/import-cert.sh`), then `APPLE_ID`, `APPLE_PASSWORD`,
`APPLE_TEAM_ID` for `notarytool` and stapling. Without them the app is ad-hoc signed.
- Windows: `packaging/windows/sign.ps1` uses a PFX (`WINDOWS_CERTIFICATE`,
`WINDOWS_CERTIFICATE_PASSWORD`) if set, otherwise Azure Trusted Signing (all six `AZURE_*`).
It signs both exes before WiX and the MSI after.
## Icons
`assets/app-icon/materialcraft.svg` is the engraved zebra (the owner's original drawing, vectorised
to three colours, craftrules `standards/icon-design.md`); `materialcraft-small.svg` is a lighter
trace for the hicolor scalable icon. `packaging/icons.sh` renders everything else with resvg and
`cargo xtask ico|icns`: the hicolor PNGs (16-512 px) and scalable SVG, `materialcraft-1024.png`,
`materialcraft.ico` and `materialcraft.icns`. The outputs are committed; rerun it after changing the
artwork and keep `ATTRIBUTION.md` in step. See `assets/app-icon/README.md`.
## Local checks
- `cargo xtask ci`: fmt, clippy, tests, `cargo xtask layers`, `cargo xtask wasm`.
- `bash packaging/linux/apprun-test.sh` and `bash packaging/freebsd/package.sh --dry-run` run
anywhere with bash.
- `packaging/macos/package.sh --arch aarch64` on a Mac builds an ad-hoc signed DMG.
- `pwsh packaging/windows/package.ps1 -Arch x64` on Windows (needs WiX 5.0.2) builds an unsigned
MSI and portable zip. Use PowerShell 7 as CI does: Windows PowerShell 5.1 with redirected output
turns cargo's stderr into an error, so there build with cargo first and pass `-SkipBuild`.
- `.github/workflows/packaging-lint.yml` runs actionlint, shellcheck, the PowerShell parser and
the desktop/AppStream/Flatpak validators on every change to `packaging/` or the workflows.
+46
View File
@@ -0,0 +1,46 @@
# Roadmap detail
> **Last reviewed:** 2026-11-02 · **Last updated:** 2026-11-02 · **Change:** major (first version) · **Target:** the professional node-based material workflow
## Milestones
| Milestone | Status | Scope |
|---|---|---|
| M0 Skeleton | Done | Workspace, licences, AGENTS.md, xtask (layers, wasm, ci, version, ico, icns), CI and packaging |
| M1 Core + engine | Done | Document model, images, node library, cooking with cache, session, commands, inspect, samples |
| M2 UI shell | Done | Docked layout, graph editor, library, properties, 2D and 3D views, dialogs, menus, status bar |
| M3 Node breadth | In progress | ~120 of ~400 library nodes |
| M4 Function graphs | In progress | Evaluator done; visual editor and dynamic parameters next |
| M5 Graph features | In progress | Exposed inputs and instances done; presets, groups, visibility next |
| M6 Files | In progress | Packages, bitmaps, export done; published archives, mesh import, browser I/O next |
| M7 Automation | Done | CLI, control channel with synthetic input, MCP server |
| M8 3D view depth | Planned | GPU renderer, tessellation, lights, meshes |
| M9 Web + packaging | In progress | WASM builds; browser file I/O and the first release run next |
| M10 Polish | Planned | Home screen at startup, keymap editor, translations, accessibility |
## Current focus
1. The visual function-graph editor (gap 1) and dynamic parameters (gap 4).
2. Node library breadth (gap 2): flood fill family, shape splatter, 3D noises, more grunge maps,
whole-material blending and height blending.
3. FX-Map lite, Text and SVG nodes (gap 3).
## Remaining effort (Opus 5.5 agent hours)
| Work | Estimate |
|---|---:|
| Node library to ~300 nodes | 40 h |
| Function editor + dynamic parameters | 16 h |
| FX-Map, Text, SVG | 12 h |
| 3D view on the GPU, tessellation, lights, mesh import | 15 h |
| Mesh-based generators | 15 h |
| Files: published archives, browser I/O | 9 h |
| UX: presets, groups, keymap, translations, accessibility, home screen | 10 h |
| Release | 3 h |
| **Total** | **≈ 120 h** |
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-11-02 | major | First version |
+38
View File
@@ -0,0 +1,38 @@
# Parity with the reference workflow
> **Last reviewed:** 2026-11-02 · **Last updated:** 2026-11-02 · **Change:** major (first assessment) · **Target:** the professional node-based material workflow (desktop app; the web app is assessed later)
**Overall: ≈ 51%** of a material artist's daily workflow works end to end (engine + UI +
automation + tests), weighted by how much of the day each area carries. **Remaining: ≈ 120 Opus
5.5 agent hours** (see [roadmap.md](roadmap.md)).
| Area | Weight | Done | What works | Main gaps |
|---|---:|---:|---|---|
| Graph editing | 15 | 75% | Pan/zoom canvas with grid; node cards with headers by category, live thumbnails and size/format labels; typed ports; bezier wires; drag to wire, re-route and unplug; drop a wire on empty canvas to add a wired node; box/Ctrl/Shift selection; move; frames (move with contents, resize), comments (inline edit), navigation pins; node search (Space, double-click); library drag and drop; align and distribute; copy/cut/paste/duplicate (with or without links); delete and relink; disable; select upstream/downstream; create graph from selection; snapshot undo with merged slider drags | Dot-node chains editing, wire tension preferences, compact node display mode, multi-graph tabs, minimap |
| Atomic nodes | 12 | 80% | Bitmap, Blend (16 modes, masks, alpha), Blur, Channels Shuffle, Curve, Directional Blur, Directional Warp, Distance (with color propagation), Emboss, Gradient (Dynamic), Gradient Map, Grayscale Conversion, HSL, Levels, Normal, Pixel Processor, Value Processor, Sharpen, Transformation 2D, Uniform Color, Warp, inputs, outputs, dots, graph instances | Text, SVG, FX-Map |
| Node library | 20 | 25% | 29 noises, 16 patterns (tile generator, tile sampler, bricks, hexagons, weave, splatter, scratches, shapes, polygons, stars, stripes, gradients), 50 filters (adjustments, blending, blurs, channels, effects, normal map tools, tiling, transforms), 4 PBR utilities | Most of the reference library's ~400 graphs: 3D noises, more grunge maps, flood fill family, shape splatter, material blending/height blending of whole materials, scan processing, mesh-based generators, spline tools, SDF functions |
| Function graphs | 10 | 35% | A compiled, 4-wide evaluator with ~55 ops (constants, $pos/$size, exposed variables, samplers, vectors, swizzles, math, logic, comparison, noise, random, if/else), pixel and value processors | Visual function editor (JSON editor for now), dynamic parameters (functions on any parameter), loops, function graphs as package items |
| Graph parameters and instances | 8 | 50% | Exposed inputs (float, int, bool, enum, color) bound to node parameters, set from the graph's properties or an instance's; sub-graph instances with their own inputs and outputs; graph attributes | Presets, parameter groups and visibility conditions, per-instance output sizes, embedded vs. linked packages |
| 2D view | 5 | 70% | Pan/zoom, fit and 1:1, RGBA/R/G/B/A isolation, 3×3 tiling check, pixel readout, size/format line, save image | Histogram, color picker to parameters, UV overlay |
| 3D view | 10 | 45% | Rounded cube, cube, sphere, cylinder, plane, torus and material ball; base color, normal, roughness, metallic, height (parallax occlusion), AO, emissive and opacity; 4 procedural environments with rotation and exposure; orbit/zoom; tiling; supersampling at rest | GPU renderer with tessellation, lights, custom meshes, material/shader switching, path-traced renderer |
| Files | 8 | 50% | `.mcraft` packages with embedded bitmaps; export of every output (PNG, JPEG, TGA, TIFF, BMP, WEBP, EXR, HDR; 8/16/32 bits; name pattern; sRGB vs. linear by usage); bitmap import (PNG, JPEG, TGA, TIFF, BMP, WEBP, EXR, HDR); atomic writes; autosave; recent files | Published (cooked) material archives, mesh import for the 3D view, package dependencies, SVG/font resources, browser file I/O |
| UI and UX | 8 | 55% | Dockable/floatable panels (explorer, library, graph, 3D, 2D, properties, console, history), menus, main toolbar, graph toolbar with atomic quick-insert, library with live previews, properties with curve/gradient/color editors, New graph dialog with rendered templates, export dialog, preferences (brightness, accent, scale, preview size, autosave), shortcuts list, home dialog, status bar | Translations, keymap editor, accessible names on custom widgets, home screen at startup |
| Platforms | 4 | 40% | Windows, macOS, Linux, FreeBSD and web builds compile; packaging scripts and release workflows copied from TextureCraft | First release run; browser file I/O |
| **Total** | **100** | **≈ 51%** | | |
Beyond the reference app: every edit is a command available through MCP, the CLI and the app's
control channel (including synthetic mouse and keyboard input), the engine runs headless with the
same results, and everything compiles to WebAssembly.
## Method
Scores are self-assessed from our code against public documentation of the professional
node-based material workflow and observation of the reference desktop app's menus, panels and
node library, area by area. A feature counts only when it works end to end (engine, UI, automation)
and is tested.
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-11-02 | major | First assessment after the first day of work |