mroxso/artcraft-skills

texturecraft

Create and edit 3D texture painting projects, texture sets, layer stacks, baking, and texture exports or automate the TextureCraft application using its control protocol, MCP bridge, or headless CLI.

Voir la source

Mode d’emploi

  1. Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
  2. Consultez le document original pour les outils, identifiants et environnements requis.
  3. Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/mroxso/artcraft-skills --skill texturecraft

Avant de commencer

  • L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
  • Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original

Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.

TextureCraft

Operate TextureCraft through its structured automation interface. Preserve the user's requested texturing workflow and target texture set.

Protocol reference

Read the relevant sections of references/control-protocol.md before constructing calls. This is the downloaded upstream protocol, captured on 2026-11-15.

Source: TextureCraft control protocol.

Useful sections: the Control channel method table, Live bake preview, the MCP server tool table, MaterialCraft materials, and CLI. Relative links inside the downloaded document refer to upstream documentation; resolve them against https://github.com/storytold/texturecraft/blob/main/docs/ when needed. The document lists example commands, not the full command library: discover command ids, labels, parameter docs and current enabled state at runtime with command.list {filter?} (MCP: command_list) instead of inventing ids.

Locate the executables

texturecraft and texturecraft-cli may not be on PATH even when TextureCraft is installed. Discover them before assuming anything is missing, and never invent a path — search for it:

  1. PATH: command -v texturecraft texturecraft-cli (POSIX) or where texturecraft texturecraft-cli (Windows).
  2. macOS: look for TextureCraft.app in /Applications and ~/Applications, or run mdfind -name TextureCraft.app; the binary inside Contents/MacOS/ is the desktop app.
  3. Linux: AppImage, Flatpak, deb/rpm, or tarball installs; the CLI may be a separate download.
  4. Built from source: cargo run --release -p texturecraft and cargo run --release -p texturecraft-cli -- ….

Select the session

  • For a user's open project or visible application, use a TextureCraft MCP bridge (texturecraft-cli mcp --bridge <port>) or the app's control channel (texturecraft --control <port>). A headless session has its own in-process project and cannot edit the user's live window.
  • For unattended file processing, use headless MCP (texturecraft-cli mcp --read-root DIR --write-root DIR), the JSON-lines server (texturecraft-cli serve [--port <port>]), or one-shot CLI subcommands (new, run, batch, bake, export, render, info).

The control channel requires an auth request first on every connection: token from TEXTURECRAFT_CONTROL_TOKEN or the file <temp>/texturecraft-control-<port>.token. Then one JSON object per line, {"id", "method", "params"}; match replies by id and check ok. Set TEXTURECRAFT_NO_PREFS (any value) for scripted runs so the user's layout and settings are left alone. Keep TCP on loopback and credentials in a private token file; do not print, commit, or expose tokens in command arguments.

Inspect, edit, and verify

Inspect before editing: session.inspect returns the project, mesh, texture sets, the layer stack with every layer, mask, effect and fill source, painted tile counts, the tool, camera, display and history — an agent can verify most work without a screenshot. project.inspect shows a .mcmat fill layer's link (the MaterialCraft graph's exposed inputs, presets and image inputs).

Edit through engine commands via command.run: project.new {mesh?, resolution?, name?, template?} (built-in meshes: material_ball, sphere, cube, rounded_cube, cylinder, torus, plane, crate), layer.add.fill {color?, roughness?, metallic?, …}, layer.add.image, mask.add.black, effect.add.generator {generator: "edgeWear"|…}, textureSet.meshMap.set / textureSet.meshMap.clear for imported mesh maps, bake.run {resolution?, maps?} (exclude single UV tiles with bake.tile.set, patch bake settings field-wise with bake.settings {ts?, patch}), material.apply {material}, and painting through tool.stroke (or the MCP paint_stroke tool, whose points are viewport pixels). edit.undo {steps?} / edit.redo {steps?} move through history; any command accepts merge: true to fold its edit into the previous undo step.

Commands run programmatically and never open dialogs. Use ui.menu.invoke only when interactive menu behavior is intended. In the app, ui.set can change layout, dock, preferences (language, brightness, accent) and keymap; debug.paintTest and debug.frames exist for performance work.

Verify visually and structurally: re-run session.inspect, then render — viewport.screenshot {view: "3d"|"2d"} (app), viewport_render (MCP; samples up to 4096 path-traces the 3D view), render (JSON-lines), or texturecraft-cli render project.tcraft out.png --size 1280x800 --yaw 30 --pitch 15 (CLI). Saved camera bookmarks (camera.add / camera.list / camera.select) pin repeatable views. Stroke points and render sizes share one space: the default render size is the session viewport (1280×800), so paint_stroke points can be read straight off a viewport_render image.

File access and output

Headless file access is workspace-scoped by launch-time roots (--read-root / --write-root); use task-scoped roots and forward-slash relative paths within them. .., absolute paths, drive letters and symlink escapes are refused. Do not bypass rejected paths by switching to ambient filesystem commands. Through command_run, path-carrying commands (file.* except file.close / file.removeUnused, resource.import, material.save, …) are refused in both MCP modes: use the dedicated tools.

  • Projects: project_open {path} (.tcraft or a mesh file) / project_save {path?}; in bridge mode project_save without a path invokes File › Save. Meshes: mesh_import {path, resolution?} (glTF/GLB, FBX, COLLADA, USD, Alembic, OBJ, PLY, STL), mesh_reimport, mesh_export {path, format?} (textured obj, glb, usd).
  • Resources and baking: resource_import {path} embeds an image (for layer.add.image or tool.stencil, or as a mesh map via textureSet.meshMap.set); bake_mesh_add {path, cage?} adds a high-poly mesh; bake {resolution?, maps?, cpu?} bakes mesh maps, on the GPU when there is one.
  • Materials: material_save {path, layer?, name?} writes a .tcmat smart material; material_load {path} reads .tcmat, a MaterialCraft .mcmat or .mcraft package; drive .mcmat inputs with material.link.set / material.link.preset / material.link.cook (re-cooks run materialcraft-cli batch, found via $MATERIALCRAFT_CLI or next to the executable).
  • Textures: textures_export {dir, preset?, ts?, format?, padding?, size?} writes engine-ready maps (PNG, JPEG, TGA, TIFF, BMP, WEBP, EXR, HDR at 8, 16 or 32 bits); CLI: texturecraft-cli export model.tcraft out/ --preset "Unreal Engine (Packed)".
  • Report successful saves and exports with the exact output path and format. Do not overwrite the user's source project unless asked; save a copy under a new name.

Batches and uncertain outcomes

Use command_batch {steps} (MCP, JSON-lines command.batch, or texturecraft-cli batch script.json) for known sequences; it stops at the first error and reports {completed, results, failed}. Batches are not transactions: earlier steps persist on failure, so inspect per-step results. Replies are capped (8 MiB of JSON, 5 MiB per PNG, 256 batch steps).

After a disconnect or any other unclear failure, run session.inspect before retrying a mutation — the command may already have completed. Stop and report unresolved state if inspection cannot determine whether replay is safe.

du même dépôt

Autres Skills

Tous les Skills