d84914ef1e5a
commands.rs
//! The command registry. Every user-visible action is a command with a stable id; the menus,
//! shortcuts, CLI, control channel and MCP server all dispatch them by id. Ids follow
//! the menu structure (see `menu_catalog`).
use serde_json::{Value, json};
use texturecraft_core::{BlendMode, Channel, NormalFormat};
use texturecraft_geom::glam::Vec3;
use crate::{EngineError, Result, Session};
pub type Run = fn(&mut Session, &Value) -> Result<Value>;
pub type Enabled = fn(&Session) -> std::result::Result<(), String>;
pub struct CommandSpec {
pub id: &'static str,
pub label: &'static str,
/// Menu placement, e.g. `["Edit"]`. Empty = not in menus.
pub menu: &'static [&'static str],
/// Default shortcut in egui notation (`Ctrl+Shift+E`), mapped per platform by the UI.
pub shortcut: Option<&'static str>,
/// Parameters, for humans and agents.
pub params: &'static str,
pub enabled: Enabled,
pub run: Run,
}
impl CommandSpec {
/// Whether a keyboard shortcut can run this command: it acts with no parameters at all, or
/// every parameter in its first `params` form is optional (`name?`) and none of them is one
/// of several alternatives. Left out: commands that need a path, name or similar, commands
/// that only return data or do nothing without parameters, and the ones that replace the
/// open project (the menu asks to save first).
pub fn bindable(&self) -> bool {
const NOT_FROM_A_KEY: [&str; 13] = [
"project.inspect",
"project.templates",
"project.new",
"tool.state",
"text.fonts",
"export.presets",
"edit.history",
"camera.get",
"textureSet.parts",
"bake.settings",
"bake.preview",
"camera.set",
"textureSet.settings",
];
const NOTHING_WITHOUT_PARAMS: [&str; 4] = ["layer.blend", "tool.stencil", "tool.fillSelection", "tool.path"];
!(self.id.ends_with(".list") || NOT_FROM_A_KEY.contains(&self.id) || NOTHING_WITHOUT_PARAMS.contains(&self.id)) && params_all_optional(self.params)
}
}
/// Whether the first `{...}` group of a `params` text has only optional entries.
fn params_all_optional(params: &str) -> bool {
let Some(body) = params.trim_start().strip_prefix('{') else { return false };
let Some(end) = body.find('}') else { return false };
// `{a?} | {b}`: other forms exist, and the first one alone may not do anything
if body[end + 1..].trim_start().starts_with('|') {
return false;
}
let (mut depth, mut start) = (0i32, 0);
let mut entries = Vec::new();
for (i, c) in body[..end].char_indices() {
match c {
'(' | '[' => depth += 1,
')' | ']' => depth -= 1,
',' if depth == 0 => {
entries.push(&body[start..i]);
start = i + 1;
}
_ => {}
}
}
entries.push(&body[start..end]);
entries.iter().filter(|entry| !entry.trim().is_empty()).all(|entry| {
// `index? | name?` asks for one of the two, so it is not optional as a whole
!entry.contains(" | ") && entry.trim().split([':', ' ', '(']).next().is_some_and(|key| key.ends_with('?'))
})
}
pub(crate) fn always(_: &Session) -> std::result::Result<(), String> {
Ok(())
}
pub(crate) fn has_layer(s: &Session) -> std::result::Result<(), String> {
s.selected_layer().map(|_| ()).ok_or_else(|| "no layer selected".into())
}
pub(crate) fn can_undo(s: &Session) -> std::result::Result<(), String> {
if s.can_undo() { Ok(()) } else { Err("nothing to undo".into()) }
}
pub(crate) fn can_redo(s: &Session) -> std::result::Result<(), String> {
if s.can_redo() { Ok(()) } else { Err("nothing to redo".into()) }
}
#[macro_export]
#[doc(hidden)]
macro_rules! cmd {
($id:literal, $label:literal, [$($m:literal),*], $sc:expr, $params:literal, $en:expr, $run:expr) => {
$crate::commands::CommandSpec { id: $id, label: $label, menu: &[$($m),*], shortcut: $sc, params: $params, enabled: $en, run: $run }
};
}
pub fn command_specs() -> &'static [CommandSpec] {
static SPECS: std::sync::OnceLock<Vec<CommandSpec>> = std::sync::OnceLock::new();
SPECS.get_or_init(|| {
let mut v = Vec::new();
v.extend(crate::view_cmds::edit_specs());
v.extend(crate::layer_cmds::specs());
v.extend(crate::layer_ops::specs());
v.extend(crate::instance_cmds::specs());
v.extend(crate::mask_cmds::specs());
v.extend(crate::mask_export::specs());
v.extend(crate::color_selection_cmds::specs());
v.extend(crate::effect_clipboard::specs());
v.extend(crate::tool_cmds::specs());
v.extend(crate::brush_preset_cmds::specs());
v.extend(crate::path_tool::specs());
v.extend(crate::view_cmds::specs());
v.extend(crate::solo::specs());
v.extend(crate::camera_cmds::specs());
v.extend(crate::quick_mask::specs());
v.extend(crate::set_cmds::specs());
v.extend(crate::meshmap_cmds::specs());
v.extend(crate::meshmap_import_cmds::specs());
v.extend(crate::uv_tile_cmds::specs());
v.extend(crate::template_cmds::specs());
v.extend(crate::project_cmds::specs());
v.extend(crate::bake::specs());
v.extend(crate::bake_preview::specs());
v.extend(crate::materialx_cmds::specs());
v.extend(crate::pbr_cmds::specs());
v.extend(crate::file_cmds::specs());
v.extend(crate::preset_cmds::specs());
v.extend(crate::resource_cmds::specs());
v.extend(crate::material_lib::specs());
v.extend(crate::link_cmds::specs());
v.extend(crate::smart_masks::specs());
v.extend(crate::filter_lib::specs());
v.extend(crate::decal_cmds::specs());
v.extend(crate::text_cmds::specs());
v
})
}
/// Commands that run in the empty state (no project open): they open or create a project, or
/// only read the libraries and the user's presets, or only move the camera (`viewport.frame`, enabled on the reference app's blank screen).
fn works_without_project(id: &str) -> bool {
matches!(
id,
"file.open"
| "file.new"
| "project.new"
| "project.sample"
| "project.inspect"
| "viewport.frame"
| "project.templates"
| "export.presets"
| "export.preset.get"
| "export.preset.save"
| "export.preset.remove"
| "brush.preset.list"
| "alpha.list"
| "filter.list"
| "material.list"
| "mask.smart.list"
| "text.fonts"
)
}
/// Whether `spec` can run on `s`: no project open refuses everything but [`works_without_project`]
pub fn check_enabled(spec: &CommandSpec, s: &Session) -> std::result::Result<(), String> {
if !s.project_open && !works_without_project(spec.id) {
return Err("no project is open".into());
}
(spec.enabled)(s)
}
pub fn find(id: &str) -> Option<&'static CommandSpec> {
command_specs().iter().find(|c| c.id == id)
}
/// Run a command by id with JSON params (empty params = defaults, never a dialog). With
/// `merge: true` its edits continue the previous undo step of the same label (drags).
pub fn execute(s: &mut Session, id: &str, params: &Value) -> Result<Value> {
let spec = find(id).ok_or_else(|| EngineError::UnknownCommand(id.to_string()))?;
check_enabled(spec, s).map_err(|why| EngineError::Disabled { cmd: id.to_string(), why })?;
let outer = std::mem::replace(&mut s.merge_edits, boolp(params, "merge").unwrap_or(false));
let result = (spec.run)(s, params);
s.merge_edits = outer;
result
}
/// Every command, as JSON (for `commands` listings and MCP).
pub fn list(s: &Session, filter: Option<&str>) -> Value {
let f = filter.map(str::to_ascii_lowercase);
let items: Vec<Value> = command_specs()
.iter()
.filter(|c| f.as_ref().is_none_or(|f| c.id.to_ascii_lowercase().contains(f) || c.label.to_ascii_lowercase().contains(f)))
.map(|c| {
json!({
"id": c.id,
"label": c.label,
"menu": c.menu,
"shortcut": c.shortcut,
"params": c.params,
"enabled": check_enabled(c, s).is_ok(),
})
})
.collect();
Value::Array(items)
}
// ---------- param helpers ----------
pub(crate) fn bad(cmd: &str, msg: impl Into<String>) -> EngineError {
EngineError::BadParams { cmd: cmd.into(), msg: msg.into() }
}
pub(crate) fn f32p(p: &Value, key: &str) -> Option<f32> {
p.get(key).and_then(Value::as_f64).map(|v| v as f32).filter(|v| v.is_finite())
}
pub(crate) fn u64p(p: &Value, key: &str) -> Option<u64> {
p.get(key).and_then(|v| v.as_u64().or_else(|| v.as_f64().filter(|f| f.is_finite() && *f >= 0.0).map(|f| f.round() as u64)))
}
/// A `[x, y, z]` param of finite numbers
pub(crate) fn vec3(params: &Value, key: &str) -> Option<Vec3> {
let [x, y, z] = params.get(key)?.as_array()?.as_slice() else { return None };
let vector = Vec3::new(x.as_f64()? as f32, y.as_f64()? as f32, z.as_f64()? as f32);
vector.is_finite().then_some(vector)
}
pub(crate) fn boolp(p: &Value, key: &str) -> Option<bool> {
p.get(key).and_then(Value::as_bool)
}
/// The `normalFormat` param (`openGl` or `directX`), if given.
pub(crate) fn normal_format_param(cmd: &str, p: &Value) -> Result<Option<NormalFormat>> {
match p.get("normalFormat") {
None | Some(Value::Null) => Ok(None),
Some(Value::String(s)) if matches!(s.as_str(), "openGl" | "opengl") => Ok(Some(NormalFormat::OpenGl)),
Some(Value::String(s)) if matches!(s.as_str(), "directX" | "directx") => Ok(Some(NormalFormat::DirectX)),
Some(other) => Err(bad(cmd, format!("unknown normal format {other} (openGl or directX)"))),
}
}
pub(crate) fn strp<'a>(p: &'a Value, key: &str) -> Option<&'a str> {
p.get(key).and_then(Value::as_str)
}
/// A layer id param (`"layer"`), defaulting to the selected layer.
pub(crate) fn layer_param(s: &Session, cmd: &str, p: &Value) -> Result<texturecraft_core::LayerId> {
match u64p(p, "layer") {
Some(id) => {
let id = texturecraft_core::LayerId(id);
s.doc.project.layer(id).map_err(|_| bad(cmd, format!("no layer {}", id.0)))?;
Ok(id)
}
None => s.selected_layer().ok_or_else(|| bad(cmd, "no layer selected and no `layer` given")),
}
}
/// [`layer_param`], following an instance to the layer whose content it draws.
pub(crate) fn content_param(s: &Session, cmd: &str, p: &Value) -> Result<texturecraft_core::LayerId> {
let id = layer_param(s, cmd, p)?;
Ok(s.doc.project.content_layer(id).map_or(id, |l| l.id))
}
pub(crate) fn channel_param(cmd: &str, p: &Value, key: &str) -> Result<Option<Channel>> {
match strp(p, key) {
None => Ok(None),
Some(s) => Channel::parse(s).map(Some).ok_or_else(|| bad(cmd, format!("unknown channel `{s}`"))),
}
}
pub(crate) fn blend_param(cmd: &str, p: &Value, key: &str) -> Result<Option<BlendMode>> {
match strp(p, key) {
None => Ok(None),
Some(s) => BlendMode::parse(s).map(Some).ok_or_else(|| bad(cmd, format!("unknown blend mode `{s}`"))),
}
}
/// A color: `[r, g, b]` (linear 0..1) or `"#rrggbb"` (sRGB hex, converted to linear).
pub(crate) fn color_param(cmd: &str, p: &Value, key: &str) -> Result<Option<[f32; 3]>> {
match p.get(key) {
None | Some(Value::Null) => Ok(None),
Some(v) => color_of(v).map(Some).ok_or_else(|| bad(cmd, format!("`{key}` must be a color ([r, g, b] linear or \"#rrggbb\" sRGB)"))),
}
}
/// A color value (see [`color_param`]).
pub(crate) fn color_of(v: &Value) -> Option<[f32; 3]> {
match v {
Value::Array(a) if a.len() >= 3 => {
let mut out = [0.0f32; 3];
for (i, x) in a.iter().take(3).enumerate() {
let f = x.as_f64()? as f32;
if !f.is_finite() {
return None;
}
out[i] = f;
}
Some(out)
}
Value::Number(n) => n.as_f64().map(|v| [v as f32; 3]).filter(|v| v[0].is_finite()),
Value::String(s) => {
let s = s.trim_start_matches('#');
if s.len() != 6 || !s.bytes().all(|b| b.is_ascii_hexdigit()) {
return None;
}
let c = |i: usize| u8::from_str_radix(s.get(i..i + 2)?, 16).ok().map(|v| texturecraft_texel::srgb_to_linear(v as f32 / 255.0));
Some([c(0)?, c(2)?, c(4)?])
}
_ => None,
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn only_commands_a_key_can_run_are_bindable() {
let bindable = |id: &str| find(id).unwrap_or_else(|| panic!("{id} is gone")).bindable();
for id in [
"layer.add.paint",
"layer.add.fill",
"layer.add.group",
"mask.invert",
"mask.clear",
"layer.visible",
"effect.add.paint",
"file.save",
"tool.paint",
"camera.add",
"effect.duplicate",
"effect.paste",
] {
assert!(bindable(id), "{id} needs no parameters");
}
for id in [
"file.saveCopy",
"textureSet.select",
"layer.rename",
"tool.select",
"layer.select",
"viewport.focusAt",
"tool.stroke",
"mask.smart.apply",
"bake.skew.set",
"textureSet.resolution",
"effect.move",
"camera.remove",
"bake.highPoly.remove",
] {
assert!(!bindable(id), "{id} needs a parameter");
}
for id in ["layer.move", "layer.list", "project.inspect", "edit.history", "export.presets", "tool.state", "project.new", "camera.set", "layer.blend"] {
assert!(!bindable(id), "{id} is a query or has several forms");
}
}
#[test]
fn params_texts_are_read_by_their_required_entries() {
for ok in ["{}", "{layer?}", "{enabled?: bool} \u{2014} toggles when omitted", "{effect?: the selected effect}"] {
assert!(params_all_optional(ok), "{ok}");
}
for no in [
"{path}",
"{layer?, name}",
"{x, y (viewport pixels), viewport?: [w, h]}",
"{a?} | {b}",
"{index? | name?}",
"{ts?, value?: 0..1 | path: image}",
"no braces",
] {
assert!(!params_all_optional(no), "{no}");
}
}
#[test]
fn color_param_accepts_valid_forms() {
let p = json!({
"hex": "#336699",
"hex_plain": "336699",
"rgb": [0.2, 0.4, 0.6],
"grey": 0.5,
});
assert!(color_param("cmd", &p, "hex").unwrap().is_some());
assert!(color_param("cmd", &p, "hex_plain").unwrap().is_some());
assert_eq!(color_param("cmd", &p, "rgb").unwrap(), Some([0.2, 0.4, 0.6]));
assert_eq!(color_param("cmd", &p, "grey").unwrap(), Some([0.5, 0.5, 0.5]));
assert_eq!(color_param("cmd", &p, "missing").unwrap(), None);
assert_eq!(color_param("cmd", &json!({"c": null}), "c").unwrap(), None);
}
#[test]
fn color_param_rejects_invalid_forms() {
let bad_cases = [
("#fff", "`color` must be a color ([r, g, b] linear or \"#rrggbb\" sRGB)"),
("red", "`color` must be a color ([r, g, b] linear or \"#rrggbb\" sRGB)"),
("#12345", "`color` must be a color ([r, g, b] linear or \"#rrggbb\" sRGB)"),
("#gggggg", "`color` must be a color ([r, g, b] linear or \"#rrggbb\" sRGB)"),
];
for (input, expected_err) in bad_cases {
let p = json!({ "color": input });
let err = color_param("test.cmd", &p, "color").unwrap_err();
assert_eq!(err.to_string(), format!("`test.cmd`: {expected_err}"));
}
let bad_array = json!({ "color": ["a", "b", "c"] });
assert!(color_param("test.cmd", &bad_array, "color").is_err());
let short_array = json!({ "color": [0.5, 0.5] });
assert!(color_param("test.cmd", &short_array, "color").is_err());
let overflow_array = json!({ "color": [1e40, 0.0, 0.0] });
assert!(color_param("test.cmd", &overflow_array, "color").is_err());
let overflow_scalar = json!({ "color": 1e40 });
assert!(color_param("test.cmd", &overflow_scalar, "color").is_err());
}
#[test]
fn hex_color_rejects_signs_and_non_hex() {
assert_eq!(color_of(&json!("#+f+f+f")), None);
assert_eq!(color_of(&json!("#-00000")), None);
assert_eq!(color_of(&json!("#GGGGGG")), None);
assert!(color_of(&json!("#ff8000")).is_some());
}
#[test]
fn no_bindable_command_asks_for_a_parameter() {
// Effect commands need a selected effect, which this session lacks
for spec in command_specs().iter().filter(|c| c.bindable() && c.shortcut.is_none() && !c.id.starts_with("effect.")) {
let mut session = crate::sample_session(256, 64).unwrap();
if (spec.enabled)(&session).is_ok()
&& let Err(err) = execute(&mut session, spec.id, &Value::Null)
{
let text = err.to_string();
assert!(!text.contains("required") && !text.contains("give "), "{} asks for a parameter: {text}", spec.id);
}
}
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.